Using the Data Export API

If you haven’t already, follow the security guide and make sure you can make API calls to PaperCut’s Add-On Platform (AOP).

The data export APIs allows you to create various solutions that consume data on a batch processing lifecycle. Some examples are:

aggregating data into high-level dashboards
archiving data for compliance or other purposes
charging job costs to members of a coworking space for invoicing
allocating costs to user accounts for cost center charging.

The data export APIs are designed to be called infrequently, for example, once a week or once a day.

Note: The AOP export job runs on a twelve hourly schedule, if the API is called more frequently no additional data is provided.

You can use the export job log API endpoint to retrieve lists of job details for a specific organization. All job types (print/copy/scan/fax) are supported.

PaperCut’s AOP API provides a single API call to export job logs, .../exports/v2/job-logs...

export workflow

Each call to this end point will provide a list of file URLs. Each URL has a begin (eventFrom), export (exportedAt), and end (eventTo) timestamp. As well as the date range, the job type is also given. For example:

...
{
  "files": [
    {
      "jobType": "print",
      "exportedAt": "2021-08-11T03:33:12Z",
      "eventsFrom": "2021-08-10T03:33:12Z",
      "eventsTo": "2021-08-11T03:33:12Z",
      "url": "https://storage.googleapis.com/pc-pmitc-combined-log-export/4725fffa/job-log-print-4725fffa-20201029101543.csv?Expires=1604307866&GoogleAccessId=pc-pmitc%40appspot.gserviceaccount.com&Signature=l3dSe%2BehSf4UxwFZqZZWgB8VkxEKbd3Hq%2B1qDztq10nFCLic0zy5wjxnGal9o3iYhhNfCxjpu8wQIp4abfhE6JL4AfSlzDh%2BkzkuOYV5cH%2Bm9AzbsFT5%2BfjAV6%2BgBtnc8HouxToux2gxoN5Ra%2BWM3%2FNSrnYspM7LTRW6gDTK8ENDDcFjb1uoyMnuZWlmR7O8PcATVvD2rgSoZ%2BjzTPdUTZ1abwX8OvtaxuMiuKKSGvhhfYxMBVDVmrds8VSJPGEmBxkg0XBfv2l8AV2FsrK6W9nGUgUAOe1Axb9IkKu6L9s3Ap0xz8lt6bPx95E1uSaQiBNiOFpdlTwsy9fS9lgSbw%3D%3D",
      "urlValidUntil": "2021-08-11T08:33:12Z"
    }
  ]
}

Refer to the API reference document for details.

Notes

When the export API is first called it is possible an empty list of files is returned to the calling add-on. The files will appear later when the asynchronous job export is complete
Old files are preserved for a minimum of 24 months. This period is fixed by PaperCut and cannot be changed. After that they are deleted
The export will contain all available records for the last 24 months
When exporting in JSON format, the file contents are a stream of JSON objects. That is, the file contains a succession of JSON objects and is not wrapped in an array or top-level object. This is called JSON streaming and specifically JSON Lines.
When each export is completed the exportedAt field is updated to the current time
Jobs accumulate in the file in date order
Generally files are closed off, and new files opened at the start of each month
When the solution processses the contents of a file (via the URL), the solution should record the job log timestamp (jobLogTime), for the last record processed, as the last processing date (used during for the next processing cycle)
When the solution reconnects during the next processing cycle, it should avoid downloading already processed files. This saves time and money. The following logic can be used

Flow chart on job log processing

Using the Data Export API

Notes

Ready to get started?