Create a Site Integration Link

To set up a new Site Integration link, navigate to the System Admin menu from the profile menu, and then follow the steps below:

1. Select the ‘Site Integrations’ sections from the left-hand side navigation pane within the System Admin page. A list of current Site Integrations will be shown (if any exist).

2. Select an option between ‘New Info Panel Integration’ and ‘New Map Tool Integration’ to initialise a new (blank) integration configuration. See Integration Types for more information on integration types.

3. Firstly, provide a Name for the integration. This name MUST be unique to any other Site Integrations you may have set up. Furthermore, the integration Name will be displayed to the end user as the button text for initiating the link.

4. Next, mark the Site Integration as either ‘Active’ or ‘Inactive’. By default, new setups are set to inactive until an administrator explicitly sets it as active. This setting can be toggled at any time to control the availability of the Site Integration for end users.

5. Enter the URL for the new Site Integration. Any dynamic fields MUST be wrapped by two (2) curly braces and preceded by a period, as per the following:

   • {{.placeholder}} - indicates a dynamic field by the name ‘placeholder’.
   • {{.1invalid placeholder}} - is an invalid placeholder name. Placeholders cannot start with a number or contains spaces or special characters.

   Once you have supplied the URL, click ‘Validate’. This will parse and verify your provided URL as well as identify any placeholders that may exist within the string.

   Example

   As an example, the following URL has three (4) placeholder values:

   https://{{.client}}.com/see_data?lat={{.lat_value}}&lon={{.long_value}}&orgKey={{.my_org_key}}

   They are:

   • client: this placeholder has been situated within the core URL path,
   • lat_value: this placeholder is being used as the ‘value’ for the URL query parameter ’lat’,
   • long_value: this placeholder is being used as the ‘value’ for the URL query parameter ’long’, and
   • my_org_key: this placeholder is being used as the ‘value’ for the URL query parameter ‘orgKey’.

6. For any placeholders that were identified within the URL, you will then need to configure how Metrix is to assign their value. Following validation, a table will be populated with the discovered placeholders. For each of the placeholders, select a valid ‘Key Type’ and, if required, supply a ‘Value’ that corresponds with the chosen ‘Key Type’.

   See Dynamic Field Types for more information on these key types.

   Warning

   If you have modified a pre-existing URL value (and subsequently performed another ‘Validation’), some of your placeholders may be ‘flagged for removal’. This means that the Site Integration URL previously contained a placeholder by the respective name, but that placeholder is no longer present.

   You will not be able to proceed with saving the Site Integration until you explicitly remove these orphaned placeholders by clicking the ‘delete’ option on the respective row.

7. For ‘Info Panel Integrations’, it is possible to OPTIONALLY constrain the integration’s availability. That is, you can specify that it only appears to an end user who has clicked on an asset/component:

   • that is of one or more Asset/Component Classifications, or
   • that is assigned to one or more Report Category Options.

   To set up constraints for your Integration, see Constraining Integration Links for additional steps to follow.

8. Once you have completed all the above (as is relevant), simply click ‘Save’ at the top of the form. The Site Integration, if marked as Active in step 4, will appear immediately following a browser refresh for end users.

Constraining Site Integration Links

To constrain the presence of a new or existing Info Panel Integration link, perform the following steps whilst editing (or creating a new) Site Integration Link:

1. From the Info Panel Integration Link edit form, click ‘Manage Integration Constraints’. A panel will appear with constraint options for the Integration.

   Info

   If you are editing an existing Info Panel Integration that is already constrained, this button will read either:

   • ‘Manage Classification Constraints’, or
   • ‘Manage Report Category Constraints’.

   For Map Tool Integrations, this button will not display at all.

2. For unconstrained Integrations the default state for this panel is ‘Classification’ based constraints. If the intention is to constrain the Integration via assignment to one or more Report Category Options, simply click ‘Use Category Constraints’.

   Info

   It is not possible to use both ‘Classification’ and ‘Report Category’ constraints on the same Integration configuration. Furthermore, if any constraints (of a specific type) have been applied previously to the Integration, then these will need to be fully removed before switching to the alternate constraint type.

3. For each of the constraints you wish to assign to the Integration, simply click ‘Assign’ next to the relevant option.

   For Classification Constraints
   The panel will be split into two halves. The upper-half lists Asset Classifications whilst the lower-half lists Component Classifications.

   Constraining an Integration to one or more Asset Classifications means that the current Integration will only appear in the Asset Info Panel for Assets of that/those types.

   Constraining an Integration to one or more Component Classifications means that the current Integration will only appear in the Component Info Panel for Components of that/those types.

   It is allowed to specify BOTH Asset and Component Classifications as constraints to any one Integration configuration.

   For Report Category Option Constraints The panel will show a single list of available Report Category Options.

   Constraining an Integration to one or more Report Category Options means that the current Integration will only appear in the Component Info Panel for Components that have been assigned to that/those category options.

4. To remove a constraint, simply click ‘Unassign’ next to the relevant option.

5. Once finished, simply click ‘Done’ at the top of the panel to stage your changes and close the panel.

   Warning

   The changes to Integration Constraints only take effect if you subsequently ‘Save’ the Integration after the constraints panel closes. Up until such point, the changes to constraints are merely staged for commit.

Integration Types

There are two (2) Integration Types supported by the Metrix Asset Management system.

• Info Panel Integrations: will appear in a (relevant) info panel when a user selects a record in the main Assets page.
• Map Tool Integrations: will appear as an option in the ‘Integrations’ menu within main Asset page’s map window. Note: if no map tool integrations exist, the ‘Integrations’ menu will not show in the map window.

The following explains the above Integration Types in further detail.

Info Panel Integrations

These integrations will appear as a button within relevant info panels when an end user selects a record in the main Assets page. Info Panel Integrations support several Dynamic Field Types as well as options for Constraining Integration Links.

Dynamic Fields Available for Info Panel Integrations

• Record Value: a value that is pulled from the selected record in the main Assets page. When using this dynamic field type, administrators will need to specify (as a ‘value’) which field value to pull from the selected record.
• Record Location: the latitude and/or longitude coordinates (WGS84) of the selected record in the main Assets page. No ‘value’ specification is required when using one of these location types of dynamic fields.
• Static Value: a value that is set by the administrator when creating the integration link and does not change. When using this dynamic field type, administrators will need to specify (as a ‘value’) the static value that they want to be injected into the Integration Link.

Constraining Info Panel Integrations

• Record Classification: the Asset and/or Component Classification(s) of the selected record in the main Assets page.
• Record Report Category: whether the selected record in the main Assets page has a Report Category assigned or not.

Map Tool Integrations

These integrations will appear as an option in the ‘Integrations’ menu within main Asset page’s map window. End users will choose an Integration from the menu and then proceed to CLICK the map to activate the integration link. The click location and the current zoom level of the map will be supplied as dynamic field values to the Integration Link.

Dynamic Fields Available for Map Tool Integrations

• Click Location: the latitude and longitude coordinates (WGS84) of the user’s click on the map. No ‘value’ specification is required when using this dynamic field type.
• Map Zoom Level: the current zoom level of the map when the user clicks on the map to activate the integration link. No ‘value’ specification is required when using this dynamic field type.
• Static Value: a value that is set by the administrator when creating the integration link and does not change. When using this dynamic field type, administrators will need to specify (as a ‘value’) the static value that they want to be injected into the Integration Link.

Constraining Map Tool Integrations

Constraining Map Tool Integrations is not supported.

Dynamic Field Types

There are several Dynamic Field Types that can be specified when configuring placeholder values within a Site Integration Link. The following list details the Dynamic Field Types that are currently supported by the Metrix Asset Management system:

Static Values

A value that is set by the administrator when creating the integration link and does not change. When using this dynamic field type, administrators will need to specify (as a ‘value’) the static value that they want to be injected into the Integration Link.

The use case for these types of dynamic fields (as opposed to simply hardcoding the value into the URL itself) is to allow administrators to easily re-use the same URL for multiple integration links, and simply update the static value for each link as required.

Feature Attribute Values

A value that is derived from the end user’s active record. As such, this dynamic field type is only available for Info Panel Integrations. When using this dynamic field type, administrators will need to specify (as a ‘value’) which field value to pull from the selected record in the main Assets page.

At present, the following field names are supported for this dynamic field type:

• record_id: the Cloud Record ID for the Asset/Component record.
• description: the Description field value for the Asset/Component record.

NOTE: Any custom field can also be used as a Feature Attribute. This will retrieve the specified custom attribute value from the Asset/Component record (if it exists). For these fields, the ‘value’ to specify should be the ID/CODE of the specific Custom Attribute. These can be found in the relevant Form Specification.

Click Location Latitude Values

The latitude coordinate (WGS84) of where the end user clicks on the map the activate the integration.

No ‘value’ specification is required when using this dynamic field type.

Click Location Longitude Values

The longitude coordinate (WGS84) of where the end user clicks on the map the activate the integration.

No ‘value’ specification is required when using this dynamic field type.

Map Zoom Level Values

The current zoom level of the map when the end user clicks on the map to activate the integration. The zoom level is specified as a number between 0 and 25 (as per Web Map Tile Zoom Levels).

No ‘value’ specification is required when using this dynamic field type.

Record Location Latitude Values

The latitude coordinate (WGS84) of the selected record in the main Assets page.

No ‘value’ specification is required when using this dynamic field type.

Record Location Longitude Values

The longitude coordinate (WGS84) of the selected record in the main Assets page.

No ‘value’ specification is required when using this dynamic field type.