Knowledgebase
Knowledgebase: PaperCut > Administration
Case Study - Custom User Sync Integration
on 22 August 2012 10:11 AM

Overview

This is a case study of an operating environment that revolves around a proprietary software system which is the primary handler of authentication and maintains and stores user records. Such systems can include proprietary industry-specific ERP and workflow systems that entire companies centralize around and can be difficult to interface with.

If one is lucky, the backend of such systems can be directly accessed or the software vendor provides utilities to allow for integration with external systems. This case study is a starting point to allow developers to integrate these custom and unique systems into PaperCut.

Technical Overview

Programs on the server can be specified in PaperCut to import users and groups and another for authentication. Depending on the request, parameters are passed to the program via command line arguments and standard-input. Information on data formats and triggers are available below. This allows developers to make utilities to bridge their system and Papercut together to the extent of user information and authentication.

PaperCut Sync Source

To achieve the above, we rely on the Sync Source feature in PaperCut, specifically, the Custom program option.

This can be accessed and enabled by doing the following:

  1. Navigate to the OptionsUser/Group Sync tab.
  2. The settings in the Sync Source section defines where PaperCut imports users and groups from. Change the Primary sync source to Custom program.
  3. Enter in the path to the program that enumerates user and group information in the field Custom user program.
  4. Enter in the path to the program that handles user authentication in the field Custom auth program.

Source code for an example program which utilizes this feature is provided with the Papercut installation and can be found at [install-path]/server/bin/linux-i686/src/.

Custom user program

Below are the different calls PaperCut will make to a configured custom user program as well as the valid and expected inputs and output.

Is-Valid

Program Call [CustomUserProgram] is-valid
Example Program Call MyCustomUserProgram.exe is-valid
Standard-input

N/A

Standard-output
  • Y\n when valid.
  • Or; N\n when invalid.
Trigger(s) This is called on application server start, or setting page access and is used to validate that the custom provider is functional and working as expected. An example maybe to say check that the directory source is reachable. Most custom implementations will simply return "Y".

All-Users

Program Call [CustomUserProgram] all-users
Example Program Call MyCustomUserProgram.exe all-users
Standard-input

N/A

Standard-output
  • username\tfullName\temailAddress\tdepartment\toffice\tcardNumber\n for each user.
  • Or; Error: [string] in the event of an error. TODO
Trigger(s) The command is called when PaperCut needs to list all system users. For example during a full network wide group sync. It many be called manually on system administrator instigated sync, or overnight as part of the automated sync.

All-Groups

Program Call [CustomUserProgram] all-groups
Example Program Call MyCustomUserProgram.exe all-groups
Standard-input
  • N/A
Standard-output
  • groupName\n for each group.
  • Or; Error: [string] in the event of an error. TODO
Trigger(s) TODO

Get-User-Details

Program Call [CustomUserProgram] get-user-details
Example Program Call MyCustomUserProgram.exe get-user-details
Standard-input
  • Single username\n
Standard-output
  • username\tfullName\temailAddress\tdepartment\toffice\tcardNumber\n for standard-input specified username.
  • Or; Error: [string] in the event of an error. TODO
Trigger(s) TODO

Group-Member-Names

Program Call [CustomUserProgram] group-member-names [groupName]
Example Program Call MyCustomUserProgram.exe group-member-names "Engineering"
Standard-input
  • N/A
Standard-output
  • username\t\t\n for each username belonging to the group. TODO
  • Or; Error: [string] in the event of an error. TODO
Trigger(s) TODO

Group-Members

Program Call [CustomUserProgram] group-members [groupName]
Example Program Call MyCustomUserProgram.exe group-members "Engineering"
Standard-input
  • N/A
Standard-output
  • username\t\t\n for each username belonging to the group. TODO
  • Or; Error: [string] in the event of an error. TODO
Trigger(s) TODO

Is-User-In-Group

Program Call [CustomUserProgram] is-user-in-group [groupName] [username]
Example Program Call MyCustomUserProgram.exe is-user-in-group "Engineering" "bobsmith"
Standard-input
  • N/A
Standard-output
  • Y\n when valid.
  • Or; N\n when invalid.
  • Or; Error: [string] in the event of an error. TODO
Trigger(s) TODO

Custom auth program

Below is a table containing the different calls Papercut will make to a configured Custom auth program as well as the valid and expected inputs and output.

Program Call
  • [CustomAuthProgram]
  • Or; to enable debugging [CustomAuthProgram] d
Example Program Call MyCustomAuthProgram.exe
Standard-input
  • username\nplaintextPassword
Standard-output
  • OK\n when authentication is successful.
  • Or; ERROR\n in the event of an error, such as authentication failure. TODO
Trigger(s) Program is called with provided standard-input only when authentication of a user is required. TODO:(Debug mode?)