Subsections of How To Guides

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:

Info

If you do not see a profile menu item titled ‘System Admin’, and you are a System Administrator, please contact the Metrix Support team for assistance.

  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.