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 is no exception! Our industry standard Web Services API allows you to integrate with PaperCut with a programming language of your choice. Web Services data is transmitted over standard HTTP or HTTPS and uses standardized XML mark-up.

There are two main Web Services implementations used for Remote Procedure Call (RPC):

  • SOAP/WSDL

  • XML-RPC

PaperCut NG uses XML-RPC. 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.

Table 98: 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.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).
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 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 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.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. Available properties include: disabled, print-stats.job-count, print-stats.page-count.
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 user data import and update 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 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.

Tip:
  • 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 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 must be secured. PaperCut NG secures access using two security layers:

  1. IP address level security

  2. Authentication tokens - required for each method call

The IP address level security is used to control which systems, denoted by IP address, 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). In the default setup the authentication token is the built-in admin user's password (This is password defined for the SysAdmin during the initial configuration wizard). Optionally, you can define an alternative web service authentication token via configuration (see below). This token must be supplied with all method calls.

You can specify an alternative web service authentication token to avoid using/sharing the built-in admin user's password:

  1. Click the Options tab.

    The General page is displayed.

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

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

  4. Enter a new value that is the new web services authentication token.

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

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