surveycto@3.0.0

cursor(value, options)

fetchSubmissions(formId, options)

jsonToCSVBuffer(rows)

list(resource, options)

uploadCsvRecords(datasetId, rows, metadata)

upsertDataset(data)

upsertRecord(datasetId, data)

This adaptor exports the following namespaced functions:

http.delete(path, params)

http.get(path, params)

http.post(path, params)

http.request(path, params)

This adaptor exports the following from common:

alterState()

chunk()

dataPath()

dataValue()

dateFns

field()

fields()

fn()

fnIf()

lastReferenceValue()

merge()

parseCsv()

sourceValue()

Functions

cursor

cursor(value, options) ⇒ Operation

Sets state.cursor to a SurveyCTO timestamp string (MMM dd, yyy h:mm:ss a). This supports natural language dates like now, today, yesterday, n hours ago, n days ago, and start, which will be converted into timestamp strings. See the usage guide at https://docs.openfn.org/documentation/jobs/job-writing-guide#using-cursors

Param	Type	Description
value	any	the cursor value. Usually an ISO date, natural language date, or page number
options	object	options to control the cursor.
options.key	string	set the cursor key. Will persist through the whole run.
options.defaultValue	any	the value to use if value is falsy
options.format	function	custom formatter for the final cursor value

Example: Use a cursor from state if present, or else use the default value

cursor('today')
fetchSubmissions('test', { date: $.cursor });

---

fetchSubmissions

fetchSubmissions(formId, options) ⇒ Operation

Fetch form submissions.

If a date filter is provided, it will be converted internally to the surveyCTO MMM dd, yyy h:mm:ss format (in UTC time).

Param	Type	Description
formId	string	Form id
options	FetchSubmissionOptions	Form submission date, format, status parameters

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode etc
references	an array of all previous data objects used in the Job.

Example: Fetch all form submissions

fetchSubmissions('test');

Example: With SurveyCTO date format (UTC)

fetchSubmissions('test', { date: 'Apr 18, 2024 6:26:21 AM' });

Example: Using a rolling cursor

cursor((state) => state.cursor, { defaultValue: 'today' });
fetchSubmissions('test', { date: (state) => state.cursor, format: 'csv' });
cursor('now');

Example: Formatting the results to CSV String

fetchSubmissions('test', { format: 'csv' });

Example: With reviewStatus filter

fetchSubmissions('test', { status: 'approved|rejected' });

---

jsonToCSVBuffer

jsonToCSVBuffer(rows) ⇒ Operation

Converts an array of objects to a CSV buffer.

Param	Type	Description
rows	*	An array of JSON objects.

Example

jsonToCSVBuffer([
 {
    lastName: 'Rothfuss',
    firstName: 'Patrick',
    book: 'The Name of the Wind'
  },
 {
    lastName: 'Martin',
    firstName: 'George',
    book: 'A Game of Thrones'
  },
])

---

list

list(resource, options) ⇒ Operation

List resources from SurveyCTO

Param	Type	Description
resource	string	Resource to fetch
options	object	Optional request query options. See the API docs for details

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the server with total and nextCursor
references	an array of all previous data objects used in the Job.

Properties

Name	Type	Description
options.limit	number	Maximum number of items to return. Defaults to 20. Maximum is 1000.
options.cursor	string	Optional string to specify the starting point of the next page of results.

Example: List all dataset records

list(`datasets/${$.datasetId}/records`)

Example: List all datasets

list('datasets')

Example: List dataset records with pagination options

list(`datasets/${$.datasetId}/records`,{
  limit: 2,
});

Example: List datasets with pagination options

list('datasets',{
  limit: 2,
});

---

uploadCsvRecords

uploadCsvRecords(datasetId, rows, metadata) ⇒ Operation

Upload CSV dataset records

Param	Type	Description
datasetId	string	ID of the dataset
rows	string	An array of JSON objects to be uploaded as records. The data will be converted to CSV format before upload.
metadata	object	Optional metadata for configuring how the uploaded data should be processed

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode etc
references	an array of all previous data objects used in the Job.

Properties

Name	Type	Description
joiningField	string	Optional field name to use for merging records. Required when uploadMode is MERGE.
uploadMode	string	Optional upload mode. One of APPEND (default), MERGE and CLEAR.

Example: Upload records

uploadCsvRecords('enumerators_dataset', [
  {
    id: '4',
    name: 'Trial update',
    users: 'All users',
  },
  {
    id: '5',
    name: 'Trials',
    users: 'All users here',
  },
]);

Example: Upload records with metadata

uploadCsvRecords(
  'enumerators_dataset',
  [
    {
      id: '4',
      name: 'Trial update',
      users: 'All users',
    },
    {
      id: '5',
      name: 'Trials',
      users: 'All users here',
    },
  ],
  {
    uploadMode: 'MERGE',
    joiningField: 'id',
  }
);

---

upsertDataset

upsertDataset(data) ⇒ Operation

Update (if exist) or create a dataset in SurveyCTO

Param	Type	Description
data	object	The dataset object to create or update

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode etc
references	an array of all previous data objects used in the Job.

Example: Upsert a dataset

upsertDataset({
  id: 'enum_dataset',
  title: 'Enum Dataset',
  discriminator: 'ENUMERATORS',
  locationContext: {
    parentGroupId: 1,
    siblingAbove: {
      id: 'new_dataset',
      itemClass: 'DATASET',
    },
  },
  allowOfflineUpdates: false,
  idFormatOptions: {
    prefix: 'enum',
    suffix: '',
    numberOfDigits: '8',
    allowCapitalLetters: true,
  },
});

---

upsertRecord

upsertRecord(datasetId, data) ⇒ Operation

Update (if exist) or create a dataset record in SurveyCTO

Param	Type	Description
datasetId	string	ID of the dataset
data	object	The record object to create or update

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode etc
references	an array of all previous data objects used in the Job.

Example: Upsert a dataset record

upsertRecord('enumerators_dataset', {
  id: '2',
  name: 'Trial update',
  users: 'All users',
});

---

http

These functions belong to the http namespace.

http.delete

delete(path, params) ⇒ Operation

Delete resources from SurveyCTO

Param	Type	Description
path	string	Path to resource
params	RequestOptions	Query and headers parameters

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode, body, etc
references	an array of all previous data objects used in the Job

Example: Delete a dataset

http.delete('/datasets/enumerators_dataset');

Example: Delete a dataset record

http.delete('/datasets/enumerators_dataset/record', {
  query: {
    recordId: 2,
  },
});

---

http.get

get(path, params) ⇒ Operation

Get resources from SurveyCTO

Param	Type	Description
path	string	Path to resource
params	RequestOptions	Query and headers parameters

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode, body, etc
references	an array of all previous data objects used in the Job

Example: Get a record with id

http.get('/datasets/enumerators_dataset/record', {
  query: {
    recordId: '4',
  },
});

Example: Get a dataset with id

http.get('/datasets/enumerators_dataset')

Example: Get a dataset in csv format

http.get('/datasets/data/csv/enumerators_dataset', {
  query: {
    asAttachment: true,
  },
});

---

http.post

post(path, params) ⇒ Operation

Send a HTTP POST request to SurveyCTO

Param	Type	Description
path	string	Path to resource
params	RequestOptions	Query, body, and headers parameters

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode, body, etc
references	an array of all previous data objects used in the Job

Example: Purge a dataset

http.post('/datasets/enumeratorse_dataset/purge');

---

http.request

request(path, params) ⇒ Operation

Make a HTTP request to SurveyCTO

Param	Type	Description
path	string	Path to resource
params	RequestOptions	Query, body, headers and method parameters

This operation writes the following keys to state:

State Key	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode, body, etc
references	an array of all previous data objects used in the Job

Example: Post JSON data to SurveyCTO

http.request("/anEndpoint", {
  method: "POST",
   contentType: "json",
  body: $.data,
});

Example: Upload a CSV blob to a dataset

  http.request('datasets/library/records/upload', {
    method: 'POST',
    contentType: 'form',
    body: {
      file: {
        blob: $.data,
        type: 'text/csv',
        filename: 'library.csv'
      }
    },
  });

---

Interfaces

FetchSubmissionOptions

Options provided to fetchSubmissions()

Properties

Name	Type	Default	Description
[date]	string	0	Fetch only submissions from this timestamp. Acccepts SuvreyCTO date strings, unix and epoch timestamps, and ISO dates. By default, all submissions will be retrieved.
[format]	string	"json"	Format the submission data type as csv or json.
[status]	string		Review status. Can be either, approved, rejected, pending or combine eg `approved

---

HTTPState

State object

Properties

Name	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode, body, etc
references	an array of all previous data objects used in the Job

---

RequestOptions

Options provided to request()

Properties

Name	Type	Default	Description
[headers]	object		An object of headers parameters.
[body]	object		Body data to append to the request.
[query]	object		An object of query parameters to be encoded into the URL.
[contentType]	object		Set the content-type header to the appropriate format. Supported values: json and form
[method]	string	"GET"	The HTTP method to use.

---

SurveyCTOListState

List State object

Properties

Name	Description
data	the parsed response body
response	the response from the server with total and nextCursor
references	an array of all previous data objects used in the Job.

---

SurveyCTOState

State object

Properties

Name	Description
data	the parsed response body
response	the response from the SurveyCTO server, including headers, statusCode etc
references	an array of all previous data objects used in the Job.

---