In Urgent a Matrix is used as a generic hierarchical method of categorization within the platform. For use with the API each Matrix Item is given a unique value, known as a Matrix Code, set against it and based on the type of matrix to identify that particular matrix item from all the others available to the tenant.

Matrix Types

The types of matrix supported by the platform can be returned via the /matrices/{tenant} method. The values of this method can be used to feed into the next method to get the content of the matrix. The matrices in use by a tenant vary depending on their specific configuration. The table below details all the types of matrix in the Urgent platform, and those in bold would be used by the majority of tenants.

While the matrices do not change on a set basis it is still good practice to regularly (perhaps once a week at most) to read and update your own copies of these matrices so that they are up to date and include new, updated and removed matrix entries.

Type	Notes
Asset	Categorization of Assets
Event	Logging of non-maintenance activities
Geographic Area	Geographic categorization of sites
Licenses and Permits	Categorization of a site's operating permits
Reactive	Categorization of reactive maintenance issues
Safety	Categorizaton of safety audits
Scheduled	Categorization of scheduled works, usually critical, compliance, statutory, recommended etc.
Scheduled Task Category	Type of scheduled task, typically Planned, Inspection etc.
Site Channel	Business unit categorization of sites
Survey	Categorization of Site Surveys
Task Permit	Categorization of Task Permits
Task Resolution Cause	The possible answers to the Task Resolution Cause question asked, if enabled, during a Task Status Change
Task Resolution Remedy	The possible answers to the Task Resolution Remedy question asked, if enabled, during a Task Status Change

Read All Matrices by Tenant

GET /matrices/{tenant}

This method returns the name and the active flag for each matrix type the API supports within a tenant, and for each item within the matrix, the text, a unique code and the active flag which is used throughout the platform, for example, when creating a reactive task. To find the individual hierarchy levels of a matrix item, simply split (and trim) the text it at the > character.

Example response

{
    "Matrices": [
        {
            "Name": "Reactive Matrix",
            "IsActive": true,
            "Items": [
                {
                    "Code": "01-01-01",
                    "Text": "Reactive Matrix > Coffee Machine > Pot Broken",
                    "IsActive": true
                },
               {
                    "Code": "01-02-01",
                    "Text": "Reactive Matrix > Pump > Nozzle Clogged",
                    "IsActive": true
                }
            ]
        }
    ]
}

Read All Matrices by Tenant by Type

GET /matrices/{tenant}/{type}

The type variable is the type of the Matrix you are requesting from the list at the top of this page. This method returns the name and the active flag for each matrix type specified within a tenant, and for each item within the matrix, the text, a unique code and the active flag which is used throughout the platform, for example, when creating a reactive task. It is more targeted than the previous request allowing you to return and process less data.

The optional includeInActive query string parameter is used to specify whether in-active matrices or matrix items are returned.

Example response

{
    "Matrices": [
        {
            "Name": "Reactive Matrix",
            "IsActive": true,
            "Items": [
                {
                    "Code": "01-01-01",
                    "Text": "Reactive Matrix > Coffee Machine > Pot Broken",
                    "IsActive": true
                },
               {
                    "Code": "01-02-01",
                    "Text": "Reactive Matrix > Pump > Nozzle Clogged",
                    "IsActive": true
                }
            ]
        }
    ]
}

Read All Matrices by Tenant by Name

GET /matrices/{tenant}/{type}/{name}

If you know the exact name of the matrix you are after, in your local language, you can use this method to retrieve it and only it. This method returns the name and the active flag for the named matrix within a tenant, and for each item within the matrix, the text, a unique code and the active flag which is used throughout the platform, for example, when creating a reactive task. It is more targeted than the previous request allowing you to return and process less data.

The optional includeInActive query string parameter is used to specify whether in-active matrices or matrix items are returned.

Example response

{
    "Matrices": [
        {
            "Name": "Reactive Matrix",
            "IsActive": true,
            "Items": [
                {
                    "Code": "01-01-01",
                    "Text": "Reactive Matrix > Coffee Machine > Pot Broken",
                    "IsActive": true
                },
               {
                    "Code": "01-02-01",
                    "Text": "Reactive Matrix > Pump > Nozzle Clogged",
                    "IsActive": true
                }
            ]
        }
    ]
}

Read Matrix Mappings

GET /matrices/{tenant}/mapping/{matrixCode}

This method returns a list of reactive matrices and the assigned asset and task resolution matrices (V29) available as options based on the partial/complete reactive matrix code. The resulting codes can be compared with the results from the Matrix By Type method for the relevant matrix to get the text value of the matrix.

Example response

{
  "ReactiveMatrixCode": "0B-01-01-01",
  "AssetMatrixCodes": [
  {
      "01-01-01-01",
      "01-01-01-02"
  }],
  "TaskResolutionCauseMatrixCodes": [
  {
      "01-01-01-01",
      "01-01-01-02"
  }],
  "TaskResolutionRemedyMatrixCodes": [
  {
      "01-01-01-01",
      "01-01-01-02"
  }]
}