The XML Web Services API
Any quality software product comes with a comprehensive APIApplication Programming Interface (API) is a set of routines, protocols, and tools for building software and applications. An API expresses a software component in terms of its operations, inputs, outputs, and underlying types, defining functionalities that are independent of their respective implementations, which allows definitions and implementations to vary without compromising the interface. 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 servicesWeb services are a standardized way of integrating Web-based applications using the XML, SOAP, WSDL and UDDI open standards over an Internet protocol backbone. 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, or https://[server_name]:9192/rpc/api/xmlrpc for secure connections. Ensure you are making your API call from an authorized address. More information on API usage is provided below.
| Method | Description |
|---|---|
| api.isUserExists | Test to see if a user exists in the system/database. |
| api.getUserAccountBalance | Get the user's current account balance. |
| api.getUserProperty | Gets a user property. Properties include the user's full name, department, email, home folder, notes, office and restriction status among others. |
| 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. |
| 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. |
| api.setUserProperties | Set multiple user properties at once. Properties include the user's full name, department, email, home folder, notes, office, password (for internal users) and restriction status among others. |
| 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). |
| api.adjustUserAccountBalanceIfAvailable | Adjust a user's account balance if there is enough credit available. |
| api.adjustUserAccountBalanceIfAvailableLeaveRemaining | Adjust a user's account balance if there is enough credit available to leave the given amount available in the account. |
| api.adjustUserAccountBalanceByGroup | Adjust the account balance for all users in a group by an adjustment amount. An adjustment can be positive (add to the user's account) or negative (subtract from the account). |
| api.adjustUserAccountBalanceByGroupUpTo | Adjust the account balance for all users in a group by an adjustment amount, but not above the given limit. An adjustment can be positive (add to the user's account) or negative (subtract from the account). |
| api.setUserAccountBalance | Set the balance on a user's account to a set value. This is conducted as a transaction. |
| api.setUserAccountBalanceByGroup | Set the balance for each member of a group to the given value. |
| api.setUserOverdraftMode | Set a restricted user's overdraft mode to either “DEFAULT” (same amount is applied to all users) or “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 is applied to all users) or “INDIVIDUAL” (the user has their own individual overdraft amount). |
| api.resetUserCounts | Reset the counts (pages and job counts) associated with a user account. |
| api.reapplyInitialUserSettings | Re-applies initial settings on the user. Initial user settings are based on group membership. |
| api.disablePrintingForUser | Disable printing for a user for selected period of time. |
| 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. |
| 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 uses the new username. |
| api.getUserGroups | Retrieves all groups a single user is a member of. |
| 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 records remain). 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 (user name, account, document name, document size, client machine, comments, digital signatureDigital signatures allow you to include metadata, such as the origin, author, time of print, and other details of print jobs, on print jobs (usually the footer). This helps organizations track documents and encourages employees to be responsible with sensitive information. Digital signatures use either a cryptographically secure HMAC or a Bates number.). |
| api.exportUserDataHistory | To comply with the EU General Data Protection Regulation (GDPR) Right to Access, export user data from reports into CSV files. Note: The files will be owned by the system account running the PaperCut NG/MF process. The output folder must also have write permissions for this user. |
| api.addNewInternalUser |
Creates and sets up a new internal user accountInternal users are user accounts that exist only inside PaperCut and are independent of the domain, network, or operating system. Internal user accounts can be self-registered, manually managed, or for non-domain Windows workgroups.
Self-registered accounts are created by the user. These are suitable when there are a large number of guest users, for example, a public library. Manually managed accounts are created by the PaperCut administrator. These are suitable when there are only a small number of guest accounts and the administrator wants to control these accounts. Suitable in an environment with a small number of guests..
In PaperCut NG/MF all internal usernames must contain only characters that can be printed
(e.g. not |
| 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. |
| 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. |
| api.addAdminAccessUser | Add a user as an admin with default admin rights. |
| api.removeAdminAccessUser | Remove an admin user from the list of admins. |
| api.addAdminAccessGroup | Add a group as an admin group with default admin rights. |
| api.removeAdminAccessGroup | Remove a group from the list of admin groups. |
| api.setUserAccountSelectionAutoSelectSharedAccount | Sets a user's account selection to charge to a single shared accountA shared account is an account that is shared by multiple users. For example, in business, shared accounts can be used to track printing costs by business unit, project, or client. Organizations like legal firms, engineering firms, or accounting offices often have long lists of accounts, projects, clients, or matters. In a school or university, shared accounts can be used to track printing by departments, classes, or subjects.. |
| api.setUserAccountSelectionAutoChargePersonal | Sets a user's account selection to automatically charge to personal account. |
| api.setUserAccountSelectionStandardPopup | Sets a user's account selection to standard account selection popupThe standard account selection popup is a mode for the account selection popup that provides the basic features required to charge to shared accounts. It is ideal for sites with a small number of accounts.. |
| 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.
E.g.:
listUserAccounts("authToken", 0, 1000) - returns users 0 through 999 listUserAccounts("authToken", 1000, 1000) - returns users 1000 through 1999 listUserAccounts("authToken", 2000, 1000) - returns users 2000 through 2999 |
| api.getTotalUsers | Gets a count of all the users in the system. |
| 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.
E.g.:
listSharedAccounts("authToken", 0, 1000) - returns shared accounts 0 through 999 listSharedAccounts("authToken", 1000, 1000) - returns shared accounts 1000 through 1999 listSharedAccounts("authToken", 2000, 1000) - returns shared accounts 2000 through 2999 |
| 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.
E.g.:
listUserSharedAccounts("authToken", "username", 0, 1000) - returns shared accounts 0 through 999 listUserSharedAccounts("authToken", "username", 1000, 1000) - returns shared accounts 1000 through 1999 listUserSharedAccounts("authToken", "username", 2000, 1000) - returns shared accounts 2000 through 2999 listUserSharedAccounts("authToken", "username", 0, 1000, TRUE) - returns shared accounts 0 through 999 even if "username" is not configured to charge to a shared account. |
| api.isSharedAccountExists | Test to see if a shared account exists in the system/database. |
| api.setSharedAccountAccountBalance | Sets a shared account's current account balance. |
| api.getSharedAccountAccountBalance | Gets a shared account's current account balance. |
| api.setSharedAccountProperty | Sets a shared account property. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others. |
| 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. |
| api.getSharedAccountProperty | Gets a shared account property. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others. |
| 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. |
| 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). |
| api.setSharedAccountAccountBalance | Set the balance on a shared account to a set value. This is conducted as a transaction. |
| api.setSharedAccountOverdraftMode | Set a shared account's overdraft mode to either “DEFAULT” (same amount is applied to all users) or “INDIVIDUAL” (the user has their own individual overdraft amount). |
| api.getSharedAccountOverdraftMode | Get a shared account's overdraft mode. This mode can be either “DEFAULT” (same amount is applied to all users) or “INDIVIDUAL” (the user has their own individual overdraft amount). |
| api.addNewSharedAccount | Create a new shared account with the given name. |
| 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). |
| api.addSharedAccountAccessUser | Allow the given user access to the given shared account without using a pin. |
| api.renameSharedAccount | Rename an existing shared account. |
| api.deleteExistingSharedAccount | Delete a shared account from the system. Use this method with care. Calling this permanently deletes it from the shared account list. |
| api.addSharedAccountAccessGroup | Allow the given group access to the given shared account without using a pin. |
| api.removeSharedAccountAccessUser | Revoke the given user's access to the given shared account. |
| api.removeSharedAccountAccessGroup | Revoke the given group's access to the given shared account. |
| api.disableSharedAccount | Disables a shared account for a selected period of time. |
| api.getPrinterProperty | Gets a printer property. |
| api.setPrinterProperty | Sets a printer property. |
| 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.
E.g.:
listPrinters("authToken", 0, 1000) - returns printers 0 through 999 listPrinters("authToken", 1000, 1000) - returns printers 1000 through 1999 listPrinters("authToken", 2000, 1000) - returns printers 2000 through 2999 |
| api.setPrinterCostSimple | Set a page cost using the Simple Charging Model. |
| api.getPrinterCostSimple | Get the page cost if, and only if, the printer is using the Simple Charging Model. |
| api.resetPrinterCounts | Reset the counts (pages and job counts) associated with a printer. |
| api.addPrinterGroup | Add a printer to a single printer groupPrinter groups allow administrators to tag or group printers by attributes. Group names are user definable and can represent any attribute appropriate for printer management. For example, you can group printers by printer type, location, make, function, owner, age, and so on. You can report by printer group and also send notifications per printer group.. |
| api.setPrinterGroups | Set the printer groups a printer belongs to, overwriting any existing group. |
| api.enablePrinter | Enables a printer. |
| api.disablePrinter | Disable a printer for select period of time. |
| api.deletePrinter | Delete a printer. Use the special text "[All Printers]" to delete all printers on the specified server. |
| api.renamePrinter | Rename a printer. This is useful after migrating a print queueA print queue displays information about documents that are waiting to be printed, such as the printing status, document owner, and number of pages to print. You can use the print queue to view, pause, resume, restart, and cancel print jobs. or print serverA print server is a system responsible for hosting print queues and sharing printer resources to desktops. Users submit print jobs to a print server rather then directly to the printer itself. A print server can be a dedicated server but on many networks this server also performs other tasks, such as file serving (i.e. 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. |
| api.addPrinterAccessGroup | Add a user group to the printer's access group list. |
| api.removePrinterAccessGroup | Remove a user group from the printer's access group list. |
| api.addNewGroup | Add a new group to system's group list. |
| api.RemoveGroup | Remove a group. |
| 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.
E.g.:
listUserGroups("authToken", 0, 1000) - returns groups 0 through 999 listUserGroups("authToken", 1000, 1000) - returns groups 1000 through 1999 listUserGroups("authToken", 2000, 1000) - returns groups 2000 through 2999 |
| api.isGroupExists | Test to see if a group exists in the system. |
| api.addUserToGroup | Adds a user to a specified group. Changes the group membership within the application, not in the OS/Network/Domain user directory. |
| api.removeUserFromGroup | Removes a user from a specified group. Changes the group membership within the application, not in the OS/Network/Domain user directory. |
| api.setGroupQuota | Set the group quota allocation settings on a given group. |
| api.getGroupQuota | Get the group quota allocation settings on a given group. |
| api.useCard | Redeem a card and place the credit on the user's account. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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 be performed only if new users are actually added to the system. |
| api.getTaskStatus | Return the status (completed flag and a status message) associated with a backgrounded task such as a sync operation started by the performGroupSync API. This method returns a struct (hashtable/map) containing elements with keys completed and message. You can poll 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). |
| api.batchImportUsers |
Import the users contained in the given tab-delimited import file (located on the server). See Batch import and update user data for a description of the file format. |
| 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. |
| api.batchImportUserCardIdNumbers | Import the user card/ID numbers and PINs contained in the given tab-delimited import file. |
| api.createUserClientAccountsFile | Saves a file containing shared accounts data for the User ClientThe User Client tool is an add-on that resides on a user's desktop. It allows users to view their current account balance via a popup window, provides users with the opportunity to confirm what they are about to print, allows users to select shared accounts via a popup, if administrators have granted access to this feature, and displays system messages, such as the "low credit" warning message or print policy popups.. 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. |
| api.getConfigValue | Gets the value of a configuration settings. |
| api.setConfigValue | Sets the value of a configuration setting. NOTE: Take care updating config values. You can cause serious problems which can only be fixed by reinstallation of the application. Use the setConfigValue API at your own risk. |
| 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 filtersFilters allow you to control attributes of the print settings by either forcing a particular attribute or denying a a print job that does not meet specific criteria. There are two types of print filters: conversions and restrictions., popups, hold/release queues etc., they are only logged. See the user manual section "Importing Print Job Details" for more information and the format. |
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.
-
All the XML Web Services commands are also accessible via the server-command program. An alternative to using a full programming environment to automate PaperCut NG/MF via Web Services is to use the server-command program to call the commands via a script such as a batch file or shell script. This is a simpler solution for common automation tasks such as scheduling a User/Group synchronization each night. For more information on the server-command program, see Server commands (server-command).
-
Programmers often report that they get an error message "ERROR: java.lang.NoSuchMethodException:" and this is frequently because they are calling the API method with the wrong number or type of parameters. Consult the Javadoc API documentation (see above) for information on what parameters to use.
Security
The Web Services API's 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 API's. By default, this is restricted to localhost (127.0.0.1) only. If the program/script making use of the API's 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).
You should 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:
-
Click the Options tab. The General page is displayed.
-
In the Actions menu, click Config editor (advanced).
The Config EditorThe Config Editor stores information used by PaperCut to configure advanced options and functions. This information is stored in config keys, which are editable by an administrator. page is displayed.
-
Find the auth.webservices.auth-token config keyA config key stores information about a specific advanced setting in PaperCut. Config keys are editable by an administrator in the Config Editor..
-
In Value, enter the new Web Services authentication token. See below for the supported formats.
-
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. T 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 Apoplication 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.