Dataset Management#
(introduced: version 2022.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 documentation, and all other text intended for end users who are not developers.
A Dataset is a named collection of Entities that have the same properties.
A Dataset can be linked to Forms as Attachments. This will make it available to clients as an automatically-updating CSV.
Related APIs:
Datasets#
GET /projects/{projectId}/datasets
The Dataset listing endpoint returns all published Datasets in a Project. If a Draft Form defines a new Dataset, that Dataset will not be included in this list until the Form is published.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
Response
HTTP Status: 200
Content Type: application/json
[
{
"name": "people",
"createdAt": "2018-01-19T23:58:03.395Z",
"projectId": 1,
"approvalRequired": true
}
]
array
|
HTTP Status: 200
Content Type: application/json; extended
[
{
"name": "people",
"createdAt": "2018-01-19T23:58:03.395Z",
"projectId": 1,
"approvalRequired": true,
"lastEntity": "2018-04-18T03:04:51.695Z",
"entities": 10
}
]
array
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
Dataset Metadata#
GET /projects/{projectId}/datasets/{name}
Returns the metadata of a published Dataset including properties and forms that create and consume the Dataset.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
Response
HTTP Status: 200
Content Type: application/json
{
"name": "people",
"createdAt": "2018-01-19T23:58:03.395Z",
"projectId": 1,
"approvalRequired": true,
"sourceForms": [
{
"xmlFormId": "treeRegistration",
"name": "Tree Registration"
}
],
"linkedForms": [
{
"xmlFormId": "simple",
"name": "Simple"
}
],
"properties": [
{
"name": "the.age",
"odataName": "the_age",
"publishedAt": "2018-01-21T00:04:11.153Z",
"forms": [
{
"xmlFormId": "simple",
"name": "Simple"
}
]
}
]
}
array
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
Update Dataset Metadata#
PATCH /projects/{projectId}/datasets/{name}
You can only update approvalRequired
using this endpoint. approvalRequired
flag controls the Entity creation flow; if it is true
then the Submission must be approved before an Entity can be created from it and if it is false
then an Entity is created as soon as the Submission is received by the ODK Central.
By default approvalRequired
is false
for the Datasets created after v2023.3. Datasets created prior to that will have approvalRequired
set to true
.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
Request body
{
"approvalRequired": true
}
object
|
Response
HTTP Status: 200
Content Type: application/json
{
"name": "people",
"createdAt": "2018-01-19T23:58:03.395Z",
"projectId": 1,
"approvalRequired": true,
"sourceForms": [
{
"xmlFormId": "treeRegistration",
"name": "Tree Registration"
}
],
"linkedForms": [
{
"xmlFormId": "simple",
"name": "Simple"
}
],
"properties": [
{
"name": "the.age",
"odataName": "the_age",
"publishedAt": "2018-01-21T00:04:11.153Z",
"forms": [
{
"xmlFormId": "simple",
"name": "Simple"
}
]
}
]
}
array
|
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|
Download Dataset#
GET /projects/{projectId}/datasets/{name}/entities.csv
Datasets (collections of Entities) can be used as Attachments in other Forms, but they can also be downloaded directly as a CSV file.
The CSV format closely matches the OData Dataset Service format, with columns for system properties such as __id
(the Entity UUID), __createdAt
, __creatorName
, etc., the Entity Label label
, and the Dataset/Entity Properties themselves. If any Property for an given Entity is blank (e.g. it was not captured by that Form or was left blank), that field of the CSV is blank.
This endpoint supports ETag
header, which can be used to avoid downloading the same content more than once. When an API consumer calls this endpoint, the endpoint returns a value in the ETag header. If you pass that value in the If-None-Match header of a subsequent request, then if the Dataset has not been changed since the previous request, you will receive 304 Not Modified
response; otherwise you'll get the new data.
Request
Parameters
projectId |
The numeric ID of the Project Example: |
name |
Name of the Dataset Example: |
Response
HTTP Status: 200
Content Type: text/csv
__id,label,geometry,species,circumference_cm,__createdAt,__creatorId,__creatorName,__updates,__updatedAt,__version
2c1ee90b-dde8-434b-9985-2eefd8465339,666cm purpleheart,-29.281608 -67.624883 0 0,purpleheart,667,2023-05-31T19:49:28.902Z,22,Alice,1,2023-05-31T19:52:34.467Z,1
84ac3a03-9980-4098-93a5-b81fdc6ea749,555cm wallaba,18.921876 77.309451 0 0,wallaba,555,2023-05-31T19:49:20.152Z,22,Alice,0,,1
string |
HTTP Status: 403
Content Type: text/csv
No Example
string |
HTTP Status: 403
Content Type: application/json
{
"code": "403.1",
"message": "The authenticated actor does not have rights to perform that action."
}
object
|