Context configuration

What this step is for

Some applications need the user to choose something after signing in, for example a workspace, an account, a region or a project. You cannot ask for it on the credentials form, because the list of choices comes from the application itself and is available only once the user is signed in.

This step defines those extra questions. They are asked once, when the user connects the application, right after the sign-in succeeds. The answers are saved and used again every time Canvas signs in later, so the user is not asked again.

Triggered by: Application registration (after successful authentication).

If your application needs no extra choice, leave this step empty.

What you see on the page

Item	What it does
Instructions (HTML)	A short text shown above the questions, for example "Choose the workspace to connect".
Fields Constructor	Build the questions one by one.
JSON editor	The same questions as text. The two views stay in sync: a change in one shows up in the other.
Add new context	Adds a question.

Settings of a question

Setting	What to enter
Short name	A short identifier without spaces, for example workspaceId. The answer is saved under this name, and your scripts read it as appVault.workspaceId (or appVaultSecret.workspaceId).
Name	The label users see.
Description	A hint shown with the question.
Type	How the user answers: a text box, a drop-down list, radio buttons, check boxes, a multi-line text, a lookup table (two lists to move items between) or a date picker.
Multiple	The user may choose several values.
Optional	The user may skip the question.
Hidden	The question is not shown to the user.
Secret	The answer is saved in the secret storage (appVaultSecret) instead of the settings storage (appVault). Turn it on for anything sensitive.
Script	Optional. A script that loads the choices from the application, for example the list of workspaces.

Loading choices with a script

Add a script when the choices must come from the application. The script runs when the question is shown. It can use appVault and appVaultSecret (so it can use the access token saved in the previous step) and api.send(...) to call the application. It must return:

Property	Meaning
shortName	Overrides ShortName property in constructor.
options	The list of choices: { label, value }, where label is what the user sees and value is what is saved.
value	The preselected value (a list of values for Multiple).
sourceOptions / targetOptions	For a lookup table: the available items and the chosen items.
hidden	true to hide the question. Overrides Hidden property in constructor

Example: let the user choose a workspace.

const r = await api.send({
  verb: 'GET',
  baseUrl: appVault.baseUrl,
  requestUrl: 'workspaces',
  headers: { Authorization: `Bearer ${appVaultSecret.access_token}` }
});
return {
  value: appVault.workspaceId || '',
  options: r.items.map(w => ({ label: w.name, value: w.id }))
};

For the full list of what the script can use and return, see Context field script.

If the script fails, the user sees the error and cannot answer the question, so test it on the Authentication step first.

Where the answers go

• Each answer is saved under the question's short name, in appVault or, if Secret is on, in appVaultSecret.
• The next steps and later sign-ins can read them. For example, in the Authorization step: appVault.workspaceId.
• Answers in appVault can also be read in workflow and block scripts with api.GetAppVault().

Anything sensitive must be marked Secret. appVault can be read from workflow scripts.

Good to know

• The question names (short names) are used in scripts. Do not rename them after users have connected the application.