Skip to content

Form Models

Form models are used to simplify that process of passing values between the workflow variables and the form. Form models enable the specification of a Map through which a set of variables can be handed to the form by the workflow. The model is defined in the workflow (or predefined model is used), enabling the workflow and form to pass a collection of variables at one time through the specified model. The form renderer is set up to use the model so form fields can name the desired attribute directly without having to reference the model name as well.

Since actions in workflows often center around Identities, a map for the identity object, called IdentityModel, is prebuilt in IdentityIQ. A workflow library method, getIdentityModel, can be called by a workflow step to create an IdentityModel map to use in a subsequent step that renders a form. To create an empty map, call this method with no arguments. To prepopulate the map with an identity's current values, specify an identity name or ID as an argument to the step. This method is used with no arguments in the new self-service registration workflow to prepare to create a new identity from the data the user enters on the form.

For an example of the simplification offered by a form model: A workflow form needs to display and permit the user to edit 10 identity attributes. Without form binding, all 10 would have to be defined as individual business process variables and all 10 would have to be sent to and returned from the approval in the workflow. The form would also require all 10 to be defined as form arguments. With a model, the whole Identity can be automatically stored in a single business process variable with a single method call, only one variable (identityModel) must be passed to and returned from the form, and no form arguments need to be defined at all.

Use these steps to use the IdentityModel in a workflow form:

  1. Go to Setup > Business Process > Process Variables tab.

  2. Define a process variable in the workflow (identityModel).

  3. In an early step in the workflow, initialize and populate the identityModel by calling the getIdentityModel method in the IdentityLibrary workflow library. Specify the identityModel process variable as the Result Variable for that step.

    To pass an identity name or ID to the method, specify it as an argument to the step (identityName or identityId).

  4. In the approval that contains the form, create an argument called workItemFormBasePath and specify the identityModel process variable as its value. The form base path is understood by the form renderer and is automatically applied to permit the form access to the map fields. This enables the passing of the model to and from the form.

  5. Reference the components of the identityModel in the form as though they were passed as individual variables, for example, as "firstname," not as "identityModel.firstname."

Note

When a base path is specified as a form argument, the form renderer assumes all fields on the form are accessed through that base path, so all attributes to be included in the form or returned from it must be included in the model.

<Section>
<Field displayName="user_name" name="name" required="true" type="string"/>
<Field displayName="first_name" name="firstname" required="true" type="string"/>
<Field displayName="last_name" name="lastname" required="true" type="string"/>
<Field displayName="email" name="email" required="true" type="string"/>…
  1. (Optional) To provision changes to the identity based on the form, call the buildPlanFromIdentityModel() method in the Identity Library. This examines the versions of the model passed to the form and back from it, identifies differences between them, and creates a provisioning plan to make the required changes.

Refer to the LCM Registration workflow, which ships with IdentityIQ Lifecycle Manager, for a full example of implementing the identityModel.

No other models currently ship with the product, but custom models can be created through some manual coding in the initialization stage.

  1. Declare the model variable as a process variable (same as the identityModel), for example appModel.

  2. Initialize the model manually, since no library method exists to populate custom models. Instead of a method call in the initialization step, the step executes a script or rule written to populate the desired data into a HashMap that is stored in the custom model variable.

  3. Specify the custom model variable as the workItemFormBasePath argument to the workflow's form step.

  4. Reference components in the custom model by name in the form. As with identityModel, no reference to the base path should be specified in the form field names.

Identity Model Structure

The IdentityModel map delivered with IdentityIQ contains the following entries:

  • all standard Identity attributes and all extended Identity attributes (most as strings; lists when multi-valued)

  • detectedRoles (List)

  • assignedRoles (List)

  • manager (String name, rather than ID)

  • info map which contains:

    • manager map (includes ID, name, and displayName of Manager Identity)

  • lastRefresh, lastLogin, and passwordExpiration dates

  • isWorkgroup, managerStatus, correlated, and correlatedOverriden flag values

  • assignedScope name and controlsAssignedScope flag value

  • transformerOptions (map of primer identityName or identityId used to populate the IdentityModel)

  • class (sailpoint.object.Identity)

  • transformerClass (sailpoint.transformer.IdentityTransformer)

Accessing Identity Model Attributes

Any identity model attributes can be displayed on a form or set based on data entered in a form field by supplying the model attribute name as the field name.

Access any single-valued attribute at the top level by specifying its name in the field's name attribute:

<Field displayName="first_name" name="firstname" type="string"/>

To display the contents of a multi-valued extended identity attribute, use the following syntax. Multi-value extended identity attributes are shown in the identityModel as a list of string values.

<Field displayName="Cost Centers" multi="true" name="costcenter" type="string"/>

Access any nested attribute, for example, those with a map within the map, using dot notation:

<Field displayName="Manager ID" name="info.manager.id" type="string"/>

Note

Values in the info map should not be altered through the form, as they will not be updated in the model; they are treated as read-only data that provides supplementary data for the corresponding top-level attribute, and they are automatically refreshed based on updates to that top-level attribute.

Display the contents of an object list in the map, such as assignedRoles, detectedRoles, or workgroups, on a form by creating it as a combo box. Do this by specifying the type as the correct object type and specifying multi="true":

<Field displayName="Detected Roles" filterString="type==&apos;it&apos;" multi="true" name="detectedRoles" type="iiq.object.Bundle"/>


<Field displayName="WorkGroups" filterString="workgroup == true" multi="true" name="workgroups" type="Identity"/>

The application of a filterString to the workgroups list ensures that only workgroup identities display.

The links list contains a map for each link (account) held by the identity. Access attributes inside that list by referencing the name of the desired link and using dot notation to traverse the map:

<Field displayName="App Owner" name="links['HR_Employees'].sys.nativeIdentity" type="string"/>

In development and debugging, it can be helpful to examine the identityModel in XML or as a string representation to clearly see its structure. The identityModel is visible in the workflowCase for any workflow where it is used and is printed to stdout if the trace variable is set to true for the workflow. It can be printed as a string from a workflow step with a System.out.println(identityModel.toString()); statement.

Referencing a Form Model

Form models can be accessed by rules and scripts within workflows or forms within workflows using the $() parsing tokens, for example, $(identityModel.name). When variables are referenced with this syntax, the ScriptPreParser expands the short hand path references into the proper MapUtil.get() reference. This notation can be used in scripts run from fields, variables, steps, transitions or step actions. The script can explicitly specify the full path to the variable in the model, for example, $(identityModel.name), or it can reference the variable directly when a modelBasePath has been defined, for example $(name).

Note: In order to set a basePath in a form, an argument named modelBasePath (defined as Rule.MODEL_BASE_PATH) must be set declaring the path to be used for all the expanded variables in the form. For example, . The modelBasePathdoes not have to be specified at the top level; for example, it can point to a list or map within the top-level map such as <Arg name='modelBasePath' value='identityModel.links[AD]'/> (this is the map representing the user's AD account link).

Note

This $() notation can only be used for retrieving values from the model; it cannot be used to set or change values in the model.

Syntax

Use the following syntax rules when writing references within the scripts:

  • A dollar sign with parentheses[$()]is used as the parsing token to indicate what contents should be expanded. For example,$(foo.bar).

  • Double quotes are valid when enclosing spaces within the variable:$(foo."bar baz"). However an expansion token within a quoted string is not processed: "$(not.expanded)"

  • Brackets can be used within a variable to access elements in a list: $(foo.bar[baz=bingo].buzz) $(foo.bar[baz="path with spaces"].buzz)

  • When the modelBasePathis set to a sub-map or list within the model, the forward slash escape character (/) can be used to jump to the root of the basePath. This escape character must be the first character after the expansion token. If basePathis set to 'identityModel.links[AD]' and the desired reference is for identityModel.firstname the variable would be written as $(/firstname) which would be converted to IIQ.tools.MapUtil.get(identityModel, "firstname"). Otherwise $(firstname) is converted to IIQ.tools.MapUtil.get(identityModel, "links[AD].firstname")

  • If no basePath is set and the variable only contains a single word, no expansion occurs and a warning is written to the log indicating a possible error condition.

Example Syntax

The following are all valid:

No base path:

  • $(foo.bar) ---> IIQ``.tools.MapUtil.get(foo, "bar")

  • $(foo."bar baz") ---> IIQ``.tools.MapUtil.get(foo, "\"bar baz\"")

  • $(foo.bar[baz="path with spaces"].buzz)---> IIQ``.tools.MapUtil.get(foo, "bar[baz=\"path with spaces\"].buzz")

Base path = 'foo'

  • $(foo.bar)---> IIQ``.tools.MapUtil.get(foo, "bar") (assuming basePath is set to 'foo'. This respects the basePath and does not try to find a "foo" attribute within the "foo" map)

  • $(bar)---> IIQ``.tools.MapUtil.get(foo, "bar")(assuming basePath is set to 'foo')

Base path = 'foo.bar[AD]'

  • $(baz)---> IIQ``.tools.MapUtil.get(foo, "bar[AD].baz")(assuming basePath is set to 'foo.bar[AD]')

  • $(/baz)---> IIQ``.tools.MapUtil.get(foo, "baz")(assuming basePath is set to 'foo.bar[AD]')