User Defined Fields

On Key allows the capturing of additional, client specific structured that can be stored directly onto their data records using User Defined Fields (UDF's). Clients can define their own custom fields that can capture any kind or data. Client's can also restrict the values being captured into these custom fields 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 UDF's that can contain any value, the On Key API captures the detail for these fields just like any normal property in a request.

To illustrate, consider the following extract of a payload snippet that sets the Make UDF on a Work Order. In this example, Make is defined as a UDF of type String that can capture any value.

curl -X 'POST' \
  'https://{server}/api/tenants/{client}/{connection}/modules/wm/workorders' \
  -H 'Content-Type: application/vnd.onkey.entity+json' \
  -H 'Authorization: Bearer {accessToken}' \  
  -d '{
  "properties": {
    "code": "R00130",
    "permissionTreeId": 5000001010,
    ...    
    "make": "Caterpillar"
    ...
  }
}'

Predefined Value

When capturing UDF's 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 UDF's, the value is captured within a <UDF Name>PredefinedValueId field where <UDF Name> is the name of the specific UDF and the value reflects the Id of the selected User Defined Field Predefined Value.

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

User Defined Field Predefined Value Id	Email Address
1742822319102685	artisan@mydomain.net
1742822319102686	manager@mydomain.net

  "properties": {
    "code": "R00130",
    "permissionTreeId": 5000001010,
    ...
    "contactEmailPredefinedValueId": 1742822319102686,
    ...
  }

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

  "properties": {
    "code": "R00130",
    "permissionTreeId": 5000001010,
    ...
    "contactEmailPredefinedValueId": {
      "converter": "ReferenceLookup",
      "type": "Custom",
      "properties": {
        "UserDefinedFieldPredefinedValue->UserDefinedField_Name": "ContactEmail",
        "UserDefinedFieldPredefinedValue->Value": {
          "type": "Email",
          "value": "manager@mydomain.net"
        }
      }
    },
    ...
  }

Any Value or Predefined Value

When capturing UDF's 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 value by setting it to null within the PATCH request.

Tip

To simplify the capturing of client specific UDF's that can match any value or a specific list of predefined values, a special User Defined Field Value Schema Converter can be used. Refer to User Defined Field Value Converter for more details.