Custom Fields

Introduction

Custom fields allow users to assign custom properties to holders. For example, a custom field could be used to store an employee ID. These values can then be set and retrieved via the customFields property of the holder object. Custom fields are scoped to a partition, so each partition can have a separate set of custom fields.

The custom field object

{
  "id": "test_custom_field",
  "type": "string",
  "displayName": "Test Custom Field",
  "visibility": "visible"
}

Property	Type	Description
id	String	The field ID.
type	String	The field type. Possible values include array, boolean, enum (dropdown), number, object (field group), and string.
displayName	String	The field display name.
required	Boolean	Whether the field is required. The default value is false.
visibility	String	The visibility setting. Possible values include hidden, readonly, and visible. The default value is visible.
items	Object	A custom field object that defines the properties of the items in an array field.
minLength	Integer	The minimum number of items in an array field.
maxLength	Integer	The maximum number of items in an array field.
values	Object[]	An array of objects representing the values in an enum (dropdown) field. Each object in the array has a required id parameter and an optional displayName parameter.
min	Integer	The minimum value in a number field.
max	Integer	The maximum value in a number field.
decimals	Integer	The number of decimal places allowed in a number field.
fields	Object[]	An array of custom field objects that define the child fields within an object field (field group).
regex	String	A regular expression used for validation of a string field.

Basic Endpoints

Create a custom field

Request

POST https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}}/custom-fields/single HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "id": "test_custom_field",
  "type": "string",
  "displayName": "Test Custom Field"
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
system_token	Header	String	Yes	A valid system token.
id	Body	String	Yes	The field ID.
type	Body	String	Yes	The field type. Possible values include array, boolean, enum (dropdown), number, object (field group), and string.
displayName	Body	String	No	The field display name. If this value is not provided, the id will be used as the display name.
required	Body	Boolean	No	Whether the field should be required. The default value is false.
visibility	Body	String	No	The visibility setting. Possible values include hidden, readonly, and visible. The default value is visible.
items	Body	Object	Sometimes	A custom field object that defines the properties of the items in an array. This is required when type is set to array. Unlike its parent, this child object does not have an id property, but the type property is required. Possible values for the type property include boolean, enum (dropdown), number, and string.
minLength	Body	Integer	No	The minimum number of items in an array field.
maxLength	Body	Integer	No	The maximum number of items in an array field.
values	Body	Object[]	Sometimes	An array of objects representing the values in a dropdown field. This is required when type is set to enum. Each object in the array has a required id parameter and an optional displayName parameter.
min	Body	Integer	No	The minimum value in a number field.
max	Body	Integer	No	The maximum value in a number field.
decimals	Body	Integer	No	The number of decimal places allowed in a number field. The minimum is 0 and the maximum is 10.
fields	Body	Object[]	Sometimes	An array of custom field objects that define the child fields within a field group. This is required when type is set to object. The id and type properties are required for each child object. Possible values for the type property include boolean, enum (dropdown), number, and string.
regex	Body	String	No	A regular expression used for validation of a string field. The maximum length is 255 characters.

Response

The response contains the ID of the newly created custom field object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "test_custom_field"
}

Retrieve a custom field

Request

GET https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}}/custom-fields/{{custom_field_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
custom_field_id	Path	String	Yes	The custom field ID.
system_token	Header	String	Yes	A valid system token.

Response

The response contains a custom field object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "test_custom_field",
  "type": "string",
  "displayName": "Test Custom Field",
  "visibility": "visible"
}

Update a custom field

Request

PUT https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}}/custom-fields/{{custom_field_id}} HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "type": "string"
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
custom_field_id	Path	String	Yes	The custom field ID.
system_token	Header	String	Yes	A valid system token.
type	Body	String	Yes	The field type. Possible values include array, boolean, enum (dropdown), number, object (field group), and string.
displayName	Body	String	No	The field display name. If this value is not provided, the id will be used as the display name.
required	Body	Boolean	No	Whether the field should be required. The default value is false.
visibility	Body	String	No	The visibility setting. Possible values include hidden, readonly, and visible. The default value is visible.
items	Body	Object	Sometimes	A custom field object that defines the properties of the items in an array. This is required when type is set to array. Unlike its parent, this child object does not have an id property, but the type property is required. Possible values for the type property include boolean, enum (dropdown), number, and string.
minLength	Body	Integer	No	The minimum number of items in an array field.
maxLength	Body	Integer	No	The maximum number of items in an array field.
values	Body	Object[]	Sometimes	An array of objects representing the values in a dropdown field. This is required when type is set to enum. Each object in the array has a required id parameter and an optional displayName parameter.
min	Body	Integer	No	The minimum value in a number field.
max	Body	Integer	No	The maximum value in a number field.
decimals	Body	Integer	No	The number of decimal places allowed in a number field. The minimum is 0 and the maximum is 10.
fields	Body	Object[]	Sometimes	An array of custom field objects that define the child fields within a field group. This is required when type is set to object. The id and type properties are required for each child object. Possible values for the type property include boolean, enum (dropdown), number, and string.
regex	Body	String	No	A regular expression used for validation of a string field. The maximum length is 255 characters.

Response

HTTP/1.1 204 No Content

Delete a custom field

Request

DELETE https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}}/custom-fields/{{custom_field_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
custom_field_id	Path	String	Yes	The custom field ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

List all custom fields

Request

GET https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}}/custom-fields HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
system_token	Header	String	Yes	A valid system token.

Response

The response contains an array of custom field objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "test_custom_field_1",
    "type": "string",
    "visibility": "visible",
    "displayName": "Test Custom Field 1"
  },
  {
    "id": "test_custom_field_2",
    "type": "string",
    "visibility": "visible",
    "displayName": "Test Custom Field 2"
  }
]

Update all custom fields

Request

The request contains an array of custom field objects. Note that this operation will overwrite all existing custom fields.

POST https://systems.pdk.io/{{system_id}}/partitions/{{partition_id}}/custom-fields/all HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

[
  {
    "id": "test_custom_field_1",
    "displayName": "Test Custom Field 1",
    "type": "string"
  },
  {
    "id": "test_custom_field_2",
    "displayName": "Test Custom Field 2",
    "type": "string"
  }
]

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
partition_id	Path	String	Yes	The partition ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content