Application context field script (JS config)

Each field of an application context config can have a JS config. The script builds the control: it loads data from the application API and returns the options and the current value. The script is JavaScript may use await.

Variables and helpers available in the script

Name	Description
appVault	Non-secret values saved for the registered application (for example appVault.baseUrl).
appVaultSecret	Secret values (for example appVaultSecret.secretKey).
api.send(request)	HTTP helper, see below.

api.send(request)

const data = await api.send({
    verb: 'GET',                      // required
    baseUrl: appVault.baseUrl,        // required
    requestUrl: 'accounts?p1=1',      // required, relative to baseUrl
    headers: { 'Consumer': appVaultSecret.consumer },   // optional
    data: { },                        // optional, request body
    responseType: 'json',             // optional: 'json' (default) | 'text' | 'arraybuffer'
    encoding: 'utf8',                 // optional
    getFullResponse: false            // optional
});

• By default returns the response body.
• With getFullResponse: true returns { statusCode, statusText, headers, responseUrl, content }.
• A non-2xx response does not throw. Check statusCode yourself (use getFullResponse: true).
• Network errors and invalid requests throw Error('GET <code> - <message> Url: <url>.').
• The query string is parsed: p1=1&p1=2 is sent as repeated parameters.

What the script must return

The script must return one object with following optional fields:

Property	Type	Description
name	string	Name of the AppVault property that the selected value is saved to. If empty, the field shortname is used.
value	string, or array of strings	Current value. A string if the field has "multiple": false, an array if "multiple": true.
options	array of { label, value }	Items for SELECT, RADIO_GROUP, CHECKBOX.
sourceOptions	array of { label, value }	Left list for LOOKUP_TABLE.
targetOptions	array of { label, value }	Right list for LOOKUP_TABLE.

{ label, value }: label is the text shown to the user, value is what gets saved. Numbers are accepted for value and converted to strings.

The type of value must match multiple. An array for a multiple: false field (or the other way round) fails deserialization, and the user gets Deserialization error: ....

Control types

All context fields must have Control type, it is one of INPUT, SELECT, RADIO_GROUP, CHECKBOX, TEXTAREA, LOOKUP_TABLE, DATEPICKER. Fill the option lists that the control uses:

Control type	Properties to return
INPUT, TEXTAREA, DATEPICKER	name, value
SELECT, RADIO_GROUP, CHECKBOX	name, options, value
LOOKUP_TABLE	name, sourceOptions, targetOptions, value

Unused properties can be left out.

Examples

SELECT, multiple: false

const request = {
    verb: 'GET',
    baseUrl: appVault.baseUrl,
    requestUrl: 'Applications',
    headers: { 'Consumer': appVaultSecret.consumer, 'SecretKey': appVaultSecret.secretKey }
};
const applications = await api.send(request);
return {
    name: 'applications',
    options: (applications || []).map(a => ({ value: a.id, label: a.name })),
    value: 'ac9341ee-456d-470d-94c3-88b1001fb556'
};

Result:

{
  "name": "applications",
  "options": [
    { "label": "My app", "value": "ac9341ee-456d-470d-94c3-88b1001fb556" }
  ],
  "value": "ac9341ee-456d-470d-94c3-88b1001fb556"
}

SELECT, multiple: true

{
  "name": "accounts",
  "options": [
    { "label": "a@example.com", "value": "6FA122E4-0D4C-4A1D-8869-7C0A86A37BF1" },
    { "label": "b@example.com", "value": "0B2F9D41-3C1E-4E57-9C1A-2B5E7A9D6F10" }
  ],
  "value": ["6FA122E4-0D4C-4A1D-8869-7C0A86A37BF1"]
}

INPUT

{ "name": "baseUrl", "value": "https://api.example.com" }

LOOKUP_TABLE

The shape of value for this control is not defined in the C# code. Check it against the UI before documenting it for users.

{
  "name": "mapping",
  "sourceOptions": [{ "label": "First name", "value": "firstName" }],
  "targetOptions": [{ "label": "Given name", "value": "givenName" }],
  "value": []
}

Errors

All context script errors are categorized as JS_APP_CONTEXT_CONFIG: <error>