Custom fields

Several entities in the API support custom fields. Entities supporting this feature allow a user to define custom fields on these entities and provide their own values. This allows a customer to set additional values to, for example, correlate entities with their source system or enrich the attributes of an entity. You could think of adding a custom field like hr-system-id or department on an Employee or a custom field in-house-course-available on the entity Skill.

A custom field can be defined using the POST createCustomFieldDefinitions call. The following example defines the custom field hr-system-id for the Employee entity. The entity type is referred to using the entityDefinitionID. To get a full list of available entity definition IDs you can use the GET /entityDefinitions call.

POST /api/orgkeep/acme/orgkeep/v4/createCustomFieldDefinitions
Content-Type: application/json

{
  "code": "hr-system-id",
  "entityDefinitionID": "1ac17b5c-13be-c79e-3cd0-d7389fe58455",
  "isUnique": true,
  "name": { "en": "HR System ID" },
  "repositoryID": "12345678-2fe4-472f-af41-0c1b936247fa"
}

Note that we set the isUnique property to true. This allows us to retrieve a specific entity through the API using that custom field (see below).

Retrieving entities by custom field

A specific entity can be retrieved through the API by its own unique AG5 defined ID. For example, to fetch an employee with id 100 you could make an API call using the GET employee call like so:

GET /api/orgkeep/acme/orgkeep/v4/employees/100

However, the IDs internally used by AG5 won't correspond with, for example, the IDs of the customer's HR system. When making an integration between AG5 and an external system you may want to track the ID of an entity in the source system in AG5. AG5 allows a customer to create custom fields to accommodate this scenario.

To look up an entity by a custom field, the custom field definition must have the isUnique property set to true. Attempting to look up by a non-unique custom field will result in an Invalid Request response.

Suppose the Employee entity has the custom field hr-system-id defined. Now an employee can be retrieved through its hr-system-id using the following API call using the {customfield}:{value} format for the ID:

GET /api/orgkeep/acme/orgkeep/v4/employees/hr-system-id:C48D038DD