Skip to content

Editing Workflow XML

There are various options for editing workflow XML. You can:

  • Create the initial workflow through the user interface and then edit the workflow directly.

  • Complete all workflow development in XML.

  • Write original XM or use XML from an existing workflow as a template for a new process

All of these methods are valid and can be used as desired.

Accessing the XML

The XML for existing workflows can be viewed and edited through the IdentityIQ Debug pages or can be exported through the IdentityIQ Console.

Debug Pages

To view the XML in the Debug pages, navigate to the Debug pages and select Workflow from the object list to view a list of all defined workflows in the system.

to view the XML representation, click the name of the workflow. From the Debug pages you can edit and save changes. A workflow can also be copied from here and pasted into an external editor of choice.

  • View and edit the XML.

  • Save changes to the XML.

  • Copy and paste the XML to an external editor.

IdentityIQ Console

You can export one or more workflows from IdentityIQ through the console. The console export is the most efficient way to get the XML for all workflows extracted from the system at one time. The IdentityIQ console export command can extract all the Workflow XMLs together into a single file. See IdentityIQ Console Commands for more details on using the IdentityIQ console.

After exporting the XML, you can parse the XML into a separate file for each workflow and save the files in the installation source code control system for later use in system environment migrations or in product upgrade processes.

Object Usage
Workflow Defines the workflow structure and steps involved in the workflow processing.
WorkflowCase Represents a workflow in progress. Contains a Workflow element in which the process is outlined and current state data is tracked, as well as identifying information about the workflow target object.
WorkflowContext Launchtime information that Workflower maintains as it advances through a workflow case. Passed into rules and scripts and to the registered WorkflowHandler. Contains all workflow variables, step arguments, current step or approval, workflow definition, libraries, and workflowCase.
Task Result Records the completion status of a task, or in this case, the workflow, contained within the WorkflowCase

Reimporting the XML

Because the system only launches Workflow XML that is saved within IdentityIQ, XML documents that are edited externally must be re-imported for the changes made to them to take effect.

To reimport an externally saved XML document, use the console import command or from the Import from File page accessed from the gear menu > Global Settings page.

Dollar-Sign Reference Syntax

You can reference workflow variables inside XML tags and in user interface fields using $() notation. These are resolved into their variable values. For example, if a variable identityName is defined and contains the full name of an Identity, for example, John Smith, an Arg specified as:

<Arg name="FullIdentityName" value="$(identityName)">

passes "John Smith" as the value for the variable FullIdentityName.

When the variable is used alone, it functions the same as specifying value="ref:identityName. However, the more common usage is to include the variable in a longer string such as:

<Arg name="Title" value="Role Update for $(identityName)">

which passes "Role Update for John Smith" as the value for the variable Title.

XML Content

This section describes the elements present in the workflow XML and explains their usage.

Header Elements

The following three lines must be included as shown in any workflow document. The tag must, of course, be matched with a tag at the end of the workflow document.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE SailPoint PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<sailpoint>

Workflow Element

The Workflow tag identifies the name and type of the workflow.

Copy <Workflow explicitTransitions="true" name="WF-Training Hello World Workflow" type="IdentityUpdate"> The attributes of a workflow element including the following:

Workflow Attribute Purpose
configForm A soft reference to a process variable form presented in the Basic View of Process Variables tab, or a step form presented in the Basic View of the Arguments tab on the Step Editor panel accessed from the Process Designer tab of the Manage Business Process page.
name Short descriptive name for the workflow this is displayed in user interface selection list-boxes and list of existing business processes on the Process Editor window.
type Workflow type. Type is used to filter workflow selection lists in configuration windows where you select the workflow based on system activities.
explicitTransitions Boolean value indicating that transitions between steps are explicitly specified and workflow should not resort to implicit, fall-through, transitions when no transition conditions evaluate to true. The default setting is false. If you so omit this argument and the specified transition conditions all evaluate to false, the workflow uses implicit transitions and launches the next sequential step in the XML. However, if you edit a workflow using the Business Process Editor, the value is changed to true. If the developer makes the last transition in any set unconditional, which is considered best practice, the transitions between steps are smoother.
libraries Lists workflow libraries the workflow needs. If this attribute is not specified, workflows automatically have access to Identity, Role, PolicyViolation, and LCM libraries.
stepLibraries Lists workflow step libraries the workflow can access. If this attribute is not specified, workflows automatically have access to the Generic Step Library, which provides access to the Start, Stop and Generic steps.
handler The default workflow handler is sailpoint.api.StandardWorkflowHandler. This attribute does not need to be specified when the default is used. In this case, the best practice is to omit it. If you use a custom workflow handler, the custom handler must EXTEND the default handler and not replace it. The custom handler must be specified in the workflow Handler argument.

Variable Definitions

The recommended best practice is to identify all variables for the workflow at the top of the XML document. The variable definitions come next in the XML.

At a minimum, variable elements require a name. Other attributes can indicate the variable type and use, such as input, required, editable, and return. A description can be specified for each variable. When needed, an initialization value can also be provided. Using the initialization option is the recommended practice rather than creating separate steps to initialize each variable. Using initialization values is more efficient, easier to read, and easier to debug, because Trace reports initializations as they occur. For more information, see Initializer Options.

```
<Variable input="true" name="project" output="true" required="true">
    <Description>
    Project that has account requests in the QUEUED state.
    </Description>
</Variable>

<Variable editable="true" initializer="true" name="doProvisioning">
    <Description>Set to true to cause immediate provisioning after the assignment</Description>
</Variable>
```

Some parts of the variable definition are expressed within attributes on the Variables element. Other parts are expressed through nested elements of their own.

Variable Attributes

Variable Attribute Purpose
name Variable name.
type Variable type. Type declaration is not enforced by the application and is used primarily for documentation.
initializer Initialization value for the field.
input Flag indicating that the variable is an argument to the workflow. Omitted if not true.
output Flag indicating that the variable is a return value for the workflow. Omitted if not true.
required Flag indicating that the variable is a required field for the workflow. Omitted if not true.
editable Flag indicating that the variable can be edited by the workflow. Omitted if not true.
Nested Tag within Variable Element
Description Provides a description of the purpose for the variable.
Script Alternative to script in the initializer attribute value. Should be used for initializer scripts of any length or complexity.
Source Nested within the Script tag and contains the java BeanShell source for the action to be executed.

Initializer Options

The Initializer attribute requires additional attention. When these attributes are set through the user interface, you can specify the attribute as a string, script, rule, call, or reference. The same options are available directly through the XML.

Note

The initializer for a variable is only used when a value for the variable is not passed in to the workflow.

Initializer Type

Initializer Type Description and Examples
string Assigns a literal value to the variable. String is the default initializer option so the "string:" prefix can be included or omitted.
Examples: <Variable initializer="string:true" name="trace"/> and <Variable initializer="spadmin" input="true" name="fallbackApprover">
script Assigns a value based on the results of a Java BeanShell script. Examples:
  • In-line Script. Only use for very short, simple scripts.
    Variable initializer="script:(identityDisplayName != void) ? identityDisplayName : resolveDisplayName(identityName)" input="true" name="identityDisplayName">
  • Script within nested element. Use for most script initializers -- scripts of any complexity or length. The displayName of the identity being who started this workflow.Query for this using a projection query and fall back to the name.
    		•
    rule Assigns a value based on the return value of a workflow Rule.
    Examples: <Variable initializer="rule:wfrule_GetIdentityName" name="IdentityName">
    call Assigns a value based on the return value of a call to a workflow library method.
    Example: <Variable initializer="call:getObjectName" name="roleName">
    ref Assigns a value based on a reference to another workflow variable. This type is rarely used.
    Example: <Variable initializer="ref:otherVar" name="myVar"/>

    Workflow Description

    A description element should be included to describe the purpose of the workflow. Although the description element is not used in the workflow process, it is recommended for usability. In the user interface, the contents of this element are displayed on the Process Details tab of the Business Process page. This element should be included near the top of the workflow, either before or after the variable definition section.

    <Description>
     Workflow called when a role is ready to be enabled.
</Description>

    Rule Libraries

    Some methods the workflows use are grouped together into Rule Libraries. These Rule Libraries are defined as rules in IdentityIQ. However, these libraries contain sets of related but unconnected methods that workflow steps can directly within a script action. Because the rule methods are in rules, rather than in the compiled Java classes, their functionality can be easily modified to meet the needs of each installation. To make the methods within one of these rules available to steps within the workflow, the RuleLibraries element must be declared. See the following example.

    Note

    Each Reference element applies to one library. Include only the libraries that contain the required methods in the RuleLibraries declaration for the workflow.

    <RuleLibraries>
    <Reference class="sailpoint.object.Rule" name="Workflow Library"/>
    <Reference class="sailpoint.object.Rule" name="Approval Library"/>
    <Reference class="sailpoint.object.Rule" name="LCM Workflow Library"/>
</RuleLibraries>

    Note

    You can create and reference custom libraries using this same syntax.

    Step Libraries

    Step libraries are designed to offer a group of common functions that can be added to existing workflows from the Add a Step panel Business Process Editor. Step libraries are a collection of steps encapsulated by a workflow with the template attribute marked true. The steps do not have any transitions and they are not executable. A Step Library must be defined. See the following example.

    Note

    The type does not have to be StepLibrary. However, using the StepLibrary type ensures that these workflows do not appear in other parts of the product.

    <Workflow name="Provisioning Step Library"
                  type="StepLibrary"
                  template="true">

    When you edit a new or existing workflow, you can include a list of step libraries by including a comma separated list in the stepLibraries attribute. See the following example.

    <Workflow name="LCM Provisioning"
                  type="Provisioning"
                  taskType="LCM"
                  libraries="Identity,Role,PolicyViolation,LCM,BatchRequest"
                  stepLibraries="Common,Provisioning"
                  handler='IIQ.api.StandardWorkflowHandler'>

    In the example above, when you edit a business process with the LCMProvisioning type, the Common and Provisioning steps are available in the Add a Step panel of the Business Process Editor.

    Steps within a step library workflow can also include a soft reference to a step form that provides a simplified form-based interface that you can use to add arguments to some steps in the workflow. This form-based interface adds a Basic view option to the Arguments tab of the Step Editor. The Basic view is built using the information contained in the referenced form. The Advanced view is a list of all possible arguments and is built using the list of arguments that the step library references.

    When you add a step form reference to a step library, use the configForm attribute, See the following example.

    <Workflow name="Provisioning Step Library" 
                     template="true" 
                 type="StepLibrary">
 <Step configForm="Provisioning Approval Step Form" 
                 icon="Task" 
                 name="Account Approval">
<Arg name="approvalMode"/>
<Arg name="approvalScheme"/>
<Arg name="approvalSet" value="ref:approvalSet"/>
...

    In the example above, when you edit an approval step in the Step Editor, the Basic and Advance Views of the Arguments tab are displayed.

    Built-in Steps

    IdentityIQ includes several built-in steps. The Start, Stop, and Generic steps apply to all workflow types. The following table lists the names, descriptions, and associated workflow types of additional built-in steps.

    Step Description Process Type
    Notify Allows users to select categories of recipients to notify, the specific recipient, recipients for each category, and the specific email template to use for each category. Identity Lifecycle and LCM Provisioning
    Account Approval Used for provisioning request approvals. The process assumes many of the Provisioning Workflow structures exist. Identity Lifecycle and LCM Provisioning

    Step Elements

    Note

    Similar to variables, some parts of a step definition are included as attributes of the step and others are expressed as nested elements within the step.

    The core of the workflow is contained within the step elements. The action attribute determines what processing the step performs. Steps usually contain one or more nested <Transition> elements and ideally also contain a nested <Description> element that tells the reader what the step is intended to do. At a minimum, a step should contain:

    • an icon

    • name

    • posX attribute

    • posY attribute

    The action attribute determines what processing the step performs. Steps usually contain one or more nested <Transition> elements and ideally also contain a nested <Description> element that tells the reader what the step is intended to do.

    <Step icon="Start" name="Start" posX="250" posY="126">
    <Description>
        The workflow's processing starts with this step.
    </Description>
    <Transition to="Initialize"/>
  </Step>

    Step Attributes

    Step Attribute Purpose
    configForm A soft reference to the form that is presented to the Basic View of the Arguments tab on the Step Editor panel.
    name Short but descriptive name for step displayed in user interface graphical display below the step icon.
    icon Icon to display for the step in the user interface graphical Process Designer. Valid icon values include: Start, Stop, Default (Generic Step), Analysis (Launch Impact Analysis), Approval, Audit, Catches, Email, Message (Add Message), Provision, Task (Launch Task), and Und
    posX, posY X and Y indicate positions where the step icon should be displayed on the user interface graphical Process Designer grid. If you omit the posX and posY values, the icon is displayed at the top right of the grid. You can drag the icon around to create the desired layout at a later time.
    action The processing action to take for the step, such as a script, rule, subprocess, or call. See Step Actions.
    wait Pauses the action for a specified duration, see Wait Attribute.
    catches Causes the step to be launch when Complete status is caught, rather than through a transition from another step. See Catches Attribute.
    resultVariable Variable name that contains the return value from the step.
    Nested Tag within Step Element
    Description Provide a description of the step purpose.
    Transition Identifies the next step the process moves to when the current step is complete. See Transition Element.
    Arg Passes variables to the step. Used for steps that require data to be passed in to them.
    Return Receives return values from subprocess steps. See Return Elements.
    Script Alternative to script in the Action attribute for the step. Use these step attributes for action scripts of any length or complexity.
    Source Nested within the Script tag and contains the Java BeanShell source for the action to execute.

    Transition Element

    The transition element indicates the name of the next step the process executes following completion of the current step and is always nested within a step in the model. Transitions can contain conditions based on a string, script, rule, call method, or reference (similar to a variable initialization). The return value for conditions must be a Boolean (True / False). When multiple transitions are stipulated, they are evaluated in the order they are listed, and the transition for the first condition met is followed. The last transition in the list should, as a best practice, not contain any conditions so it can be used as the default action.

    Transitions contain two attributes:

    • to – next step

    • when – condition for progressing to the next step

    When a script is evaluated as the condition for a transition, it is often specified through these nested elements instead of as a when attribute on the transition element, especially if you use a long script.

    Nested Tag Within Transition Element Purpose
    Script Alternative to script in the transition when attribute. The script should be used for scripts of any length or complexity.
    Source Nested within the Script tag. This tag contains the BeanShell source for the condition evaluation.

    Example:

    <Transition to="end">
    <Script>
       <Source>
           ("cancel".equals(violationReviewDecision) || ((size(policyViolations) 
            > 0 ) &amp;&amp; (policyScheme.equals("fail"))))
       </Source>
    </Script>
</Transition>

    Conditions in the when attribute can be specified using the following types of conditions:

    Condition Type Description and Examples
    string Not used. This condition type is an artifact of the common structure used for variable setting and does not apply to conditions. A literal value of True or False can be specified. However, using one of those literal values does not enable any evaluation in the transition. True always executes the associated step and False always bypasses the step.
    script Evaluates script result value to determine step transition. Very short scripts are specified inline on the transition element, within the when attribute. Longer scripts are expressed within nested <script> and <source> elements.

    Because script is the default transition when option, the "script:" prefix can be included or omitted.

    Examples:

    (1) In-line Script. Use only for very short, simple scripts.

    <Transition to="Exit On Policy Violation"<br><br>when="script:((size(policyViolations)> 0)<br><br>&& (policyScheme.equals("fail")))"/>

    (2) Longer script within nested <script> tag should be use for transition scripts of any complexity or length.

    <Transition to="end"&gt;<br><br>&lt;Script&gt;<br><br>&lt;Source&gt;<br><br>("cancel".equals(violationReviewDecision) \| ((size(policyViolations)<br><br>\> 0 ) && (policyScheme.equals("fail"))))<br><br>&lt;/Source&gt;<br><br>&lt;/Script&gt;<br><br>&lt;/Transition&gt;
    rule Evaluates the return value of a workflow rule to determine step transition.

    Examples:

    &lt;Transition to="Process Approval" when="rule:RequireApprovalRule"&gt;
    call Evaluates return value of a call to a workflow library method to determine step transition.

    Example:

    &lt;Transition to:"Check Status" when="call:requiresStatusCheck" /&gt;
    ref Evaluates a defined, Boolean, workflow variable to determine step transition.

    Example:

    &lt;Transition to="Refresh Identity" when="ref:doRefresh"/&gt;
    Unconditional Specified as last transition option to give a default path for the transition.

    Example:

    &lt;Transition to="Approve"/&gt;

    Step Actions

    Most steps involve much more than a name and a transition. Steps also include an action attribute that executes the workflow processing. The action of a step can be a script or can a rule, subprocess, or a call to a workflow library method.

    Action Type Description
    Script Similar to scripts in other parts of the workflow XML, the script can be contained within the action attribute or can be nested within the Step in a <Script> block.

    Examples:

    (1) In-line Script, used only for very short, simple scripts.


    &lt;Step action="script:approvalSet.setAllProvisioned();" icon="Task" name="Post Provision"&gt;<br><br>&lt;Transition to="Stop"/&gt;<br><br>&lt;/Step&gt;

    (2) Longer script within nested <script> tag. Used for action scripts of any complexity or length.

    &lt;Step name="Start" icon="Start" posX="20" posY="20"&gt;<br><br>&lt;Script&gt;<br><br>&lt;Source&gt;<br><br>String wfName = wfcontext.getWorkflow().getName();<br><br>System.out.println("Starting workflow: \[" + wfName + "\]");<br><br>&lt;/Source&gt;<br><br>&lt;/Script&gt;<br><br>&lt;Transition to="Compile Provisioning Project"/&gt;<br><br>&lt;/Step&gt;
    Rule A step can execute a block of Java BeanShell code encapsulated in a reusable workflow Rule.

    Example:

    &lt;Step action="rule:WFRule_verifyIdentity" icon="Task" name="Verify Identity" posX="600" posY="202"&gt;
    Subprocess When you include a <WorkflowRef> element within the step and reference the SailPoint.object.Workflow class and the specific workflow by name, a subprocess is defined.

    Example:

    &lt;Step icon="Task" name="Initialize" posX="320" posY="126"&gt;<br><br>…<br><br>&lt;WorkflowRef&gt;<br><br><Reference class="sailpoint.object.Workflow" name="Identity<br><br>Request Initialize"/><br><br>&lt;/WorkflowRef&gt;<br><br>&lt;Transition to="end"&gt;<br><br>&lt;/Step&gt;
    Call Calls to workflow library methods can be used to do step processing.

    Call is the default action option. Therefore the "call:" prefix can be included or omitted.

    Example:

    &lt;Step action="call:refreshIdentity" icon="Task" name="Refresh Identity" posX="618" posY="242"&gt;

    Arguments

    Any variables to be passed to a script, rule, subprocess, or library method must be declared as step arguments through elements. Similar to other variables, the values for arguments can be specified by string, script, rule, call, or reference. The default specification type is string. Therefore, the "string:" qualifier can be omitted. However, arguments are also commonly passed by referencing workflow variables.

        Step icon="Task" name="Initialize" posX="320" posY="126">
        <Arg name="w" vaflolue="ref:flow"/>
        <Arg name="formTemplate" value="string:Identity Update"/>
        <Arg name="identityName" value="ref:identityName"/>
        ...
        <Description>Call the standard subprocess to initialize the request, 
        this includes auditing, building the approvalset, compiling the plan into 
        project and checking policy violations.</Description>
        ...    
        <WorkflowRef>
            <Reference class="sailpoint.object.Workflow" name="Identity Request 
            Initialize"/>
        </WorkflowRef>
        <Transition to="end">
    </Step>

    When an argument is specified as a script, rule, or call, for example, <Arg name="myVar" value="rule:myWFRule"/>, any needed arguments to the script, rule, or library method cannot be explicitly specified.

    Because these scripts, rules, and library methods automatically have access to the workflow context object, the scripts can access workflow variables directly through the workflow context get methods. These scripts/rules/methods can also access any step arguments that were defined before them in the step declaration. For example, the method that identifies the value for the Manager argument can use the value in the identityName argument in its processing, if needed. See the following example.

        <Step icon="Task" name="Processing Step" posX="320" posY="126">
        <Arg name="identityName" value="ref:identityName"/>
        <Arg name="Manager" value="call:getManager"/>
        ...
    </Step>

    The following table lists the available Arg attributes

    Arg Attributes Purpose
    name Variable name in process to which the data is being passed.
    value Value to pass into the variable, such as string, script, rule, call, reference.

    Return Elements

    To return more than one value from a subprocess, you can declare elements for the step. At a minimum, a return element contains: a name attribute and a to attribute. The name attribute is the name of the variable in the subprocess workflow and the to attribute is the variable name in the calling (current) workflow. If these names are the same in both workflows, a to attribute is not required. However, specifying a to attribute is a best practice for clarity.

    Use the merge attribute when the variable is a List and the returned values should be appended to the current workflow's list instead of replacing it. Similar to Args, value attribute for return elements can be specified as a string, script, rule, call, or reference. String is the default. If the value argument is omitted, the value of the name variable is copied as-is into the to variable, However, a script/rule/method can be used to transform or modify the value as it is passed.

    • name attribute – name of the variable in the subprocess workflow

    • to attribute – variable name in the calling (current) workflow

    Note

    If these names are the same in both workflows, a to attribute is not required. However, specifying the to attribute is best practice.

        <Step icon="Task" name="Initialize" posX="320" posY="126">
        <Arg name="flow" value="ref:flow"/>
        <Arg name="formTemplate" value="string:Identity Update"/>
        <Arg name="identityName" value="ref:identityName"/>
        ...
        <Return name="project" to="project"/>
        <Return merge="true" name="workItemComments" to="workItemComments"/>
        <WorkflowRef>
            <Reference class="sailpoint.object.Workflow" name="Identity Request 
            Initialize"/>
        </WorkflowRef>
        <Transition to="end">
    </Step>

    The following table lists the available Return attributes.

    Return Attribute Purpose
    name Variable name in process from which the data is returned.
    to Variable name in the workflow step to which the data is passed.
    value Value to pass into the variable, such as string, script, rule, call, reference.
    merge Flag indicating that the value should be merged into the target variable instead of replacing the variable. This attribute is used for list variables.
    local Only applies to returns on Approvals. See Approval Steps. A flag that indicate the value is passed to local storage within the parent approval and not passed to a workflow case variable. This attribute is used for complex approvals where a work item state is saved for later analysis in a script.

    Call

    Note

    Installations can create custom libraries for commonly used and required business methods. However, custom library methods must be named with unique names that do not conflict with standard library method names. Conflicts resolve as a reference to the standard library method. It is possible to extend a standard library and overload its method names. Extending a standard library is not consider a best practice. Therefore, the best practice is to create new names for nonstandard methods. Creating new names makes it clear that the method is not a standard method.

    Use calls to workflow library methods to do step processing. Similar to subprocesses, they sometimes require arguments to be passed to them. You declare method arguments the same way as subprocesses. You use Library methods with a call action. See the following example.

        <Step action="call:refreshIdentity" icon="Task" name="Refresh Identity" posX="618" posY="242">
        <Arg name="identityName" value="ref:identityName"/>
        <Arg name="correlateEntitlements" value="string:true"/>
        <Description>Add arguments as necessary to enable refresh features. Typically you 
        only want this to correlate roles. Don't ask for provisioning since that
        can result in provisioning policies that need to be presented and it's
        too late for that. This is only to get role detection and exception
        entitlements in the cube.</Description>
        <Transition to="Notify"/>
    </Step>

    The methods available for the call action are those included in the libraries attribute for the workflow element, if specified. If no libraries attribute is specified, the workflow automatically has access to the methods in the Identity, Role, PolicyViolation, and Lifecycle Manager libraries. If other libraries, including custom libraries, are explicitly listed in the libraries attribute, any of the default libraries whose methods are needed by the workflow must also be explicitly included in the list to be available. See Workflow Library Methods for details about the methods available in each library.

    Wait Attribute

    The step wait attribute causes the workflow to pause in its execution for the duration specified. The wait value can be specified as a string, script, rule, call, or reference. String is the default.

        <Step name="Wait for next check" wait="ref:provisioningCheckStatusInterval">
        <Description>
        Pause and wait for things to happen on the PE side.  
        Use the configurable interval to determine how long
        we wait in between checks.
        </Description>
        <Transition to="CheckStatus"/>
    </Step>

    This attribute creates a special type of step with the sole purpose of creating a pause in the action. Wait steps are commonly used in retry logic to enable behind-the-scenes processing to occur before the workflow attempts to repeat an action.

    Catches Attribute

    These steps are not caused through a transition from a previous step. These steps are caused by a thrown message that the steps intercepts or catches. Currently, only a complete message is thrown and can be caught. This process occurs when one of the following items occurs:

    • All sequential steps in a workflow are executed to completion.
      OR

    • Failure condition results in the termination of the workflow.

        <Step catches="complete" icon="Task" name="Finalize">
        <Arg name="project" value="ref:project"/>
        <Arg name="approvalSet" value="ref:approvalSet"/>
        <Arg name="trace" value="ref:trace"/>
        <Description>
        Call the standard subprocess that can audit/finalize the request.
        </Description>
        <WorkflowRef>
        <Reference class="sailpoint.object.Workflow" name="Identity Request Finalize"/>
        </WorkflowRef>
        <Transition to="end"/>

    The primary purpose of these steps is to update the IdentityRequest object, which tracks and reports the status of a LifecycleManager request, making the history of LCM request processing available even after the TaskResult for the workflow was purged.

    Each installation can drive custom logic based on catching this complete message.

    Approval Steps

    Approval is one of the most common actions that a workflow process performs. The IdentityIQ Approval model is constructed to simplify the process of defining an approval structure. Approvals are a special type of step that contain an element, specifying how the approval work item is presented for approval.

    Some approval steps are designed to get a user's approval on a requested change, as the name implies. However, the approval element can be used any time data needs to be gathered from a user.

    Typically, when you use approval steps to gather non-approval data, you use a custom form to:

    • Present the work item to the user and

    • Request the needed information from the user.

    For information on creating approval steps, see the section above. Through the XML, the custom form is manually defined within an approval step. You can also specify custom forms for traditional approvals when you need to present the information differently than the standard approval forms layout. See Workflow Forms for more details on usage of custom forms.

    Similar to other Workflow elements, you specify some modifiers as attributes on the approval element and specify other modifiers through nested elements within the approval.

    Approval Attributes

    Approval Attribute Purpose
    mode Specifies how an approval is processed. Mode can be determined from string, script, rule, call, or reference String is the default. The user interface only supports the selection of a string of one of the values listed below. The XML also enables reference to a process variable containing one of those values or the specification of a script, rule, or method call that can determine one of those values programmatically. Valid values are:
  • serial -- approvers are specified in order and the item is passed to each approver in that order. If any approver in the chain rejects, the item is rejected.
  • serialPoll -- approvers are specified in order and item is passed to each approver in that order. Data is collected on approvals and rejections. However, if one approver rejects, does not necessarily result in the item being rejected. The action decision is expected to be specified in AfterScript logic.
  • parallel -- item is sent to all named approvers at one time. The item is rejected if any approver rejects it.
  • parallelPoll -- item is sent to all named approvers at one time. Data is collected on approvals and rejections but rejection by one does not mean rejection of item. The action decision is expected to be specified in AfterScript logic.
  • any -- item is sent to all named approvers at one time. The first approver to respond makes the decision for the group.
  		•
    owner One or more approvers can be specified by string, script, rule, call, or reference. String is the default. The mode determines how and when the item is submitted to each listed owner when more than one is specified.
    renderer JSF include to render the work item details.
    return Comma-separated values (CSV) list of variable names to copy from completed work items back into workflow.
    send CSV list of variable names to include in the work items.
    description Defines work item description. For nested approvals, child approvals use the work item defined by the parent approval unless the child approval defines its own work item. You can set the description by string, script, rule, call, or reference String is the default.
    validation Used to validate any information the user entered during the approval. This attribute can be specified as string, script, rule, call, or reference. Script is the default. You generally use a nested validationScript element instead of a validation argument.
    Nested Tag within Approval Element
    AfterScript Provides instructions for additional processing to be done on the item after the approval is complete, and only if approved. Often uses methods in the Approval Rule Library and LCM Workflow Rule Library. If those methods are to be used, the rule libraries must be explicitly included in the workflow using the element. ParallelPoll and serialPoll items always execute this script after all responses are collected. With either of these modes, the logic in this script should aggregate the results and determine if the item should be approved or rejected. The business determines the criteria for approval or rejection, for example majority rule, any approval=approval, etc. In either poll mode, the AfterScript is inherited by child approvals if one is not specified.In other modes, child approvals do not inherit the after script.
    InterceptorScript This script is more complex than the AfterScript and is used less often. The script is called in several places in the approval processing: at the approval start, pre-Assimilation, post-Assimilation, when the work item is archived, and at the end of the approval. The stage of the processing is passed to the script as an argument called method that can be used to determine what the script should do at that time. The workflow context's args are also passed to the script. Method values for conditional analysis within InterceptorScript logic:
  • startApproval
  • preAssimilation
  • postAssimilation
  • archive
  • endApproval
    • If an InterceptorScript and AfterScript exist, the InterceptorScript postAssimilation logic launches before the AfterScript.
    validationScript Script to perform validation on the work item. For example, you can use this script to validate any data the user enters on the approval before the data is assimilated. This script is inherited by any child approvals.
    Source Nested within the AfterScript, InterceptorScript, and validationScript tags and contains the java BeanShell source for the script.
    Arg Arguments available to the approval action. Specified by string, script, rule, call, or reference. Most variables are passed to approval through send list. However, args that require any transformation must be sent through an Arg element. Additionally, the following args defined with reserved system names are passed through the Arg element with that name specified:
  • workItemRequester
  • workItemDescription
  • workItemType
  • workItemTargetId
  • workItemTargetName
  • workItemTargetClass
  • workItemDisableNotification
  • workItemNotificationTemplate
  • workItemEscalationTemplate
  • workItemReminderTemplate
  • workItemEscalationRule
  • workItemEscalationStyle
  • workItemHoursTillEscalation
  • workItemHoursBetweenReminder
  • workItemMaxReminders
  • workItemPriority
  • workItemIdentityRequestId
  • workItemArchive
    		•
    Return Return value defines how things should be assimilated from a work item back into the workflow case. This attribute is an alternative to the return attribute CSV of variables. It is more complex and also more powerful. This attribute is rarely used in approvals. It is most often used when returning an approval work item variable to a workflow variable of a different name or when you need to transform the variable contents of a work item with a script. The use of these types of return elements follows the same rules as step returns from steps that subprocesses, with addition of local attribute options. See Step Elements.

    The following basic approval step example presents an account change to the identity's manager for approval. The AfterScript records the approval decision and creates an audit record.

    <RuleLibraries>
    <Reference class="sailpoint.object.Rule"  name="Approval Library"/>
    <Reference class="sailpoint.object.Rule"  name="LCM Workflow Library"/>
</RuleLibraries>

<Step icon="Approval" name="Manager Approval">
<Approval mode="serial" owner="script:getManagerName(identityName, launcher, fallbackApprover);" renderer="lcmWorkItemRenderer.xhtml" send="approvalSet,identityDisplayName,identityName,policyViolations">

<Arg name="workItemDescription" value="Manager Approval - Account Changes for User: $(identityDisplayName)"/>
<Arg name="workItemNotificationTemplate" value="ref:managerEmailTemplate"/>
<Arg name="workItemRequester" value="$(launcher)"/>

<AfterScript>
        <Source>

          import sailpoint.workflow.IdentityRequestLibrary;
          assimilateWorkItemApprovalSet(wfcontext, item, approvalSet);
IdentityRequestLibrary.assimilateWorkItemApprovalSetToIdentityRequest(wfcontext, approvalSet);
auditDecisions(item);

</Source>
      </AfterScript>

</Approval>

    <Description>
      If approvalScheme contains manager, send an approval for all 
      requested items in the request. This approval will get the entire       
      approvalSet as part of the workitem.
    </Description>

<Transition to="Build Owner ApprovalSet"   
    when="script:isApprovalEnabled(approvalScheme, &quot;owner&quot;)"/>
<Transition to="Build Security Officer ApprovalSet" 
    when="script:isApprovalEnabled(approvalScheme, &quot;securityOfficer&quot;)"/>
<Transition to="end"/>

  </Step>

    Note

    In the AfterScript in this example, the methods not qualified by the library name are in the LCM Workflow Rule Library that is available to the workflow through the declaration.

    The assimilateWorkItemApprovalSetToIdentityRequest method is part of the IdentityRequestLibrary, this is available to the script through the import of that library in the script.

    Library methods called through step action attributes are available through the workflow libraries attribute list,. However, when the library methods are executed from within scripts, the library must be specifically imported for the script.

    Nested Approvals

    Child approvals created through the user interface are expressed as nested approval elements in the XML. When nested approvals exist, the parent ceases to be an approval of its own. In those case, the sole purpose of the parent approval is to organize and contain the child approvals. The mode on the parent determines how to process the set of peer child approvals.

       <Approval mode="string:parallel" name="Approve Region" owner="ref:regionApprover" 
       send="identityName,region">
      <Arg name="workItemDescription" value="string:Approve Region for $(identityName)"/>
      <Approval name="childApproval1" owner="string:Walter.Henderson" 
          send="identityName,region"/>
      <Approval name="childApproval2" owner="string:Alan.Bradley" 
          send="identityName,region"/>
   </Approval>

    In the example above, childApproval1 and childApproval2 are processed in parallel. Because both of these child approvals are identical (no custom work item config and no children of their own), the same objective can be accomplished with a single approval with multiple owners:

       <Approval mode="string:parallel" name="Approve Region" owner="ref:regionApprover" 
       send="identityName,region">
      <Arg name="workItemDescription" value="string:Approve Region for $(identityName)"/>
      <Approval name="childApproval1" owner="string:Walter.Henderson" 
          send="identityName,region"/>
      <Approval name="childApproval2" owner="string:Alan.Bradley" 
          send="identityName,region"/>
   </Approval>

    Nested approvals can be used effectively when different approval levels are implemented with custom configurations and specifications. For example, the workItemConfig for each of the child approvals can be different, which can result in a notification scheme, escalation policy, etc. for the different approvers.

    Nested approvals can be governed by a different approval mode from the one used on the master set and/or can contain their own child approval levels. One child approval can be done as an any approval, one that accepts the ruling of the first responder of several listed approvers, while the highest approval level is managed serially. Another child approval can implement custom workItemConfigs for its own child approvals. The example below illustrates all of these concepts.

    Nested approvals can be used effectively when different approval levels are implemented with custom configurations and specifications. For example, the workItemConfig for each of the child approvals can be. The following example that illustrates all of these concepts.

       <!-- Approval submitted to HR and to supervisor and manager in serial manner -->
   <Approval mode="string:serial" name="Approve Region" owner="spadmin" 
       send="identityName,region">
      <Arg name="workItemDescription" value="string:Approve Region for $(identityName)"/>

      <!-- HR Personnel approve region (whoever responds first makes decision) -->
      <Approval name="HRApproval" mode="string:any" 
           owner="ref:HRApprovers" send="identityName,region"/>

      <!-- Supervisor and Manager approve region serially after HR approves -->
      <!-- Each has a different email template (work item config) for notification -->
      <Approval mode="string:serial" name="SupMgrApproval" send="identityName,region">
          <Approval name="Supervisor" send="identityName,region" owner="Tom.Jones"> 
            <WorkItemConfig escalationStyle="none">
               <NotificationEmailTemplateRef>
                  <Reference class="sailpoint.object.EmailTemplate"               
                    name="SupervisorApprovalEmail"/>
               </NotificationEmailTemplateRef>
            </WorkItemConfig>
          </Approval>
          <Approval name="Manager" send="identityName,region" owner="Mary.Peterson">
            <WorkItemConfig escalationStyle="none">
               <NotificationEmailTemplateRef>
                  <Reference class="sailpoint.object.EmailTemplate"               
name="ManagerApprovalEmail"/>
               </NotificationEmailTemplateRef>
            </WorkItemConfig>
          </Approval>
      </Approval>
   </Approval>

    This ability to nest approvals, with options to assign different approval modes and work item configurations to each, enables implementers to create highly customized approval structures to meet the needs of the installation.