Top Tips for using the Public Web Services API

KB Home   |   Top Tips for using the Public Web Services API

Main.TopTipsForUsingThePublicWebServicesAPI History

Show minor edits - Show changes to output

January 30, 2019, at 05:16 AM by Alec - Add -H option to curl
Changed line 218 from:
curl -v http://<servername>:9191/rpc/api/xmlrpc --data @file.xml
to:
curl -v  -H "content-type:text/xml"  http://<servername>:9191/rpc/api/xmlrpc --data @file.xml
January 11, 2019, at 03:22 AM by Ryan Reichenberg - Change SSL To TLS
Changed line 125 from:
Another security consideration is the use of end-to-end encryption via the use of a '''Secure Sockets Layer(SSL)'''. This allows for the data to be securely passed from client to server - meaning you can pass your [@auth.webservices.auth-token@] to the PaperCut servers without having it exposed to the internet.
to:
Another security consideration is the use of end-to-end encryption via the use of a '''Transport Layer Security(TLS)'''. This allows for the data to be securely passed from client to server - meaning you can pass your [@auth.webservices.auth-token@] to the PaperCut servers without having it exposed to the internet.
January 11, 2019, at 12:26 AM by Ryan Reichenberg - Add not operator to API call.
Changed line 167 from:
if proxy.api.isUserExists(auth, user):
to:
if not proxy.api.isUserExists(auth, user):
January 11, 2019, at 12:18 AM by Ryan Reichenberg - Remove link to server proxy
Changed line 141 from:
You can now make API calls through the ServerProxy instance.
to:
You can now make API calls through the proxy instance.
January 11, 2019, at 12:15 AM by 139.130.165.134 -
Added lines 124-141:

Another security consideration is the use of end-to-end encryption via the use of a '''Secure Sockets Layer(SSL)'''. This allows for the data to be securely passed from client to server - meaning you can pass your [@auth.webservices.auth-token@] to the PaperCut servers without having it exposed to the internet.

An example of how to do this in Python:
[@

from ssl import create_default_context, Purpose

# Prefer HTTPS connection
host="https://localhost:9192/rpc/api/xmlrpc" # If not localhost then this address will need to be whitelisted in PaperCut
auth="token"  # Value defined in advanced config property "auth.webservices.auth-token". Should be random

proxy = xmlrpc.client.ServerProxy(host, verbose=False,
      context = create_default_context(Purpose.CLIENT_AUTH))

@]

You can now make API calls through the ServerProxy instance.
January 10, 2019, at 11:25 PM by Alec - Added note about using very long auth.webservices.auth-token
Changed lines 113-116 from:
The authentication token (required on each method call) should be defined in the advanced config key [@auth.webservices.auth-token@].
Using the admin password could be a security risk if the password leaks.

Note also that using
the admin password is also approximately 10 time slower because the auth token must be processed on each call.
to:
The authentication token (required on each method call) should be defined in the advanced config key [@auth.webservices.auth-token@]. This is because:

* Using the admin password could be a security risk if the password leaks

* It's possible to define a very large random secret in the [@auth.webservices.auth-token@] config key which  would be secure, but not suitable as an admin password.

* Using
the admin password is also approximately 10 time slower because the auth token must be processed on each call.
March 14, 2018, at 11:40 PM by Alec - Add tip about XML element names being case sensitive
Added line 176:
# Double check your XML content, including the case of XML element names.  For instance it's [@<methodName>@], not [@<methodname>@]
December 21, 2017, at 04:14 AM by Alec - Added a link to the new XML-RPC blog post
Added lines 98-100:

If you are new to XML-RPC programming you might this blog [[https://blog.papercut.com/blog/2017/12/21/write-xml-rpc-clients/#more|post]] useful.

October 23, 2017, at 12:03 AM by Alec - Add better info about getTaskStatus()
Changed line 227 from:
# Advanced Technical Notes -- https://github.com/PaperCutSoftware/PaperCutExamples/wiki/Public-Web-Services-API
to:
# Advanced Technical Notes on using [@getTaskStatus()@] -- https://github.com/PaperCutSoftware/PaperCutExamples/wiki/Public-Web-Services-API
October 19, 2017, at 09:17 PM by Alec - Added explicit example for int instead of float type
Changed line 162 from:
# At least one parameter is the wrong type.
to:
# At least one parameter is the wrong type. For instance supplying an integer when a double float type is required.
October 10, 2017, at 03:13 AM by Alec - Add note to wiki on GitHub
Added line 227:
# Advanced Technical Notes -- https://github.com/PaperCutSoftware/PaperCutExamples/wiki/Public-Web-Services-API
September 18, 2017, at 12:35 AM by Alec - Add note about security penalty of using admin pwd as auth token
Added lines 112-113:

Note also that using the admin password is also approximately 10 time slower because the auth token must be processed on each call.
Changed line 99 from:
Python 3 provides the [https://docs.python.org/3/library/xmlrpc.html|xmlrpc] library (Python 2 uses xmlrpclib).
to:
Python 3 provides the [[https://docs.python.org/3/library/xmlrpc.html|xmlrpc]] library (Python 2 uses xmlrpclib).
Changed lines 54-55 from:
Additional examples can also be found on the PaperCut MF/NG server [@[app dir]/erver/examples/scripting@]
to:
Additional examples can also be found on the PaperCut MF/NG server [@[app dir]/server/examples/scripting@]
Changed line 93 from:
We also provide examples in C#, Ruby, PHP and Java (on your PaperCut server go to [@[app dir]/erver/examples/webservices/@]). On our `GitHub repo you can also find a Perl [[https://github.com/PaperCutSoftware/PaperCutExamples/blob/master/PublicWebServicesAPI_AND_servercommandScripts/Update_Card_Number/update_card_numbers.pl|example]] contributed by [[https://github.com/Joffcom|@Joffcom]] (more contributions always welcome).
to:
We also provide examples in C#, Ruby, PHP and Java (on your PaperCut server go to [@[app dir]/server/examples/webservices/@]). On our `GitHub repo you can also find a Perl [[https://github.com/PaperCutSoftware/PaperCutExamples/blob/master/PublicWebServicesAPI_AND_servercommandScripts/Update_Card_Number/update_card_numbers.pl|example]] contributed by [[https://github.com/Joffcom|@Joffcom]] (more contributions always welcome).
Changed line 99 from:
Python 3 provides the [xmlrpc](https://docs.python.org/3/library/xmlrpc.html) library (Python 2 uses xmlrpclib).
to:
Python 3 provides the [https://docs.python.org/3/library/xmlrpc.html|xmlrpc] library (Python 2 uses xmlrpclib).
Changed line 224 from:
# Integrating the C# proxy wrapper into Windows PowerShell -- https://www.papercut.com/kb/Main/AdministeringPaperCutWithPowerShell
to:
# Integrating the C# proxy wrapper into Windows `PowerShell -- https://www.papercut.com/kb/Main/AdministeringPaperCutWithPowerShell
Changed line 93 from:
We also provide examples in C#, Ruby, PHP and Java (on your PaperCut server go to [@[app dir]/erver/examples/webservices/@]). On our `GitHub repo you can also find a Perl [[https://github.com/PaperCutSoftware/PaperCutExamples/blob/master/PublicWebServicesAPI_AND_servercommandScripts/Update_Card_Number/update_card_numbers.pl|example]].
to:
We also provide examples in C#, Ruby, PHP and Java (on your PaperCut server go to [@[app dir]/erver/examples/webservices/@]). On our `GitHub repo you can also find a Perl [[https://github.com/PaperCutSoftware/PaperCutExamples/blob/master/PublicWebServicesAPI_AND_servercommandScripts/Update_Card_Number/update_card_numbers.pl|example]] contributed by [[https://github.com/Joffcom|@Joffcom]] (more contributions always welcome).
Changed line 25 from:
The easiest way to use the API is to use the `server-command` program from
to:
The easiest way to use the API is to use the[@server-command@] program from
Changed line 46 from:
# The path to the program is `[app dir]/server/bin/<platform>/server-command`. Obviously you will need to select the correct path for you server platform
to:
# The path to the program is [@[app dir]/server/bin/<platform>/server-command@]. Obviously you will need to select the correct path for you server platform
Changed lines 54-55 from:
Additional examples can also be found on the PaperCut MF/NG server `[app dir]/erver/examples/scripting`
to:
Additional examples can also be found on the PaperCut MF/NG server [@[app dir]/erver/examples/scripting@]
Changed lines 72-75 from:
The next few commands just get repeated for each user (that's the magic `while read...` bit).

When we have each user name we can a) read both card numbers from the database with `get-user-property` and then b) write them back to the database with `set-user-property` command.
to:
The next few commands just get repeated for each user (that's the magic [@while read...@] bit).

When we have each user name we can a) read both card numbers from the database with [@get-user-property@] and then b) write them back to the database with [@set-user-property@] command.
Changed line 97 from:
All the method calls use XML-RPC as the transport mechanism. You can find more details about XML-RPC [[http://xmlrpc.scripting.com/spec.html|here].
to:
All the method calls use XML-RPC as the transport mechanism. You can find more details about XML-RPC [[http://xmlrpc.scripting.com/spec.html|here]].
Changed line 114 from:
[@auth.webservices.allowed-addresses`@] advanced config key,
to:
[@auth.webservices.allowed-addresses@] advanced config key,
Changed line 97 from:
All the method calls use XML-RPC as the transport mechanism. You can find more details about XML-RPC [here](http://xmlrpc.scripting.com/spec.html).
to:
All the method calls use XML-RPC as the transport mechanism. You can find more details about XML-RPC [[http://xmlrpc.scripting.com/spec.html|here].
Changed lines 145-146 from:
Notice the parameter [@auth@], which ```must```  be provided in every API call.
to:
Notice the parameter [@auth@], which '''must'''  be provided in every API call.
Changed lines 172-174 from:
## Install Curl (on a MacOS and Linux itís already installed)
## Optionally set up an access token (advanced config key auth.webservices.auth-token)
 ## Create an XML data file with your API call paramters with the content of your method call. For instance
to:
** Install Curl (on a `MacOS and Linux itís already installed)
** Optionally set up an access token (advanced config key auth.webservices.auth-token)
** Create an XML data file with your API call paramters with the content of your method call. For instance
Changed line 189 from:
## Run a command similar to
to:
** Run a command similar to
Changed lines 215-218 from:
Java: [@[app dir]/server/examples/webservices/java/ServerCommandProxy.java@]
C#: [@[app dir]/server/examples/webservices/csharp/ServerCommandProxy.cs@]

to:
* Java: [@[app dir]/server/examples/webservices/java/ServerCommandProxy.java@]
* C#: [@[app dir]/server/examples/webservices/csharp/ServerCommandProxy.cs@]

Changed lines 221-226 from:
1. Email Group -- https://groups.google.com/forum/#!forum/papercut-webservices-api
2. More information about PaperCut APIs in general -- https://www.papercut.com/kb/Category/API
3. Online chat forum -- https://gitter.im/PaperCutSoftware/PaperCutExamples
4. Integrating the C# proxy wrapper into Windows PowerShell -- https://www.papercut.com/kb/Main/AdministeringPaperCutWithPowerShell

to:
Email Group -- https://groups.google.com/forum/#!forum/papercut-webservices-api
# More information about PaperCut APIs in general -- https://www.papercut.com/kb/Category/API
# Online chat forum -- https://gitter.im/PaperCutSoftware/PaperCutExamples
# Integrating the C# proxy wrapper into Windows PowerShell -- https://www.papercut.com/kb/Main/AdministeringPaperCutWithPowerShell
Added lines 1-231:
(:title  Top Tips for using the Public Web Services API:)

! Introduction

The PaperCut public API is super handy for a lot of different things,
from the simple to the complex. This post provides some hints and tips to
help you get the most from the API.

Before going any further you should read the API
[[https://www.papercut.com/products/ng/manual/common/topics/tools-web-services.html|Overview]].
This post mainly expands on the overview material and calls out specific topics that we have been asked about before.

!! What can you do with the API?

The functionality in the API is broad and covers things such as:

* Managing users, shared account, groups and printers. It includes things such as updating user's account balance.
* Adding jobs details from a third party system
* Managing admin users
* Getting and settings advanced config settings
* Starting import jobs

! Starting out with server-command

The easiest way to use the API is to use the `server-command` program from
a script. This examples use the Bash shell as the script engine. If you are
using Windows
you will either need to install the Windows 10 Linux subsystem, Cygwin or convert the
script to a Windows batch file (more on how to support Windows in the resources links below).

Let's start with an example. This script will swap the primary and secondary card numbers
for every user in the PaperCut database.

[@
server-command list-user-accounts | while read x;do
  primary=$(server-command get-user-property $x "secondary-card-number")
  secondary=$(server-command get-user-property $x "primary-card-number")
  server-command set-user-property $x "primary-card-number" "$primary"
  server-command set-user-property $x "secondary-card-number" "$secondary"
done
@]

There are a number of things to note:

# The serve command utility can only be run on the PaperCut application server
# The path to the program is `[app dir]/server/bin/<platform>/server-command`. Obviously you will need to select the correct path for you server platform
# The server command will perform one command (API call) at a time. If you are performing very large bulk updates you may find this slow
# The program does not return error codes in an expected fashion because of the several types of errors that can occur. You will need to parse the text output


The example above, and others, can be found on the
[[https://github.com/PaperCutSoftware/PaperCutExamples/tree/master/PublicWebServicesAPI_AND_servercommandScripts|PaperCut Examples]]
repository.
Additional examples can also be found on the PaperCut MF/NG server `[app dir]/erver/examples/scripting`

So let's briefly look at the example script above in more detail. I suggest that you open up
a command shell (cmd.exe on Windows) and try these out for yourself. Just make
sure that server command is on your path.

So the first call is to get a list of the users (internal and external) in PaperCut. When I run this command on my test system I get this

[@
$ server-command list-user-accounts
ah
alec
copieruser
jane
john
suhail
@]

The next few commands just get repeated for each user (that's the magic `while read...` bit).

When we have each user name we can a) read both card numbers from the database with `get-user-property` and then b) write them back to the database with `set-user-property` command.

So for instance

[@
$ server-command get-user-property alec primary-card-number
998899
@]

More information about [@server-command@] [[https://www.papercut.com/products/ng/manual/common/topics/tools-server-command.html|here]].

! Using the API

If you want to use the API across the network or incorporate API calls  into something larger then you will
need to use the API directly. The following discussion assumes you have read the [[https://www.papercut.com/products/ng/manual/common/topics/tools-web-services.html|overview]] and I will also refer you to other documentation to read as we progress.

The following code examples are in Python 3. This is a common language and should provide easy to understand fragments that
you can translate into your preferred programming language.

We also provide examples in C#, Ruby, PHP and Java (on your PaperCut server go to [@[app dir]/erver/examples/webservices/@]). On our `GitHub repo you can also find a Perl [[https://github.com/PaperCutSoftware/PaperCutExamples/blob/master/PublicWebServicesAPI_AND_servercommandScripts/Update_Card_Number/update_card_numbers.pl|example]].

!! XML-RPC

All the method calls use XML-RPC as the transport mechanism. You can find more details about XML-RPC [here](http://xmlrpc.scripting.com/spec.html).
However generally you don't need to worry about the protocol details as that is handled by a library.
Python 3 provides the [xmlrpc](https://docs.python.org/3/library/xmlrpc.html) library (Python 2 uses xmlrpclib).
Please look in the example code for suggestions of libraries you can use.
If you are using Go then consider using the [[https://github.com/divan/gorilla-xmlrpc|gorilla-xmlrpc]] library.
Otherwise Google is your friend.

So using Python 3 as our example, at the top of you script put [@import xmlrpc.client@].

!! Security

Pay special attention to the section on [[https://www.papercut.com/products/ng/manual/common/topics/tools-web-services.html#aanchor773y|security]] in the overview.

The authentication token (required on each method call) should be defined in the advanced config key [@auth.webservices.auth-token@].
Using the admin password could be a security risk if the password leaks.

In addition the IP white list can be set in the Admin GUI or via setting the
[@auth.webservices.allowed-addresses`@] advanced config key,
which you can do via the [@server-command@] utility or API.

!! Making API calls

Before making API calls it's usual to set up values. In addition most XML-RPC libraries require you to set up some library object for
later calls. In Python this looks like

[@
#!/usr/bin/env python3

import xmlrpc.client

# If not localhost then this address will need to be whitelisted in PaperCut
host="http://localhost:9191/rpc/api/xmlrpc"

# Value defined in advanced config property "auth.webservices.auth-token". Should be random
auth="token"

proxy = xmlrpc.client.ServerProxy(host)
@]

You can now make method calls. For example

[@
user="aUser"

if proxy.api.isUserExists(auth, user):
  print("Can't find user {}".format(user)
@]

Notice the parameter [@auth@], which ```must```  be provided in every API call.

The API overview does not provide enough detail on each API (specific parameters and types) and developers
will need to refer to the detailed documentation installed on the PaperCut MF/NG server
at [@[app dir]/server/examples/webservices/java/docs/api/index.html@]. Note
that this Javadoc does not provide any information about the requirement to add the [@auth@] token as the first method
parameter to every call.

!! Troubleshooting

* You get the error "[@ERROR: java.lang.NoSuchMethodException:"@]: Usually you have either:

# Forgotten to add the auth token parameter,
# Misspelled the method name,
# Provided the wrong number of parameters or
# At least one parameter is the wrong type.

* You are getting an error message about the client IP address not being whitelisted, even though you added in PaperCut.

Often your network or IT infrastructure is mangling the IP address in some fashion.
Look in the PaperCut server log to
see the IP address that PaperCut is seeing -- look for the string [@BaseXMLRPCServlet@]

* You have checked everything in your code and it's still not working.

# Check the PaperCut server log -- look for the string [@BaseXMLRPCServlet@]
# Do some low level XML-RPC debugging
## Install Curl (on a MacOS and Linux itís already installed)
## Optionally set up an access token (advanced config key auth.webservices.auth-token)
 ## Create an XML data file with your API call paramters with the content of your method call. For instance
[@
<?xml version="1.0"?>
<methodCall>
<methodName>api.getUserAccountBalance</methodName>
<params>
<param>
<value>token</value>
</param>
<param>
<value>username</value>
</param>
</params>
</methodCall>
@]
## Run a command similar to
[@
curl -v http://<servername>:9191/rpc/api/xmlrpc --data @file.xml
@]

and check the output.

Some partners have reported success in using [[https://www.getpostman.com|Postman]] as a debugging tool as well.

!!  Proxy Wrappers

The Python example above uses an XML-RPC library and the application programmer makes
direct calls on the network API to connect to the PaperCut server.
For certain languages (Java and C#)
we have created example proxy wrappers around the network code.

In this case PaperCut have provided classes that implement each API call.
The developer just makes a method call and the proxy class handles the marshalling and
unmarshaling of the network calls.

Please note that the example proxy classes are often not up to date with the latest
API changes.
If you notice any omissions please let us know at <integration-dev-support@papercut.com>

You can find the proxy wrapper examples on the PaperCut MF/NG server:

Java: [@[app dir]/server/examples/webservices/java/ServerCommandProxy.java@]
C#: [@[app dir]/server/examples/webservices/csharp/ServerCommandProxy.cs@]


! More Resources

1. Email Group -- https://groups.google.com/forum/#!forum/papercut-webservices-api
2. More information about PaperCut APIs in general -- https://www.papercut.com/kb/Category/API
3. Online chat forum -- https://gitter.im/PaperCutSoftware/PaperCutExamples
4. Integrating the C# proxy wrapper into Windows PowerShell -- https://www.papercut.com/kb/Main/AdministeringPaperCutWithPowerShell



----
''Categories:'' [[Category.API|+]]
----
[-Keywords: API-]

Comments

Share your findings and experience with other PaperCut users. Feel free to add comments and suggestions about this Knowledge Base article. Please don't use this for support requests.

Article last modified on January 30, 2019, at 05:16 AM
Printable View   |   Article History   |   Edit Article