Data sources

A data source is an address of one of your systems, such as your ERP or a vendor portal, that answers in JSON. A workflow script reads it with ctx.sources.get, for example to fetch a vendor’s cost center by the vendor number on an invoice. Acriva calls the source, not the script: only GET over HTTPS, and only to the host you entered. Scripts themselves have no network.

You find the data sources in the settings under Filing › Data sources. For reference data that you keep in Acriva itself, such as a vendor list, use a data table instead.

Who manages data sources

To see the page you need the permission Configure the workflow templates, and manage every workflow and the absences of others.
To add, change, test and delete a data source you need Manage data sources. The built-in roles Owner and Admin have it; the page says Create and change: owners and admins.
Adding and changing data sources is part of the Workflow designer add-on (see Who has the designer). Without it, the page says so: you can still view, delete and remove the secret of existing data sources.

Add a data source

Select Add data source.
Enter the Key: the name scripts call the source by, such as erp. It starts with a lowercase letter, contains only letters and digits and has at most 40 characters. It can’t be changed later.
Enter the Base URL, such as https://erp.example.com/api. Only this host is allowed; the path and the parameters come from the script.
Choose the Authentication:
- None;
- Bearer token: enter the Token;
- Basic: enter the User name and the Password;
- API key header: enter the Header name, such as X-API-Key, and its Value.
Set the Timeout: at most 5 seconds per call.
Set the Cache: 0 to 24 hours. Identical requests are answered from the cache within that time; No cache calls the source every time.
Decide whether to Send values of confidential documents. When it is off, this source isn’t called for confidential documents.
Select Save.

A workspace has at most 20 data sources. A token, a password or a header value has at least 8 and at most 4,096 characters.

Which addresses are allowed. The base URL must be a complete HTTPS address on the standard port with a host name that is reachable from the internet: no IP address, no address in your internal network, no user name in the address, no query and no fragment. Acriva checks the address again on every call, also when the host’s DNS answer changes, and follows a redirect only to the same host over HTTPS, at most three times. An address that doesn’t meet this is refused with Address blocked. Saving checks only the address’s form; whether a host is in an internal network shows at Test and on every call, since a name may resolve differently later.

Secrets are write-only. A token, a password or a header value is stored encrypted and never shown again; the form only says set. Select Replace to enter a new one, or Keep the stored value. When you change the base URL to another host, or the header name of an API key, enter the secret again: a stored secret never goes to another host or header.

Test the connection

Select Test in the row’s menu, or Test connection in the form of a saved data source. Acriva calls the saved base URL once with GET, with its authentication and timeout, and shows the outcome, the HTTP status, the duration and the size of the response, never the response itself. The test uses the saved version, not unsaved changes in the form.

The outcomes are Succeeded, Blocked, Timed out, Response too large, Invalid response, HTTP error and Failed. You can test at most 10 times a minute.

The list shows the Last call of each data source, from a workflow, a test run or a connection test, with its outcome.

Change, remove the secret, delete

Edit changes a data source; the changes apply from the next call. If someone changed it meanwhile, close the dialog and open the data source again.
Remove secret removes the stored credentials. Acriva then calls the source without them until you enter new ones, and scripts that use the source may fail.
Delete removes the data source. It isn’t possible while a published workflow or a running instance uses it: remove it there first. The logged calls are kept.

Use a data source in a script

A script may only call the data sources its step names as inputs. In the script step, open Inputs, and under Data sources and data tables select Add data source; Manage data sources leads to this page. Then call the source by its key:

const result = await ctx.sources.get('erp', {
  path: `vendors/${ctx.document.fields.vendorNumber}`,
  query: { fields: 'costCenter' },
});
if (!result.ok) {
  ctx.hint(`The ERP didn't answer (${result.error}). Please allocate by hand.`);
  return;
}
ctx.setField('costCenter', result.data.costCenter);

Acriva puts the path under the base URL and encodes every part of it and every query parameter, so a value from the document can’t leave the base path or reach another host. The answer must be JSON (application/json) of at most 1 MB.

A call that fails doesn’t end the run: ctx.sources.get then returns { ok: false, error }, and the script decides what to do. The error is one of these:

`error`	Meaning
`data-source-blocked`	The address or a redirect isn’t allowed.
`timeout`	The source didn’t answer within its timeout, or within the time the run has left for data sources.
`too-large`	The answer is larger than 1 MB.
`invalid-response`	The answer isn’t JSON (`application/json`), or it is compressed.
`http-error`	The source answered with an error status (in `status`), or the connection failed.
`not-declared`	The step doesn’t name the source as an input, or the workspace has no data source with this key.
`confidential`	The document is confidential, and the source doesn’t allow values of confidential documents.
`limit`	The run has made its 10 calls or used its 30 seconds for data sources already.

A run makes at most 10 calls, each at most as long as the source’s timeout, and at most 30 seconds together; an answer from the cache counts as a call too. A test run in the editor calls the sources for real, and its calls are logged like a workflow’s.

Privacy and logging

Every call is logged with the workflow run: the source, the address called, the outcome, the status, the duration and the size, never the response or the secret. The address can hold a document’s values, so Acriva removes it 90 days after the workflow ended (for a test, 90 days after the call); the rest of the entry stays.
Secrets are encrypted per workspace and removed from every answer before a script or a log sees it.
Confidential documents only reach sources that allow them.