Entity Management#
(introduced: version 2023.3)
⚠️ In this API and in the related ODK XForms specification, collections of
Entities
are referred to asDatasets
. 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.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
Response
HTTP Status: 200
Content Type: application/json
[
{
"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,
"currentVersion": {
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4"
}
}
]
array
|
HTTP Status: 200
Content Type: application/json; extended
[
{
"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,
"creator": {
"createdAt": "2018-04-18T23:19:14.802Z",
"displayName": "My Display Name",
"id": 115,
"type": "user",
"updatedAt": "2018-04-18T23:42:11.406Z",
"deletedAt": "2018-04-18T23:42:11.406Z"
},
"currentVersion": {
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4",
"creator": {
"createdAt": "2018-04-18T23:19:14.802Z",
"displayName": "My Display Name",
"id": 115,
"type": "user",
"updatedAt": "2018-04-18T23:42:11.406Z",
"deletedAt": "2018-04-18T23:42:11.406Z"
}
}
}
]
array
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
Creating an Entity#
POST /projects/{projectId}/datasets/{name}/entities
Creates an Entity in the Dataset. Request body takes the JSON representation of the Entity. It should have uuid
and label
property in addition to the user-defined properties of the Dataset in data
property.
Value type of all properties is string
.
You can provide header X-Action-Notes
to store the metadata about the request. The metadata can retrieved using Entity Audit Log
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
Request body
{
"uuid": "54a405a0-53ce-4748-9788-d23a30cc3afa",
"label": "John Doe (88)",
"data": {
"firstName": "John",
"age": "88"
}
}
object
|
Response
HTTP Status: 200
Content Type: application/json
{
"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,
"currentVersion": {
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4",
"data": {
"firstName": "John",
"age": "88"
}
}
}
object
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
Getting Entity Details#
GET /projects/{projectId}/datasets/{name}/entities/{uuid}
This returns the metadata and current data of an Entity
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
uuid |
UUID of the Entity Example: |
Response
HTTP Status: 200
Content Type: application/json
{
"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,
"currentVersion": {
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4",
"data": {
"firstName": "John",
"age": "88"
}
}
}
array
|
HTTP Status: 200
Content Type: application/json; extended
{
"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,
"creator": {
"createdAt": "2018-04-18T23:19:14.802Z",
"displayName": "My Display Name",
"id": 115,
"type": "user",
"updatedAt": "2018-04-18T23:42:11.406Z",
"deletedAt": "2018-04-18T23:42:11.406Z"
},
"currentVersion": {
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4",
"data": {
"firstName": "John",
"age": "88"
},
"creator": {
"createdAt": "2018-04-18T23:19:14.802Z",
"displayName": "My Display Name",
"id": 115,
"type": "user",
"updatedAt": "2018-04-18T23:42:11.406Z",
"deletedAt": "2018-04-18T23:42:11.406Z"
}
}
}
array
|
HTTP Status: 403
Content Type: application/json; extended
{
"code": "pencil",
"message": "pencil"
}
object
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
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.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
uuid |
UUID of the Entity Example: |
Response
HTTP Status: 200
Content Type: application/json
{
"message": "Success"
}
object
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
Updating an Entity#
PATCH /projects/{projectId}/datasets/{name}/entities/{uuid}
Use this API to update one or all properties of an Entity. It will throw 400 - Bad Request
if any of the updating properties doesn't exist in the dataset.
To unset value of any property, you can set it to empty string (""). Setting it to null
will throw an error.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
uuid |
UUID of the Entity Example: |
Request body
{
"label": "John Doe (88)",
"data": {
"firstName": "John",
"age": "88"
}
}
object
|
Response
HTTP Status: 200
Content Type: application/json
{
"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,
"currentVersion": {
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4",
"data": {
"firstName": "John",
"age": "88"
}
}
}
object
|
HTTP Status: 403
Content Type: application/json; extended
{
"code": "pencil",
"message": "pencil"
}
object
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
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.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
uuid |
UUID of the Entity Example: |
Response
HTTP Status: 200
Content Type: application/json
[
{
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4",
"data": {
"firstName": "John",
"age": "88"
}
}
]
array
|
HTTP Status: 200
Content Type: application/json; extended
[
{
"label": "John (88)",
"current": true,
"createdAt": "2018-03-21T12:45:02.312Z",
"creatorId": 1,
"userAgent": "Enketo/3.0.4",
"data": {
"firstName": "John",
"age": "88"
},
"creator": {
"createdAt": "2018-04-18T23:19:14.802Z",
"displayName": "My Display Name",
"id": 115,
"type": "user",
"updatedAt": "2018-04-18T23:42:11.406Z",
"deletedAt": "2018-04-18T23:42:11.406Z"
}
}
]
array
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
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.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
uuid |
UUID of the Entity Example: |
Response
HTTP Status: 200
Content Type: application/json
[
[
{
"new": "John",
"old": "Dana",
"propertyName": "firstName"
},
{
"new": "Doe",
"old": "Roe",
"propertyName": "lastName"
},
{
"new": "John Doe",
"old": "Jane Roe",
"propertyName": "label"
}
],
[
{
"new": "Robert",
"old": "Doe",
"propertyName": "firstName"
},
{
"new": "Robert Doe",
"old": "Doe Doe",
"propertyName": "label"
}
]
]
array
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
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.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
uuid |
UUID of the Entity Example: |
Response
HTTP Status: 200
Content Type: application/json
[
{
"actorId": 42,
"action": "entity.create",
"acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
"loggedAt": "2018-04-18T23:19:14.802Z"
}
]
array
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|