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(LINK IN DOC) 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(LINK IN DOC).

```
<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 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