Configure Data Integrations
From PaperCut MF version 20.1.0, 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 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
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
- 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:
- 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.
- 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
Last updated March 15, 2024
Comments