commcare@3.2.4
- bulk(type, data, params)
- fetchReportData(reportId, params, postUrl)
- get(path, [params], [callback])
- post(path, data, [params], [callback])
- request(method, path, body, options)
- submit(data)
- submitXls(data, params)
This adaptor exports the following from common:
- alterState()
- arrayToString()
- combine()
- cursor()
- dataPath()
- dataValue()
- dateFns
- each()
- field()
- fields()
- fn()
- fnIf()
- http
- lastReferenceValue()
- merge()
- sourceValue()
Functions
bulk
bulk(type, data, params) ⇒ Operation
Bulk upload data to CommCare for case-data or lookup-table. Accepts an array of objects, converts them into an XLS representation, and uploads.
Param | Type | Description |
---|---|---|
type | 'case-data' | 'lookup-table' | The type of data being processed. |
data | Object | Array.<Object> | An object or an array of objects to upload. - If type is 'case-data' , this should be an object array of objects. - If type is 'lookup-table' , this should be an object. |
params | Object | Input parameters, see CommCare docs for case-data and Commcare Docs for lookup-table. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | the response from the CommCare Server |
Example: Upload a single row of data for case-data
bulk(
'case-data',
[
{name: 'Mamadou', phone: '000000'},
],
{
case_type: 'student',
search_field: 'external_id',
create_new_cases: 'on',
}
)
Example: Upload a single row of data for a lookup-table
bulk(
'lookup-table',
{
types: [{
'DELETE(Y/N)':'N',
table_id: 'fruit',
'is_global?':'yes',
'field 1': 'type',
'field 2': 'name',
}],
fruit: [{
UID: '',
'DELETE(Y/N)':'N',
'field:type': 'citrus',
'field:name': 'Orange',
}],
},
{replace: false}
)
fetchReportData
fetchReportData(reportId, params, postUrl) ⇒ Operation
Make a GET request to CommCare's Reports API and POST the response somewhere else.
Param | Type | Description |
---|---|---|
reportId | String | API name of the report. |
params | Object | Input parameters for the request, see Commcare docs. |
postUrl | String | URL to which the response object will be posted. |
Example: Fetch 10 records from a report and post them to example.com
fetchReportData(
"9aab0eeb88555a7b4568676883e7379a",
{ limit: 10 },
"https://www.example.com/api/"
)
get
get(path, [params], [callback]) ⇒ Operation
Make a GET request to any CommCare endpoint. The response body will be returned to state.data
as JSON.
Paginated responses will be fully downloaded and returned as a single array, unless an offset
is passed.
Param | Type | Description |
---|---|---|
path | string | Path to resource |
[params] | Object | Input parameters for the request. These vary by endpoint, see CommCare docs. |
[callback] | function | Optional callback function. Invoked once per page of data retrieved. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | The response body (as JSON) |
response | The HTTP response from the CommCare server (excluding the body) |
references | An array of all previous data objects used in the Job |
Example: Get a specific case by id
get("/case/12345")
Example: Get exactly 20 cases
get("/case", { offset:0, limit: 20 })
Example: Get forms by app id
get("/form", { app_id: "02bf50ab803a89ea4963799362874f0c" })
Example: Get all cases, 50 at a time, and add them to state
get("/case", {}, (state) => {
state.cases.push(...state.data) // adds 50 cases to the cases array
return state;
})
post
post(path, data, [params], [callback]) ⇒ Operation
Make a POST request to any CommCare endpoint.
Param | Type | Description |
---|---|---|
path | string | Path to resource |
data | object | Object or JSON to use as the request body |
[params] | Object | Optional request params |
[callback] | function | Optional callback to handle the response |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | The response body (as JSON) |
response | The HTTP response from the CommCare server (excluding the body) |
references | An array of all previous data objects used in the Job |
Example: Post a user object to to the /user endpoint
post("/user", { "username":"test", "password":"somepassword" })
request
request(method, path, body, options) ⇒ Operation
Make a general HTTP request against the Commcare server.
Param | Type | Description |
---|---|---|
method | string | HTTP method to use |
path | string | Path to resource |
body | object | Object which will be attached to the body |
options | RequestOptions | Optional request params |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | The response body (as JSON) |
response | The HTTP response from the CommCare server (excluding the body) |
references | An array of all previous data objects used in the Job |
Example: Make a GET request to get cases
request("GET", "/a/asri/api/v0.5/case");
submit
submit(data) ⇒ Operation
Submit forms to CommCare. Accepts an array of JSON objects, converts them into XML, and submits to CommCare as an x-form.
Param | Type | Description |
---|---|---|
data | Object | The form as a JSON object |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | the response from the CommCare Server |
Example: Submit a form to CommCare
submit(
fields(
field("@", (state) => ({
"xmlns": `http://openrosa.org/formdesigner/${state.formId}`
}),
field("question1", (state) => state.data.answer1),
field("question2", (state) => state.data.answer2),
)
)
submitXls
submitXls(data, params) ⇒ Operation
Bulk upload data to CommCare. Accepts an array of objects, converts them into an XLS representation, and uploads.
Param | Type | Description |
---|---|---|
data | array | Array of objects to upload |
params | Object | Input parameters, see CommCare docs. |
This operation writes the following keys to state:
State Key | Description |
---|---|
data | the response from the CommCare Server |
Example: Upload a single row of data
submitXls(
[
{name: 'Mamadou', phone: '000000'},
],
{
case_type: 'student',
search_field: 'external_id',
create_new_cases: 'on',
}
)