10.1 Workflow Variables, Transitions, and Step Conditions
Key Takeaways
Variables have name, initializer, input, output, required, and editable attributes; an initializer is used only when no value is passed in.
Initializers, arguments, and conditions can be string, script, rule, call, or ref values.
Transitions are evaluated in order and the first true (or unconditional) transition wins; the last transition should be unconditional.
With explicitTransitions true, a step whose conditions are all false does not fall through to the next step in the XML; the workflow ends.
A step condition decides whether a step's action runs, so a step can be skipped without complex transition logic.
Workflow Variables, Transitions, and Step Conditions
Objective 4.3 is use workflow variables, transitions, and step conditions. These three features control what data a workflow holds and which path it takes.
The Workflow Element
<Workflow name="ACME Contractor Extension" type="IdentityUpdate"
explicitTransitions="true" libraries="Identity,Role,LCM">
| Attribute | Meaning |
|---|---|
name | Shown in selection lists |
type | Filters where the workflow can be selected, such as LCM Provisioning, Identity Lifecycle, or Subprocess |
explicitTransitions | If true, no implicit fall-through to the next step when all transition conditions are false. The Business Process Editor sets it to true when you edit there. |
libraries | Compiled workflow libraries for call: actions. The default is Identity, Role, PolicyViolation, and LCM. |
stepLibraries | Step libraries shown in the editor. The default is the Generic Step Library (Start, Stop, Generic). |
handler | Defaults to sailpoint.api.StandardWorkflowHandler. A custom handler must extend it. |
configForm | A form providing the Basic View of process variables |
Four runtime objects matter. Workflow is the definition. WorkflowCase is a running instance, tracking one target such as one identity or one plan. WorkflowContext (wfcontext) holds the live state: variables, arguments, current step, and libraries. TaskResult records the outcome and appears under Task Results.
Variables
The documentation recommends declaring all variables at the top of the workflow:
<Variable name="identityName" input="true" required="true"/>
<Variable name="daysToExtend" initializer="string:30" editable="true"/>
<Variable name="managerName" initializer="script:getManagerName(identityName)"/>
<Variable name="approved" output="true"/>
<Variable name="trace" initializer="string:false"/>
- input – a value can be passed in when the workflow is launched.
- output – the variable is returned, for example to a parent workflow.
- required – it must be non-null at start.
- editable – it can be edited in the Basic View.
- type – documentation only. It is not enforced.
- Order matters. A variable whose initializer uses another variable must be declared after it. Variables created in the UI are listed in the opposite order from the XML.
Initializer Types (the Same Choices Apply to Arguments and Conditions)
| Type | Example |
|---|---|
| string (default; prefix optional) | initializer="string:true" or initializer="spadmin" |
| script | initializer="script:resolveDisplayName(launcher)" or a nested <Script><Source> |
| rule | initializer="rule:wfrule_GetIdentityName" |
| call | initializer="call:getObjectName" (a workflow library method) |
| ref | initializer="ref:otherVar" |
An initializer runs only when no value was passed in. That is why LCM defaults can be overridden at launch. SailPoint recommends initializers over extra "set variable" steps, because trace output reports initializations as they happen.
Dollar-Sign References
$(identityName) resolves a variable inside a string, for example <Arg name="Title" value="Role Update for $(identityName)"/>. Used alone, it behaves like ref:identityName.
Transitions
Each step has one or more <Transition to="..." when="..."> elements:
- Transitions are evaluated in the order listed.
- The first transition whose condition is true, or that has no condition, is taken.
- Best practice: make the last transition unconditional, as the default path.
- If every transition has a condition and none is true, then with
explicitTransitions="true"the workflow ends. Without it, the workflow falls through to the next step in the XML.
Condition types are script (the default, which must return a Boolean), rule, call, and ref (a Boolean variable). A string literal "true" or "false" is technically allowed but does no evaluation. Long conditions go in a nested <Script>:
<Transition to="Exit On Policy Violation"
when="script:(size(policyViolations) > 0) && "fail".equals(policyScheme)"/>
<Transition to="Approve"/>
Remember that XML special characters must be escaped in attributes (&& for &&).
Loops
A loop is a transition back to an earlier step. That step's state is reinitialized and it runs again. A loop transition should almost always have a condition, or the workflow can loop forever. Retry patterns combine a loop with a wait step (section 10.3).
Worked Example: Tracing a Path
Suppose a step named Check Violations has these transitions, in order:
to="Fail"whensize(policyViolations) > 0 && "fail".equals(policyScheme)to="Violation Review"whensize(policyViolations) > 0to="Approve"(no condition)
If there are two violations and policyScheme is continue, transition 1 is false and transition 2 is true, so the workflow goes to Violation Review. If there are no violations, both conditions are false and the unconditional transition 3 sends it to Approve. If someone deletes transition 3 and the workflow has explicitTransitions="true", a request with no violations would simply end. That silent failure is exactly why the last transition should be unconditional.
Step Conditions
A step condition (right-click a step and choose Add Step Condition) decides whether the step's action runs once the workflow arrives at the step. Use it to skip optional work, such as sending a notification only if notifyManager is true, without drawing extra transitions around the step. Condition types are Reference (a Boolean variable), Script, Rule, and Call Method. Negate inverts the result.
| Need | Use |
|---|---|
| Choose between different next steps | Transitions with conditions |
| Run or skip one step's action on the same path | Step condition |
| Repeat a step until something is true | Loop transition with a condition, often with a wait |
A step has three transitions: the first two have conditions and the last has none. The first condition is false and the second is true. Which step runs next?
The target of the last, unconditional transition
The target of the second transition, because transitions are evaluated in order and the first true one is taken
All three targets in parallel
The workflow ends because the first condition was false
A workflow with explicitTransitions="true" reaches a step whose only two transitions both have conditions, and both evaluate to false. What happens?
The next step in the XML runs.
The workflow ends, because no transition is taken and there is no implicit fall-through.
The first transition is taken by default.
The step repeats until a condition becomes true.
A workflow variable approvalScheme has initializer="manager". The workflow is launched with approvalScheme set to owner. What value does the variable hold?
manager, because initializers always override launch values
owner, because an initializer is used only when no value is passed in
manager,owner, because values are merged
It is null, because the two values conflict
A notification step should run only when the Boolean variable notifyManager is true, and the workflow should continue on the same path either way. What is the simplest design?
Add two conditional transitions around the step.
Change the step into a subprocess.
Set explicitTransitions to false.
Add a step condition that references notifyManager.
Sections you finish are checked off in the contents.