AdHoc Reporting API - PaperCutSoftware/PaperCutExamples GitHub Wiki

XML-RPC API for generating AdHoc Reports

Introduction

PaperCut MF/NG provides administrators with the ability to monitor and track printing metrics and organisational goals through it’s reporting feature. Administrators also have the option to specify parameters about the data they wish to see in the report. Most users will either run reports from the admin web interface or use scheduled reports.

As of PaperCut NG/MF 19.1, Administrators now have the option to automate the creation of AdHoc Reports through the Web Services API.

If you are not familiar with the PaperCut MF/NG web services API please see start at this KB page.

Notes:

This ad hoc report generation feature does not work with server-command utility because it is difficult to work with json on the command line.
Running report queries on a production application server may put noticeable load on the server. You should use this API call with care.
Report automation will probably be most useful when an output file format of CSV is used. Data can then be processed and imported into other systems. However the file type PDF can be used to create reports for attaching to emails or direct publication. HTML format reports are not supported.
Note The executive summary report only supports PDF output.
The report output can only be written to the PaperCut MF/NG server file system. After the report is created another step (e.g. ftp file transfer) is needed to transfert the report to another system.

Example

Here is a complete example Python program for PaperCut MF/NG running on a Windows server. It creates a User List report.

#!/usr/bin/env python3

import xmlrpc.client
import json
from ssl import create_default_context, Purpose
import sys

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

# If not localhost then the client address will need to be whitelisted
# in PaperCut MF/NG
host="https://localhost:9192/rpc/api/xmlrpc"

proxy = xmlrpc.client.ServerProxy(host, verbose=False,

context = create_default_context(Purpose.CLIENT_AUTH))

report_name = "user_list"
report_title = "Test Report"

# report parameters
example_user = "aStudent"
example_group = "GroupA"
min_balance = 0.0
restriction_status = "YES"
save_location = "c:\\tmp" # Windows path on PaperCut MF/NG app

# Report parameters formatted into JSON
data = json.dumps( {
    "user-name": example_user,
    "group-name": example_group,
    "min-balance": min_balance,
    "restriction-status": restriction_status} )

try:
  resp = proxy.api.generateAdHocReport(auth,
                            report_name,
                            data,
                            "CSV",
                            report_title,
                            save_location
                            )

  print("saved report in location {} with prefix {}".format(
                                  save_location,
                                  report_title)
      )
except Exception as err:
  print("report API call failed {}".format(err))

Please note: You can provide no parameters (empty json) if no filtering is needed. The idea of these examples is to show you all the applicable data parameters available for each report type and it’s up to the discretion of the integrator or admin to determine which work best to achieve the desired results.

The report can only be saved to a location on the PaperCut MF/NG application server. In the above example the final report will have a name similar to c:\tmp\Test_Report_user_list_10-Nov-09-50.csv.

Other reports examples

Short examples of other reports now follow. Only the json payload and the API call are shown. Please see the complete example above for other details. The call to json.dumps() has also been moved into the main API call as an alternative approach (use whatever convention suites).

Note: This is not a complete list of all the reports or all the options. Please contact PaperCut support if you have questions about any of the undocumented reports.

Executive Summary report

This report supports:

Printing summary of the whole organization
Top 10 users, printers and printer groups
Environment impact for the whole organization
Filtering information by group, department or office

Note: Only PDF output is supported

Parameter	Definition
from-date	Filter report results from this date. Format: yyyy-mm-dd’T’hh:mm
to-date	Include all reports to this date. Format: yyyy-mm-dd’T’hh:mm
group-name	Report all activities from this group.
account-name	Report all activities from this account.
department-list	Report all activities from this department.
office-list	Report all activities from this office
printer-group	Report all activities from this printer group.

data = {
"from-date":"2019-03-01T09:30",
"to-date":"2019-06-01T09:30",
"group-name": "Physics",
"account-name": "STEM",
"department-list": "STEM",
"office-list": "Camberwell-office",
"printer-group": "Print-Lab1",
}

proxy.api.generateAdHocReport(auth,
                              "Executive_summary",
                              json.dumps(data),
                              "PDF",
                              "Exec_summary",
                              "C:\\tmp"
                              )

Largest Print Users report

Compare users' print usage
See users' average print job statistics - do users mostly print large or small jobs?
Also sort by total pages or jobs - see who is printing the most jobs or largest jobs

Parameter	Definition
from-date	Filter report results from this date. Format: yyyy-mm-dd’T’hh:mm
to-date	Include all reports to this date. Format: yyyy-mm-dd’T’hh:mm
group-name	Report all printing activities from this group
user-name	Report all printing activities from this user
department-list	Report all printing activities from this department.
office-list	Report all printing activities from this office.
printer-group	Report all printing activities from this printer group.
allocated-account-type	Show all printing activities from personal and/or shared accounts
job-type	Filters the report to show all instances of the Job type. I.e PRINT or COPY
server-name	Show all printing activities from this server.
printer-name	Show all printing activities from this printer.
show-filters-in-headers	Whether or not these parameters will be shown in the header of the report.

Notes:

A report can be created that shows jobs allocated to both personal and shared accounts by not including the "allocated-account-type" property.

Similarity omitting the "job-type" property will report on both copy and print jobs.

data = {
"from-date":"2019-03-01T09:30",
"to-date":"2019-06-01T09:30",
"user-name": "ryanr",
"group-name": "Physics",
"department-list": "STEM",
"office-list": "Camberwell-office",
"printer-group": "Print-Lab1",
"allocated-account-type": "PERSONAL",
"job-type": "PRINT",
"server-name": "l-ryanr.papercutsoftware.com",
"printer-name": "PDFWriter",
"show-filters-in-header": True
}

proxy.api.generateAdHocReport(auth,
                              "PRINT_SUMMARY_BY_USER_SORT_BY_PAGES_TOP_X",
                              json.dumps(data),
                              "PDF",
                              "Largest_print_users",
                              "C:\\tmp"
                              )

User print/copy/scan/fax - breakdown report

Breakdown of each users print, copy, fax and scan contributions

Parameter	Definition
from-date	Filter report results from this date. Format: yyyy-mm-dd’T’hh:mm
to-date	Include all reports to this date. Format: yyyy-mm-dd’T’hh:mm
group-name	Report all printing activities from this group.
user-name	Report all printing activities from this user.
department-list	Report all printing activities from this department.
office-list	Report all printing activities from this office.
printer-group	Report all printing activities from this printer group.
allocated-account-type	Show all printing activities from personal and/or shared accounts
job-type	Filters the report to show all instances of the Job type. I.e PRINT or COPY
server-name	Show all printing activities from this server.
printer-name	Show all printing activities from this printer.
printed	Whether or not the job produced a physical output. For example: PRINTED(produced paper) or NOT_PRINTED(Didn't produce paper)

data = {
    "from-date":"2019-03-01T09:30",
    "to-date":"2019-06-01T09:30",
    "user-name": "ryanr",
    "group-name": "Physics",
    "department-list": "STEM",
    "office-list": "Camberwell-office,Portland-office",
    "printer-group": "Print-Lab1",
    "allocated-account-type": "PERSONAL",
    "server-name": "l-ryanr.papercutsoftware.com",
    "printer-name": "PDFWriter",
    "printed": "PRINTED
}

proxy.api.generateAdHocReport(auth,
                              "PRINT_COPY_SUMMARY_BY_USER",
                              json.dumps(data),
                              "PDF",
                              "user_breakdown",
                              "c:\\tmp"
                              )

Again many of the properties above are optional. If a property is not present it will not be used to filter the report. NOTE: As previously mentioned this is generally true for all reports, however to save space this will not be repeated

Note that currently this report cannot be filtered by a list of printers, only a single printer, printer server, or print group.

User Printing - Logs

Shows what was printed by user
See what printing is done on certain days in your organization - who printed on a Saturday?
Filter data by printer, server, user, or document type. For example, report all grayscale documents

Parameter	Definition
allocated-account-type	"PERSONAL" or "SHARED"
web-print	"ANY", "YES" or "NO"
protocol	"GOOGLE_CLOUD_PRINT", "EMAIL_PRINTING" or "STANDARD"
cancelled	"ANY", "CANCELLED" or "NOT_CANCELLED"
invoiced	"INVOICED" or "NOT_INVOICED"
offline-usage	"YES” or ”NO"
paper-size	See appendix
offline-usage	"YES" or NO"
denied	"ANY", "ALLOWED", or "DENIED"
printed	"ANY", "PRINTED", or "NOT_PRINTED"
duplex	"SIMPLEX" or "DUPLEX"
grayscale	"GRAYSCALE" or "NOT_GRAYSCALE"
refund-status	See below

Refund Status -- Valid Options:

NOT_CHARGED - Not charged (i.e. user was never charged - denied jobs, cancelled at release station, etc).
NOT_REFUNDED - No refund (in progress, complete, rejected, etc).
REFUNDED_MANUAL_FULL - Full manual refund has been completed.
REFUNDED_MANUAL_PARTIAL - Partial manual refund has been completed.
REFUNDED_AUTO_FULL - Full automatic refund is completed.
REFUNDED_AUTO_PARTIAL - Partial automatic refund is completed.
REFUND_REQUEST_PENDING - Refund request is pending.
REFUND_REQUEST_REJECTED - Refund request is rejected.|

data = {
  "user-name": "ryanr",
  "group-name": "Physics",
  "department-list": "STEM",
  "office-list": "Camberwell-office",
  "server-name": "l-ryanr.papercutsoftware.com",
  "printer-name": "PDFWriter",
  "printer-group": "Campus-1",
  "allocated-account-type": "PERSONAL",
  "web-print": "ANY"
  "protocol": " STANDARD",
  "document-name": "report"
  "client-machine": "10.100.67.1"
  "paper-size": "A4" ,
  "invoiced": "NOT_INVOICED",
  "duplex": "DUPLEX",
  "grayscale": "NOT_GRAYSCALE",
  "cancelled":"ANY",
  "refunded": "ANY",
  "refund-status": "NOT_REFUNDED",
  "printed": "ANY",
  "denied": "ANY",
  "show-filters-in-header": True,
  "offline-usage": "YES"
}

proxy.api.generateAdHocReport(auth
                "PRINT_LOGS_BY_USER",
                json.dumps(data),
                "CSV",
                "User_printing_logs",
                "/tmp")

Printer Usage - Summary:

Compare printer usage over a set time period
See which printers are used most or least, and use the information to help re-organize printer distribution or evaluate printer upgrades

Parameter	Definition
from-date	Filter report results from this date. Format: yyyy-mm-ddThh:mm
to-date	Include all reports to this date. Format: yyyy-mm-ddThh:mm
printer-group	Report printer usage from this group
allocated-account-type	Show printer usage from personal and/or shared accounts
job-type	Filters the report to show all instances of the Job type. I.e PRINT or COPY
server-name	Show printer usages from this server.
printer-name	Show printer usage from this printer.
printer-location	Show printer usage from this printer location.
show-filters-in-headers	Whether or not these parameters will be shown in the header of the report.

It is also important to note that “to-date” and “from-date” must be specified in ISO 8601 format (e.g. 2019-08-20T21:39)

data = {
      "from-date":"2019-03-01T09:30",
      "to-date":"2019-06-01T09:30",
      "printer-group": "Print-Lab1",
      "allocated-account-type": "PERSONAL",
      "job-type": "PRINT"
      "server-name": "l-ryanr.papercutsoftware.com",
      "printer-name": "PDFWriter",
      "printer-location": "Print-Lab1",
      "show-filters-in-header": True
}

proxy.api.generateAdHocReport(auth,
                              "PRINT_SUMMARY_BY_PRINTER",
                              json.dumps(data),
                              "PDF",
                              "Print_usage",
                              "C:\\tmp"
                              )

Transaction Logs

Shows a list of balance adjustments either manually or through automated systems.

Parameter	Definition
any-account-name	Filter reports by shared account
account-type	Show transactions from personal and/or shared accounts
transacted-by	Show all transactions by user
transaction-direction	Filter by credit or debit transactions
transaction-type	Filter by transaction type
transaction-comment	Filter transactions by comment
group-name	Show all transactions by group
transaction-direction	“CREDIT” or “DEBIT”
transaction-type

data = {
    "any-account-name": "STEM\\Maths",
    "account-type": "PERSONAL",
    "transacted-by": "ryanr",
    "transaction-direction": "CREDIT",
    "transaction-type": "INITIAL",
    "transaction-comment": "External funds",
    "group-name": "Physics"
  }

proxy.api.generateAdHocReport(auth,
        "TRANSACTION_LOGS",
        json.dumps(data),
        "CSV",
        "Transaction_logs",
        "C:\\tmp"
        )

Group print/copy/scan/fax - breakdown

Parameter	Definition
from-date	Filter report results from this date. Format: yyyy-mm-dd’T’hh:mm
to-date	Include all reports to this date. Format: yyyy-mm-dd’T’hh:mm
group-name	Report all printing activities from this group.
user-name	Report all printing activities from this user.
department-list	Report all printing activities from this department.
office-list	Report all printing activities from this office.
printer-group	Report all printing activities from this printer group.
allocated-account-type	Show all printing activities from personal and/or shared accounts
job-type	Filters the report to show all instances of the Job type. I.e PRINT or COPY
server-name	Show all printing activities from this server.
printer-name	Show all printing activities from this printer.
show-filters-in-headers	Whether or not these parameters will be shown in the header of the report.

Breakdown of each groups print, copy, fax and scan contributions

data = {
    "from-date":"2019-03-01T09:30",
    "to-date":"2019-06-01T09:30",
    "group-name": "Physics",
    "printer-group": "Print-Lab1",
    "allocated-account-type": "PERSONAL",
    "server-name": "l-ryanr.papercutsoftware.com",
    "printer-name": "PDFWriter",
    "printed": "PRINTED",
}

proxy.api.generateAdHocReport(auth,
                            "PRINT_COPY_SUMMARY_BY_GROUP",
                            json.dumps(data),
                            "CSV",
                            "Group_breakdown",
                            "C:\\tmp"
                            )

Cash Loader Reconciliation Report

Breakdown of each groups print, copy, fax and scan contributions

Parameter	Definition
from-date	Filter report results from this date.Format: yyyy-mm-dd’T’hh:mm
to-date	Include all reports to this date. Format: yyyy-mm-dd’T’hh:mm
device-name	Limit all data to a single device
from-date	Filter report results from this date. Format: yyyy-mm-dd’T’hh:mm
to-date	Include all reports to this date. Format: yyyy-mm-dd’T’hh:mm
device-name	Limit all data to a single device

data = {
    "from-date":"2019-03-01T09:30",
    "to-date":"2019-06-01T09:30",
    "device-name": "Toshiba2505",
}

proxy.api.generateAdHocReport(auth,
                              "DEVICE_CASH_RECONCILIATION_SUMMARY",
                              json.dumps(data),
                              "CSV",
                              "cash_loader_reconciliation",
                              "C:\\tmp"
                              )

Other Reports

Other reports can also be generated. If you need information on the reports below please contact PaperCut Support.

User list

user_list

User balances

User_balance

User printing - summary

print_summary_by_user

Department printing - summary

print_summary_by_department

Department printing - job type summary

print_summary_by_department_by_job_type

Department print/copy/scan/fax - breakdown

print_copy_summary_by_department

Office printing - summary

print_summary_by_office

Office printing - job type summary

print_summary_by_office_by_job_type

Office print/copy/scan/fax - breakdown

print_copy_summary_by_office

User printing - job type summary

print_summary_by_user_by_job_type

User printing - printer summary

print_summary_by_user_by_printer

Deleted user list

deleted_user_list

User printing - period comparison

print_summary_by_user_period_comparison

User configuration

User_configuration

Printer list

printer_list

Printer attributes

printer_attributes

Busiest printers

print_summary_by_printer_sort_by_pages_top_x

Printer usage - summary

print_summary_by_printer

Device copy/scan/fax - breakdown

job_type_summary_by_device

Physical printer usage - summary

print_summary_by_physical_printer

Printer usage - job type summary

print_summary_by_printer_by_job_type

Printer usage - logs

print_logs_by_printer

Printer usage - user summary

print_summary_by_printer_by_user

Printer usage - user job type summary

print_summary_by_printer_by_user_by_job_type

Printer usage - paper area summary

print_summary_by_printer_by_paper_area

Unreleased jobs, environmental impact -

summary

hold_release_paper_saving_environmental_impact_summary

Largest print jobs

print_logs_sort_by_pages_top_x

Print logs

print_logs

Denied print jobs

print_logs_denied

Unreleased jobs paper saving - logs

print_logs_timed_out

Printer groups - summary

print_summary_by_printer_group

Printer groups - job type summary

print_summary_by_printer_group_by_job_type

Printer groups - printer summary

print_summary_by_printer_group_by_printer

Printer usage - ratios

print_ratios_by_printer

Printer usage - period comparison

print_summary_by_printer_period_comparison

Printer configuration

printer_configuration

Device configuration

Device_configuration

APPENDIX Paper Sizes

A0
A1
A2
A3
A4
A5
A6
A7
B0
B1
B2
B3
B4
B5
B6
B7
C3
C4
C5
C6
LETTER
LEGAL
FOLIO
EXECUTIVE
STATEMENT
QUARTO
FOOLSCAP
SIZE_9X11
SIZE_9X12
SIZE_10X11
SIZE_10X14
SIZE_11X17
SIZE_12X18
SIZE_13X19
SIZE_15X11
SIZE_18X24
SIZE_21X30
SIZE_22X34
SIZE_24X36
SIZE_26X38
SIZE_27X39
SIZE_30X40
SIZE_30X42
SIZE_34X44
SIZE_36X48
ANSI_C
ANSI_D
ANSI_E
ANSI_F
ENVELOPE_10
ENVELOPE_C4
ENVELOPE_DL
JIS_B1
JIS_B2
JIS_B3
JIS_B4
JIS_B5
RA0
RA1
RA2
RA3
RA4
SRA0
SRA1
SRA2
SRA3
SRA4
SIZE_8K - PWG "roc_8k_10.75x15.5in", 10.75x15.5in = 273.05x393.7mm
SIZE_16K - PWG "roc_16k_7.75x10.75in", 7.75x10.75in = 196.85x273.05mm