{ "operations": [ { "name": "fetchSubmissions", "params": [ "formId", "options" ], "docs": { "description": "Fetch form submissions.\n\nIf a date filter is provided, it will be converted internally to the surveyCTO `MMM dd, yyy h:mm:ss` format (in UTC time).", "tags": [ { "title": "example", "description": "fetchSubmissions('test');", "caption": "Fetch all form submissions" }, { "title": "example", "description": "fetchSubmissions('test', { date: 'Apr 18, 2024 6:26:21 AM' });", "caption": "With SurveyCTO date format (UTC)" }, { "title": "example", "description": "cursor((state) => state.cursor, { defaultValue: 'today' });\nfetchSubmissions('test', { date: (state) => state.cursor, format: 'csv' });\ncursor('now');", "caption": "Using a rolling cursor" }, { "title": "example", "description": "fetchSubmissions('test', { format: 'csv' });", "caption": "Formatting the results to CSV String" }, { "title": "example", "description": "fetchSubmissions('test', { status: 'approved|rejected' });", "caption": "With reviewStatus filter" }, { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "param", "description": "Form id", "type": { "type": "NameExpression", "name": "string" }, "name": "formId" }, { "title": "param", "description": "Form submission date, format, status parameters", "type": { "type": "NameExpression", "name": "FetchSubmissionOptions" }, "name": "options" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } }, { "title": "state", "description": "{SurveyCTOState}" } ] }, "valid": true }, { "name": "list", "params": [ "resource", "options" ], "docs": { "description": "List resources from SurveyCTO", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "example", "description": "list(`datasets/${$.datasetId}/records`)", "caption": "List all dataset records" }, { "title": "example", "description": "list('datasets')", "caption": "List all datasets" }, { "title": "example", "description": "list(`datasets/${$.datasetId}/records`,{\n limit: 2,\n});", "caption": "List dataset records with pagination options" }, { "title": "example", "description": "list('datasets',{\n limit: 2,\n});", "caption": "List datasets with pagination options" }, { "title": "function", "description": null, "name": null }, { "title": "param", "description": "Resource to fetch", "type": { "type": "NameExpression", "name": "string" }, "name": "resource" }, { "title": "param", "description": "Optional request query options. [See the API docs for details](https://developer.surveycto.com/api-v2.html#getdatasets-parameters)", "type": { "type": "NameExpression", "name": "object" }, "name": "options" }, { "title": "property", "description": "Maximum number of items to return. Defaults to 20. Maximum is 1000.", "type": { "type": "NameExpression", "name": "number" }, "name": "options.limit" }, { "title": "property", "description": "Optional string to specify the starting point of the next page of results.", "type": { "type": "NameExpression", "name": "string" }, "name": "options.cursor" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } }, { "title": "state", "description": "{SurveyCTOListState}" } ] }, "valid": true }, { "name": "upsertDataset", "params": [ "data" ], "docs": { "description": "Update (if exist) or create a dataset in SurveyCTO", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "example", "description": "upsertDataset({\n id: 'enum_dataset',\n title: 'Enum Dataset',\n discriminator: 'ENUMERATORS',\n locationContext: {\n parentGroupId: 1,\n siblingAbove: {\n id: 'new_dataset',\n itemClass: 'DATASET',\n },\n },\n allowOfflineUpdates: false,\n idFormatOptions: {\n prefix: 'enum',\n suffix: '',\n numberOfDigits: '8',\n allowCapitalLetters: true,\n },\n});", "caption": "Upsert a dataset" }, { "title": "function", "description": null, "name": null }, { "title": "param", "description": "The dataset object to create or update", "type": { "type": "NameExpression", "name": "object" }, "name": "data" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } }, { "title": "state", "description": "{SurveyCTOState}" } ] }, "valid": true }, { "name": "upsertRecord", "params": [ "datasetId", "data" ], "docs": { "description": "Update (if exist) or create a dataset record in SurveyCTO", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "example", "description": "upsertRecord('enumerators_dataset', {\n id: '2',\n name: 'Trial update',\n users: 'All users',\n});", "caption": "Upsert a dataset record" }, { "title": "function", "description": null, "name": null }, { "title": "param", "description": "ID of the dataset", "type": { "type": "NameExpression", "name": "string" }, "name": "datasetId" }, { "title": "param", "description": "The record object to create or update", "type": { "type": "NameExpression", "name": "object" }, "name": "data" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } }, { "title": "state", "description": "{SurveyCTOState}" } ] }, "valid": true }, { "name": "uploadCsvRecords", "params": [ "datasetId", "rows", "metadata" ], "docs": { "description": "Upload CSV dataset records", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "example", "description": "uploadCsvRecords('enumerators_dataset', [\n {\n id: '4',\n name: 'Trial update',\n users: 'All users',\n },\n {\n id: '5',\n name: 'Trials',\n users: 'All users here',\n },\n]);", "caption": "Upload records" }, { "title": "example", "description": "uploadCsvRecords(\n 'enumerators_dataset',\n [\n {\n id: '4',\n name: 'Trial update',\n users: 'All users',\n },\n {\n id: '5',\n name: 'Trials',\n users: 'All users here',\n },\n ],\n {\n uploadMode: 'MERGE',\n joiningField: 'id',\n }\n);", "caption": "Upload records with metadata" }, { "title": "function", "description": null, "name": null }, { "title": "param", "description": "ID of the dataset", "type": { "type": "NameExpression", "name": "string" }, "name": "datasetId" }, { "title": "param", "description": "An array of JSON objects to be uploaded as records. The data will be converted to CSV format before upload.", "type": { "type": "NameExpression", "name": "string" }, "name": "rows" }, { "title": "param", "description": "Optional metadata for configuring how the uploaded data should be processed", "type": { "type": "NameExpression", "name": "object" }, "name": "metadata" }, { "title": "property", "description": "Optional field name to use for merging records. Required when uploadMode is `MERGE`.", "type": { "type": "NameExpression", "name": "string" }, "name": "joiningField" }, { "title": "property", "description": "Optional upload mode. One of `APPEND` (default), `MERGE` and `CLEAR`.", "type": { "type": "NameExpression", "name": "string" }, "name": "uploadMode" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } }, { "title": "state", "description": "{SurveyCTOState}" } ] }, "valid": true }, { "name": "cursor", "params": [ "value", "options" ], "docs": { "description": "Sets `state.cursor` to a SurveyCTO timestamp string (`MMM dd, yyy h:mm:ss a`).\nThis supports natural language dates like `now`, `today`, `yesterday`, `n hours ago`, `n days ago`, and `start`,\nwhich will be converted into timestamp strings.\nSee the usage guide at {@link https://docs.openfn.org/documentation/jobs/job-writing-guide#using-cursors}", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "example", "description": "cursor('today')\nfetchSubmissions('test', { date: $.cursor });", "caption": "Use a cursor from state if present, or else use the default value" }, { "title": "function", "description": null, "name": null }, { "title": "param", "description": "the cursor value. Usually an ISO date, natural language date, or page number", "type": { "type": "NameExpression", "name": "any" }, "name": "value" }, { "title": "param", "description": "options to control the cursor.", "type": { "type": "NameExpression", "name": "object" }, "name": "options" }, { "title": "param", "description": "set the cursor key. Will persist through the whole run.", "type": { "type": "NameExpression", "name": "string" }, "name": "options.key" }, { "title": "param", "description": "the value to use if value is falsy", "type": { "type": "NameExpression", "name": "any" }, "name": "options.defaultValue" }, { "title": "param", "description": "custom formatter for the final cursor value", "type": { "type": "NameExpression", "name": "Function" }, "name": "options.format" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": false }, { "name": "jsonToCSVBuffer", "params": [ "rows" ], "docs": { "description": "Converts an array of objects to a CSV buffer.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "example", "description": "jsonToCSVBuffer([\n {\n lastName: 'Rothfuss',\n firstName: 'Patrick',\n book: 'The Name of the Wind'\n },\n {\n lastName: 'Martin',\n firstName: 'George',\n book: 'A Game of Thrones'\n },\n])" }, { "title": "param", "description": "An array of JSON objects.", "type": { "type": "AllLiteral" }, "name": "rows" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true } ], "exports": [], "common": [ { "name": "fn", "params": [ "func" ], "docs": { "description": "Creates a custom step (or operation) for more flexible job writing.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "fn(state => {\n // do some things to state\n return state;\n});" }, { "title": "param", "description": "is the function", "type": { "type": "NameExpression", "name": "Function" }, "name": "func" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true }, { "name": "fnIf", "params": [ "condition", "operation" ], "docs": { "description": "Execute a function only when the condition returns true", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "fnIf((state) => state?.data?.name, get(\"https://example.com\"));" }, { "title": "param", "description": "The condition that returns true", "type": { "type": "NameExpression", "name": "Boolean" }, "name": "condition" }, { "title": "param", "description": "The operation needed to be executed.", "type": { "type": "NameExpression", "name": "Operation" }, "name": "operation" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true }, { "name": "sourceValue", "params": [ "path" ], "docs": { "description": "Picks out a single value from source data.\nIf a JSONPath returns more than one value for the reference, the first\nitem will be returned.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "sourceValue('$.key')" }, { "title": "param", "description": "JSONPath referencing a point in `state`.", "type": { "type": "NameExpression", "name": "String" }, "name": "path" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true }, { "name": "dataPath", "params": [ "path" ], "docs": { "description": "Ensures a path points at the data.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "dataPath('key')" }, { "title": "param", "description": "JSONPath referencing a point in `data`.", "type": { "type": "NameExpression", "name": "string" }, "name": "path" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "string" } } ] }, "valid": true }, { "name": "dataValue", "params": [ "path" ], "docs": { "description": "Picks out a single value from the source data object—usually `state.data`.\nIf a JSONPath returns more than one value for the reference, the first\nitem will be returned.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "dataValue('key')" }, { "title": "param", "description": "JSONPath referencing a point in `data`.", "type": { "type": "NameExpression", "name": "String" }, "name": "path" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true }, { "name": "lastReferenceValue", "params": [ "path" ], "docs": { "description": "Picks out the last reference value from source data.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "lastReferenceValue('key')" }, { "title": "param", "description": "JSONPath referencing a point in `references`.", "type": { "type": "NameExpression", "name": "String" }, "name": "path" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true }, { "name": "combine", "params": [ "operations" ], "docs": { "description": "Combines two operations into one", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "combine(\n create('foo'),\n delete('bar')\n)" }, { "title": "param", "description": "Operations to be performed.", "type": { "type": "NameExpression", "name": "Operations" }, "name": "operations" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true }, { "name": "field", "params": [ "key", "value" ], "docs": { "description": "Returns a key, value pair in an array.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "field('destination_field_name__c', 'value')" }, { "title": "param", "description": "Name of the field", "type": { "type": "NameExpression", "name": "string" }, "name": "key" }, { "title": "param", "description": "The value itself or a sourceable operation.", "type": { "type": "NameExpression", "name": "Value" }, "name": "value" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Field" } } ] }, "valid": true }, { "name": "fields", "params": [ "fields" ], "docs": { "description": "Zips key value pairs into an object.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "fields(list_of_fields)" }, { "title": "param", "description": "a list of fields", "type": { "type": "NameExpression", "name": "Fields" }, "name": "fields" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Object" } } ] }, "valid": true }, { "name": "merge", "params": [ "dataSource", "fields" ], "docs": { "description": "Merges fields into each item in an array.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "example", "description": "merge(\n \"$.books[*]\",\n fields(\n field( \"publisher\", sourceValue(\"$.publisher\") )\n )\n)" }, { "title": "function", "description": null, "name": null }, { "title": "public", "description": null, "type": null }, { "title": "param", "description": null, "type": { "type": "NameExpression", "name": "DataSource" }, "name": "dataSource" }, { "title": "param", "description": "Group of fields to merge in.", "type": { "type": "NameExpression", "name": "Object" }, "name": "fields" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "DataSource" } } ] }, "valid": true }, { "name": "chunk", "params": [ "array", "chunkSize" ], "docs": { "description": "Chunks an array into an array of arrays, each with no more than a certain size.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "chunk([1,2,3,4,5], 2)" }, { "title": "param", "description": "Array to be chunked", "type": { "type": "NameExpression", "name": "Object" }, "name": "array" }, { "title": "param", "description": "The maxiumum size of each chunks", "type": { "type": "NameExpression", "name": "Integer" }, "name": "chunkSize" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Object" } } ] }, "valid": true }, { "name": "parseCsv", "params": [ "csvData", "parsingOptions", "callback" ], "docs": { "description": "Takes a CSV file string or stream and parsing options as input, and returns a promise that\nresolves to the parsed CSV data as an array of objects.\nOptions for `parsingOptions` include:\n- `delimiter` {string/Buffer/[string/Buffer]} - Defines the character(s) used to delineate the fields inside a record. Default: `','`\n- `quote` {string/Buffer/[string/Buffer]} - Defines the characters used to surround a field. Default: `'\"'`\n- `escape` {Buffer/string/null/boolean} - Set the escape character as one character/byte only. Default: `\"`\n- `columns` {boolean / array / function} - Generates record in the form of object literals. Default: `true`\n- `bom` {boolean} - Strips the {@link https://en.wikipedia.org/wiki/Byte_order_mark byte order mark (BOM)} from the input string or buffer. Default: `true`\n- `trim` {boolean} - Ignore whitespace characters immediately around the `delimiter`. Default: `true`\n- `ltrim` {boolean} - Ignore whitespace characters from the left side of a CSV field. Default: `true`\n- `rtrim` {boolean} - Ignore whitespace characters from the right side of a CSV field. Default: `true`\n- `chunkSize` {number} - The size of each chunk of CSV data. Default: `Infinity`\n- `skip_empty_lines` {boolean} - Ignore empty lines in the CSV file. Default: `true`", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "param", "description": "A CSV string or a readable stream", "type": { "type": "UnionType", "elements": [ { "type": "NameExpression", "name": "String" }, { "type": "NameExpression", "name": "Stream" } ] }, "name": "csvData" }, { "title": "param", "description": "Optional. Parsing options for converting CSV to JSON.", "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Object" } }, "name": "parsingOptions" }, { "title": "param", "description": "(Optional) callback function. If used it will be called state and an array of rows.", "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "function" } }, "name": "callback" }, { "title": "returns", "description": "The function returns a Promise that resolves to the result of parsing a CSV `stringOrStream`.", "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true }, { "name": "log", "params": [ "args" ], "docs": { "description": "Outputs a message, like calling `console.log`. Use this at the top level of your job code, but not inside callbacks.", "tags": [ { "title": "public", "description": null, "type": null }, { "title": "function", "description": null, "name": null }, { "title": "example", "description": "log('Patient List::', $.patients);", "caption": "Log values from state" }, { "title": "example", "description": "fn((state) => {\n console.log(state.data);\n return state;\n})", "caption": "Use console.log inside a callback or fn block" }, { "title": "param", "description": "A value or message to display in the logs", "type": { "type": "NameExpression", "name": "any" }, "name": "args" }, { "title": "returns", "description": null, "type": { "type": "NameExpression", "name": "Operation" } } ] }, "valid": true } ] }