Introduction
The ActivityInfo API allows you to query and update public and private ActivityInfo databases. You can also push updates to ActivityInfo databases for which you have write permissions.
ActivityInfo offers a JSON-based API that mostly follows RESTful principles, so you can either use your favorite REST client library to send and receive JSON, or you can use a client library for R for convenience.
Authentication
ActivityInfo users can access the ActivityInfo API using a Personal API Token to authenticate to ActivityInfo.
The authentication token can be included in the request as the value of the Authorization
header.
curl -H "Authorization: Bearer <API TOKEN>" \
https://www.activityinfo.org/resources/databases
For clients that only support Basic Authentication, the API token can be set as the 'password', with any value in the username field:
curl -u anything:<API TOKEN> \
https://www.activityinfo.org/resources/databases
Resource IDs
In order to allow ActivityInfo clients to work while disconnected from the internet, most identifiers are generated by the client using a combination of a timestamp, a local counter, and random numbers.
This means when submitting a request to add a new database, folder, form, etc, you will need to generate the id of the new resource.
The Collision-resistant ids (CUID) project has libraries in a number of languages for generating IDs that will be accepted by ActivityInfo.
Databases
Add a database
Add a new database to ActivityInfo.
Only users who have a billing account with ActivityInfo are permitted to add new databases.
HTTP Request
POST https://www.activityinfo.org/resources/databases
Request Body application/json
object | |||
id | string | The id of the new database. | required |
label | string | Human readable name of the database. | required |
templateId | string | The id of the template to use in creating the new database. The the two templates currently supported are "reporting" (Multi-partner reporting) and "casemanagement." If ommitted, a blank database with three simple roles will be added. | required |
description | string | An optional, longer description for the database. | optional |
Responses application/json
Status Code | Error Code | Description |
---|---|---|
200 | Database was successfully created. | |
401 | AUTHENTICATION_REQUIRED | The request must be authenticated, using basic authentication. |
400 | BILLING_ACCOUNT_NOT_ACTIVE | The authenticated user's billing account is not active. |
400 | NO_BILLING_ACCOUNT | The authenticated user has no billing account, and so cannot add a database. |
409 | DATABASE_EXISTS | A database with this id already exists. |
List databases
Lists all the databases that the requesting user owns, or that have been shared with the requesting user.
HTTP Request
GET https://www.activityinfo.org/resources/databases
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/resources/databases
The above command returns JSON structured like this:
[
{
"databaseId": "ck8oykh8m5",
"label": "2018 IRQ Internally Displaced Persons (IDP)",
"description": "",
"ownerId": "432201",
"billingAccountId": 3.4298234040238E13,
"suspended": false,
"publishedTemplate": false
},
{
"databaseId": "c4wb14glfs3a55z2",
"label": "COVID-19 Response",
"description": "",
"ownerId": "432201",
"billingAccountId": 3.4298234040238E13,
"suspended": false,
"publishedTemplate": false
}
]
Successful Response application/json
array[object] | |||
databaseId | string | The globally-unique id of this database. | required |
label | string | The human-readable name of this database. | required |
description | string | A longer, optional description for this database. | required |
ownerId | string | The id of the user who owns this database. | required |
billingAccountId | integer | The id of the billing account to which this database belongs | required |
suspended | boolean | True if this database belongs to a billing account that has been suspended. | required |
publishedTemplate | boolean | True if this database has been published as a template. | required |
Get a database's tree
The database tree includes the key elements of a database, including:
- The list of resources (folders, forms, and sub-forms)
- The user roles defined for the database
- The record locks in force
The tree includes only resources visible to the requesting user, along with the requesting user's permission grants for the database.
HTTP Request
GET https://www.activityinfo.org/resources/databases/{databaseId}
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/resources/databases/ck8oykh8m5
Successful Response application/json
object | |||
databaseId | string | This database's id | required |
userId | string | The id of the requesting user. The contents of the tree depends on the permissions of the requesting user. | optional |
version | string | The monotonically-increasing version of the database tree. The version number is incremented whenever a change is made that affects the database tree. | required |
label | string | This database's human-readable label. | required |
description | string | required | |
ownerRef | object | required | |
id | string | required | |
name | string | required | |
string | required | ||
language | string | Current database language | required |
originalLanguage | string | Original database language | optional |
languages | array[string] | The languages that have been defined for this database translation. | required |
continuousTranslation | boolean | True if the database continuous automatic translation is enabled | required |
translationFromDbMemory | boolean | True if automatic translation from database memory is allowed for the database | required |
thirdPartyTranslation | boolean | True if third-party translation is allowed for the database | required |
suspended | boolean | True if this database is suspended for billing reasons | required |
storage | string | Opaque string that provides information about where and how this database is stored. Used to support data migration. | required |
role | object | The requesting user's assigned role in this database. | required |
roleId | string | The id of the role assigned to this user. | required |
roleParameters | object | The values of the parameters defined for this role. | required |
roleResources | array[string] | The resources (database, folder, forms, or subforms) to which the role's permissions are to apply. | required |
roles | array[object] | The roles that have been defined for this database. | required |
id | string | This role's id | required |
label | string | This role's human-readable label | required |
permissions | array[object] | Permissions granted this role. | required |
operation | string | Values:
|
required |
filter | string | A formula which restricts a permission to specific records. Only record-level permissions can be filtered. | optional |
securityCategories | array[string] | required | |
parameters | array[object] | Parameters defined for this role. Parameters can be referenced in filtering formulas. | required |
parameterId | string | required | |
label | string | required | |
range | string | required | |
filters | array[object] | Pre-defined filters. Role filters allow other users to choose filters for permissions without having to write formulas themselves. | required |
id | string | This filter's id. | required |
label | string | This filter's human-readable label | required |
filter | string | A formula that can be used to filter a record-level permission. | required |
grants | array[object] | required | |
resourceId | string | required | |
operations | array[string] | required | |
version | integer | required | |
grantBased | boolean | required | |
securityCategories | array[object] | The security categories that have been defined for this database. | required |
id | string | This security category's id | required |
label | string | This security category's human-readable label | required |
resources | array[object] | The set of resources (folders, forms, and subforms) that belong to this database. | required |
id | string | The resource's id. Form and subform resources must have globally-unique ids (across all of ActivityInfo) but folder ids are only guaranteed to be unique within a single database. | required |
type | string | The resource type.Values:
|
required |
parentId | string | The id of this resource's parent, for example, a folder id. If this is a top-level folder or form, the the parentId will be the id of the database itself. | required |
label | string | The resource's human-readable label. | required |
visibility | string | The resource's visibility.Values:
|
required |
locks | array[object] | The record locks that have been defined on this database. | required |
id | string | This lock's id. | required |
label | string | A human-readable label for this lock | required |
resourceId | string | The resource (database, folder, form, or subform) to which this lock applies. | required |
dateRange | object | The date range to which this lock applies. | optional |
startDate | local_date | required | |
endDate | local_date | required | |
formula | string | The formula to which this rule based lock applies. | optional |
message | string | user descroption pf the rule based lock. | optional |
deactivated | boolean | required | |
grants | array[object] | The permission grants that have been made to the requesting user for this database. | required |
resourceId | string | required | |
operations | array[string] | required | |
billingAccountId | integer | required | |
publishedTemplate | boolean | required |
Update a database's tree
Add, update or delete a resource, lock, or role in the database tree.
HTTP Request
POST https://www.activityinfo.org/resources/databases/{databaseId}
Request Body application/json
object | |||
resourceUpdates | array[object] | List of resources to add or update. | required |
id | string | The resource's id. Form and subform resources must have globally-unique ids (across all of ActivityInfo) but folder ids are only guaranteed to be unique within a single database. | required |
type | string | The resource type.Values:
|
required |
parentId | string | The id of this resource's parent, for example, a folder id. If this is a top-level folder or form, the the parentId will be the id of the database itself. | required |
label | string | The resource's human-readable label. | required |
visibility | string | The resource's visibility.Values:
|
required |
resourceDeletions | array[string] | List of resource ids to delete from the database. | required |
lockUpdates | array[object] | List of locks to add or update | required |
id | string | This lock's id. | required |
label | string | A human-readable label for this lock | required |
resourceId | string | The resource (database, folder, form, or subform) to which this lock applies. | required |
dateRange | object | The date range to which this lock applies. | optional |
startDate | local_date | required | |
endDate | local_date | required | |
formula | string | The formula to which this rule based lock applies. | optional |
message | string | user descroption pf the rule based lock. | optional |
deactivated | boolean | required | |
lockDeletions | array[string] | List of lock ids to delete | required |
roleUpdates | array[object] | List of roles to add or update. | required |
id | string | This role's id | required |
label | string | This role's human-readable label | required |
permissions | array[object] | Permissions granted this role. | required |
operation | string | Values:
|
required |
filter | string | A formula which restricts a permission to specific records. Only record-level permissions can be filtered. | optional |
securityCategories | array[string] | required | |
parameters | array[object] | Parameters defined for this role. Parameters can be referenced in filtering formulas. | required |
parameterId | string | required | |
label | string | required | |
range | string | required | |
filters | array[object] | Pre-defined filters. Role filters allow other users to choose filters for permissions without having to write formulas themselves. | required |
id | string | This filter's id. | required |
label | string | This filter's human-readable label | required |
filter | string | A formula that can be used to filter a record-level permission. | required |
grants | array[object] | required | |
resourceId | string | required | |
operations | array[string] | required | |
version | integer | required | |
grantBased | boolean | required | |
roleDeletions | array[string] | List of role ids to delete. | required |
languageUpdates | array[string] | List of languages to add or update | required |
languageDeletions | array[string] | List of languages to delete | required |
originalLanguage | string | Original language update | optional |
continuousTranslation | boolean | Update of continuous automatic translation | optional |
translationFromDbMemory | boolean | Update of allowing the translation from database memory | optional |
thirdPartyTranslation | boolean | Update of allowing the use of third-party services for translation | optional |
publishedTemplate | boolean | optional |
Responses application/json
Status Code | Error Code | Description |
---|---|---|
200 | The database was successfully updated | |
401 | AUTHENTICATION_REQUIRED | The request must be authenticated, using basic authentication. |
400 | INVALID_UPDATE | One of the items to be deleted could not be found |
403 | PERMISSION_DENIED | |
404 | DATABASE_NOT_FOUND |
Database Users
Get list of database users
HTTP Request
GET https://www.activityinfo.org/resources/databases/{databaseId}/users
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/resources/databases/ck8oykh8m5/users
The above command returns JSON structured like this:
[
{
"databaseId": "ck8oykh8m5",
"userId": "401",
"name": "Bob",
"email": "bob@example.com",
"role": {
"id": "admin",
"parameters": null,
"resources": [
"ck8oykh8m5"
]
},
"version": 34,
"inviteDate": "",
"deliveryStatus": "OK",
"inviteAccepted": true
},
{
"databaseId": "ck8oykh8m5",
"userId": "499",
"name": "Amin",
"email": "amin@abc.org",
"role": {
"id": "rp",
"parameters": {
"partner": "ck8oyloog8:cjt46yclfs3a5hu3"
},
"resources": [
"cn0lxeglfs3a5hu4",
"cmnwsh3lfs3a5hu5"
]
},
"version": 34,
"inviteDate": "",
"deliveryStatus": "OK",
"inviteAccepted": true
}
]
Successful Response application/json
array[object] | |||
databaseId | string | required | |
userId | string | required | |
name | string | The user's name, provided either when invited or by the user themselves after activating their account. | required |
string | This user's email address. | required | |
role | object | This user's assigned role in the database. | required |
roleId | string | The id of the role assigned to this user. | required |
roleParameters | object | The values of the parameters defined for this role. | required |
roleResources | array[string] | The resources (database, folder, forms, or subforms) to which the role's permissions are to apply. | required |
version | integer | A monotonically-increasing version number. This version is incremented each time a change is made to the users permissions. | required |
inviteDate | string | The date on which the user was invited to this database. | required |
deliveryStatus | string | Values:
|
required |
inviteAccepted | boolean | True if the user has accept the invitation to create an ActivityInfo account. | required |
Add a database user
HTTP Request
POST https://www.activityinfo.org/resources/databases/{databaseId}/users
Request Body application/json
object | |||
string | The email of the user to add | required | |
name | string | The name of the user to add. This is only used in the email invitation to the user if there is no existing ActivityInfo account with this email address. | required |
locale | string | The locale to use when sending an email invite to the user. | required |
role | object | The role to assign to the user. | required |
roleId | string | The id of the role assigned to this user. | required |
roleParameters | object | The values of the parameters defined for this role. | required |
roleResources | array[string] | The resources (database, folder, forms, or subforms) to which the role's permissions are to apply. | required |
grants | array[object] | Additional permissions to grant to the user. | required |
resourceId | string | required | |
operations | array[string] | required |
Responses application/json
Status Code | Error Code | Description |
---|---|---|
200 | User successfully added to database | |
401 | AUTHENTICATION_REQUIRED | The request must be authenticated, using basic authentication. |
400 | CANNOT_ADD_OWNER | The owner of a database cannot be added as a user. |
400 | CANNOT_ADD_SELF | You cannot add yourself to a database. |
400 | DATABASE_NOT_FOUND | A database with this id could not be found |
400 | INVALID_LOCALE | The requested locale is invalid or not available. |
400 | INVALID_ROLE_PARAMETERS | The role parameters must be a JSON object including a value for each of the role parameters. |
400 | ROLE_NOT_FOUND | A role with the requested id could not be found in this database. |
400 | USER_ALREADY_ADDED | A user with this email address has already been added to the database. |
402 | BILLING_ACCOUNT_CLOSED | The billing account associated with this database has been closed and so no additional users can be added. |
402 | BILLING_ACCOUNT_SUSPENDED | The billing account associated with this database has been suspended so no additional users can be added. |
402 | USER_LIMIT_EXCEEDED | The user limit of the billing account associated with this database has been exceeded so no additional users can be added. |
403 | PERMISSION_DENIED | You do not have sufficient permission to add a user to this database. |
500 | INTERNAL_SERVER_ERROR |
Update a user's role
HTTP Request
POST https://www.activityinfo.org/resources/databases/{databaseId}/users/{userId}
Request Body application/json
object | |||
assignments | array[object] | required | |
roleId | string | The id of the role assigned to this user. | required |
roleParameters | object | The values of the parameters defined for this role. | required |
roleResources | array[string] | The resources (database, folder, forms, or subforms) to which the role's permissions are to apply. | required |
Deletes a user from a database
HTTP Request
DELETE https://www.activityinfo.org/resources/databases/{databaseId}/users/{userId}
Request Body application/json
object | |||
assignments | array[object] | required | |
roleId | string | The id of the role assigned to this user. | required |
roleParameters | object | The values of the parameters defined for this role. | required |
roleResources | array[string] | The resources (database, folder, forms, or subforms) to which the role's permissions are to apply. | required |
Responses application/json
Status Code | Error Code | Description |
---|---|---|
401 | AUTHENTICATION_REQUIRED | The request must be authenticated, using basic authentication. |
200 | OK | The user was successfully deleted from the database |
400 | DATABASE_DELETED | The database was deleted and no longer exists. |
400 | DATABASE_NOT_FOUND | A database with this id could not be found. |
400 | USER_NOT_FOUND | A user with this id could not be found in the database. |
403 | DELETED_USERS_PERMISSION_SUPERIOR | The user with this id has permissions superior to yours and so you may not delete the user. |
403 | MANAGE_USER_PERMISSION_MISSING | You do not have the permission to manage users in this database. |
Forms
Get a form's schema
HTTP Request
GET https://www.activityinfo.org/resources/form/{formId}
Update a form's schema
HTTP Request
POST https://www.activityinfo.org/resources/form/{formId}
Request Body application/json
object | |||
id | string | required | |
label | string | required | |
schemaVersion | string | required | |
databaseId | string | required | |
parentFormId | string | optional | |
elements | array[object] | required | |
id | string | required | |
code | string | required | |
label | string | required | |
relevanceCondition | string | required | |
validationCondition | string | required | |
visible | boolean | required | |
required | boolean | required | |
key | boolean | required | |
type | string | required | |
securityCategoryId | string | optional | |
typeParameters | object | required | |
units | string | optional | |
inputMask | string | optional | |
cardinality | string | optional | |
range | object | optional | |
formId | string | optional | |
items | array[object] | optional | |
formula | string | optional | |
prefixFormula | string | optional |
Relocate a form to a new database
Relocating a form moves the form, together with all of its subforms, records, and record history, to a new database.
In order to relocate a form, the user must have "delete" permission in the source database, and permission to add new forms in the target database.
HTTP Request
POST https://www.activityinfo.org/resources/form/{formId}/database
Request Body application/json
object | |||
databaseId | string | The id of the database to which this form should be transferred | required |
Responses application/json
Status Code | Error Code | Description |
---|---|---|
401 | AUTHENTICATION_REQUIRED | The request must be authenticated, using basic authentication. |
200 | RELOCATED | The form has been successfully relocated. |
400 | CANNOT_RELOCATE_TO_SAME_DATABASE | The source and target databases are the same. |
400 | SUB_FORMS_CANNOT_BE_RELOCATED | The form requested to relocate is a subform. Only top level forms can be relocated. |
403 | ADDING_FORM_FORBIDDEN | The authenticated user does not have permission to add the form to the target database. |
403 | DELETING_FORM_FORBIDDEN | The authenticated user does not have permission to delete the form from its current database. |
404 | DATABASE_NOT_FOUND | Either the source or target database does not exist. |
404 | FORM_NOT_FOUND | No such form with this id exists in the given database. |
Records
Get a record
HTTP Request
GET https://www.activityinfo.org/resources/form/{formId}/record/{recordId}
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/resources/form/ck8oyloog8/record/ck34ujs6v8
The above command returns JSON structured like this:
{
"recordId": "c6kcr2elfs3a5k97",
"formId": "ca67dy4lfs3a5k96",
"lastEditTime": 1.616167934481E12,
"fields": {
"co8ffaslfs3a5k98": "Simple text value",
"cnk4yqplfs3a5k99": {
"prefix": "AA",
"number": 3423
},
"cpj31rrlfs3a5k9a": 42.5,
"case12dlfs3a5kab": [
"cy8ujhglfs3a5kgc",
"cskv879lfs3a5kgd"
],
"c5gtoa1lfs3a5kme": {
"latitude": 52.0705,
"longitude": -4.3007
},
"cxifestlfs3a5knf": "ck8oyloog8:ck34ujs6v8",
"c29d51zlfs3a5kog": "2019-12-31",
"c2n6cazlfs3a5koh": [
{
"mimeType": "application/pdf",
"width": 0,
"height": 0,
"filename": "annual_report.pdf",
"blobId": "fhodvllfs3a5kpi"
}
]
}
}
Query records in a form
Queries the form's records as list of JSON objects.
The request returns a list of JSON objects, with one object for each record.
Where provided, a field's code is used as the JSON field name, otherwise the field's label will be used.
By default, text values will be truncated to 128 characters. Truncation can be disabled by passing the query parameter _truncate=false
.
HTTP Request
GET https://www.activityinfo.org/form/{formId}/query
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/form/ck8oyloog8/query
The above command returns JSON structured like this:
[
{
"record": "cs24y79lfs3a5kzj",
"partnerId": "ck8oyloog8:ck34ujs6v8",
"partnerName": "NRC",
"num_kits": 42,
"choose_any_id_you_like": 84,
"date": "2020-01-31",
"year": 2020
},
{
"record": "cfz0at0lfs3a5kzk",
"partnerName": "NRC",
"num_kits": null,
"choose_any_id_you_like": null,
"date": "2020-01-31",
"year": 2020
}
]
Query records as GeoJSON points
HTTP Request
GET https://www.activityinfo.org/form/{formId}/query/points?x={longitudeFormula}&y={latitudeFormula}
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/form/ck8oyloog8/query/points?x={longitudeFormula}&y={latitudeFormula}
Add, update, or delete records
Add, update, or delete one or more records.
The request can include up to 10 changes that are applied together.
When adding or updating records, fields
objects should contain the new field values, with the field's id or code as the property name.
HTTP Request
POST https://www.activityinfo.org/resources/update
curl -X POST https://www.activityinfo.org/resources/update \
-u me@example.com:mypassword \
-H 'Content-type: application/json' \
--data-binary @- << EOF
{
"changes": [
{
"formId": "ck8oyloog8",
"recordId": "ck34ujs6v8",
"parentRecordId": null,
"deleted": true,
"fields": null
},
{
"formId": "c4ua9y2lfs3a5l9l",
"recordId": "calw287lfs3a5l9m",
"parentRecordId": null,
"deleted": false,
"fields": {
"ccif8tilfs3a5l9n": "Simple text value",
"cwtlnjlfs3a5l9o": {
"prefix": "AA",
"number": 3423
},
"cms1onxlfs3a5l9p": 42.5,
"ct8kqlalfs3a5l9q": [
"cpackq5lfs3a5l9r",
"cuhzq3xlfs3a5l9s"
],
"c3zt0eylfs3a5l9t": {
"latitude": 52.0705,
"longitude": -4.3007
},
"clz7jt1lfs3a5l9u": "ck8oyloog8:ck34ujs6v8",
"cu44s2nlfs3a5l9v": "2019-12-31",
"cirz03plfs3a5l9w": [
{
"mimeType": "application/pdf",
"width": 0,
"height": 0,
"filename": "annual_report.pdf",
"blobId": "y7xfjtlfs3a5l9x"
}
]
}
}
]
}
EOF
Request Body application/json
object | |||
changes | array[object] | required | |
formId | string | required | |
recordId | string | required | |
parentRecordId | string | optional | |
deleted | boolean | required | |
fields | object | required |
Reports
Get a report's definition
HTTP Request
GET https://www.activityinfo.org/resources/reports/{reportId}
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5
The above command returns JSON structured like this:
{
"id": "cht8p4kdeimokm5",
"ownerType": "PERSONAL",
"ownerId": "432201",
"ownerName": "",
"databaseId": null,
"label": "My report",
"published": true,
"grants": {
"roles": [
]
},
"layout": "SINGLE",
"icon": "",
"sources": {
"forms": [
"ck8pu9ha07"
],
"reports": [
],
"calculatedTables": [
]
},
"components": [
{
"id": "cv5wyndkqv9yuuq2",
"type": "ANALYSIS",
"content": "My table",
"subtitle": null,
"analysisType": "pivot",
"visualizationType": null,
"dataUrl": null,
"visible": true,
"position": null
}
],
"editType": "EDITABLE",
"pages": [
]
}
Get an analysis definition
HTTP Request
GET https://www.activityinfo.org/resources/reports/{reportId}/analyses/{analysisId}
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5/analyses/cv5wyndkqv9yuuq2
The above command returns JSON structured like this:
{
"id": "cv5wyndkqv9yuuq2",
"model": {
"visualization": "TABLE",
"measures": [
{
"id": "bfrxqvlfs3a5m8y",
"code": "",
"label": "Number",
"formId": "ck8pu9ha07",
"formula": "Number",
"statistics": [
"SUM"
],
"calculated": false
}
],
"dimensions": [
{
"id": "o137y4lfs3a5mfz",
"label": "",
"mappings": [
{
"formula": "Gender",
"type": "VALUE"
}
],
"axis": "ROW",
"totals": false,
"missingIncluded": false,
"percentage": false,
"dateLevel": null,
"totalLabel": null,
"missingLabel": null,
"categoryMappings": [
{
"label": "Male",
"source": [
"Male"
],
"visible": false
}
],
"mapTemplateId": null
}
]
},
"modelType": "pivot"
}
Get a report's results as rows
Queries a pivot table's rows as list of JSON objects.
The request returns a list of JSON objects, with one object for each row in the report.
HTTP Request
GET https://www.activityinfo.org/resources/reports/{reportId}/rows
curl -u anything:YOUR_API_TOKEN \
https://www.activityinfo.org/resources/reports/cht8p4kdeimokm5/rows
The above command returns JSON structured like this:
[
{
"Gender": "Female",
"Value": 97
},
{
"Gender": "Male",
"Value": 42
}
]
Jobs
Some requests, like exporting whole forms or databases, may take time to proccess. We call these "batch jobs" and they have a common API for starting batch jobs and retrieving their results.
For example, if you wanted to export an entire database, you would:
- Submit a request to Start a batch job
- Get the job's status until the job's state is
COMPLETED
orFAILED
. - Use the
downloadUrl
in the job result to retrieve the export.
Export form
HTTP Request
POST https://www.activityinfo.org/resources/jobs
curl -X POST https://www.activityinfo.org/resources/jobs \
-u me@example.com:mypassword \
-H 'Content-type: application/json' \
--data-binary @- << EOF
{
"type": "exportForm",
"descriptor": {
"model": {
"formId": "ck8pu9ha07",
"columns": [
],
"ordering": [
{
"formula": "AGE",
"ascending": false
}
],
"filter": "AGE > 18"
},
"format": "TEXT",
"utcOffset": 120
},
"locale": "en"
}
EOF
Request Body application/json
object | |||
type | string | The type of the job to start. Must be 'exportForm' | required |
descriptor | object | required | |
tableModel | object | required | |
formId | string | The id of the form from which the table should be created. | required |
columns | array[object] | A list of columns to include in the table. If the list is empty, a list of columns will be computed from the form's fields. | required |
id | string | The id of the column. This is used to identify the column in the result. | required |
label | string | The text to use as the column's header. | optional |
width | integer | The width, in pixels of the column. | required |
formula | string | The formula used to compute this column's values. | required |
ordering | array[object] | List of columns to use in ordering the form's records. | required |
formula | string | required | |
ascending | boolean | required | |
filter | string | A boolean-valued formula which filters which records are included. | optional |
format | string | Values:
|
required |
utcOffset | integer | The time zone to use for time values, as an offset from Universal Coordinate Time (UTC) in minutes, | required |
The above command returns JSON structured like this:
{
"type": "exportForm",
"descriptor": {
"model": {
"formId": "ck8pu9ha07",
"columns": [
],
"ordering": [
{
"formula": "AGE",
"ascending": false
}
],
"filter": "AGE > 18"
},
"format": "TEXT",
"utcOffset": 120
},
"locale": "en"
}
Export database forms
HTTP Request
POST https://www.activityinfo.org/resources/jobs
curl -X POST https://www.activityinfo.org/resources/jobs \
-u me@example.com:mypassword \
-H 'Content-type: application/json' \
--data-binary @- << EOF
{
"type": "exportDatabaseForms",
"descriptor": {
"databaseId": "ck8oykh8m5",
"folderId": "ceponkikiswy1bt2",
"format": "LONG",
"fileFormat": "XLSX",
"filter": "Month == '2021-01'",
"includeBlanks": false,
"utcOffset": 120
},
"locale": "en"
}
EOF
Request Body application/json
object | |||
type | string | The type of the job to start. Must be 'exportDatabaseForms' | required |
descriptor | object | required | |
databaseId | string | The id of the database containing the forms to export. | required |
folderId | string | Optionally, the folder or form to include in the export. If ommitted, then all forms in the database will be included. | optional |
format | string | The format of the table structure.Values:
|
required |
fileFormat | string | The file format.Values:
|
required |
filter | string | A formula that is applied to each form to filter the resulting records. | optional |
includeBlanks | boolean | True if the export should include rows for blank quantities. Only applies to the LONG format. | required |
utcOffset | integer | The time zone to use for time values, as an offset from Universal Coordinate Time (UTC) in minutes, | required |
The above command returns JSON structured like this:
{
"id": "c8my7utlfs3a5oq10",
"userId": "432201",
"type": "exportDatabaseForms",
"descriptor": {
"databaseId": "ck8oykh8m5",
"folderId": "ceponkikiswy1bt2",
"format": "LONG",
"fileFormat": "XLSX",
"filter": "Month == '2021-01'",
"includeBlanks": false,
"utcOffset": 120
},
"state": "completed",
"locale": "EN",
"percentComplete": 100,
"result": {
"downloadUrl": "resources/jobs/AXSDddl2aXR5aW5m32AJFDFadsl/My_database__20201124_124106_UTC.xlsx",
"filename": "My_database__20201124_124106_UTC.xlsx"
}
}
Get a batch job's status
HTTP Request
GET https://www.activityinfo.org/resources/jobs/{jobId}
Successful Response application/json
object | |||
id | string | The job's id | required |
userId | string | The id of the user who started the job | required |
descriptor | object | The job descriptor used to start this job | required |
state | string | The job's current stateValues:
|
required |
jobResult | object | required | |
filename | string | The filename of the export. | required |
downloadUrl | string | The (par | required |
locale | string | The localeValues:
|
required |
percentComplete | float | required | |
error | object | If the job state is FAILED, the reason for the failure. | optional |
code | string | required | |
message | string | required | |
localizedMessage | string | required |
The above command returns JSON structured like this:
{
"id": "cce3i84lfs3a5pq11",
"userId": "432201",
"type": "exportDatabaseForms",
"descriptor": {
"databaseId": "ck8oykh8m5",
"folderId": "ceponkikiswy1bt2",
"format": "LONG",
"fileFormat": "XLSX",
"filter": "Month == '2021-01'",
"includeBlanks": false,
"utcOffset": 120
},
"state": "completed",
"locale": "EN",
"percentComplete": 100,
"result": {
"downloadUrl": "resources/jobs/AXSDddl2aXR5aW5m32AJFDFadsl/My_database__20201124_124106_UTC.xlsx",
"filename": "My_database__20201124_124106_UTC.xlsx"
}
}