Skip to content

Specifying Custom Forms

Form specification is different for each available use. All types of provisioning policies can be specified through the IdentityIQ user interface. In all cases, some of the more advanced and custom forms for workflows can be generated through the Business Process Editor. Some of the more advanced options. however, are only available through subsequent editing of the XML definition. Workflow forms created through the Business Process Editor are embedded within the workflow XML.

Alternatively, they can be defined as independent form objects which can be referenced by multiple workflows, by creating them directly in XML and importing them into IdentityIQ. Report forms must be created as external XML documents and imported into IdentityIQ.

Role / Application Provisioning Policies

Provisioning forms are presented to a user when a provisioning request cannot be completed without user input. The data collection fields that are presented on the form come from the role or application's Provisioning Policy, which is defined by the Form element inside the Bundle (role) or Application object's XML. The actual form presented to the user during provisioning of roles or application accounts are system-generated at run-time based on skeleton forms that are predefined in IdentityIQ. Requests made through LCM are built with the Identity Update form. Requests that come through the Identity Refresh workflow use the Identity Refresh form. These forms contain a read-only section at the top that displays identifying information about the request, for example, Account ID, First name, and Last name. The fields defined in the provisioning policy forms are added to the form at run time, when the form is presented to a user.

Provisioning policy forms define the fields required for the role or application account to be provisioned, often including a default value or script / rule for calculating a value. When a field cannot be calculated by the system during provisioning of an account or role, it must be presented to a user through a form to get the required value. When multiple accounts or roles are part of the same provisioning request, the form might display a collection of fields pulled from various provisioning police forms. On the form, the fields are, by default, grouped in sections according to the application or role to which they belong. This grouping can be overridden by specifying a section attribute on each of the fields, naming the section into which each field should be placed. See the section attribute description in Fields.

Defining Application Provisioning Policy

An application provisioning policy can be defined for an application on the Provisioning Policies tab of the Application Configuration page, Applications > Application Definition. Separate policies can be defined for create, update, and delete requests. Additionally, provisioning policies can be specified for creating or updating groups.

The required fields should be specified in the policy with the appropriate field attributes defined. These attributes can include a default value or a script / rule to calculate a default value for the field that can be based on the Identity attributes for the Identity for whom the request is being made. The field Name should match the corresponding native attribute on the application. If Review Required is selected, the field is always presented on a form during provisioning-request processing, even if a default value is provided or calculated successfully.

For creation-type operations you can specify dependencies between applications and application attributes that imply ordering of the provisioning requests.

Field Properties and Value Properties

The provisioning policy field attributes are grouped into two categories: Field Properties and Value Properties.

Field Properties describe field meta data. This includes the field's name, display name, tool tip help text, type, and owner. It also includes indications of whether the field is single or multi-valued, read-only, hidden, required, or review required. Fields can also be marked with a flag to indicate whether changes to the field value should cause the form to be reloaded. The Read-Only and Hidden attributes can be set to a static value (True or False) or can be defined programmatically through a rule or script. The rule and script options are used to dynamically hide and show the field, or change its edit properties, when the form is reloaded based on changes to values of other fields.

The Value Properties section includes properties specifically related to the field's value. A default value, a set of permitted values, and the field's validation logic can all be set here. The Dynamic attribute determines whether the field's value should be reevaluated on every form reload, when the form is reloaded based on a change in another field's value. It should only be selected when the field's value is rule or script based, such that it might change during the form processing based on other field values entered there.

The default value can be specified as a static value or can be calculated programmatically by a rule or script. In an account creation provisioning policy, an additional option, Dependent, is available as part of the ordered provisioning implementation, which is only available on account create provisioning policies. When the dependent option is selected, an application and attribute must also be selected and the value of the field is set to that attribute value for the Identity. Only applications on which this application is dependent are available for selection here.

The Allowed Values list can be specified as a list of values or can be set dynamically by a rule or script. Field validation is optional and can be managed by a reusable rule or with a script.

Defining Role Provisioning Policies

Role provisioning policies are specified through the Role Editor: go to Setup > Roles, select the role name, and click Edit Role. Then click Add Provisioning Policy and specify the fields for the policy.

Select the application to which the role provisioning policy applies and then specify the fields for the policy. Fields are specified for role provisioning policies exactly as they are specified for application provisioning policies. Role provisioning policies and application provisioning policies are not the same or to be used interchangeably, however.

Role provisioning is not intended for initial role assignment or for the provisioning of account attributes that are not entitlements. Using role provisioning and application provisioning interchangeably cause conflicts and should be avoided.

Role provisioning is designed to be used for profiles that use complex logic, where it is unclear what should be provisioned or deprovisioned. The role provisioning policy is used to state what to provision, "x and y" or "p and q," and to use the contents of the Identity to make that decision.

Identity Provisioning Policy

The Identity Provisioning Policies are optional forms that can be specified to define the fields that must be provided when an Lifecycle Manager Create or Edit Identity request is submitted. When no Identity Provisioning Policy is defined for the create function, IdentityIQ automatically builds a form that includes the entire set of defined Identity attributes (standard and extended) for the installation. The auto-generated update provisioning policy form contains only identity attributes marked as editable. An Identity Provisioning Policy can be defined to select a subset of those fields, to affect the presentation of those fields, for example, grouping in sections or multi-column layout, or to build in some logic to auto-populate some of the fields.

A third identity provisioning policy also exists to support self-service registrations for IdentityIQ. This form is presented when self-service registration is enabled and a new user requests an IdentityIQ account. The form prompts the user for the information required to create a new user account for the installation.

  1. To create an Identity Provisioning Policy, go to Identity Provisioning Policy of the Lifecycle Manager configuration page.

  2. Three policies are available: Create Identity, Update Identity, and Self-service Registration.

    If a policy has already been defined, the name is displayed.

  3. Click the name to open and edit the policy.

  4. If no policy has been defined for one of these types, click Add Policy to add a new one.
  5. Add fields to the policy, defining field attributes as needed on the field definition parallels for an application or role provisioning policy.

Identity Provisioning Policy forms are saved as independent form objects. System Configuration entries (entry key="createIdentityForm", "updateIdentityForm", and "registerForm") point to the appropriate forms for each identity provisioning policy by name. The identity provisioning policy forms are saved as

objects inside the UIConfig attributes map under the keys lcmCreateIdentityProvisioningPolicy and lcmUpdateIdentityProvisioningPolicy on the IdentityIQ Debug pages. These form definitions can be edited directly to implement some of the presentation options, for example, multi-columns or sections. The configurable option available on the user interface do not include these features.

Note

Form features related to the Section attribute (which includes subdividing the form into sections and creating multi-column form configurations) are not supported through the user interface. These must be managed directly in the Form Object XML. Any fields added through the user interface after dividing the form into sections are automatically added to the first section. These fields can be moved to other sections by editing the XML.

Workflow Forms

Several standard work item renderers are provided with IdentityIQ for presenting approvals or other data requests to users. These are written as JSF pages. It is possible to write custom forms in JSF, specifying the JSF page as the renderer for the approval. This is rarely done. Customers who want to use custom forms generally specify these through a Form object.

Forms are used in workflows to present data-gathering pages to a user and define data presentation for approval activities. In many cases, implementations rely on the standard approval work item forms for normal approval actions so do not need to implement custom forms for their approval steps, but they still might choose to use custom forms for non-approval data-gathering activities to which the normal approval forms do not apply. A custom form can be added to a workflow through the Business Process Editor (Setup > Business Processes) by right-clicking a step and choosing Add Form or by adding a form element to a step in the Workflow XML.

Whether the form is specified for an approval or a data-gathering activity, the form element must be embedded within an approval element in the XML. The user interface auto-creates it within an approval element. The workflow XML to specify a custom form looks like this:

?xml version='1.0' encoding='UTF-8'?><!DOCTYPE SailPoint PUBLIC "sailpoint.dtd" "sailpoint.dtd"><sailpoint><Workflow  explicitTransitions="true"  libraries="Identity"  name="Example Workflow" type="IdentityLifecycle">...  <Step name="Display Form">     <Approval name="Please enter some data" owner="admin" return="selectedApprover" send="trace ">       <Form>        ...         <!-- Form content goes here -->      </Form>    </Approval>  </Step>

A custom form can also be created as an independent form object, defined in a separate XML document and imported into IdentityIQ, visible through the console or the Debug pages by viewing the Form objects, and referenced in the approval element as an argument like this:

<Approval...>     <Arg name='workItemForm' value='Custom Form Name'/>      ... </Approval>

This option promotes form reuse across workflows. However, these independent form objects cannot be edited through the Business Process Editor like the embedded forms can.

Process Variable and Step Forms in Workflows

While forms added to steps on the Process Designer tab of the Business Process Editor are used to request data required by the process from a user, such as a value for a missing attribute, the process variable and step forms are used to define the information presented on the Basic Views of the Process Variables tab and the Arguments tab of the Step Editor.

These forms are created as an independent form object, defined in a separate XML document and imported into IdentityIQ. They are visible through the console or the Debug pages by viewing the Form objects.

The process variables forms are used to simplify the information displayed on the Process Variables tab by hiding those variables that are rarely, if ever, modified and displaying variables in more logical groups. Changes made in the Basic View are persisted to the Advanced View and more complex configuration can be performed there if needed.

The step forms are referenced from the workflows or stepLibraries. These forms define the form that is presented on the Arguments tab of the Step Editor panel and works similarly to the process variable forms.

Both of these forms are referenced from workflows using the configForm variable. The forms can be defined and viewed and edited on the IdentityIQ debug page.

Report Forms

Report definitions often include a reference to a Form object for displaying the report-specific filter options to the report user. In the Report XML, the form is referenced with a tag:

<ReportForm><Reference class="sailpoint.object.Form" id="39535985298ff9839ff98dd" name="My Custom Report Form" /></ReportForm>

The Form is defined separately in its own XML document and imported into IdentityIQ as a Form object. Each section within the form is created as a separate page in the Edit Report window, where you specify the filters that are applied to the report. The report-specific forms are always merged with the Report Form Skeleton, which defines the Standard Properties and Report Layout pages that apply to every report.