Attributes

On Key allows the capturing of additional data that can be stored as an association with existing data records using Attributes. Clients can define their own custom attributes that can capture any kind of data using a special complex data type called a Dynamic Value. Client's can also restrict the values being captured into these attributes to a specific client-defined list of values or even support a combination of both where either any value or an existing pre-defined value can be captured.

Any Value

To support capturing Attributes that can contain any value, the On Key API captures the detail using a special complex data type called a Dynamic Value. A Dynamic Value consists out of the value and type defined for a field. When sending any values for these custom fields via the On Key API, both the type and value information need to be specified.

The different data types supported by Dynamic Values are:

Data Type	Description	Example
Boolean	Capture true or false values	true
Currency	Capture monetary values	100.50
Date	Capture year, month and day values	2025-10-15
DateTime	Capture date and time values	2025-10-15 06:35:00
Duration	Capture information about a period of time using ISO8601 Duration Format	P4DT12H30M5S
Email	Capture e-mail addresses	joe.doe@google.com
Float	Capture floating point numbers	1000.523
Integer	Capture whole numbers	1000
Long	Capture range of whole numbers wider than those provided by Integer	1742822319100685
Time	Capture hour, minute and second values	20:35:02
String	Capture sequence of alpha-numeric characters	My asset description

To illustrate, consider the following example that adds a Make Attribute to a Work Order. In this example, Make is defined as an Attribute of type String that can capture any value.

curl -X 'POST' \
  'https://{server}/api/tenants/{client}/{connection}/modules/wm/workorders/attributes' \
  -H 'Content-Type: application/vnd.onkey.entity+json' \
  -H 'Authorization: Bearer {accessToken}' \  
  -d '{
  "properties": {
    "workOrderId": 1742822319100685,
    "attributeId": {
      "converter": "ReferenceLookup",
      "code": "Make"
    },
    "value": {
      "type": "String",
      "value": "Caterpillar"
    },
    "predefinedValueId": 0,
    "permissionTreeId": 0,
  }
}'

Notice that the value property for the Work Order Attribute is a Dynamic Value that specifies both the type and value to be used. In this example, the Id of the attribute is resolved using a Schema Converter.

Predefined Value

When capturing Attributes that should match a list of predefined values, the On Key API expects the Id of the specific predefined value item to be provided. For Attributes the value is captured within a predefinedValueId field and reflects the Id of the selected Attribute Allowed Value.

To illustrate, consider the following example that adds a ContactEmail attribute to the Attributes of a Work Order. In this example, ContactEmail is defined as an Attribute with a predefined list of allowed email addresses:

Attribute Allowed Value Id	Email Address
1742822319102685	artisan@mydomain.net
1742822319102686	manager@mydomain.net

curl -X 'POST' \
  'https://{server}/api/tenants/{client}/{connection}/modules/wm/workorders/attributes' \
  -H 'Content-Type: application/vnd.onkey.entity+json' \
  -H 'Authorization: Bearer {accessToken}' \  
  -d '{
  "properties": {
    "workOrderId": 1742822319100685,
    "attributeId": {
      "converter": "ReferenceLookup",
      "code": "ContactEmail"
    },
    "predefinedValueId": 1742822319102686,
    "permissionTreeId": 0,
  }
}'

Using a Schema Converter, the request can also be altered to automatically resolve the predefinedValueId using the value specified, i.e:

curl -X 'POST' \
  'https://{server}/api/tenants/{client}/{connection}/modules/wm/workorders/attributes' \
  -H 'Content-Type: application/vnd.onkey.entity+json' \
  -H 'Authorization: Bearer {accessToken}' \  
  -d '{
  "properties": {
    "workOrderId": 1742822319100685,
    "attributeId": {
      "converter": "ReferenceLookup",
      "code": "ContactEmail"
    },
    "predefinedValueId": {
      "converter": "ReferenceLookup",
      "type": "Custom",
      "properties": {
        "AttributeAllowedValue->Attribute_Code": "ContactEmail",
        "AttributeAllowedValue->Value": {
          "type": "Email",
          "value": "manager@mydomain.net"
        }
      }
    },
    "permissionTreeId": 0,
  }
}'

Any Value or Predefined Value

When capturing Attributes that support any value or a list of predefined values, simply set either the value or predefined value as highlighted above.

Important

When updating existing records to switch from a predefined value to any value or vice versa, it is important to remember to also clear the old predefinedValueId or value by setting it to null within the PATCH request.