Dataset Management

Creating Datasets

Changed on

You can create a Dataset with a specific name within a Project. This Dataset can then be populated with Entities via the API or via Forms and Submissions, and then used by other Forms. This endpoint allows a Dataset to be created programatically without an input form.

The name of a Dataset is case-sensitive in that it will keep the capitalization provided (e.g. "Trees"). But Central will not allow a second Dataset with the same name but different capitalization to be created (e.g. "trees" when "Trees" already exists).

By default, the Dataset will have no properties, but each Entity will have a label and a unique ID (uuid). You can add additional properties with this related endpoint.

The Dataset name must follow the the same rules as XML identifiers and not start with . or __. See the Entities XForms Specification for more information.

post/v1/projects/{projectId}/datasets

Request

  • Base URL
    / (relative, and the document was published on a file host, not at the API’s origin)
  • URL
    /v1/projects/{projectId}/datasets
  • Auth
    none declared

Path parameters

projectIdnumber required

The numeric ID of the Project

Request body */*

namestring required

The desired name of the Dataset. Must be a valid

approvalRequiredboolean

Control whether a Submission should be approved before an Entity is created from it.

ownerOnlyboolean

If ownerOnly is true, and an Actor only has access to the Dataset CSV file via linked Form Attachments, then only Entities created by the Actor will be downloaded to the OpenRosa client. If ownerOnly is false, or if an Actor has direct access to the Dataset CSV file, then all Entities will be downloaded.

Example request

{
  "name": "Trees",
  "approvalRequired": false
}

Response

OK

namestring required

The name of the Dataset

createdAtstring required

ISO date format.

projectIdnumber required

The numerical ID of the Project that the Dataset belongs to.

approvalRequiredboolean

Control whether a Submission should be approved before an Entity is created from it.

ownerOnlyboolean

Legacy flag. If ownerOnly is true, and an Actor only has access to the Dataset CSV file via linked Form Attachments, then only Entities created by the Actor will be downloaded to the OpenRosa client. Superseded by accessFilter when set.

lastUpdatestring

ISO date format. The timestamp of the most recent change to the dataset or its entities

Example response

{
  "name": "people",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "projectId": 1,
  "approvalRequired": true,
  "accessFilter": {
    "type": "property",
    "rules": [
      {
        "datasetProperty": "state",
        "actorProperty": "region"
      }
    ]
  },
  "lastUpdate": "2020-10-10T03:04:51.695Z",
  "linkedForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "sourceForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "properties": [
    {
      "name": "the.age",
      "odataName": "the_age",
      "publishedAt": "2018-01-21T00:04:11.153Z",
      "forms": [
        {
          "xmlFormId": "simple",
          "name": "Simple"
        }
      ]
    }
  ]
}

Changes