Table of Contents

Schema Converters

On Key API calls support the use of a few pre-defined schema converters within API requests. Schema converters transform data provided within an API request after the payload is received, but before the payload is processed by the server. This allows On Key to execute conversions/transformations on the payload data being provided before the data is processed by the server.

Tip

Schema converters are provided to make it easier to issue certain types of API requests. Using them is optional.

Reference Lookup Converter

A reference lookup converter automatically assigns the Id for a reference/lookup using a lookup strategy. A reference/lookup can can be viewed as a relationship between two different resources, i.e. the Asset associated with a Work Order.

Two lookup strategies are currently supported:

  1. Code - find the Id for the reference using the code specified with the converter
  2. Custom - find the Id for the reference using the combination of property values specified with the converter

When a request with a reference lookup converter is received, the server automatically does the lookup for the reference using the converter strategy specified. If found, it automatically resolves and assigns the Id to the property to ensure that the reference is set before the request proceeds.

To illustrate, consider the following json payload for creating an Asset Importance resource without using a reference lookup converter.

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances \
-H 'Content-Type:application/vnd.onkey.entity+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "properties": {
          "code": "HIGH",
          "description": "High Importance",
          "notes": "High Importance",
          "weight": 1,
          "permissionTreeId" : 5000000
        }
    }'

Notice the permissionTreeId reference lookup property needs to be set with a value which you can get by doing separate API calls.

In data integration scenarios you often do not know the specific Id or just want the server to figure out what the Id is by either specifying the well-known Code or by specifying a combination of property values to identify the entity.

Code Lookup Converter

The following request illustrates the same json payload to create an Asset Importance resource, but this time it uses a Code resource lookup converter to resolve the PermissionTreeId.

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances \
-H 'Content-Type:application/vnd.onkey.entity+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "properties": {
          "code": "HIGH",
          "description": "High Importance",
          "notes": "High Importance",
          "weight": 1,
          "permissionTreeId": {
             "converter": "ReferenceLookup",
             "type": "Code",
             "code": "A20"
          }
        }
    }'

When the request is received by the server, the server will do a reference lookup for the permissionTreeId property and use A20 as code to automatically resolve the PermissionTree lookup. If found, the id will be assigned to the permissionTreeId before the server starts processing the request.

As the Code Reference Lookup Converter is the default schema converter for the system, you can use its shorthand notation by omitting the converter and type properties and just specify the code, for example:

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances \
-H 'Content-Type:application/vnd.onkey.entity+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "properties": {
          "code": "HIGH",
          "description": "High Importance",
          "notes": "High Importance",
          "weight": 1,
          "permissionTreeId": {
             "code": "A20"
          }
        }
    }'

If the code was not found, the request will fail.

{
    "messages": [
        {
            "code": "Core_ValueCouldNotBeConverted",
            "message": "Value specified for property {AssetImportance->PermissionTree_Id} could not be converted or resolved.",
            "properties": [
                "AssetImportance->PermissionTree_Id"
            ],
            "severity": "error"
        }
    ]
}

Custom Lookup Converter

The following request illustrates a sample json payload to create a Warehouse resource using a combination of Code and Custom resource lookup converters to resolve the different required references/lookups on the Warehouse.

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/mm/warehouses \
-H 'Content-Type:application/vnd.onkey.entity+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "properties": {
          "code": "CPT",
          "description": "Cape Town Warehouse",
          "notes": "Main warehouse in Western Cape",
          "permissionTreeId": {
            "converter": "ReferenceLookup",
            "type": "Code",
            "code": "A20"
          },
          "costCentreId": {
            "converter": "ReferenceLookup",
            "type": "Code",
            "code": "065"
          },
          "siteId": {
            "converter": "ReferenceLookup",
            "type": "Custom",
            "properties": {
                "Site->Code": "A10",
                "Site->SiteType_Code": "FAC"
            }
          }
        }
    }'

When the request is received by the server, the server will do a reference lookup for the permissionTreeId and costCentreId properties and use A20 and 065 as the codes to automatically resolve the PermissionTree and CostCentre references. It wiIll also resolve the Site for the Warehouse by finding a Site with A10 set for its Code and FAC set for the Code of the SiteType associated with the Site.

If Site, CostCentre or PermissionTree entities matching these filter criteria were not found, the request will fail.

{
    "messages": [
        {
            "code": "Core_ReferenceLookupNoMatchFound",
            "message": "Reference lookup match could not be found",
            "properties": [
                "Warehouse->CostCentre_Id"
            ],
            "severity": "error"
        },
        {
            "code": "Core_ReferenceLookupNoMatchFound",
            "message": "Reference lookup match could not be found",
            "properties": [
                "Warehouse->Site_Id"
            ],
            "severity": "error"
        }
    ]
}

User Defined Field Value Converter

A User Defined Field Value Converter (UDFVC) automatically resolves and assigns the value for User Defined Fields that support both a list of predefined values or any ad-hoc value. If the value provided for the UDF field matches any of the existing predefined values, the UDFVC will automatically resolve and use the Id of the predefined value. If no match is found in the list of predefined values, the UDFVC will use the value provided.

To illustrate, consider the following json payload for creating an Asset Importance resource with an ReviewStatus UDF. The ReviewStatus UDF can contain an ad-hoc value or be any one of the following list of predefined values:

  • NotDone
  • UnderReview
  • Accepted
  • Rejected

The following request illustrates how to set the value for the ReviewStatus to NotDone without using a UDFVC.

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances \
-H 'Content-Type:application/vnd.onkey.entity+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "properties": {
          "code": "HIGH",
          "description": "High Importance",
          "notes": "High Importance",
          "weight": 1,
          "permissionTreeId" : 5000000
          "reviewStatusPredefinedValueId": {
            "converter": "ReferenceLookup",
            "type": "Custom",
            "properties": {
              "UserDefinedFieldPredefinedValue->UserDefinedField_Name": "ReviewStatus",
              "UserDefinedFieldPredefinedValue->Value": {
                "type": "String",
                "value": "NotDone"
              }
            }
          }          
        }
    }'

Notice that the name of the UDF as well as data type and value needs to be specified.

The following request illustrates how to set the value for the ReviewStatus to an ad-hoc value not available in the predefined list without using a UDFVC.

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances \
-H 'Content-Type:application/vnd.onkey.entity+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "properties": {
          "code": "HIGH",
          "description": "High Importance",
          "notes": "High Importance",
          "weight": 1,
          "permissionTreeId" : 5000000
          "reviewStatus": "DecisionPending"
        }
    }'

Notice that a different payload, setting only the reviewStatus to the ad-hoc value, needs to be specified.

Using a UDFVC, a consistent payload that caters for both scenarios can be created. The following request illustrates how to set the UDF to a value in the predefined list of values while using a UDFVC:

curl -v -X POST https://{server}/api/tenants/{client}/{connection}/modules/risk/assetimportances \
-H 'Content-Type:application/vnd.onkey.entity+json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
        "properties": {
          "code": "HIGH",
          "description": "High Importance",
          "notes": "High Importance",
          "weight": 1,
          "permissionTreeId" : 5000000
          "reviewStatus": { 
            "converter": "UserDefinedFieldValueResolve",
            "value" : "NotDone"
          }          
        }
    }'

Notice that the value property can now be used for setting both a predefined or any value. The UDFVC will try to find the Id of the value in the list of predefined values. If found, it will automatically set the reviewStatusPredefinedValueId to the correct Id. If not found, it will use the value provided to set the reviewStatus UDF.

Note

When changing the value for the UDF from a predefined value to any value of vice versa, the UDFVC will also take care of clearing the respective value not used anymore.

Reference Lookup System Filters

Reference Lookup System Filters are filters applied by On Key to prevent users from using records that are managed by On Key itself. For example, On Key stores a backup record of all Asset Type records as part of the Asset Type Development functionality and this system data should not be used. On Key therefore automatically applies a system filter to any Asset Type related Reference Lookup to prevent the records from being returned.

Note

In almost all scenarios, this kind of system data should be ignored. However, if for some reason there is a requirement to circumvent the filter, users can opt out of the filter being applied by adding ?skipRLSFilter=true to the request being issued.

On Key ships with the following system filters.

Asset Type Development Status System Filter

This filter prevents Asset Type related records from being returned based on the following filter criteria:

Property Filter Reason
IsBackup IsBackup = false Don't return records that are under development and have not been confirmed
DevelopmentStatus DevelopmentStatus <> 'DeletedConfirmed' Don't return records that have been confirmed as deleted

Asset Development Status System Filter

The filter prevents Asset related records from being returned based on the following filter criteria:

Property Filter Reason
IsProposed IsProposed = false Don't return records that are under development and have not been confirmed
DevelopmentStatus DevelopmentStatus <> 'DeletedConfirmed' Don't return records that have been confirmed as deleted