commcare@3.2.13

bulk(type, data, params)

fetchReportData(reportId, params, postUrl)

get(path, [params], [callback])

post(path, data, [params], [callback])

request(method, path, body, params)

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 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: Upload a single row of a case-data resource

bulk('case-data', [{ name: 'Mamadou', phone: '000000' }], {
  case_type: 'student',
  search_field: 'external_id',
  create_new_cases: 'on',
});

Example: Upload a single row of a lookup-table resource

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.

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 10 records from a report and post them to example.com. Equivalent to <baseUrl>/configurablereportdata/abcde?limit=10

fetchReportData(
  "abcde",
  { limit: 10 },
  "https://www.example.com/api/"
)

---

get

get(path, [params], [callback]) ⇒ Operation

Make a GET request to CommCare. Use this to fetch resources directly from Commcare REST API. You can pass Commcare query parameters as an object of key value pairs, which will map to parameters in the URL. 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 resource by Id. Equivalent to GET <baseUrl>/case/12345

get("/case/12345")

Example: Get a resource with exactly 20 items. Equivalent to <baseUrl>/case?offset=0&limit=20

get("/case", { offset:0, limit: 20 })

Example: Get all items in a resource, and add them to state. Equivalent to <baseUrl>/case

get("/case", {}, (state) => {
  state.cases.push(...state.data) // adds all cases to the cases array
  return state;
})

---

post

post(path, data, [params], [callback]) ⇒ Operation

Make a POST request to CommCare. Use this to send resources directly to Commcare REST API. You can pass Commcare body data as a JSON object.

Param	Type	Description
path	string	Path to resource
data	object	Object or JSON to create a resource
[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: Create a user resource.Equivalent to <baseUrl>/user

post("/user", { "username":"test", "password":"somepassword" })

---

request

request(method, path, body, params) ⇒ Operation

Make a general HTTP request against the Commcare server. Use this to make any request to Commcare REST API.

Param	Type	Description
method	string	HTTP method to use
path	string	Path to resource
body	object	Object which will be attached to the body
params	object	An object of query parameters to be encoded into the URL

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 resource. Equivalent to <baseUrl>/a/asri/api/v0.5/case

request("GET", "/a/asri/api/v0.5/case");

Example: Get a resource using query parameters. Equivalent to <baseUrl>/case?offset=0&limit=20

request("GET", "/case", {}, { offset:0, limit: 20 })

---

submit

submit(data) ⇒ Operation

Submit forms to CommCare. Use this to send forms directly to Commcare REST API. 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 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: Submit a form resource.

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. Use this to send multiple items for a single resource at once to Commcare. It 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 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: Upload a single row of data for a resource.

submitXls([{ name: 'Mamadou', phone: '000000' }], {
  case_type: 'student',
  search_field: 'external_id',
  create_new_cases: 'on',
});

---