QGIS Integration

The Metrix Asset Management system QGIS Plugin enables users to swiftly and easily access their Asset Records directly within the QGIS interface. This provides the capacity to:

• Edit Geometries using QGIS’s powerful editing suite of tools,
• Create detailed maps with custom styling and layouts,
• Overlay other user data for custom integrations

Install

To install the QGIS Plugin we will use the Plugin Manager to add new plugin repository in order to make sure you can receive the latest plugin versions updates when they are released.

1. Select ‘Plugins -> Manage and Install plugins..’

2. Select ‘Settings’

3. In the ‘Plugin’ Repositories section select ‘Add’

4. Use the following details

   • Name: Metrix Assets
   • URL: https://qgis.metrixassets.com/plugins

5. Click ‘Ok’ to add the new repository

You should now have two plugin ‘Plugin Repositories’ shown; the official one and the Metrix Assets one

6. Select the ‘All’ side menu item to show all available plugins

7. Search for ‘Metrix Assets’ and select ‘Install’

Setting Up a Connection

To begin using the QGIS plugin for Metrix Assets we first have to create a connection to the Cloud Portal. To do this:

1. Right click on the Metrix Assets node in your QGIS Browser.

2. Select ‘Connection Settings…’ from the dialogue menu.

   

   NOTE: These options are also available from the Plugin’s Menu Bar.

3. In the resulting dialogue box, set the ‘Client ID’ based on your normal Metrix Assets Portal URL. For example; for a Metrix Assets Portal of http://demo.Metrixassets.com the ‘Client ID’ will be demo.

4. The next step is to setup the Authentication parameters (username and password).

5. Click the ‘+’ icon to begin adding your Authentication parameters.

   NOTE: QGIS maintains its own secure Authentication Parameter store. If you have never setup Authentication Parameters in QGIS before, you will be prompted for a Master Password that secures and encrypts the Parameter Store on your local machine.

6. In the resulting dialogue box, set the following:

   • Name: This is simply a name that can be used to edit this Authentication Parameter at a later date - set it to whatever works best.
   • Username: The email address you sign into Metrix Assets with.
   • Password: The password you use to sign into Metrix Assets with.

7. Click Save once the above parameters are set.

8. You will be taken back to the ‘Connection Settings’ dialogue box with all the required settings now established. To connect to your data, simply click ‘Connect’ with the Authentication Configuration you defined in the ‘Authentication Configuration’ menu.

Loading Data using the Metrix Assets QGIS Plugin

Once you have setup a connection to your Metrix Assets environment, accessing your available layers can be achieved using the QGIS Browser Panel node ‘Metrix Assets’. To do this:

1. If not already connected, right click on the ‘Metrix Assets’ node in the QGIS Browser Panel and click ‘Connect’.

2. Once connected, expand the ‘Metrix Assets’ node in the QGIS Browser Panel to display the layers available. Each layer is constructed by a complete Asset Class.

3. To add a layer to the map, simply double-click the layer, or drag it into the map.

4. From this point, the geometries in the layer can be manipulated just like any other layer in QGIS. That is, to make an alteration to the layer, toggle editing for the layer and process your changes from there, using any native QGIS tools.

   NOTE: Attribute management is NOT currently supported by the tool.

5. Just like standard QGIS methodology, when you have finished making your alterations, simply toggle editing and Save the changes. At this point, your changes have been saved to a local cache on your local machine.

6. The final step is to synchronise these changes with the Cloud. To do this, navigate to the Plugin’s Menu bar and expand the ‘Synchronise’ sub-menu. From this sub-menu, select ‘Push All Local Changes…’

   

7. Your changes will then be processed up to the Cloud and reflected there immediatley.

   

Using the Panel Interface

The Metrix Assets QGIS Plugin also has support for a Panel interface to view the status of your changes per layer. To use this:

1. In the Plugin’s menu bar, ensure ‘Status’ is enabled (ticked).

2. When enabled, you will have access to the Metrix Asset’s control panel which shows the sync status of your changes per layer.

Linking to the Cloud Portal

At any time whilst using the Metrix Assets QGIS Plugin, you can view one or many selected assets in the Cloud Portal with a simple click of a button. To do this:

1. Select one or many assets in your layer.

2. From the Plugin’s menu, select ‘View Selection in Metrix Assets’.

3. This will open your default Internet Browser and show you the selected asset(s) in the portal.

Metrix Sync

Metrix Sync enables administrators to schedule the download of component data locally (on-premise) into a local database. The local data can then be ingested into 3rd party software such as Intramaps/QGIS for viewing purposes only.

For edit capabilities, refer to the QGIS Plugin.

NB. Users can alternatively manually download Reports that can contain more information than Metrix Sync supports such as conditions/financials/treatments.

Features

• Able to be scheduled via Task Scheduler
• Downloads component attribution
• Built-in Search lookup
• Security details are encrypted
• User-defined Database connection parameters
• User-defined Attributes to download
• User-defined Search attributes
• Built-in Metadata
• Asset-based and component-based views per geometry type
• Data loads in popular GIS software such as Intramaps/QGIS
• Support for commonly used database flavors - Microsoft SQL Server
• Self-updating

Requirements

• Windows Operating System
• .NET Framework 4.6.1
• SQL Server 2014+

Installation

Request a Metrix consultant to roll this out for you. Refer to Metrix Sync Admin.

Example Screenshots

Schedule data to sync to a local SQL Server instance and detect changes made since the last sync.

Setup data in 3rd party software with select, search, layer toggle and integration capabilities

Site Integrations

Metrix Site Integrations enable administrators to establish URL-based links to any 3rd-party environment that supports hyperlinking ‘into’. When an end user triggers a site integration link, Metrix will build the target URL (based on the defined parameters of the integration) and redirect the user to that URL in a new browser tab.

There are no restrictions on the shape of the integrating URL aside from those stipulated by the rules of HTTP redirection, being:

• Only GET endpoints are supported,
• Custom request headers cannot be set, since browsers do not allow them for standard link navigation, and
• Request bodies are not supported, (as GET requests do not include a body).

Features

Site integration links support the following features:

• Fully customisable URL endpoint specifications
• Dynamic value injection, including:
  • User click location: latitude/longitude and zoom level of where the user clicked.
  • Active record location: latitude/longitude of the user’s currently active record.
  • Dynamic record values: field values from the user’s currently active record.
  • Static values: to assist with URL re-usability across integration specifications.

Read More

See the following guides for more information on Site Integrations:

• About: Integration Types
• About: Dynamic Field Types
• How To: Creating a new Site Integration
• How To: Constraining Integration Links

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.