Report Runner Tool

The Report Runner tool available for sites using the Metrix Asset Management system allows users to automate the running and subsequent download of any CSV report available through the system. This can be useful for sites that wish to store spreadsheet versions of their asset data in a local file system for use by other applications or the like.

Getting the Report Runner Tool

To get the Report Runner tool, simply contact our support team. We will provide you with the latest stable version of the tool. The tool is a simple executable file that can be run on any Windows machine.

Setting up the Report Runner Tool

The Report Runner tool leverages a simple configuration file to instruct it on which report(s) to fetch, where to store the downloaded CSV file(s), and how to authenticate with Metrix in order to perform each request. The following outlines the required configuration parameters. Also shown, is an example configuration file.

token: a valid API token (with asset:read scope) generated within your Metrix Asset Management environment. This token is used to authenticate the Report Runner tool with your Metrix environment.
log_file: the file path to which the Report Runner tool should write its log output to. This can be useful for debugging and monitoring purposes.
reports: an ARRAY of report objects that the Report Runner tool should fetch and download. Each report object should contain the following parameters:
- template_id: the unique identifier of the report template you wish to run. This can be seen in the URL when you open any report template within the Metrix Asset Management system. For example, for a report template with a URL of …/reports/template/RTO_E3MWCDP the template id will be RTO_E3MWCDP.
- name: the name of the CSV file you wish to have the report saved as. This should be a simple string value and should NOT include any file path or extension details.
- output_location: the file path to which the Report Runner tool should save the downloaded CSV file to. This should be a valid file path on the machine that the Report Runner tool is being executed on.
- max_status_retries: the maximum number of times the Report Runner tool should retry checking the status of a report run before it gives up on downloading it and moves on to the next report. This can be useful for handling cases where report runs may take a long time to complete. A safe standard value for this field is, 5.
- config: an object containing key-value pairs that represent the configuration parameters for the report you wish to run. For specific advice on what configuration parameters are required for various report templates, see the section below. For any reports that are not listed below, please contact our support team.

Example Configuration File

{
   "token": "super-secure-api-token",
   "log_file": "C:/report-runner/logs/report-runner.log",
   "reports": [
      {
         "template_id": "RTO_E3MWCDP",
         "name": "component_information",
         "output_location": "C:/report-runner/outputs",
         "max_status_retries": 5,
         "config": {
            "selected_date": "${end-of-day}",
            "append_asset_data": false,
            "append_component_data": false,
            "fields_to_include": [ "finance_category", "gross_value", "depreciable_value" ],
            "filter": "$DEFAULT",
            "selected_report_categories": []
         }
      },
      {
         "template_id": "RTB_EFYWCDPP",
         "name": "raw_finance_data_export",
         "output_location": "C:/report-runner/outputs",
         "max_status_retries": 5,
         "config": {
            "selected_date": "${end-of-day}"
         }
      }
   ]
}

Note: in the above example, the keyword ${end-of-day} is used as a special/dynamic value for the selected_date configuration parameter. When the Report Runner tool encounters this keyword, it will automatically replace it with the current date at 11:59:59 PM. This can be useful for ensuring that your reports always run with the most up-to-date data without having to manually update the configuration file each time.

Running the Report Runner Tool

To run the Report Runner tool, simply execute it by calling the following from a command line interface:

report-runner.exe config_file.json

Note: in the above command, the terminal’s current working directory is within the folder that contains both the report-runner.exe file and the config_file.json file.

Report Template Configuration Parameters

The following outlines the required configuration parameters for some of the most commonly used report templates within the Metrix Asset Management system. For any report templates not listed below, please contact our support team.

Component Data Export

Template ID: RTO_E3MWCDP

The Component Data Export report template allows you to export a comprehensive dataset containing information about all of your assets and their components. The report takes the following configuration parameters:

selected_date: the date for which you want to run the report for. This should be in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ) and specified at UTC. Being a date, users can also leverage the dynamic keyword ${end-of-day} for this configuration parameter.
filter: a string value that references the filter to apply to your asset network when running this report. This can either be the ID of a valid filter you have defined, or set to one of the following:
- $DEFAULT: this is the standard default filter that includes all asset types, but excludes disposed and proposed assets.
- $ALL_ASSETS: this is the same as default, but includes disposed and proposed assets as well.
append_asset_data: a boolean value indicating whether you want the report to include asset-level custom attribute data. This option is currently only available when the filter configuration parameter is NOT set to $DEFAULT.
append_component_data: a boolean value indicating whether you want the report to include component-level custom attribute data.
fields_to_include: an array of string values that specify which standard fields you want to include in the report output. The full list of available fields is as follows:
- component_id,
- asset_id,
- component_description,
- asset_description,
- asset_barcode_value,
- barcode_value,
- asset_class,
- asset_type,
- asset_subtype,
- asset_group,
- comp_group,
- depreciable,
- carries_value,
- requires_condition,
- finance_category,
- gross_value,
- depreciable_value,
- designated_period_depreciation,
- accumulated_depreciation_value,
- carrying_value,
- estimated_annual_depreciation,
- last_depreciation_date,
- construction_date,
- intervention_date,
- latest_condition,
- latest_condition_date,
- intervention_treatment,
- intervention_useful_life,
- intervention_residual_life,
- residual_life_offset,
- expected_residual_life,
- cost_units,
- intervention_cost_rate,
- intervention_cost_method,
- next_treatment,
- next_treatment_rate,
- next_treatment_cost_units,
- next_treatment_description,
- next_treatment_reason,
- next_treatment_expected_date,
- status,
- effective_date,
- shape_id,
- shape_wkt,
- shape_x,
- shape_y,
- shape_projection,
- shape_longitude,
- shape_latitude,
- shape_source,
- shape_source_text,
- shape_confidence,
- component_import_reference,
- asset_import_reference,
- asset_record_id,
- component_record_id (automatically injected, need not specify),
- mod_user,
- mod_date
selected_report_categories: an array of string values that specify which report categories you want to include in the report output. The string value to use will be the Report Category label as defined for your site. E.g. “Special Schedule 7”.

Raw Finance Data Export

Template ID: RTB_EFYWCDPP

The Raw Finance Data Export report template allows you to export a dataset containing complete dump of financial transactions from your environment. The report takes the following configuration parameters:

selected_date: the date for which you want to run the report for. This should be in ISO format (YYYY-MM-DDTHH:MM:SS.SSSZ) and specified at UTC. Being a date, users can also leverage the dynamic keyword ${end-of-day} for this configuration parameter.

Asset Data Export

Template ID: REP_A75909GJD

The Asset Data Export provides a comprehensive dataset with one asset per row. Each component is fanned out to columns of the same row. The report takes the following configuration parameters: fields_to_include: an array of string values that specify which standard fields you want to include in the report output. The full list of available fields is as follows:

Construction_Date,
Intervention_Date,
Useful_Life,
Residual_Life,
Cost_Units,
Condition,
Condition_Date,
Treatment,
Treatment_Unit_Rate,
Treatment_UOM append_custom_data: a boolean value indicating whether you want the report to include asset-level custom attribute data. selected_report_categories: an array of string values that specify which report categories you want to include in the report output. The string value to use will be the Report Category label as defined for your site. E.g. “Special Schedule 7”. filter: a string value that references the filter to apply to your asset network when running this report. This can either be the ID of a valid filter you have defined, or set to one of the following:
$DEFAULT: this is the standard default filter that includes all asset types, but excludes disposed and proposed assets.
$ALL_ASSETS: this is the same as default, but includes disposed and proposed assets as well.