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):
SOAP/WSDL
XML-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:
Method | Description |
---|---|
| Test to see if a user exists in the system/database. |
| Get the user's current account balance. |
| Gets a user property. Properties include the user's full name, department, email, notes, office and restriction status among others. |
| Get multiple user properties at once. Properties include the user's full name, department, email, notes, office and restriction status among others. |
| Sets a user property. Properties include the user's full name, department, email, notes, office, password (for internal users) and restriction status among others. |
| Set multiple user properties at once. Properties include the user's full name, department, email, notes, office, password (for internal users) and restriction status among others. |
| 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). |
| Adjust a user's account balance if there is enough credit available. |
| Adjust a user's account balance if there is enough credit available to leave the given amount available in the account. |
| 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). |
| 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). |
| Set the balance on a user's account to a set value. This is conducted as a transaction. |
| Set the balance for each member of a group to the given value. |
| Reset the counts (pages and job counts) associated with a user account. |
| Re-applies initial settings on the user. Initial user settings are based on group membership. |
| Disable printing for a user for selected period of time. |
|
Triggers the process of adding a new user account defined by a given
|
| 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. |
| 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). |
| Creates and sets up a new internal user account. |
| 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. |
| 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. |
| Add a user as an admin with default admin rights. |
| Remove an admin user from the list of admins. |
| Add a group as an admin group with default admin rights. |
| Remove a group from the list of admin groups. |
| Sets a user's account selection to charge to a single shared account. |
| Sets a user's account selection to automatically charge to personal account |
| Sets a user's account selection to standard account selection popup. |
|
List all user accounts (sorted by username) starting at 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
|
|
List all shared accounts (sorted by account name) starting at 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
|
|
List all shared accounts the user has access to (sorted by account name), starting at
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
|
| Test to see if a shared account exists in the system/database. |
| Sets a shared account's current account balance. |
| Gets a shared account's current account balance. |
| Sets a shared account property. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others. |
| Sets multiple shared account properties at once. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others. |
| Gets a shared account property. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others. |
| Gets multiple shared account properties at once. Properties include access groups, balance, comment options, disabled status, notes, pin and restriction status among others. |
| 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). |
| Set the balance on a shared account to a set value. This is conducted as a transaction. |
| Create a new shared account with the given name. |
| 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). |
| Allow the given user access to the given shared account without using a pin. |
| Rename an existing shared account. |
| Delete a shared account from the system. Use this method with care. Calling this will permanently delete it from the shared account list. |
| Allow the given group access to the given shared account without using a pin. |
| Revoke the given user's access to the given shared account. |
| Revoke the given group's access to the given shared account. |
| Gets a printer property. Available properties include: disabled, print-stats.job-count, print-stats.page-count. |
| Sets a printer property. |
|
List all printers (sorted by printer name), starting at 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
|
| Set a page cost using the Simple Charging Model. |
| Get the page cost if, and only if, the printer is using the Simple Charging Model. |
| Reset the counts (pages and job counts) associated with a printer. |
| Add a printer to a single printer group. |
| Set the printer groups a printer belongs to, overwriting any existing group. |
| Enables a printer. |
| Disable a printer for select period of time. |
| Delete a printer. Use the special text "[All Printers]" to delete all printers on the specified server. |
| 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. |
| Add a user group to the printer's access group list. |
| Remove a user group from the printer's access group list. |
| Add a new group to system's group list. |
| Remove a group. |
|
List all groups (sorted by group name), starting at 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
|
| Test to see if a group exists in the system. |
| Set the group quota allocation settings on a given group. |
| Get the group quota allocation settings on a given group. |
| Redeem a card and place the credit on the user's account. |
| 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. |
| 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. |
| Start a full user and group synchronization. This is equivalent to pressing the 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. |
| 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. |
| 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. |
|
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
|
| Import the shared accounts contained in the given tab separated import file (located on the server). |
| 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. |
| 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. |
|
Import the user card/ID numbers and PINs contained in the given tab-delimited import file. |
|
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: If this file already exists it will be over-written. |
| Gets the value of a configuration settings. |
| 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. |
| 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
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
.
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)”.
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:
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 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
→ → .
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:
Login to the system.
Navigate to the Options section.
Click on the Config editor link in the list of actions.
Find the auth.webservices.auth-token
config setting.
Enter a new value that will be the new web services authentication token.
Press the
button to the right to apply the change.This authentication token can now be used in addition to the built-in admin user's password.
© Copyright 1999-2011. PaperCut Software International Pty Ltd. All rights reserved.