Configure Data Integrations

You can export usage data by configuring any one or both of the following:

  • Daily data export - Daily export of your required data.
  • Historical data export - Export of needed historical data.

Steps to export usage data from PaperCut MF to a 3rd party tool

1. Navigate to: [PaperCut MF Install Location]\server\lib-ext\data-integrations

2. Create a new empty text file with a .properties extension. Or make a copy of the data-integration.properties.template file and rename it to a new name with .properties extension. For example, intuitivebi.properties

3. Using a text editor, open this new .properties text file and add/edit the following:

Data Integrations properties file

Data Export Configuration from PaperCut MF (top):

  • Data.export-historical-data.days-back

Specify the time period (days before the current date) of historical data being exported.

Default = 90 (days before the current date)

Note: If this value is significantly higher than the default value (ie 365 or 1095) and you have a large organisation using PaperCut MF, it could increase the time taken to export user changes, printer changes and daily printing logs data. You can also set the value to 0 to not export historical data and commence exporting daily changes

  • Data.export.directory

Specify the location where the exported data is saved.

Default = [PaperCut MF Install Location]\server\lib-ext\data-integrations\data\[sub-folder name of your 3rd party tool]

Note: Leaving this blank or not specifying a fully qualified path causes the exported data to be saved in the default location. In the example picture above, this folder is called data-exports. It gets automatically created by PaperCut MF the first time data is exported.

  • Data.export.types

Specify the data types being exported.

Accepted values = users, printers, printer_usage_logs, accounts, servers

  • Data.export.delete-files-older-than.days

Specify the time period (in days) after which exported data files are automatically purged.

Default = 60 (days)

Details of the Data Integration within PaperCut MF (bottom):

  • Integration.name

Specify the name of your integration that will appear as the title on the Integration box displayed on the Data Integrations page

  • Integration.info

A short sentence to explain what your integration is for, like a 3 second elevator pitch

  • Integration.help

Do you need to provide any helpful steps to use the integration? This is where you provide them.

  • Integration.url

If your integration has a webpage to use it, provide the URL of it here so that a link appears via a button on the PaperCut MF Admin web console. When clicked, the URL will be opened in a new browser tab.

Example of how the configuration parameter map to the UI

Data Integrations properties file
Data Integrations properties file map to UI

4. Save the file.

5. Go to PaperCut MF > Reports > Data Integrations and click Load Integrations to load new integrations and refresh existing integrations files which you have changed.

6. Verify your PaperCut MF usage data exported:

  • Historical Data Export
  • Daily accounts, users, printers, printer_usage_log, servers changes

Exported Data Structure

All data files are exported as Comma Separated Value (CSV) files. The exported CSV’s (including historical data export) are exported under data.export.directoy defined in the configuration file above.

  • The files are saved into a date based folder hierarchy mapping to numerical year and numerical month (ie January = 01) with a file name format TYPE-YYYY-MM-DD.csv
Exported file structure
  • environment-values.csv (contains environment variables defined in PaperCut MF environment config keys. The same file will be overwritten every night in order to support changes to values
  • the printers file contains an added column for PRINTER_GROUP which contains a comma-delimited string of group names (if they’re available)
  • the printer_usage_log are exported in real-time
  • account, user, printer, server and environment datasets are exported nightly during maintenance (ie yesterday’s data is exported)

FAQs

What if the nightly scheduled task time changes?

There are situations where usage data may export twice in the same. This scenario would likely only happen if the PaperCut admin changes the maintenance schedule, causing the maintenance task to run twice on that day. Just in case it does happen, the consumer of our CSV files must be aware of the following:

  1. Each CSV file might contain the same entity (like a user or printer) multiple times. The consumer needs to check if an insert or update is required on their side. I think they would need to do that anyway.
  2. As CSV files can be updated, the consumer must re-import files if/when they have been modified. If they just watch out for newly created files, they might miss out on some data.

If the maintenance job does not run on a day (e.g. because the server is down), this day’s data will not be exported. The admin might have to trigger another initial export to fill the gaps.

If either of these situations applies to you, a workaround that could be followed is dropping the data in your 3rd party application database and to change the PaperCut integration properties file to bulk export historical data. Remember that you would need to set the data.export-historical-data.days-back parameter and to delete the backup flag file named after your integration, in this example .intuitivebi-historical-export-done.


Categories: How-to Articles, Reporting


Keywords: reporting, data, usage log

Comments