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 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 |
---|---|
|
Triggers the process of adding a new user account defined by a given
|
| Test to see if a user exists in the system/database. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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 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). |
| Set the balance on a user's account to a set value. This is conducted as a transaction. |
| 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). |
| Get the user's current account balance. |
| Get the user's current printing statistics job count as an integer. |
| Get the user's current printing statistics page count as an integer. |
| Disable printing for a user for selected period of time. |
| Enable printing for a user with printing disabled. |
| Set a user's restriction status. (Restricted or Unrestricted) |
| Create a new shared account with the given name. |
| Test to see if a shared account exists in the system/database. |
| 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). |
| The current account balance associated with a shared account. |
| 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. |
| Set the restriction status on a shared account. |
| Allow the given user access to the given shared account without using a pin. |
| Revoke the given user's access to the given shared account. |
| 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. |
| Allow the given group access to the given shared account without using a pin. |
| Revoke the given group's access to the given shared account. |
| 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. |
| Import the shared accounts contained in the given tab separated import file (located on the server). |
| Disable a printer for select period of time. |
| Enable a disabled printer. |
| Reset the counts (pages and job counts) associated with a printer. |
| Reset the counts (pages and job counts) associated with a user 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. |
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 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 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.
© Copyright 1999-2006. PaperCut Software Pty Ltd. All rights reserved.