The XML Web Services API

Over the past few years, Web Services has been one of the IT industry's "buzz words" - and rightly so! Web Services provide a standardized way to transfer data and call functions across different operating system, programming languages, and networks. Web Services data is transmitted over standard HTTP and uses standardized XML mark-up.

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

PaperCut NG uses XML-RPC. 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. The list of XML-RPC methods exposed by PaperCut NG at the URL http://[server_name]:9191/rpc/api/xmlrpc are summarized below:

MethodDescription

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, notes, office and restriction status among others.

api.setUserProperty

Sets a user property. Properties include the user's full name, department, email, 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 may 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 may 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 may 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 will be created with the correct initial settings as defined by the rules set up in the admin interface under the Group's section. 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. This should be performed in conjunction with a rename of the user in the domain / user directory, as all future usage and authentication will need to use the new username.

api.deleteExistingUser

Delete/remove an existing user from the user list. Use this method with care. Calling this will perminently delete the user account from the user list (print and transaction history records remain).

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.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. This can be used 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.listSharedAccounts

List all shared accounts (sorted by account name) starting at offset and ending at limit. This can be used 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 users 0 through 999
    listSharedAccounts("authToken", 1000, 1000) - 
    returns users 1000 through 1999
    listSharedAccounts("authToken", 2000, 1000) - 
    returns users 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. This can be used 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.

E.g.:

    listUserSharedAccounts("authToken", "username", 0, 1000) - 
    returns users 0 through 999
    listUserSharedAccounts("authToken", "username", 1000, 1000) - 
    returns users 1000 through 1999
    listUserSharedAccounts("authToken", "username", 2000, 1000) - 
    returns users 2000 through 2999
                                

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

Sets a shared account property. 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.adjustSharedAccountAccountBalance

Adjust a shared account's account balance by an adjustment amount. An adjustment may 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 will permanently delete it from the shared account list (print history records will remain).

api.addSharedAccountAccessUser

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

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

Gets a printer property. Available properties include: disabled, print-stats.job-count, print-stats.page-count.

api.setPrinterProperty

Sets a printer property.

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.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 can be useful after migrating a print queue or print server (i.e. the printer retains its history and settings under the new name). Note that in some cases case sensitivity is important, so care should be taken to enter the name exactly as it appears in the OS.

api.addNewGroup

Add a new group to system's group list.

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 pressing the manual backup button in the web based admin 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 will commence the sync process and the operation will complete in the background.

api.performUserAndGroupSync

Start a full user and group synchronization. This is equivalent to pressing the Synchronize Now button in the admin interface. No existing users will be removed. Whether or not full details for existing users will be updated depends on the current user/group sync settings as defined in the admin interface. A call to this method will commence the sync process and the operation will complete 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 will commence the sync process and the operation will complete in the background.

api.addNewUsers

Calling this method will start a specialized user and group synchronization process optimized for tracking down and adding any new users that exist in the OS/Network/Domain user directory and not in the system. Any existing user accounts will not be modified. A group synchronization will only be performed 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. This method may 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 the section called “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 the section called “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 this feature can be used. The file will be saved on the server to the location: [app-path]\server\data\client\client-accounts.dat

If this file already exists it will be 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 may 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, pop-ups, hold/release queues etc., they are simply logged. See the user manual section "Importing Print Job Details" for more information and the format.

Table A.1. XML Web Services Methods

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.

Please see the README.txt files in the examples directories for more information. The Java example includes full JavaDoc style documentation under examples/webservices/java/docs/api.

Developers using other languages such as Perl or Python will 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 may be a simpler solution for common automation tasks such as scheduling a User/Group synchronization each night.

More information on the server-command program can be found in the section called “Server Commands (server-command)”.

Security

The Web Services API's provide full access to the system's internals and hence need to 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 this system's IP address will need to be added to the list of approved addresses under OptionsGeneralAllowed 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 admin during the initial configuration wizard). Optionally an alternative web service authentication token may be defined via configuration - see below. This token must be supplied with all method calls.

To specify an alternative web service authentication token, to avoid the need to use/share the built-in admin user's password:

  1. Login to the system.

  2. Navigate to the Options section.

  3. Click on the Config editor link in the list of actions.

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

  5. Enter a new value that will be the new web services authentication token.

  6. Press the Update button to the right to apply the change.

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