Entity Management¶

(introduced: version 2023.3)

⚠️ In this API and in the related ODK XForms specification, collections of Entities are referred to as Datasets. The term "Entity List" is used for this concept in the Central frontend UI, user facing documentation, and all other text intended for end users who are not developers.

Entities are data objects that can be shared between Forms to support workflows with multiple steps. They can be created either through form design or through this API. A collection of Entities is a Dataset.

Entities Metadata¶

GET /projects/{projectId}/datasets/{name}/entities

This endpoint returns a list of the Entities of a Dataset. Please note that this endpoint only returns metadata of the entities not the data. If you want to get the data of all entities then please refer to OData Dataset ServiceYou can provide ?deleted=true to get only deleted entities.

Creating Entities¶

POST /projects/{projectId}/datasets/{name}/entities

Creates one or more Entities in the Dataset.

For creating a single Entity, the request body takes a JSON representation of the Entity, which has the following properties:

A data object containing values for the user-defined Dataset properties. (Not all properties have to have values.)
A label property, which cannot be blank or an empty string. (This is used as a human-readable label in Forms that consume Entities.)
An optional uuid property. If the uuid is not specified, Central will generate a UUID for an Entity with the provided data and label.

{ "label": "John Doe", "data": { "firstName": "John", "age": "22" } }

The value type of all properties is string.

For creating multiple Entities in bulk, the request body takes an array entities containing a list of Entity objects as described above. The bulk entity version also takes a source property with a required name field and optional size, for example to capture the filename and size of a bulk upload source.

{ "entities": [...], "source": {"name": "file.csv", "size": 100} }

You can provide header X-Action-Notes to store the metadata about the request. The metadata can retrieved using Entity Audit Log

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "deletedAt": "2018-03-21T12:45:02.312Z",
  "creatorId": 1,
  "conflict": null,
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "conflictingProperties": null,
    "version": 1,
    "baseVersion": null,
    "branchId": null,
    "trunkVersion": null,
    "branchBaseVersion": null,
    "data": {
      "firstName": "John",
      "age": "88"
    },
    "dataReceived": {
      "label": "John (88)",
      "firstName": "John",
      "age": "88"
    }
  }
}

Schema

object

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

ISO date format. The time that the server received the Entity.

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

Timestamp of the last update in ISO date format. null when there is only one version of the Entity.

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

Timestamp of the deletion in ISO date format. null if the Entity is not deleted.

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

conflict

enum

Type of the conflict.

hard: baseVersion conflicts and multiple versions update the same property

soft: baseVersion conflicts but data updates are independent

expand

soft	`string`
hard	`string`

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

conflictingProperties

array

list of properties updated offline simultaneously.

version

number

The version number of the Entity. Each update increments this number.

Example: 2

baseVersion

number

The version number of the version that was the "base version" of this version.

Example: 1

branchId

string

The uuid of a branch linking multiple offline entity updates together.

Example: b0e927b6-958a-42f6-8344-1deb37ee9672

trunkVersion

number

The version number of the last known base server version of an entity, in the case of an offline branch of updates.

Example: 1

branchBaseVersion

number

The base version of the entity according to the submission. In the case of an offline branch of updates, this may not match the version of the base submission on Central.

Example: 1

data

object

expand

firstName

string

Example: John

age

string

Example: 88

dataReceived

object

expand

firstName

string

Example: John

age

string

Example: 88

label

string

Example: John (88)

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Getting Entity Details¶

GET /projects/{projectId}/datasets/{name}/entities/{uuid}

This returns the metadata and current data of an Entity.

The data and label of an Entity are found in the currentVersion object under data and label respectively. The currentVersion object also contains version-specific metadata fields such as version, baseVersion, details about conflicts that version introduced, etc. See the versions endpoint for more details.

The Entity also contains top-level system metadata such as uuid, createdAt and updatedAt timestamps, and creatorId (or full creator if extended metadata is requested).

Conflicts

An Entity's metadata also has a conflict field, which indicates the current conflict status of the Entity. The value of a conflict can either be:

null. The Entity does not have conflicting versions.
soft. The Entity has a version that was based on a version other than the version immediately prior to it. (The specified baseVerson was not the latest version on the server.)
hard. The Entity has a version that was based on a version other than the version immediately prior to it. Further, that version updated the same property as another update.

If an Entity has a conflict, it can be marked as resolved. After that, the conflict field will be null until a new conflicting version is received.

Deleting an Entity¶

DELETE /projects/{projectId}/datasets/{name}/entities/{uuid}

Use this API to delete an Entity. With this API, Entity is soft-deleted, which means it is still in the database and you can retreive it by passing ?deleted=true to GET /projects/:id/datasets/:name/entities. In the future, we will provide a way to restore deleted entities and purge deleted entities.

Updating an Entity¶

PATCH /projects/{projectId}/datasets/{name}/entities/{uuid}

This endpoint is used to update the label or the properties (passed as JSON in the request body) of an Entity. You only need to include the properties you wish to update. To unset the value of any property, you can set it to empty string (""). The label must be a non-empty string. Setting a property to null will throw an error. Attempting to update a property that doesn't exist in the Dataset will throw an error.

Specifying a base version

You must either provide the query parameter baseVersion or use the force=true query parameter. The specified baseVersion must match the current version of the Entity on the server or the request will be rejected. This acts as a check to ensure you are not trying to update based on stale data. To update an Entity regardless of its current state, use the force flag with value true.

Resolving a conflict

You can also use this endpoint to resolve an Entity conflict by passing the resolve=true query parameter, in which case providing data in the request body is optional. When not providing new data, only the conflict status from the Entity will be cleared and no new version will be created. When providing data, the conflict will be cleared and an updated version of the Entity will be added.

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "deletedAt": "2018-03-21T12:45:02.312Z",
  "creatorId": 1,
  "conflict": null,
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "conflictingProperties": null,
    "version": 1,
    "baseVersion": null,
    "branchId": null,
    "trunkVersion": null,
    "branchBaseVersion": null,
    "data": {
      "firstName": "John",
      "age": "88"
    },
    "dataReceived": {
      "firstName": "John",
      "age": "88",
      "label": "John (88)"
    }
  }
}

Schema

object

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

ISO date format. The time that the server received the Entity.

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

Timestamp of the last update in ISO date format. null when there is only one version of the Entity.

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

Timestamp of the deletion in ISO date format. null if the Entity is not deleted.

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

conflict

enum

Type of the conflict.

hard: baseVersion conflicts and multiple versions update the same property

soft: baseVersion conflicts but data updates are independent

expand

soft	`string`
hard	`string`

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

conflictingProperties

array

list of properties updated offline simultaneously.

version

number

The version number of the Entity. Each update increments this number.

Example: 2

baseVersion

number

The version number of the version that was the "base version" of this version.

Example: 1

branchId

string

The uuid of a branch linking multiple offline entity updates together.

Example: b0e927b6-958a-42f6-8344-1deb37ee9672

trunkVersion

number

The version number of the last known base server version of an entity, in the case of an offline branch of updates.

Example: 1

branchBaseVersion

number

The base version of the entity according to the submission. In the case of an offline branch of updates, this may not match the version of the base submission on Central.

Example: 1

data

object

expand

firstName

string

Example: John

age

string

Example: 88

dataReceived

object

expand

firstName

string

Example: John

age

string

Example: 88

label

string

Example: John (88)

HTTP Status: 403

Content Type: application/json

Example

{
  "code": 403.1,
  "message": "The authenticated actor does not have rights to perform that action."
}

Schema

object

code

number

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Listing Versions¶

GET /projects/{projectId}/datasets/{name}/entities/{uuid}/versions

This returns the Entity metadata and data for every version of this Entity, in ascending creation order.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to return a creator data object alongside the creatorId Actor ID reference.

There is an optional query flag relevantToConflict that returns the subset of past versions of an Entity that are relevant to the Entity's current conflict. This includes the latest version, the base version, the previous server version, and any other versions since the last time the Entity was in a conflict-free state. If the Entity is not in conflict, zero versions are returned.

Getting changes between Versions¶

GET /projects/{projectId}/datasets/{name}/entities/{uuid}/diffs

This returns the changes, or edits, between different versions of an Entity. These changes are returned as an array of arrays. Between two Entities, there is an array of objects representing how each property changed. This change object contains the old and new values, as well as the property name.

Entity Audit Log¶

GET /projects/{projectId}/datasets/{name}/entities/{uuid}/audits

Returns Server Audit Logs relating to an Entity. They will be returned most recent first.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No