Administering PaperCut with PowerShell

PaperCut has a number of solutions for configuring PaperCut using scripts or programs. These include using the server-command tool on the PaperCut Application Server, or using the web services API from a number of programming languages such as C#, Java and more.

It is also possible to configure PaperCut from Windows PowerShell using the web services API, which brings a number of benefits, and this article explains how to get the best performance AND remote access by building a web services library to use in PowerShell.

(many, many, thanks to Jeffry Spain from Cincinnati Country Day School for help with this content)

Process

PaperCut ships with a ServerCommandProxy class for C#, which presents most available API calls as methods of a class called PaperCUt.ServerCommand. This class can be compiled into a library and imported into PowerShell. The following notes should help you in your development environment:

1. Make sure:

   1. The current version of PowerShell installed. These examples were tested on PowerShell 7.x. These examples will not work on PowerShell 5 for exmaple.

   2. NuGet package provider installed. In PowerShell with admin privilege, execute Install-Module PowerShellGet -AllowClobber -Force

   3. A supported version of the .NET SDK is installed

   4. A local installation of PaperCut NG. You can download PaperCut NG from the PaperCut.com website. Alternatively copy the C# proxy code from your PaperCut MF server (step 5). The C# code is identical for NG and MF.

2. Use .NET Core SDK tools to create a new Project of type Class Library

   dotnet new classlib --name ServerCommandProxy

3. Make the new project directory the current directory

   cd ServerCommandProxy

4. Remove the default Class1.cs file that will have been added to the project.

   Remove-Item Class1.cs

5. Copy the PaperCut supplied server proxy source code file into your project

   Copy-Item `
   'C:\Program Files\PaperCut MF\server\examples\webservices\csharp\ServerCommandProxy.cs'
   

6. Add the third party XML-RPC .NET Core lib with the command

   dotnet add package Kveer.XmlRPC

   NOTE: You may receive the following error message:

   error: There are no versions available for the package 'Kveer.XmlRPC'.

   It’s been found that in some circumstances you may need to manually add the relevant package repository before you can add the XML-RPC library in question. If you encounter the above error, run this command before then reattempting this step.

   dotnet nuget add source --name nuget.org https://api.nuget.org/v3/index.json

7. Build the library with

   dotnet build --configuration Release

8. Import the installed Kveer library into the Powershell environment. For example:

   Add-Type -Path `
   "$env:USERPROFILE\.nuget\packages\kveer.xmlrpc\1.2.0\lib\netstandard2.0\Kveer.XmlRPC.dll"
   

9. Import the new ServerCommandProxy library you have just built into the Powershell environment. For example:

   Add-Type -Path "$PWD\bin\Release\net6.0\ServerCommandProxy.dll"

1. Create a new instance of the ServerCommandProxy class

   $s = New-Object PaperCut.ServerCommandProxy("localhost",9191,"token")

   NOTES:

   1. Make sure you have configured the auth token in PaperCut MF/NG by editing the advanced config key auth.webservices.auth-token
   2. In versions of PaperCut prior to version 19.2.3 use $s = New-Object ServerCommandProxy("localhost",9191,"token")

2. Finally, make your first call against the PaperCut server programmatically

   $s.IsUserExists(“sulman”)

Here is another more complex, if slightly crude, example that deletes all internal users. Note: Needs PaperCut MF/NG 19.2.3 or above

$s.GetGroupMembers("!!Internal Users!!", 0, 10000) |
  foreach {$s.DeleteExistingUser($_)}

That’s it! You’re now able to make calls to the PaperCut Application Server via the web services API. More tips on using the.API here.