Top Tips for using the Public Web Services API

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

Main.TopTipsForUsingThePublicWebServicesAPI History

Hide minor edits - Show changes to markup

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:
  1. Double check your XML content, including the case of XML element names. For instance it’s <methodName>, not <methodname>
February 05, 2018, at 10:47 PM by Alec - Add permanent anchor -- thanks docs team
Changed line 111 from:

Pay special attention to the section on security in the overview.

to:

Pay special attention to the section on security in the overview.

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 post useful.

October 23, 2017, at 12:03 AM by Alec - Add better info about getTaskStatus()
Changed line 227 from:
  1. Advanced Technical Notes — https://github.com/PaperCutSoftware/PaperCutExamples/wiki/Public-Web-Services-API
to:
  1. 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:
  1. At least one parameter is the wrong type.
to:
  1. 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:
  1. 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 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 example contributed by @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 example contributed by @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:
  1. Integrating the C# proxy wrapper into Windows PowerShell — https://www.papercut.com/kb/Main/AdministeringPaperCutWithPowerShell
to:
  1. 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 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 example contributed by @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 theserver-command program from

Changed line 46 from:
  1. 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:
  1. 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 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:
  1. Install Curl (on a MacOS and Linux itís already installed)
  2. 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:
  1. 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:
  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
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 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:

  1. The serve command utility can only be run on the PaperCut application server
  2. 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
  3. 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
  4. 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 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 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 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 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 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 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:
  1. Forgotten to add the auth token parameter,
  2. Misspelled the method name,
  3. Provided the wrong number of parameters or
  4. 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.
  1. Check the PaperCut server log — look for the string BaseXMLRPCServlet
  2. Do some low level XML-RPC debugging
    1. Install Curl (on a MacOS and Linux itís already installed)
    2. 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>
  1. 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 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: APIs


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