Defining Entity Types

Entity Types define schemas for Live Data that will be managed within Data Refinery Workbench. Every Live Data object is based on exactly one Entity Type. An Entity Type associates a name with a set of Attribute Types. An Attribute Type defines an attribute name, along with data validation for the attribute.

An Entity Type is the basis of a Workflow Definition and Data Objects, and is used to define important characteristics of Data Objects, including:

  • Key Attributes, which are attributes that define a unique Data Object. Data Objects that share the same value for all key attributes are treated as the same object.
  • Required Attributes, which must be provided with a value to successfully save an Object using that Entity Type.
  • Optional Attributes, which are attributes that can be provided but are not required.
  • Attribute Display Order, which can optionally customize the display order of Attributes.

An Entity Type can have up to 5 key Attributes, and a maximum of 100 total Attributes. The Entity Type can also define Validation for each Attribute. See Attribute Validation for more information.

To manage Entity Types, a user must work with Data Refinery Workbench APIs. This page will explain how to use Data Refinery Workbench APIs to retrieve, create, update, and delete Entity Types.

To perform any of the following actions, a user must have the DEFINITION_ADMIN permission.

Table of contents

How to Retrieve an Existing Entity Type

The Entity Type GET API allows users to retrieve existing Entity Types, including Attribute Types that match the given parameters. To find an existing Entity Type, a user can query by ID or name. To obtain existing Entity Types, use the following curl command below.

curl -X 'GET' \
  'https://{host}/api/entitytypes?ID={entityTypeID}&name=Name' \
  -H 'accept: application/json'

A sample return response can be found below.

Get Entity Type API Sample Response 
 
// Some fields are omitted for brevity
[
  {
    "ID": 1,
    "name": "natural person",
    "validateOnCreate": false,
    "AttributeTypes": [
      {
        "ID": 1,
        "Name": "DoingBusinessAs",
        "IsRequired": true,
        "IsKey": true,
        "EntityTypeID": 1,
        "Validation": null,
        "ValidationMessage": null,
        "DropdownID": null,
        "displayOrder": null
      },
      {
        "ID": 2,
        "Name": "Address",
        "IsRequired": true,
        "IsKey": false,
        "EntityTypeID": 1,
        "Validation": null,
        "ValidationMessage": null,
        "DropdownID": null,
        "displayOrder": null
      },
      {
        "ID": 3,
        "Name": "GlobalUltimateParent",
        "IsRequired": false,
        "IsKey": false,
        "EntityTypeID": 1,
        "Validation": null,
        "ValidationMessage": null,
        "DropdownID": null,
        "displayOrder": null
      }
    ]
  }
]

Refer to the DR Workbench API Entity Type Reference to learn more about finding an existing Entity Type.

How to Create an Entity Type

The Entity Type POST API allows users to create an Entity Type. The validateOnCreate field determines whether a Data Object’s Attribute values will be validated upon creation of the Data Object.

Note. The Entity Type Name is globally unique and Attribute Type Names are unique within an Entity.

To create an Entity Type, use the following curl command below.

curl -X 'POST' \
  'https://{host}/api/entitytypes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "legal entity",
    "validateOnCreate": false,
    "AttributeTypes": [
        {
            "displayOrder": 10, 
            "isKey": true,
            "isRequired": true,
            "name": "Address",
        },
        {
            "dropdownID": 1,
            "isKey": true,
            "isRequired": true,
            "name": "DoingBusinessAs",
            "validationMessage": "string"
        },
        {
            "isRequired": false,
            "isKey": false,
            "name": "GlobalUltimateParent"
        }
    ]
}'

To view sample API responses for creating new Entity Types, refer to the DR Workbench API Entity Type Reference.

How to Update an Entity Type

The Entity Type PUT API allows users to update an existing Entity Type. Updates to an Entity Type are based on the Entity Type ID provided in the API path. To update an existing Attribute Type, the Attribute Type ID must exist. An Entity Type name is globally unique, and Attribute Type names are unique within an Entity. An Entity Type cannot have more than 5 key Attributes as a result of an update.

To update an Entity Type, use the following curl command below.

  curl -X 'PUT' \
  'https://{host}/api/entitytypes/{entityTypeID}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "updated name",
    "attributeTypes": [
        {
            // deletes an attribute
            "ID": 3, 
            "deleteAttributeType": true
        },
        {
            // updates an attribute
            "ID": 4, 
            "name": "new attribute name",
            "displayOrder": 50

        },
        {
            // creates a new attribute
            "name": "country",
            "isRequired": true,
            "isKey": false,
            "validation": "string",
            "validationMessage": "string"
        }
    ]
}'

Warning. Updating an Attribute with a new “IsKey=true” AttributeType may impact the functionality of previously imported records.

To view sample API responses for updating an Entity Type, refer to the DR Workbench API Entity Type Reference.

How to Delete an Entity Type

The Entity Type DELETE API allows users to delete an Entity Type. Deleting an Entity Type will remove all associated Attributes.

To delete an Entity Type, follow the curl command below.

curl -X 'DELETE' \
  'https://{host}/api/entitytypes/{entityTypeID}' \
  -H 'accept: application/json'

To view sample API responses for deleting an Entity Type, refer to the DR Workbench API Entity Type Reference.

How to Create an Attribute Type

The Attribute Type POST API allows users to create an Attribute Type and associate it to an existing Entity Type. Attribute Type names are unique within the Entity Type.

An Entity Type cannot have more than 100 Attribute Types, no more than 5 of which can be key Attribute Types, as a result of adding a new Attribute Type.

To create an Attribute Type, use the following curl command below.

curl -X 'POST' \
  'https://{host}/api/entitytypes/{entityTypeID}/attributetypes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "isKey": true,
  "isRequired": true,
  "name": "country of origin",
  "displayOrder": 15
}'

Warning. Adding a new “IsKey=true” Attribute Type to an existing Entity Type may impact the functionality of previously imported records.

To view sample API responses for creating an Attribute Type, refer to the DR Workbench API Entity Type Reference.

How to Update an Attribute Type

The Attribute Type PUT API allows users to update an existing Attribute Type identified by the given Attribute Type ID within a given Entity Type ID. In order to update an Attribute Type: - The Attribute Type must be associated with the requested Entity Type. - Attribute Type names are unique within an Entity Type. - An Entity Type cannot have more than 5 key Attribute Types as a result of an update.

To update an Attribute Type, use the following curl command below.

curl -X 'PUT' \
  'https://{host}/api/entitytypes/{entityTypeID}/attributetypes/{attributeTypeID}' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "isKey": true,
  "isRequired": false,
  "name": "country of origin",
  "displayOrder": 10
}'

Warning. Updating an Attribute with a new “IsKey=true” Attribute Type may impact the functionality of previously imported records.

To view sample API responses for updating an Attribute Type, refer to the DR Workbench API Entity Type Reference.

How to Order Attributes

Through the DR Workbench API, attributes can be displayed in a custom order. All attributes or a partial number of attributes can be custom ordered depending on the needs of the user.

Data attributes are normally displayed in alphabetical order by Attribute Type name. To influence the display order of attributes, a user can add an optional displayOrder integer field to attributes during the creation of an Entity Type, or during an update of the Entity Type attributes.

  • Attributes with displayOrder values are sorted by display order at the front of the list of attributes.
  • Attributes without displayOrder values are sorted alphabetically by Attribute Type name at the end of the list.
  • If two attributes have the same displayOrder value, they are sorted alphabetically by attribute name within that display order position.

Using Dropdown Values in Entity Types

Some Attribute Types are best represented by a list of options instead of using free form values. In Data Refinery Workbench, a Dropdown represents a list of options that are appropriate for an Attribute Type. These options are displayed by the Workbench User Interface in dropdown graphical elements.
A list of up to 1,000 values may be provided for users to choose from.

Dropdowns are created separately, then linked to Attribute Types after they’ve been created. This allows an Entity Type (or multiple Entity Types) to use the same Dropdown for multiple Attribute Types.

When creating or updating data objects using a Dropdown, while validation is enabled, validation will enforce that the value provided for an Attribute matches one of the options available for the dropdown.

Validation is enabled under the following conditions:

  • Updating Data Objects through import
  • Creating Data Objects through import when ValidateOnCreate = true
  • Applying a Workflow Transition when ValidateOnTransition = true for that transition
  • Applying an End Workflow Transition that updates an existing Data Object
  • Applying an End Workflow Transition that creates a Data Object when ValidationOnCreate = true

When updating Workflow Data, validation failures produce warning feedback but will not prevent the update.

How to Find an Existing Dropdown

The Dropdown GET API allows users to retrieve Dropdown information. The values for a Dropdown are not returned by default, but can be retrieved using a flag on the API.

To obtain a list of existing Dropdowns, use the following curl command below.

curl -X 'GET' \
  'https://{host}/api/dropdowns \
  -H 'accept: application/json'

A sample return response can be found below.

Get Dropdowns API Sample Response 
 
// Some fields are omitted for brevity
[
  {
    "ID": 1,
    "name": "Country",
    "DropdownValues": null
  },
  {
    "ID": 2,
    "name": "Legal Structures",
    "DropdownValues": null
  }
]

To obtain the DropdownValues for a Dropdown, use the following curl command below.

curl -X 'GET' \
  'https://{host}/api/dropdowns?name=Country \
  -H 'accept: application/json'

A sample return response can be found below.

Get Dropdown API with DropdownValues Sample Response 
 
// Some fields are omitted for brevity
[
  {
    "ID": 1,
    "name": "Country",
    "DropdownValues": [
      {
        "ID:" 1,
        "name": "United States",
        "dropdownID": 1
      },
      {
        "ID:" 2,
        "name": "Canada",
        "dropdownID": 1
      },
      {
        "ID:" 3,
        "name": "Mexico",
        "dropdownID": 1
      }
    ]
  }
]

Refer to the DR Workbench API Dropdown Reference to learn more about finding an existing Dropdown.

How to Associate a Dropdown to an Entity Type

The standard Update Entity Type Definition API calls can be used to associate a Dropdown to an Entity Type Attribute. To use a Dropdown for an Attribute, include the dropdownID Attribute with a non-0 value when creating or updating the Entity Type. The below example shows using the Dropdown with an id of 1 for the Country Attribute:

curl -X 'POST' \
  'https://{host}/api/entitytypes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "legal entity",
    "AttributeTypes": [
        {
            "name": "Address",
            "isRequired": true,
            "isKey": false
        },
        {
            "name": "DoingBusinessAs",
            "isRequired": true,
            "isKey": true
        },
        {
            "name": "GlobalUltimateParent",
            "isRequired": false,
            "isKey": false
        },
        {
            "name": "Country",
            "isRequired": false,
            "isKey": false,
            "dropdownId": 1
        }
    ]
}'

How to Create a Dropdown

The Dropdown POST API allows users to create a Dropdown and its associated Values. A maximum of 1,000 dropdown values may be included within a single dropdown.

Note. The Dropdown Name is globally unique and Values are unique within a Dropdown.

To create a Dropdown, use the following curl command below.

curl -X 'POST' \
  'https://{host}/api/dropdowns' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Country",
  "DropdownValues": [
    "United States",
    "Canada",
    "Mexico"
  ]
}'

How to Update a Dropdown

The Dropdown PUT API allows users to update a Dropdown and its associated Values. A maximum of 1,000 dropdown values may be included within a single dropdown, which is calculated after all delete and insert operations have completed.

Deleting a value is indicated by including deleteValue set to true. Creating a new value is indicated by the ID not existing or being blank.

Note. The Dropdown Name is globally unique and Values are unique within a Dropdown.

curl -X 'PUT' \
  'https://{host}/api/dropdowns/1' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "New Country Name",
  "DropdownValues": [
    {
      "ID": 1,
      "deleteValue": true
    },
    {
      "ID": 2,
      "name": "Canada Updated Name"
    },
    {
      "ID": 3,
      "name": "Mexico Updated Name"
    },
    {
      "name": "United Kingdom"
    }
  ]
}'

Copyright © 2025 Kingland Systems LLC