Find your dream job at PaperCut

Choose your language

Choose your login

Contact us

Help Center menu

PRODUCT MANUALS

PaperCut NG & PaperCut MF Manual

PRODUCTS FEATURED

The XML Web Services API

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, 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.

XML Web Services Methods
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 will use 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 signature).
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 account. 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.
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 account.
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 popup.
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. For example: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. For example: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. For example: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. For example: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 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 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.
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. For example: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 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.
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 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.

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 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:

  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. 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 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