Skip to main content
Back to JavaScript

Flow Variables

A flow can declare variables that a delegated admin overrides for their organization unit, for example a support email address or a login method toggle. These helpers read the declared variables, work out what a unit may do with each one, list the choices of a select variable, and validate a value before it is saved. The React <FlowVariablesForm /> is built on them, and you can use them with any UI.

To load and save the values, use getFlow, getFlowVariables, updateFlowVariables, and getFlowOverlayRules from the management API.

FlowVariableDefinition​

A variable a flow declares on its VARIABLES node.

PropertyTypeDescription
identifierstringName of the variable, which a {{var(name)}} placeholder uses.
typeFlowVariableTypeThe input the variable is edited with. See Variable types.
labelstringDisplay name.
descriptionstringHelp text.
defaultValueFlowVariableValueThe value the variable has until another is set.
optionsFlowVariableValue[]For a SELECT: the values it can take.
categorystringFor a CONNECTION_SELECT: the kind of connection it takes. The server accepts only IDENTITY_PROVIDER.
connectionTypesstring[]For a CONNECTION_SELECT: limits it to these vendors. The server accepts google, github, oidc, and oauth.
minnumberFor a NUMBER_INPUT: the lowest value.
maxnumberFor a NUMBER_INPUT: the highest value.
validationFlowVariableValidationRule[]Rules a text value has to meet.

FlowVariableValue is string | number | boolean. A value is never null. FlowVariableValues is the set of values an organization unit has set, keyed by identifier. A variable the unit has not set is absent.

Variable types​

FlowVariableTypeValue type
TEXT_INPUTstring
EMAIL_INPUTstring
PHONE_INPUTstring
NUMBER_INPUTnumber
DATE_INPUTstring in YYYY-MM-DD format
BOOLEAN_INPUTboolean
SELECTOne of options
CONNECTION_SELECTThe identifier of a connection

FlowVariableValidationRule​

PropertyTypeDescription
type'regex' | 'minLength' | 'maxLength'The kind of rule.
valuestring | numberThe pattern for regex, or the length for minLength and maxLength.
messagestringThe message shown when the rule fails. An i18n key or a literal string.

getFlowVariableDefinitions(flow)​

Reads the variables a flow declares. A flow shared with an organization unit lists them in variables. A flow the unit owns declares them on its VARIABLES node.

ts
import { getFlow, getFlowVariableDefinitions } from '@thunderid/javascript'

const flow = await getFlow({ baseUrl, fetcher, flowId, ouId })
const definitions = getFlowVariableDefinitions(flow)
ParameterTypeDescription
flowPick<ManagedFlowDefinition, 'nodes' | 'variables'> | undefinedThe flow, as getFlow returns it.

Returns: FlowVariableDefinition[]. Empty when the flow declares none.

resolveFlowVariableRule(definition, overlay?)​

Works out what an organization unit a flow was shared with may do with a variable. The owning unit does not use these helpers: the server rejects an override saved for it with HTTP 400, so it changes defaults in the flow's VARIABLES node.

  • For a flow shared with the unit, a variable that no sharing policy names cannot be edited and keeps the owner's default.
  • Without an overlay, such as in a preview, every variable is editable.
ts
import { getFlowOverlayRules, resolveFlowVariableRule } from '@thunderid/javascript'

const overlay = await getFlowOverlayRules({ baseUrl, fetcher, flowId, ouId })
const { editable, defaultValue, allowedValues } = resolveFlowVariableRule(definition, overlay)
ParameterTypeDescription
definitionFlowVariableDefinitionThe variable.
overlayResolvedOverlayWhat the unit may do with the flow, as getFlowOverlayRules returns it.

Returns: ResolvedFlowVariableRule

PropertyTypeDescription
editablebooleanWhether the unit may set its own value.
defaultValueFlowVariableValue | undefinedThe value the variable has until the unit sets its own, or the value it is pinned to when it cannot set one.
allowedValuesstring[]The values the unit may choose from. Absent means anything the variable accepts.
excludedValuesstring[]Values taken out of what the unit may choose.

getFlowVariableOptions(definition, connections?, restriction?)​

Lists what a select variable can take. A SELECT takes the values it declares. A CONNECTION_SELECT takes the connections that match its category and connectionTypes. Any other type returns an empty array.

ts
import { getConnections, getFlowVariableOptions } from '@thunderid/javascript'

const { connections } = await getConnections({ baseUrl, fetcher, ouId, limit: 100 })
const options = getFlowVariableOptions(definition, connections, { excludedValues: ['legacy'] })
// [{label: 'Google', value: 'a1b2c3'}]
ParameterTypeDescription
definitionFlowVariableDefinitionThe variable.
connectionsPick<ConnectionInstance, 'categories' | 'id' | 'name' | 'type'>[]The connections available to the organization unit. Defaults to none.
restrictionFlowVariableOptionRestrictionThe values a sharing policy lets the unit choose from (allowedValues), or takes away (excludedValues).

Returns: FlowVariableOption[]. Each option has a label and the value to store. For a connection, the label is the connection name and the value is its identifier. For a SELECT, both are the option converted to a string, so convert the value back to the declared type, such as a boolean or a number, before you validate or save it.

validateFlowVariableValue(definition, value)​

Checks a value against the variable's type, options, and rules, so a form can report a problem before the server does. The server validates again on save.

ts
import { validateFlowVariableValue } from '@thunderid/javascript'

const error = validateFlowVariableValue({ identifier: 'email', type: 'EMAIL_INPUT' }, 'nope')
// {code: 'invalid'}
ParameterTypeDescription
definitionFlowVariableDefinitionThe variable the value is for.
valueFlowVariableValue | undefinedThe value to check.

Returns: FlowVariableValidationError | undefined. undefined means the value is valid. A BOOLEAN_INPUT is valid when it is a boolean or not set. Every other type requires a value.

codeMeaning
requiredThe value is empty.
invalidThe value is not valid for the type, such as text that is not an email address or a number that is not numeric.
minA number is below min.
maxA number is above max.
not_optionA SELECT value is not one of its options.
min_lengthText is shorter than a minLength rule allows.
max_lengthText is longer than a maxLength rule allows.
patternText does not match a regex rule.

For the three text rules, the error also carries the rule's message when it has one. The text rules are checked for TEXT_INPUT only, so a value can pass here and still be rejected by the server, which validates again on save. A regex rule that the runtime cannot compile is skipped, and the server judges it.

Cache Keys​

FlowVariableQueryKeys and FlowQueryKeys name flow resources for caching. The React hooks use them to refetch after a mutation. Reuse them as keys in your own data fetching cache.

ConstantKeys
FlowVariableQueryKeysDEFINITIONS ('flow-variable-definitions'), VALUES ('flow-variable-values')
FlowQueryKeysFLOWS ('flows')

Explore with AI

ThunderID LogoThunderID Logo

Product

DocsAPIsSDKs
© Copyright Linux Foundation Europe.For web site terms of use, trademark policy and other project policies please see https://linuxfoundation.eu/en/policies.