I can get a printer location via the API, but when I try to set this property, I get "java.lang.Exception: The property \'location\' is not valid.". As api.getPrinterProperty and api.setPrinterProperty are identical except for the last parameter, I don't see why getting succeeds and setting fails, when I provide the same values.

Hi Jörn,

The location field that is shown in the PaperCut NG/MF admin interface, against each printer entry, is obtained by our Print Provider from the "Location" field on the print queue installed on Windows or CUPS. This will automatically update if the field is updated on the print queue in either location.

As this is set based on an external source, it is not possible to configure or change the value from the API. This means this call is not present in the api.setPrinterProperty, but the current value can be queried using api.getPrinterProperty.

I am confused: But I can set this value via the GUI!?! I'd like to set the location fields via the API using data from my documentation, so that I have a consistent naming scheme everywhere the location is mentioned.

Hi Jörn,

The PaperCut system will always look at the 'Location' field specified on the queue and will import this value. Although it is possible to manually configure the Location/Department field within PaperCut, this will be quickly overwritten again. This will not occur if the Location field on the queue is empty.

This means this call is not present in the api.setPrinterProperty, but the current value can be queried using api.getPrinterProperty.

Some housekeeping will be required on your queues to enable a consistent naming convention.

We have been using this API (esp processJob) for years, and very thankful for it.
However, we noticed processJob does not seem to take into account if the job will overdraft.
Is there/will there be a way to submit jobs with overdraft protection?
or is there/will there be an 'api.wouldOverdraftUser(price) -> boolean' api call so we could deny jobs locally?

I suppose it is possible to replicate the entire overdraft checking logic on the client by pulling balance, overdraft-mode, overdraft-amount, etc - but that seems sloppy.
Is there a better solution I am missing?

Hi Nils,

processJob does not currently take in to account overdraft protection, as you say. I think you have correctly identified that replicating the overdraft checking logic on the client is currently the only way to achieve what you are after.

All the best!

"We did not find an API method to retrieve a user-specific list of current print jobs in the documentation. Could you please tell us if this method exists? If not, how can we obtain the necessary amount on the user's balance for printing each job through the API?"

Hi Yerlan,

Thanks for posting! You're correct that there is not a way to use the XML-RPC API to access jobs pending release for users. For info about the print job as it's being printed, you can sometimes If you wouldn't mind submitting a ticket throughhttps://www.papercut..., I'd love to get a conversation about what all you're looking to do so we can make sure that you get as close to perfect as possible!

Best,
-T

Hello, Tyler!

I cant open the link, can you provide your email or can you contact me by mail? I would like to discuss with you several issues regarding API.

Thanks for your reply!

Hi Yerlan,
It looks like Tylers response had a typo in the support URL.
Please head over to https://support.papercut.com/ where you'll be able to start a chat. Please have your CRN on hand so we are able to identify your support partner.

Hello David, I tried to open a ticket in chat, but it didn't work. Can you help me?

Hi Yerlan,

I can confirm that we have received your support ticket. Someone will reach out to you in due course to discuss this.

Thanks!

Is possible to get usage stats from the API?

Hi Stream,

You can indeed. If you would like to fetch multiple user properties then you can use the "api.getUserProperties"
Username - string
Array of property names - array of strings see ‘getUserProperty’ example for list of valid properties

You can view the supported values here: https://www.papercut.com/he...
We provide more information about how XMLPRC works here: https://www.papercut.com/bl...

For hands-on assistance using XMLRPC, we recommend reaching out directly to your PaperCut reseller.

Many thanks,

Thank you!

I want to get the pricing of the printer via with papercut xml api. how can I do that ?

Hi Furki,

To retrieve printer pricing information using the PaperCut XML API, it's important to understand that direct access to specific pricing details, such as colour, greyscale, or duplex printing costs, are not available through the API's standard commands.

However, you can determine the cost model applied to a printer (e.g., simple or standard) by utilizing the API effectively. Here's a step-by-step guide to approach your requirements:

List Printers:
Use the ListPrinters command to obtain a list of printers. The command syntax looks like this:
var printers = pcProxy.ListPrinters(0, 1000);

This will return a list of printer names, which might include entries like "ml-vs-testing\PaperCut Global PostScript" or "ml-vs-testing\Printer 2".

Exclude Template Printers:
Before proceeding, you'll want to exclude any template printers from your list, as these are not actual printers and therefore don't have pricing information.

Get Printer Property:
For each printer, use the GetPrinterProperty method to retrieve the cost model. The method requires three parameters: serverName, printerName, and propertyName. Here's the method signature:
public string GetPrinterProperty(string serverName, string printerName, string propertyName) { return _proxy.GetPrinterProperty(_authToken, serverName, printerName, propertyName); }

You'll need to parse the printer names from the ListPrinters result to correctly format these parameters.

Parsing Printer Names:
When parsing the printer names, split the string to separate the print server and printer name. Here's an example of filtering out template printers and splitting the printer names:
var printers = scp.ListPrinters(0, 1000); foreach (var printer in printers) { if (printer != "!!template printer!!") { String[] printerSplit = printer.Split('\\'); Console.WriteLine("Print Server: " + printerSplit[0]); Console.WriteLine("Printer Name: " + printerSplit[1]); } }

Accessing Detailed Pricing:
If you need detailed pricing information beyond the cost model, such as specific costs for colour or duplex printing, this would require direct queries to the PaperCut database. Note, this is feasible only if your PaperCut installation is set up with an external database, as the internal database does not permit external connections.

If you have any questions please don't hesitate to open a support ticket here: https://support.papercut.com

All the best,

I hope I am not barking up the wrong tree but is it possible to print a document on a printer with this API? I can't see any services connected to print jobs.

Hi Rowan,

Thanks for commenting!

Programmatic print submission is not currently something we have support for - however, we often see folks leveraging our email to print configuration to submit jobs with some form of programmatic automation. If you wanted to talk through some of those options, we'd love to get a ticket from you via support.papercut.com.

-T

Hello,

I am using get.PrinterProperty.
Gets a printer property. Available properties include: disabled, print-stats.job-count, print-stats.page-count.

have any other available properties like that ?

Hey there,

It depends on what you're after and trying to achieve.

Shoot us a message via support.papercut.com, we'll be keen to find out what you're trying to achieve. This will give us a better understanding of your requirements, and perhaps there is an api that can help you with it :).

Thanks,

How do we define the PIN code to a user?

Hi Furkan,

If you are looking to import the User ID or PIN for new users then you can use "api.addNewInternalUser".

User ID's are often referred to as "Pins", if the users already exist and you would like to bulk update user IDs then you can use "api.batchImportUserCardIdNumbers"

if you would like any further assistance with this then please don't hesitate to open a support ticket with us here: https://support.papercut.com

Many thanks,

Three formats are presented for the value of auth.webservices.auth-token, yet the first does not work when multiple tokens are entered using the documented format above.

The documentation states that multiple tokens can be entered using the following format:

{"payments":"Zuj0hiazoo5hahwa","userUpdate":"heitieGuacoh8zo6"}

However, when passing in a single token (example below) within a Papercut API call, authentication fails:

{"payments":"Zuj0hiazoo5hahwa"}

Reproduction steps:
1. Set [auth.webservices.auth-token] = {"app1":"token1","app2":"token2"}
2. Pass the first token ({"app1":"token1"}); result is authentication fails;
3. Pass the second token ({"app2":"token2"}); result is authentication fails;
4. Pass both tokens as stored in [auth.webservices.auth-token] ({"app1":"token1","app2":"token2"}); authentication succeeds.

This isn't how I interpreted the documentation to work. Have I misunderstood; is the documentation incorrect; is something broken within the API's implementation?

Cheers,
Lain

Hi Lain,

When using a single token I don't believe you need to define "payments"

Can you try:
server-command set-config auth.webservices.auth-token \\ '\{"Zuj0hiazoo5hahwa"\}'

in place of:
server-command set-config auth.webservices.auth-token \\ '\{"payments":"Zuj0hiazoo5hahwa","userUpdate":"heitieGuacoh8zo6"\}'

For assistance configuring the payment gateway API, I would recommend reaching out to your PaperCut Reseller/Authorised Solutions centre directly.

If you have any questions please don't hesitate to open a support ticket with us here: https://support.papercut.com

Many thanks,

Thanks, Tristan - that worked.

Though, when reading this statement:

A token value can be used by more than one application, but the application name must be unique.

If two tokens are the same for two different applications, yet you cannot specify the application name, does that not leave auditing in an unreliable state?

There's shared responsibility in creating this ambiguity and can be easily remedied, but I have to wonder if it shouldn't be allowed at all (by taking the whole token key-value pair instead of just the token value)?

Anyhow, your answer has solved my most pressing issue which is being able to specify and then use multiple tokens. The rest is debatable (in the spirit of what "can vs. should" happen).

It'd be useful if the documentation outlining the first auth token format could be re-worded to call out the fact that in using the example JSON format in the config key, you must not then use that same JSON format within the XML auth parameter, as "PaperCut NG/MF ignores the application names" doesn't adequately convey this. Or even another example showing format of the actual XML param would serve well enough.

Cheers,
Lain

That's great to hear that worked and we really appreciate your feedback about the KB.

If possible, please can you submit this as a feature request so that we can look to update the KB and provide some examples to make the process clearer.

We look forward to hearing from you,

There is a bug in the api.addNewUser API under the following configuration:

- Sync source: Windows AD
- Using the userPrincipalName as the primary username has been enabled as described here, and works with the sync.

What should happen:
- api.addNewUser is called using the userPrincipalName;
- Papercut performs its LDAP lookup using the "(&(userPrincipalName={0}))" format;
- The account resolves and Papercut populates the remaining Papercut account fields.

What is happening:
- api.addNewUser is called using userPrincipalName;
- Papercut performs its LDAP lookup using the "(&(sAMAccountName={0}))" format;
- The account does not resolve as the userPrincipalName passed in clearly isn't going to match the sAMAccountName - which from a configuration standpoint should no longer be being used;

In addition to not truly cutting over from sAMAccountName to userPrincipalName in line with the configuration, if you are running the userPrincipalName-as-username configuration and call the api.addNewUser using the sAMAcountName, then the Active Directory account passes the second step, but Papercut populates the primary username with the sAMAccountName - ignoring the "userPrincipalName-as-username" configuration altogether.

The output from not respecting the configuration settings is that to get an API implementation working under the "userPrincipalName-as-username" model, you have to action two separate steps:

1. Add the user to Papercut using the sAMAccountName, which allows Papercut to populate all fields;
2. Rename the new account so that the incorrect username (derived from sAMAccountName) is correctly set to the userPrincipalName.

api.addNewUser is badly broken under the Windows AD agent. The LDAP agent (with the "ACTIVE_DIRECTORY" subtype) seems a better option.

As an aside, having a 50 character limit on the primary Papercut username (if your KB article is still current) is skating on thin ice - particularly as the Active Directory schema defines a maximum length of 1,024 Unicode characters for userPrincipalName.

The longest userPrincipalName in the customer environment I'm working with is 88 characters long - well beyond what Papercut can handle (again, if the Papercut KB article is still accurate).

Cheers,
Lain

Hi Lain,

Thanks for bringing this to our attention and including so much detail in your message.

When syncing users from on prem AD via the AD or LDAP connectors I believe we use the samAccountName by default. However, if you have changed this to use the UPN and users are still being created with their samAccxountName then we will need to investigate this further.

api.addNewUser
Triggers the process of adding a new user account defined by a given username. Assuming the user exists in the OS/Network/Domain user directory, the account is created with the correct initial settings as defined by the rules set up in the Admin web interface on the Groups page. Calling this method is equivalent to triggering the ’new user’ event when a new user performs printing for the first time.

So that we can confirm if this is expected behaviour or a bug please can you open a support ticket with us via our portal: https://support.papercut.com

We look forward to hearing from you.

All the best,

Hi, Tristan.

I've lodged that as ticket 1257542, and I've also provided an LDAP client trace that confirms what I'd assumed above.

From that LDAP trace, you can see that Papercut continues to query against sAMAccountName despite being configured to use the userPrincipalName as the primary username, leaving api.addNewUser broken and requiring the two-step hack I mentioned above of calling api.renameUserAccount after addNewUser to "fix up" the inappropriate sAMAccountName-based primary username.

Cheers,
Lain

Thanks for opening a support ticket with us Lain,

With the additional information on the ticket we will continue to investigate if this is a bug.

I hope you are able to find a solution soon.

I'm currently testing on a trial edition with the version number of 22.1.4.

What I'm noticing is that when adding or removing accounts, the user count on the Dashboard screen is not updating.

If I log out of the admin interface and then back in, the adjusted (correct) count is then shown.

Is this expected behaviour?

Hi Lain,
The users are imported from your sync source, you can also create internal users, furthermore users can also be created via the on demand creation method.
Creating accounts will not add additional users.
If this is causing particular issues for you, I would recommend that you raise a ticket with us @ support.papercut.com so that we can take a closer look. Please ensure you provide your CRN and screen recordings etc..

Hi, David.

I'm using the API to create accounts based on the sync source, as the API notes it can do.

I create the account using the API (api.addNewUser), after which Papercut queries the sync source, resolves the user, and imports the rest of the details, such as alias, display name, etc. - all from the source.

This works as documented and isn't the issue.

The issue is the user count shown on the dashboard doesn't change until I log out and then back in.

My thinking is that if it weren't meant to change at all, or only change on a manual sync from the web UI, then logging out and back in wouldn't result in a change to the user count. However, it does change with the log out/back in process, which in turn has me thinking that it is intended to change, but for whatever reason, is not doing so during the existing session.

Perhaps it's just this version; perhaps it's all of them - no idea. But it feels like if it's refreshing upon logging out and back in that it ideally should also refresh without needing to log out and back in.

Cheers,
Lain

Hi Lain,
Looking through our ticketing system, I can see this is normal behaviour. The user will not show up until you log back in, or you run a new sync. I hope this answers your question.

The user shows up fine and can log into the Papercut user web page straight away. This isn't about the account not showing up or not working.

When you log into the Papercut web admin interface, you land on the Dashboard screen, where on the left side under "System Status" there is a statistical panel.

Within that panel is a subheading of "Users" with a count next to it.
https://uploads.disquscdn.c...

When you use the API to add or remove users, this count does not update until you log out and back in again, where you'd expect that either refreshing the page or even moving away from the Dashboard page and then returning to it should be enough to see the updated count.

What I'm asking is if you should have to log out of the Papercut web admin interface and log back in again just to see updated statistics?

If we do have to, that's fine. It just seemed unintuitive and counterproductive, hence asking the question.

Cheers,
Lain

Hi Lain,
Thank you for the clarification.
The behaviour which you are seeing is normal. Only a logout or sync will update the user count on the dashboard. If you feel this is something we should address, please feel free to open a ticket @ support.papercut.com and we can add it to our feature request system.

Hello, when following the example, it shows me the same thing, that my IP is not allowed access.

I am making the request through Postman.

http://[server}/rpc/api/xmlrpc?token=[token]&username=[username]

<methodcall>
<methodname>api.getUserProperty</methodname>
<params>
<param>
<value>
<string>[token]</string>
</value>
</param>
<param>
<value>
<string>[username]</string>
</value>
</param>
</params>
</methodcall>

Hi Jesus,

Thanks for getting in touch!

By default, access is restricted to localhost (127.0.0.1) as it relates to the XML Web Services API. You'd need to follow the steps in the Security section of this page to allow other IP addresses.

If you end up doing this and the issue persists, I'd suggest logging a ticket with us at support.papercut.com.

Cheers!

I already made the settings but it shows me the status 200 and the response to the request is empty

Jesus,

Thank you for letting me know!

I would definitely log a ticket so we can better assist you directly.

Thanks!

Hello, is there any way to get the information about BW and Color page count for printer via API ?

Hi Sergey,

You should be able to query if a job is grayscale or not using the "grayscale" value with api.processJob. We provide more information in this KB: https://www.papercut.com/he...

If you have any questions or would like any further assistance with this then please feel free to open a support ticket with us here: https://support.papercut.com

Many thanks,

I'm looking at the api.getTaskStatus method and left wondering: Are the nine other methods (from above) that refer to it for checking the current status synchronous? i.e. running any one of those nine precludes running any of the remaining eight?

Otherwise, I can't see how you can tell that your task is finished as distinct from someone else's task, or even from other asynchronous calls you've made, since the only values returned are a generic "completed" flag and a likely empty "message" string.

Since it appears there's no infallible way to align the returned status to a specific task given it could relate to a call from another process - including admin actions taken via the web interface (i.e. if this were an asynchronous, job-like model), is it better to think of api.getTaskStatus as "the system as a whole is busy" rather than "your task is busy"?

Hey there Lain,

Apologies for the delay in getting back to you on this one! Digging around in the code, it appears tasks such as those triggered by the methods you've referenced are registered with our background task manager, with a unique ID for each task being returned by the service. However, a closer look at getTaskStatus itself revealed it did not seem to perform any sort of indexing against the background tasks currently submitted.

It turns out I kind of jumped three steps ahead of myself by going straight to the source, as searching a little further afield I discovered we actually document the logic over in one of our public GitHub repositories:

https://github.com/PaperCut...

Please note that currently getTaskStatus() method... will only check the status of the last job submitted. You should wait for the job to complete before starting another asynchronous method call.

In other words, whilst these tasks are asynchronous, getTaskStatus can only tell if you the most recently submitted task is complete. This puts the onus on the API client to only submit new asynchronous tasks once we're sure no other such tasks are running, if we indeed need to be sure that a given task has completed before proceeding. The recommendation, then, would be to check with getTaskStatus first, submit the job, and then iterate getTaskStatus and a sleep/wait until we get true returned for completed.

In other other words, yes, I think it'd be wise to treat the method as "the system as a whole is busy". Not especially elegant, I know, but hopefully enough to work with =)

Thanks for the follow-up, Peter.

That's the approach I'd adopted.

Cheers,
Lain

Hey. where can i find a list of all properties that is available for api.getPrinterProperty method?

Hi Erik,

The inputs available for api.getPrinterProperty are:

get-printer-property <server_name> <printer_name> <property>
Gets a printer property.
<server_name> - the name of the server the printer is hosted on.
<printer_name> - the name of the printer.
<property> - the name of the property to get. Valid properties include:
cost-model - the cost model used by the printer (e.g. SIMPLE)
custom-field-1 - the value for custom field 1 if set.
custom-field-2 - the value for custom field 2 if set.
custom-field-3 - the value for custom field 3 if set.
custom-field-4 - the value for custom field 4 if set.
custom-field-5 - the value for custom field 5 if set.
custom-field-6 - the value for custom field 6 if set.
disabled - whether or not the printer is currently disabled
print-stats.job-count - the total print job count for this printer
print-stats.page-count - the total printed page count for this
printer
printer-id - the printer's unique identifier
virtual - If the printer is a virtual queue
device-functions - The the functions of the device. E.g COPIER
release-station - Returns the held job mode. I.e User held(STANDARD)

If you have any questions please feel free to open a support ticket with us here: https://support.papercut.com

Many thanks,

Any way to get a list of the printer's currently configured groups? addPrinterGroup/setPrinterGroups both allow editing, but I can't find a way to read them. Do we have to edit blindly?

Ryan,

Thank you for reaching out!

As it stands, the XMLRPC API, nor Server Commands provide a get method as it relates to Printer Groups. An alternative that comes to mind is the Printer groups - printer summary report"' - though it may not be the most straightforward option. It's located in the PaperCut Admin web interface under "Printers" section of the Reports tab.

If that doesn't end up doing the trick, drop us a line at support.papercut.com and we can get a feature request going for the functionality you're looking for.

Cheers!