Custom data exports feature

[joshuaberetta]

List of export settings for a specific asset

Required permissions: view_submissions (View submissions)

GET /api/v2/assets/{asset_uid}/export-settings/

Example

curl -X GET https://[kpi]/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/export-settings/

CRUD

• asset_uid - is the unique identifier of a specific asset
• setting_uid - is the unique identifier of a specific export setting

Create an export setting for an asset

Required permissions: manage_asset (Manage project)

POST /api/v2/assets/{asset_uid}/export-settings/

Example

curl -X POST https://[kpi]/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/export-settings/

Payload

{
    "name": "foo",
    "export_settings": {
        "fields_from_all_versions": "true",
        "group_sep": "/",
        "hierarchy_in_labels": "true",
        "lang": "English (en)",
        "multiple_select": "both",
        "type": "csv",
        "fields": ["field_1", "field_2"]
    }
}

where:

• "name" (required) is the name of the export setting displayed in the UI
• "export_settings" (required) is a map of defined settings containing the following valid options:
  • "fields" (optional) is an array of column names to be included in the export (including their group hierarchy). Valid inputs include:
    • An array containing any string value that matches the XML column name
    • An empty array which will result in all columns being included
    • If "fields" is not included in the "export_settings", all columns will be included in the export
  • "fields_from_all_versions" (required) is a boolean to specify whether fields from all form versions will be included in the export.
  • "group_sep" (required) is a value used to separate the names in a hierarchy of groups. Valid inputs include:
    • Non-empty value
  • "hierarchy_in_labels" (required) is a boolean to specify whether the group hierarchy will be displayed in labels
  • "multiple_select" (required) is a value to specify the display of multiple_select-type responses. Valid inputs include:
    • "both",
    • "summary", or
    • "details"
  • "type" (required) specifies the export format. Valid export formats include:
    • "csv",
    • "geojson",
    • "spss_labels",
    • "xls"

Retrieves a specific export setting

Required permissions: view_submissions (View submissions)

GET /api/v2/assets/{asset_uid}/export-settings/{setting_uid}/

Example

curl -X GET https://[kpi]/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/export-settings/espj4oFeS9tVhQQMVfitTB2/

Updates an asset's export setting

Required permissions: manage_asset (Manage project)

PATCH /api/v2/assets/{asset_uid}/export-settings/{setting_uid}/

Example

curl -X PATCH https://[kpi]/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/export-settings/espj4oFeS9tVhQQMVfitTB2/

Payload

{
    "name": "bar",
    "export_settings": {
        "fields_from_all_versions": "true",
        "group_sep": "/",
        "hierarchy_in_labels": "true",
        "lang": "English (en)",
        "multiple_select": "both",
        "type": "csv",
        "fields": ["field_1", "field_2", "field_3"]
    }
}

Deletes current export setting

Required permissions: manage_asset (Manage project)

DELETE /api/v2/assets/{asset_uid}/export-settings/{setting_uid}/

Example

curl -X DELETE https://[kpi]/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/export-settings/espj4oFeS9tVhQQMVfitTB2/

Description

Allow for export setting preferences to be created and managed for an asset as well in including a new option for filtering exports by field.

Related issues

closes #2967
related to #2963, #2881