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

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

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

Start the process of synchronizing the system's group membership with the OS/Network/Domain's group membership. The call to this method will start the synchronization process. The operation will commence and complete in the background.

api.performUserAndGroupSync

Start a full user and group synchronization. This is equivalent to pressing on the "Synchronize Now" button in the admin user interface. The behavior of the sync process, such as deleting old users, is determined by the current system 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 behavior. A call to this method will commence the sync process and the operation will complete in the background.

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

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

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

Get the user's current account balance.

api.getUserPrintStatsJobCount

Get the user's current printing statistics job count as an integer.

api.getUserPrintStatsPageCount

Get the user's current printing statistics page count as an integer.

api.disablePrintingForUser

Disable printing for a user for selected period of time.

api.enablePrintingForUser

Enable printing for a user with printing disabled.

api.setUserRestriction

Set a user's restriction status. (Restricted or Unrestricted)

api.addNewSharedAccount

Create a new shared account with the given name.

api.isSharedAccountExists

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

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

The current account balance associated with a shared account.

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

Set the restriction status on a shared account.

api.addSharedAccountAccessUser

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

api.removeSharedAccountAccessUser

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

api.setSharedAccountAccessUsers

Set access to the given shared account to the given users (a comma separated list). Any users who currently have access but do not exist in the list will have their access revoked.

api.addSharedAccountAccessGroup

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

api.removeSharedAccountAccessGroup

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

api.setSharedAccountAccessGroups

Set access to the given shared account to the given groups (a comma separated list). Any groups who currently have access but do not exist in the list will have their access revoked.

api.batchImportSharedAccounts

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

api.disablePrinter

Disable a printer for select period of time.

api.enablePrinter

Enable a disabled printer.

api.resetPrinterCounts

Reset the counts (pages and job counts) associated with a printer.

api.resetUserCounts

Reset the counts (pages and job counts) associated with a user 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.

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 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 current release the authentication token is the built-in admin user's password (This is password defined in the server.properties file). The password must be supplied to all method calls.