Request Content Types

The On Key API makes use of specific content types for sending API requests using the PATCH, POST or DELETE HTTP methods. Use one of the content types below to populate the Content-Type header based on the documentation for any request.

Entity

Content Type: application/vnd.onkey.entity+json

Used to create a resource or execute a custom resource action using a POST request. Put the request body containing the list of entity properties with their values within a properties collection.

Sample Payload

{
  "properties": {
    "code": "ALARM1",
    "description": "Alarm 1",
    "permissionTreeId": 5000001004,
    "notes": "Alarm Notes"
  }
}

EntityCollection

Content Type: application/vnd.onkey.entitycollection+json

Used to create a batch of resources using a POST request. Put the request body for the individual entities within an array within the request body. For every entity, specify a userObjectId to uniquely identify the entity. This will be used to associate any response from the server to the specific entity instance processed - refer to Batch Create for more details.

Sample Payload

[{
  "userObjectId": "record1",
  "properties": {
    "code": "ALARM1",
    "description": "Alarm 1",
    "permissionTreeId": 5000001004,
    "notes": "Alarm 1 Notes"
  }
},
{
  "userObjectId": "record2",
  "properties": {
    "code": "ALARM2",
    "description": "Alarm 2",
    "permissionTreeId": 5000001004,
    "notes": "Alarm 2 Notes"
  }
}]

EntityPatch

Content Type: application/vnd.onkey.entitypatch+json

Used to update a resource or execute a custom resource action using a PATCH request. In addition to the version of the entity being update, add a patch operation to a operations collection for every entity property that needs to change. For every property, use the path to specify the name and the value to specify the change. To clear a value for a property, specify null for the value.

Sample payload

{
  "version": 1,
  "operations": [
    {
      "path": "code",
      "value": "ALARM2"
    },
    {
      "path": "description",
      "value": "Alarm 2"
    }
  ]
}

EntityPatchCollection

Content Type: application/vnd.onkey.entitypatchcollection+json

Used to update a batch of resources using a PATCH request. Put the request body for the individual entities within an array within the request body. For every entity, specify the id and version and also a collection of patch operations within a operations collection - refer to Batch Update for more details.

Sample Payload

[{
  "id": 5000010034,
  "version": 2,
  "operations": [
      {
          "path": "code",
          "value": "CSUP"
      },
      {
          "path": "description",
          "value": "Call Supervisor"
      },
  ]
},
{
  "id": 5000010035,
  "version": 3,
  "operations": [
      {
          "path": "notes",
          "value": "Measurement of critical bearing and gearbox oil temperatures"
      }
  ]
}]

EntityDelete

Content Type: application/vnd.onkey.entitydelete+json

Used to delete a resource using a DELETE request. Specify the version of the entity being deleted within the request body.

Sample payload

{
  "version": 1
}

EntityDeleteCollection

Content Type: application/vnd.onkey.entitydeletecollection+json

Used to delete a batch of resources using a DELETE request. Put the request body for the individual entities within an array within the request body. For every entity, specify the id and version - refer to Batch Delete for more details.

Sample Payload

[{
  "id": 5000010034,
  "version": 2
},
{
  "id": 5000010035,
  "version": 3
}]

EntityMatchUpdateCollection

Content Type: application/vnd.onkey.entitymatchupdatecollection+json

Used to update properties for a batch of entities to match (i.e. have same values) using a PATCH request. For every entity specify the id and version within the records collection. For every change add a patch operation to the operations collection.

Sample Payload

{
  "records": [
    {
      "id": 5000010034,
      "version": 2
    },
    {
      "id": 5000010035,
      "version": 3
    }
  ],
  "operations": [
    {
      "path": "description",
      "value": "All are the same"
    }
  ]
}

EntityImportCollection

Content Type: application/vnd.onkey.entityimportcollection+json

Used to import and action (Create,Update,Delete or Merge) multiple entities using a PUT request. Put the entities to action within an array within the request body. For every entity specify the action, entityType and, if a Merge, Update or Delete action, the id that identifies the entity. The id can be the actual id for the entity or, if not known, a Code or Custom reference lookup converter.

Put the request body containing the list of entity properties with their values within a properties collection. The properties collection is not required for Delete actions. Also include an unique userObjectId that will be used to associate the results returned within the response to the individual entities actioned.

Entities can be grouped and executed in order by appending the optional ordered=true query string parameter to the request uri and by assigning individual entities within the request the same GroupOrder identifier. Groups with a smaller GroupOrder identifier are actioned first.

Sample Payload

[
    {
        "entityType": "Site",
        "action": "Merge",
        "userObjectId": "SAP-XXX",
        "id": {
            "converter": "ReferenceLookup",
            "type": "Code",  
            "code": "CPT"
        },
        "groupOrder": 2,
        "properties": {
            "code": "CPT",
            "description": "Cape Town",
            "permissionTreeId": {
                "converter": "ReferenceLookup",
                "type": "Code",
                "code": "A20"
            },
            "parentSiteId": 5000001001,
            "sequenceNumber": "2",
            "siteTypeId": 5000001000,
            "currencyId": 14,      
            "timeZoneOffset": 2,
            "isVirtual": false
        }
    },
    ...
    {
        "entityType": "SiteType",
        "action": "Merge",
        "userObjectId": "SAP-YYY",
        "id": {
            "converter": "ReferenceLookup",
            "type": "Custom",
            "properties": {
                "SiteType->Code": "WHOUSE"
            }
        },
        "groupOrder": 1,
        "properties": {
            "code": "WHOUSE",
            "description": "Warehouse",
            "permissionTreeId": {
                "converter": "ReferenceLookup",
                "code": "A20"
            }
        }
    }
    ...    
]

EntityExistCheckCollection

Content Type: application/vnd.onkey.entityexistscheckcollection+json

Used to check if entities, that match the criteria specified within the check collection, exist using a PUT request. Put the different check criteria within an array of checks within the request body. For every check specify the checkType, entityType and also the properties to filter on. Also include an unique userObjectId as this will be used to associate a check with the data returned in the response. Refer to the application/vnd.onkey.entityexistscheckresultcollection content type for the structure of the response body content.

Sample Payload

[
    {"checkType" : "Code", "entityType" : "RegularAsset", "userObjectId" : 1, "properties" : 
        {
          "Code": "FOL100"
        }
    },
    {"checkType" : "Custom", "entityType" : "RegularAsset", "userObjectId" : 2, "properties" : 
        {
          "RegularAsset->CostCentre_Code": "095",
          "RegularAsset->AssetType_Code": "BUI001"
        }
    },
    {"checkType" : "Custom", "entityType" : "RegularAsset", "userObjectId" : 3, "properties" : 
        {
          "RegularAsset->CostCentre_Code": "076",
          "RegularAsset->AssetType_Code": "*1089"
        }
    },
    {"checkType" : "Custom", "entityType" : "RegularAsset", "userObjectId" : 4, "properties" : 
        {
          "RegularAsset->CostCentre_Code": "076",
          "RegularAsset->AssetType_Code": "*1084",
          "RegularAsset->AssetType_ParentAssetType_Code": "*1084"
        }
    },
    {"checkType" : "Custom", "entityType" : "ResourceTrade", "userObjectId" : 5, "properties" : 
        {
          "ResourceTrade->Resource_Code": "BERA",
          "ResourceTrade->Trade_Code": "HAND"
        }
    }
]

CustomResourceActionCreate

Content Type: application/vnd.onkey.customresourceactioncreate+json

Used to create a resource action customisation using a POST request. For a request customisation put the customised request body content within the request property. For a response customisation put the customised response body content within the response property.

Sample Payload

{
    "name": "MyAlarmList",
    "description": "This is my alarm list",
    "isTemp": false,
    "response": {
      "properties": [
    	{ "path": "Alarm->Id" },
    	{ "path": "Alarm->Description" }
    	],
    	"orderBy": "Alarm->Id"
    }
}

CustomResourceActionUpdate

Content Type: application/vnd.onkey.customresourceactionupdate+json

Used to update an existing resource action customisation using a PUT request. For a request customisation put the customised request body content within the request property. For a response customisation put the customised response body content within the response property.

Sample Payload

{
    "name": "MyAlarmList",
    "description": "This is my alarm list",
    "response": {
      "properties": [
    	{ "path": "Alarm->Id" },
    	{ "path": "Alarm->Description" },
        { "path": "Alarm->Notes" }
    	],
    	"orderBy": "Alarm->Id"
      }
}

CustomTemplateCreate

Content Type: application/vnd.onkey.customtemplatecreate+json

Used to create a template customisation using a POST request. Put the customised template body content within the content property. Refer to the application/vnd.onkey.template content type for the structure of the template body content.

Sample Payload

{
    "name": "MyAlarmDashboard",
    "description": "This is my alarm dashboard",
    "isTemp": false,
    "content": {
        same as application/vnd.onkey.template+json content type
    }
}

CustomTemplateUpdate

Content Type: application/vnd.onkey.customtemplateupdate+json

Used to update an existing template customisation using a PUT request. Put the customised template body content within the content property. Refer to the application/vnd.onkey.template content type for the structure of the template body content.

Sample Payload

{
    "name": "MyAlarmDashboard",
    "description": "This is my alarm dashboard",
    "content": {
        same as application/vnd.onkey.template+json content type
    }
}

Table of Contents

Request Content Types

Entity

Sample Payload

EntityCollection

Sample Payload

EntityPatch

Sample payload

EntityPatchCollection

Sample Payload

EntityDelete

Sample payload

EntityDeleteCollection

Sample Payload

EntityMatchUpdateCollection

Sample Payload

EntityImportCollection

Sample Payload

EntityExistCheckCollection

Sample Payload

CustomResourceActionCreate

Sample Payload

CustomResourceActionUpdate

Sample Payload

CustomTemplateCreate

Sample Payload

CustomTemplateUpdate

Sample Payload