Skip to content

Choose your language

  • No results

Choose your login

  • No results
Support
Search

The XML Web Services API

This page applies to:

Any quality software product comes with a comprehensive API for deep integration, and PaperCut NG/MF is no exception! Our industry standard Web Services API allows you to integrate with PaperCut NG/MF with a programming language of your choice. Web Services data is transmitted over standard HTTP or HTTPS and uses standardized XML mark-up.

Our Web Services API uses XML-RPC (Remote Procedure Call). XML-RPC is a lightweight web services implementation and has good support for all major programming and scripting languages such as C#, Java, Visual Basic, Perl, Ruby and Python.

API methods are accessed by the URL:

  • http://[server_name]:9191/rpc/api/xmlrpc - HTTP
  • https://[server_name]:9192/rpc/api/xmlrpc - HTTPS
  • https://[server_name]:9195/rpc/api/xmlrpc - HTTPS

Ensure you are making your API call from an authorized address. More information on API usage is provided below .

In the following table, parameters are provided with their respective data type (string, int, double, boolean, etc), followed by their valid inputs in square brackets (for example [0,1], or [‘default’,‘individual’]). Most XML-RPC parameters will need a data type included in the XML formatting (see included examples). When forming commands, the auth token should always be the first parameter passed in your command. Arguments supplied in the table below are to be included after the auth token unless otherwise specified.

XML METHOD

Inputs*

Notes/Outputs

api.isUserExists

Test to see if a user exists in the system/database.

Input(s):
Username - string
Output(s):
Boolean (1 if exists)

Example

api.getUserAccountBalance

Get the user’s current account balance.

Input(s):
Username - string
Account name - string (optional, defaults to primary)
Output(s):
double

api.getUserProperty

Gets a user property. Properties include the user’s full name, department, email, home folder, notes, office, and restriction status among others.

Input(s):
Username - string
Property name - string, see Example for valid property names
Output(s):
value

Example

api.getUserProperties

Get multiple user properties at once. Properties include the user’s full name, department, email, home folder, notes, office, and restriction status among others.

Input(s):
Username - string
Array of property names - array of strings see ‘getUserProperty’ example for list of valid properties
Output(s):
array of values

Example

api.setUserProperty

Sets a user property. Properties include the user’s full name, department, email, home folder, notes,office, password (for internal users), and restriction status among others.

Input(s):
Username - string
Property name - string
Property value - string
Output(s):
boolean (1 if success)

Example

api.setUserProperties

Set multiple user properties at once. Properties include the user’s full name, department, email, homefolder, notes, office, password (for internal users), and restriction status among others. See ‘setUserProperty’ example for list of valid properties

Input(s):
Username - string
Array of arrays
Arrays In each nested array: Property name - string
Property value - string
Output(s):
boolean (1 if success)

Example

api.adjustUserAccountBalance

Adjust a user’s account balance by an adjustment amount. An adjustment can be positive (add to the user’s account) or negative (subtract from the account).

Input(s):
Username - string
Adjustment - double (+/-) Comment - string
Account name - string
Output(s):
boolean (1 if success)

api.adjustUserAccountBalanceIfAvailable

Adjust a user’s account balance if there is enough credit available.

Input(s):
Username - string
Adjustment - double (+/-) Comment - string
Account name - string
Output(s):
boolean (1 if success)

api.adjustUserAccountBalanceIfAvailableLeaveRemaining

Adjust a user’s account balance if there is enough credit available to leave the given amount availablein the account.

Input(s):
Username - string
Adjustment - double (+/-) Leave remaining - double (+/-) Comment - string
Account name - string
Output(s):
boolean (1 if success)

api.adjustUserAccountBalanceByGroup

Adjust the account balance for all users in a group by an adjustment amount. An adjustment can bepositive (add to the user’s account) or negative (subtract from the account).

Input(s):
Group name - string
Adjustment - double (+/-) Comment - string
Account name - string
Output(s):
boolean (1 if success)

api.adjustUserAccountBalanceByGroupUpTo

Adjust the account balance for all users in a group by an adjustment amount, but not above the givenlimit. An adjustment can be positive (add to the user’s account) or negative (subtract from theaccount).

Input(s):
Group name - string
Adjustment - double (+/-) Limit - double (+/-) Comment - string
Account name - string
Output(s):
boolean (1 if success)

api.setUserAccountBalance

Set the balance on a user’s account to a set value. This is conducted as a transaction.

Input(s):
Username - string
Balance - double (+/-) Comment - string
Account name - string
Output(s):
boolean (1 if success)

api.setUserAccountBalanceByGroup

Set the balance for each member of a group to the given value.

Input(s):
Group name - string
Balance - double (+/-) Comment - string
Account name - string
Output(s):
*boolean (1 if success)

api.setUserOverdraftMode

Set a restricted user’s overdraft mode.

Input(s):
Username - string
Mode - string [‘default’,‘individual’]
Output(s):
boolean (1 if success)
Note: Input ‘DEFAULT’ - same amount is applied to all users.
Input ‘INDIVIDUAL’ - the user has their own individual overdraft amount.

api.getUserOverdraftMode

Get a restricted user’s overdraft mode. The mode can be either ‘DEFAULT’ (same amount isapplied to all users) or ‘INDIVIDUAL’ (the user has their own individual overdraft amount).

Input(s):
Username - string
Output(s):
‘default’, ‘individual’

api.resetUserCounts

Reset the counts (pages and job counts) associated with a user account. Can include the name of theuser/script/process resetting the counts.

Input(s):
Username - string
Reset by - string
Output(s):
boolean (1 if success)

api.reapplyInitialUserSettings

Re-applies initial settings on the user. Initial user settings are based on group membership.

Input(s):
Username - string
Output(s):
boolean ​​​​​​​(1 if success)

api.disablePrintingForUser

Disable printing for a user for selected period of time.

Input(s):
Username - string
Disable duration minutes - int
Output(s):
boolean (1 if success)

Example

api.addNewUser

Triggers the process of adding a new user account defined by a given username. Assuming the user exists in the OS/Network/Domain user directory, the account is created with the correct initial settings as defined by the rules set up in the Admin web interface on the Groups page. Calling this method is equivalent to triggering the ’new user’ event when a new user performs printing for the first time.

Input(s):
Username - string
Output(s):
boolean ​​​​​​​(1 if success)

api.renameUserAccount

Rename a user account. Useful when the user has been renamed in the domain/directory, so that usage history can be maintained for the new username. Perform this in conjunction with a rename of the user in the domain/user directory, as all future usage and authentication will use the new username.

Input(s):
Current Username - string
New Username - string
Output(s):
boolean ​​​​​​​(1 if success)

api.getUserGroups

Retrieves all groups a single user is a member of.

Input(s):
Username - string
Output(s):
array of values

api.getGroupMembers

Lists all members of a designated group. Can be used to enumerate all user groups in ‘pages’. When retrieving a list of all user groups, the recommended page size/limit is 1000. Batching in groups of 1000 ensures efficient transfer and processing.

Input(s):
Group Name - string
Offset/starting user index - int
Limit/batch size - int
Output(s):
array of values

Example

api.deleteExistingUser

Delete/remove an existing user from the user list. Use this method with care. Calling this permanently deletes the user account from the user list (print and transaction history recordsremain).

Input(s):
Username - string
Redact user data - boolean [0,1]
Output(s):
boolean (1 if success)
Note: To comply with the EU General Data Protection Regulation (GDPR) Right to be Forgotten, the permanently-redact-user-data flag permanently removes (redacts) identifiable user information (username, account, document name, document size, client machine, comments, digital signature)

api.exportUserDataHistory

To comply with the EU General Data Protection Regulation (GDPR) Right to Access, export user data fromreports into CSV files.

Input(s):
Username - string
Save location - string [filepath formatted for PaperCut HostOS]
Output(s):
boolean (1 if success)
Note: The files will be owned by the system account running the PaperCut NG/MF process. The output foldermust also have write permissions for this user

api.addNewInternalUser

Creates and sets up a new internal user account.

Input(s):
Username - string
Password - string
Full name - string
Email - string
Card ID - string
PIN - string
Send email? - boolean [0,1]
Output(s):
boolean (1 if success)
Note: In PaperCut NG/MF all internal usernames must contain only characters that can be printed (e.g. notnewline) and must not contain /, \ or @.

api.lookUpUserNameByIDNo

Looks up the user with the given user id number and returns their user name. If no match was found an empty string is returned.

Input(s):
ID ’number’ - string
Output(s):
string (empty if no match)

api.lookUpUserNameByCardNo

Looks up the user with the given user card number and returns their user name. If no match was found an empty string is returned.

Input(s):
Card ’number’ - string
Output(s):
string (empty if no match)

api.addAdminAccessUser

Add a user as an admin with default admin rights.

Input(s):
Username - string
Output(s):
boolean ​​​​​​​(1 if success)

api.removeAdminAccessUser

Remove an admin user from the list of admins.

Input(s):
Username - string
Output(s):
boolean ​​​​​​​(1 if success)

api.addAdminAccessGroup

Add a group as an admin group with default admin rights.

Input(s):
Group name - string
Output(s):
boolean ​​​​​​​(1 if success)

api.removeAdminAccessGroup

Remove a group from the list of admin groups.

Input(s):
Group name - ​​​​​​ string
Output(s):
boolean ​​​​​​​(1 if success)

api.setUserAccountSelectionAutoSelectSharedAccount

Sets a user’s account selection to charge to a single shared account.

Input(s):
Username - string
Shared Account name - string
Charge to personal account? - boolean
Output(s):
boolean (1 if success)

api.setUserAccountSelectionAutoChargePersonal

Sets a user’s account selection to automatically charge to personal account.

Input(s):
Username - string
Use popup confirmation? - boolean [0,1]
Output(s):
boolean (1 if success)

api.setUserAccountSelectionStandardPopup

Sets a user’s account selection to standard account selection popup.

Input(s):
Username - string
Allow personal account? - boolean [0,1]
Allow list selection? - boolean [0,1]
Allow PIN code? - boolean [0,1]
Allow Printing as other user? - boolean [0,1]
Charge to personal when shared accountselected? - boolean [0,1]
Output(s):
boolean (1 if success)

Example

api.listUserAccounts

List all user accounts (sorted by username) starting at offset and ending at limit. Use this to enumerate all user accounts in pages. When retrieving a list of all user accounts, the recommended page size/limit is 1000. Batching in groups of 1000 ensures efficient transfer and processing.

Input(s):
Offset/starting user - int
Limit/batch size - int
Output(s):
array of values

Example

api.getTotalUsers

Gets a count of all the users in the system.

Input(s):
No additional inputs (token only)
Output(s):
int

api.listSharedAccounts

List all shared accounts (sorted by account name) starting at offset and ending at limit. Use this to enumerate all shared accounts in pages. When retrieving a list of all accounts, the recommended page size / limit is 1000. Batching in groups of 1000 ensures efficient transfer and processing.

Input(s):
Offset/starting account - int
Limit/batch size - int
Output(s):
array of values (child accounts will begin with the parent account name, followed by a \ mark)

Example

api.listUserSharedAccounts

List all shared accounts the user has access to (sorted by account name), starting at offset and ending at limit. Use this to enumerate the accounts in pages. When retrieving a list of all accounts, the recommended page size/limit is 1000. Batching in groups of 1000 ensures efficient transfer and processing. You can optionally specify TRUE to list accounts even if the user is currently not configured to charge to a shared account.

Input(s):
Username - string
Offset/starting account - int
Limit/batch size - int
Ignore user account selection config - boolean [0,1](optional)
Output(s):
array of values

Example

api.isSharedAccountExists

Test to see if a shared account exists in the system/database.

Input(s):
Shared account name - string
Output(s):
boolean ​​​​​​​(1 if exists)

api.setSharedAccountAccountBalance

Sets a shared account’s current account balance.

Input(s):
Shared account name - string
Balance - double (+/-)
Comment - string
Output(s):
boolean ​​​​​​​(1 if success)

api.getSharedAccountAccountBalance

Gets a shared account’s current account balance.

Input(s):
Shared account name - string
Output(s):
double

api.getSharedAccountProperty

Gets a shared account property. Properties include access groups, balance, comment options, disabledstatus, notes, pin, and restriction status among others.

Input(s):
Shared account name - string Shared account Property name - string See Example for valid property names.
Output(s):
boolean ​​​​​​​(1 if success)

Example

api.setSharedAccountProperty

Sets a shared account property. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others.

Input(s):
Shared account name - string
Property name - string See ‘getSharedAccountProperty’ example for list of valid properties
Property value - string
Output(s):
boolean ​​​​​​​(1 if success)

api.setSharedAccountProperties

Sets multiple shared account properties at once. Properties include access groups, balance, comment options, disabled status, notes, pin, and restriction status among others.

Input(s):
Shared account name - string Array of arrays
Arrays In each nested array:
Shared account Property name - string
Property value - string
See ‘getSharedAccountProperty’ example for list of valid properties
Output(s):
boolean ​​​​​​​(1 if success)

api.getSharedAccountProperties

Gets multiple shared account properties at once. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others.

Input(s):
Shared account name - string
Array of shared account property names - Array of strings
Output(s):
array of values

Example

api.adjustSharedAccountAccountBalance

Adjust a shared account’s account balance by an adjustment amount. An adjustment can be positive (add to the account) or negative (subtract from the account).

Input(s):
Shared account name - string
Adjustment - double (+/-) Comment - string
Output(s):
boolean ​​​​​​​(1 if success)

api.setSharedAccountAccountBalance

Set the balance on a shared account to a set value. This is conducted as a transaction.

Input(s):
Shared account name - string
Balance - double
Comment - string
Output(s):
boolean (1 if success)

api.setSharedAccountOverdraftMode

Set a shared account’s overdraft mode to either Default or Individual

Input(s):
Shared account name - string
Mode - string [‘default’,‘individual’]
Output(s):
boolean (1 if success)
Note: Input ‘DEFAULT’ - same amount is applied to all users.
Input ‘INDIVIDUAL’ - the user has their own individual overdraft amount.

api.getSharedAccountOverdraftMode

Get a shared account’s overdraft mode configuration

Input(s):
Shared account name - string
Output(s):
‘default’, ‘individual’
Note: Output ‘DEFAULT’ - same amount is applied to all users.
Output ‘INDIVIDUAL’ - the user has their own individual overdraft amount.

api.addNewSharedAccount

Create a new shared account with the given name.

Input(s):
Shared account name - string
Output(s):
boolean (1 if success)

api.deleteExistingSharedAccount

Delete a shared account from the system. Use this method with care. Deleting a shared account permanently deletes it from the shared account list (print history records remain).

Input(s):
Shared account name - string
Output(s):
boolean (1 if success)

api.addSharedAccountAccessUser

Allow the given user access to the given shared account without using a pin.

Input(s):
Shared account name - string
Username to add - string
Output(s):
boolean (1 if success)

api.renameSharedAccount

Rename an existing shared account.

Input(s):
Current Shared account name - string
New shared account name - string
Output(s):
boolean (1 if success)

api.deleteExistingSharedAccount

Delete a shared account from the system. Use this method with care. Calling this permanently deletes itfrom the shared account list.

Input(s):
Shared account name - string
Output(s):
boolean (1 if success)

api.addSharedAccountAccessGroup

Allow the given group access to the given shared account without using a pin.

Input(s):
Shared account name - string
Group name - string
Output(s):
boolean (1 if success)

api.removeSharedAccountAccessUser

Revoke the given user’s access to the given shared account.

Input(s):
Shared account name - string
Username to remove - string
Output(s):
boolean (1 if success)

api.removeSharedAccountAccessGroup

Revoke the given group’s access to the given shared account.

Input(s):
Shared account name - string
Group name - string
Output(s):
boolean (1 if success)

api.disableSharedAccount

Disables a shared account for a selected period of time.

Input(s):
Shared account name - string
Disable duration minutes - int
Output(s):
boolean (1 if success)

api.getPrinterProperty

Gets a printer property.

Input(s):
Server name - string
Printer name - string
Property name - string
Output(s):
value

api.setPrinterProperty

Sets a printer property.

Input(s):
Server name - string
Printer name - string
Property name - string
Property value - string
Output(s):
boolean (1 if success)

api.listPrinters

List all printers (sorted by printer name), starting at offset and ending at limit. Use this to enumerate the printers in pages. When retrieving a list of all printers, the recommended page size/limit is 1000. Batching in groups of 1000 ensures efficient transfer and processing.

Input(s):
Offset/starting printer - int
Limit/batch size - int
Output(s):
array of values (ServerName\PrinterName

Example

api.setPrinterCostSimple

Set a page cost using the Simple Charging Model.

Input(s):
Server name - string
Printer name - string
Cost per page - double
Output(s):
boolean (1 if success)

api.getPrinterCostSimple

Get the page cost if, and only if, the printer is using the Simple Charging Model.

Input(s):
Server name - string
Printer name - string
Output(s):
double (if configured to simple charging)
Fault code 292 (if configured to other charging method)

api.resetPrinterCounts

Reset the counts (pages and job counts) associated with a printer. Can include the name of theuser/script/process resetting the counts.

Input(s):
Server name - string
Printer name - string
Reset by - string
Output(s):
boolean (1 if success)

api.addPrinterGroup

Add a printer to a single printer group.

Input(s):
Server name - string
Printer name - string
Printer Group name - string
Output(s):
boolean (1 if success)

api.setPrinterGroups

Set the printer groups a printer belongs to, overwriting any existing group.

Input(s):
Server name - string
Printer name - string
Printer group names - string [comma-separated list ofprinter groups]
Output(s):
boolean (1 if success)

api.enablePrinter

Enables a printer.

Input(s):
Server name - string
Printer name - string
Disable duration minutes - int
Output(s):
boolean (1 if success)

api.disablePrinter

Disable a printer for select period of time.

Input(s):
Server name - string
Printer name - string
Disable duration minutes - int
Output(s):
boolean (1 if success)

api.deletePrinter

Delete a printer. Use the special text ‘[All Printers]’ to delete all printers on the specified server.

Input(s):
Server name - string
Printer name - string
Output(s):
boolean (1 if success)

api.renamePrinter

Rename a printer. This is useful after migrating a print queue or print server (that is, the printer retains its history and settings under the new name). Note that in some cases case sensitivity is important, so take care to enter the name exactly as it is displayed in the OS.

Input(s):
Current server name - string
Current printer name - string
New Server name - string
New printer name - string
Output(s):
boolean (1 if success)

api.addPrinterAccessGroup

Add a user group to the printer’s access group list.

Input(s):
Server name - string
Printer name - string
User Group name - string
Output(s):
boolean (1 if success)

api.removePrinterAccessGroup

Remove a user group from the printer’s access group list.

Input(s):
Server name - string
Printer name - string
User Group name - string
Output(s):
boolean (1 if success)

api.addNewGroup

Add a new group to system’s group list.

Input(s):
Group name - string
Output(s):
boolean (1 if success)

api.RemoveGroup

Remove a group.

Input(s):
Group name - string
Output(s):
boolean (1 if success)

api.listUserGroups

List all groups (sorted by group name), starting at offset and ending at limit. Use this to enumerate the groups in pages. When retrieving a list of all groups, the recommended page size / limit is 1000. Batching in groups of 1000 ensures efficient transfer and processing.

Input(s):
Offset/starting group - int
Limit/batch size - int
Output(s):
array of values

Example

api.isGroupExists

Test to see if a group exists in the system.

Input(s):
Group name - string
Output(s):
boolean (1 if exists)

api.addUserToGroup

Adds a user to a specified group. Changes the group membership within the application, not in the OS/Network/Domain user directory.

Input(s):
Username - string
Group name - string
Output(s):
boolean (1 if success)
Note: These changes will be overwritten during the next scheduled User/Group sync unless the membership is changed in the directory source.

api.removeUserFromGroup

Removes a user from a specified group. Changes the group membership within the application, not in the OS/Network/Domain user directory.

Input(s):
Username - string
Group name - string
Output(s):
boolean (1 if success)

api.setGroupQuota

Set the group quota allocation settings on a given group.

Input(s):
Group name - string
Quota amount - double
Interval - string [‘DAILY’, ‘WEEKLY’, ‘MONTHLY’, comma-separated value of custom dates]
Output(s):
boolean (1 if success)
Note: Example of comma separated list of dates (YYYY-MM-DD):2010-03-15,2010-08-20,-08-01,-*-0

api.getGroupQuota

Get the group quota allocation settings on a given group.

Input(s):
Group name - string
Output(s):
QuotaAmount,- double
QuotaMaxAccumulation- double
QuotaPeriod- (DAILY , WEEKLY, MONTHLY, CUSTOM)

Example

api.useCard

Redeem a pre-paid card and place the credit on the user’s account.

Input(s):
Username - string
Card number - string
Output(s):
boolean (1 if success)

api.performOnlineBackup

Instigate an online backup. This process is equivalent to clicking Manual Backup in the web-based Admin web interface. The data is exported into the server/data/backups directory as a timestamped, zipped XML file.

Input(s):
No additional inputs (token only)
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.performGroupSync

Start the process of synchronizing the system’s group membership with the OS/Network/Domain’s group membership. A call to this method starts the sync process and the operation completes in the background.

Input(s):
No additional inputs (token only)
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.performUserAndGroupSync

Start a full user and group synchronization. This is equivalent to clicking Synchronize Now in the Admin web interface. No existing users are removed. Whether or not full details for existing users are updated depends on the current user/group sync settings as defined in the Admin web interface. A call to this method starts the sync process and the operation completes in the background.

Input(s):
No additional inputs (token only)
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.performUserAndGroupSyncAdvanced

An advanced version of the user and group synchronization process providing control over the sync settings. A call to this method starts the sync process and the operation completes in the background.

Input(s):
Delete non-existent users? - boolean [0,1]
Update user details? - boolean [0,1]
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.addNewUsers

Calling this method starts a specialized user and group synchronization process optimized for tracking down and adding any new users who exist in the OS/Network/Domain user directory and not in the system. Any existing user accounts are not modified. A group synchronization is to be performed only if new users are actually added to the system.

Input(s):
No additional inputs (token only)
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.getTaskStatus

Return the status (completed flag and a status message) associated with a backgrounded task such as async operation started by the ‘performGroupSync’ API call.

Input(s):
No token required No parameters necessary
Output(s):
struct (hashtable/map) containing elements with keys completed and message. This method can be polled to determine if a sync has completed

api.batchImportSharedAccounts

Import the shared accounts contained in the given tab separated import file (located on the server).

Input(s):
Import file - string [filepath formatted for PaperCut HostOS]
Run as test? - boolean [0,1]
Delete shared accounts not in file? - boolean [0,1]
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.batchImportUsers

Import the users contained in the given tab-delimited import file (located on the server). See ‘Batch import and update user dat’ for a description of the file format.

Input(s):
Import file - string [filepath formatted for PaperCut HostOS]
Create new users? - boolean [0,1]
Email new users? - boolean [0,1]
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)
Note: If ‘Create new users’ is set ‘TRUE’, users will be created similarly to on-demand users (no credentials stored in PaperCut).
If ‘Create new users’ is set to ‘false’, process will only update existing users’ details (will be overwritten in next schedule User/Group sync)

api.batchImportInternalUsers

Import the internal users contained in the given tab-delimited import file (located on the server). See Batch internal user import and update for details of the required file format.

Input(s):
Import file - string [filepath formatted for PaperCut HostOS]
Overwrite existing passwords? - boolean [0,1]
Overwrite existing PINs? - boolean [0,1]
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.batchImportUserCardIdNumbers

Import the user card/ID numbers and PINs contained in the given tab-delimited import file.

Input(s):
Import file - string [filepath formatted for PaperCut HostOS]
Overwrite existing PINs? - boolean [0,1]
Output(s):
boolean (1 if successfully initiated, use ‘api.getTaskStatus’ for sync success/failure)

api.createUserClientAccountsFile

Saves a file containing shared accounts data for the User Client. See the manual for more information on how you can use this feature. The file is saved on the server to the location:[app-path]\server\data\client\client-accounts.dat
If this file already exists it is over-written.

Input(s):
No additional inputs (token only)
Output(s):
boolean (1 if success)

api.getConfigValue

Gets the value of a configuration settings.

Input(s):
Config name - string
Output(s):
value

api.setConfigValue

Sets the value of a configuration setting.
Take care updating config values. You can cause serious problems that can only be fixed by reinstalling the application. Use the setConfigValue API at your own risk.

Input(s):
Config name - string
Config value - string
Output(s):
boolean (1 if success)
Note: See ‘Config Editor (Advanced)’ in your PaperCut admin interface for reference of available config keys

api.processJob

Takes the details of a job and logs and charges as if it were a ‘real’ job. Jobs processed via this method are not susceptible to filters, popups, hold/release queues etc., they are only logged. See the user manual section ‘Importing Print Job Details’ for more information and the format.

Input(s):
Job details - string [comma-separated key=value pairs of job details]
Output(s):
boolean (1 if success)
Note: See example for full input. Note that these details are arbitrary - any username, any time, any document name, and any server/printer name will be valid! Check your spelling!

Example

*Inputs will always come after the auth token for your application. Pass your auth token as the first parameter in your request.

Web Services example code

The best way to demonstrate how to use the Web Services interface is using example code. PaperCut NG/MF ships with example code for Java, C#, Python and Ruby located in:

[app-path]/server/examples/webservices/


The C# and Java examples also include a full documented Proxy class - a proxy is a common program design pattern. The Proxy wraps and exposes the Web Services methods as standard methods. The setup and use of the underlying XML-RPC library is all handled in the proxy class meaning you can just focus on calling the methods.

See the README.txt files in the examples directories for more information. The Java example includes full JavaDoc style documentation under

[app-path]/server/examples/webservices/java/docs/api


Developers using other languages, such as Perl or Python need to use an XML-RPC library to call the methods directly. All methods are exposed via the URL http://[server_name]:9191/rpc/api/xmlrpc.

Security

The Web Services APIs provide full access to the system’s internals so they must be secured. PaperCut NG/MF secures access using two security layers:

  • IP address level security

  • Authentication tokens - required for each method call.

The IP address level security is used to control which systems, denoted by IP addresses, are allowed to connect to the server and call the APIs. By default, this is restricted to localhost (127.0.0.1) only. If the program/script making use of the APIs resides on another system, then add this system’s IP address to the list of approved addresses under Options > Advanced > Allowed XML Web Services callers.

The first argument to all method calls is an authentication token (authToken).

Define Web Services authentication tokens with the advanced configuration editor (see below). A valid token must be supplied with all method calls.

To configure a web service authentication:

  1. Click the Options tab. The General page is displayed.

  2. In the Actions menu, click Config editor (advanced).

    The Config Editor page is displayed.

  3. Find the auth.webservices.auth-token config key.

  4. In Value, enter the new Web Services authentication token. See below for the supported formats.

  5. Click Update to the right of Value to apply the change.

    This authentication token can now be used in addition to the built-in admin user’s password.

Auth tokens can be configured in three different formats

  • The most flexible, and recommended, approach is a JSON object that lists the name of the applications and the tokens they use. For example:

    {"payments":"Zuj0hiazoo5hahwa","userUpdate":"heitieGuacoh8zo6"}

    PaperCut NG/MF ignores the application names ("payments" and "userUpdate" in the above example) during validation. They are supported to help the PaperCut NG/MF administrator keep a record of which API applications are using the various tokens. A token value can be used by more than one application, but the application name must be unique. When an API call is made PaperCut NG/MF will record the application name in the server log for auditing purposes when debug is enabled. Debug can be enabled in the Application server logs via Options > Advanced.

  • If you don’t need to keep a record of which applications are using the various tokens, you can specify the tokens as a simple JSON array. For example:

    ["Zuj0hiazoo5hahwa","heitieGuacoh8zo6"]

  • The simplest option is to provide a single token as a string that is shared across all API applications. This feature is provided for backwards compatibility. For example:

    Zuj0hiazoo5hahwa

If you are using an external system to manage your API auth tokens, then these values can be managed from the PaperCut NG/MF server-command utility (or the Web Services API) via the set-config subcommand. For example:

From the Linux or macOS command line.

  ~papercut/server/bin/linux-x64/server-command set-config auth.webservices.auth-token \\ '\{"payments":"Zuj0hiazoo5hahwa","userUpdate":"heitieGuacoh8zo6"\}'

From the Windows Powershell command line:

  &'C:\\Program Files\\PaperCut MF\\server\\bin\\win\\server-command.exe' set-config auth.webservices.auth-token \` --% "\{""payments"":""Zuj0hiazoo5hahwa"",""userUpdate"":""heitieGuacoh8zo6""\}"

(Note: In the Powershell the last line cannot contain a line break.)

You can verify the contents with the get-config subcommand. Refer to the server-command documentation for more details.

If a Web Services authentication token (as described above) is not available, then you can use the built-in admin user’s password. This is the password defined for the SysAdmin during the initial configuration wizard).

Using the admin password could be a security risk if the password leaks. The admin password is also approximately ten time slower because the auth token requires additional processing on each call.

Comments