Skip to content

Components of a Form Definition

The basic elements in a Form definition are:

<Form>   <Attributes>    (map of name/value pairs that influence the form renderer)   <Button>     (determine form processing actions)   <Section>    (Subdivision of form; may contain nested Sections and Fields)     <Field>    (may contain Attributes map, Script to set value, Allowed Values Definition script, and Validation Script)

Within each of these sections of the form definition, certain attributes might apply to some form uses and not to others. The table below provides a high-level overview of which of the available form elements can be specified for each.

Form Usage Form Component Availability
Attributes Button
--- ---
Application and role provisioning policies (Form)
Identity provisioning policy X*
Workflow approval X
Report

*Limitations on the Attribute and Button elements for Identity provisioning policy are discussed in Attributes(LINK IN DOC) and Buttons(LINK IN DOC).

Form

The Form element should contain a single attribute to define the form: a name.

  <Form name="My Custom Form">

If the form is stored in the database as an independent Form object, the name must be unique; no two Form objects can share the same name. This restriction does not apply to Forms defined inline within a workflow approval step. While a name is required for independent Form objects, it is recommended but is not required on inline forms.

Attributes

Forms can include a map of attributes that are used by the renderer. These are applicable only to workflow forms and, in a limited way, to the identity provisioning policy form.

Attributes are specified with the following keys:

Key Description
pageTitle Title to render at top of page, typically larger and a different color than the form title; also displayed in browser window header bar in some cases
title FormTitle, shown at top of form body
subtitle Form subtitle, shown below title
readOnly <entry key="readOnly= "" value="true""/> makes form read-only so the fields are rendered as uneditable text or as disabled HTML components
hideIncompleteFields hideIncompleteFields="true" hides any fields that do not have all of their dependencies met. Usually only set programmatically to control field presentation in provisioning policy forms, though can be specified in a workflow form XML. This does not create dynamically displayed fields on forms. Fields are not displayed on a form after their dependency values on the same form are entered. Use the new hidden attribute on Fields and Sections to achieve this dynamic display functionality.

Note

The Boolean attributes are only specified if they are true; they default to false when omitted.

Attributes maps are specified as shown here:

 <Attributes>
   <Map>
      <entry key="pageTitle" value="Review Non-Employee Request"/>
      <entry key="readOnly" value="true"/>
   </Map>
</Attributes>

Attributes do not apply to report forms because the sections in a report form are pulled out of the report's form definition and combined into the Report Form Skeleton for display in the user interface. Even if they are specified in the report form, these attributes are never applied to the resultant form that is displayed to the user.

On an identity provisioning policy form, the pageTitle attribute is ignored because the main page title is programmatically set based on the other action being performed (Create New Identity, Edit Identity Attributes for [Username], or New User Registration). The title and subtitle attributes are displayed in the user interface when specified in the form's attributes map. The readOnly and hideIncompleteFields function on this form type should not be used because they do not provide useful functionality for this type of form.

Buttons

Buttons enable the user to indicate which action to take next and how to process the data on the form. Buttons only apply to workflow forms. Buttons can be specified on identity provisioning policy forms, but the window does not support any action on them other than next (submit). Since Submit and Cancel buttons already exist on the window and perform the appropriate functions for the window, additional buttons are unnecessary. They cannot be specified in a role or application provisioning policy form, and they are not used by the report executor when it combines the specific report's form with the Report Form Skeleton.

Buttons require two attributes, a label and an action. The label determines the text displayed on the button. The action determines what the system does in response to clicking that button. There are four available actions:

  • next - save (and validate fields with validation scripts where specified) any entered form data and set the work item status to approved. This can then be used in the Transition logic to advance the workflow to the next step (OK/Save/Approve/Submit functionality).

  • back - save entered form data (no validation is performed) and set the work item status to rejected. This can then be used in the Transition logic to return to a previous step or any other appropriate action for a rejection. Saved value is redisplayed on this form if the workflow logic process back through this step again.

  • cancel - close the form, suspend the workflow and return to previous page in user interface. This leaves the work item active, awaiting a different action choice by the user.

  • refresh - save the entered form data and regenerate the form. Not a state transition, just a redisplay of the form (rarely used).

These are examples of button elements.

<Button label='Submit' action='next'/>
<Button label="Cancel" action="cancel"/>

Sections

Sections divide a form into logical groupings that are visually marked on the window with boxes around the fields in each section. They can be specified in the XML for all policies except application and role provisioning policies. By default, a separate section is created on the provisioning form for each application (each application's provisioning policy form is rendered in its own section). However, fields in a provisioning policy form can be specified with a section attribute that causes them to be displayed in different sections from the defaults. Sections are treated differently on report forms, each section becomes a separate page on the Edit Report window rather than just a separate section on a contiguous form.

Sections are specified in the form object's XML with a <Section> tag and can be modified by the attributes shown in the table below.

Section Attributes Description
name Internal name for section (might be referenced by field objects in some forms).
label If non-null, the label is displayed above the section fields in a box on the section border. For report forms, the label is specified in the Edit Report window's sections list. Labels can be specified with text, message catalog keys, or variables (specified with $(varName) notation).
type Rendering type (optional). When no type is specified, fields in the section are editable fields, displayed one field per row, unless the columns attribute specifies otherwise. Other type options are:
  • datatable - makes fields in the section non-editable; generally used to display a read-only informational table to give the form user a context for the form's requested data.
  • text - indicates the section is a block of informational text; if multiple fields are included in a text section, each field is rendered on a separate line with line breaks between them.
    		•
    columns Number of columns contained in the form section; fields are placed in columns left to right, one field per column before moving to the next row. For example, in a 2 column layout (columns="2"), 4 fields are displayed:
  • Field 1 Field 2
  • Field 3 Field 4
    		•

    These are examples of Section elements in the XML for forms.

    <Section name="authorizations" label="Authorizations" type="datatable">
<Section columns="2" label="rept_app_section_label" name="customProperties">

    Sections contain nested field elements and might contain nested sections when sub-groupings are needed.

    Fields

    Fields are the core element of forms. They are the mechanism by which data gets communicated to and from the user. Fields offer options that affect the appearance or functionality of the field. Some of these are commonly used and others are used very infrequently. Some of these are specified as inline attributes in the <Field>tag and others are specified as nested elements within the Field.

    Field attributes appropriate to all form uses

    Field Attributes Description
    name Name for the field that can be referenced in code as the variable name in which the field's value is stored.
  • Avoid using the following field names:
  • accept
  • accept-charset
  • action
  • autocomplete
  • enctype
  • method
  • name
  • novalidate
  • target
  • As well as global attributes:
  • accesskey
  • class
  • contenteditable
  • contextmenu,data-*
  • dir
  • draggable
  • dropzone
  • hidden
  • id
  • itemid
  • itemprop
  • itemref
  • itemscpe
  • itemtype
  • lang
  • spellcheck
  • style
  • tabindex
  • title
    		•
    displayName Label for the field; can be text or a message key.
    helpKey Tool tip help text; can be text or a localizable message key. Example:
  • <Field name="firstName" displayName="First Name" helpKey="Enter the person's first name" />
    		•
    type Field datatype; influences the display widget used to display the field on a form.Valid values are:
  • string, int, long, boolean, date, and SailPoint object types (Identity, Bundle, Permission, Rule, Application), default is string.
  • SailPoint objects are displayed as dropdown lists or combo boxes if multi="true" is also specified.
  • Specifying type="boolean" renders the field as a checkbox; specifying type="date" adds a calendar from which the date can be selected.
  • To preselect an object in the list, specify the name of the object (not an actual object) as the "value" attribute.
  • Example:
  • <Field name="role" displayName="Role" type="Bundle" value="TRAKK Basic" />
    		•
    multi Boolean indicating whether the field is multi-selectable.This attribute is only appropriate to drop-down lists, which are then displayed as combo boxes. Used this with SailPoint object field types or with a nested AllowedValues / AllowedValuesDefinition element that populates a selection list for the field. Example:
  • <Field name="apps" displayName="Applications" type="Application" multi="true"/>
    		•
    readOnly Boolean indicating that the field cannot be edited on the form. The value is displayed as text, not in an editable box. Not necessary to specify on fields in a datatable section, since they are already read-only.
    hidden Boolean that, when true, prevents the field from being displayed on the form. This attribute is used in reporting to make fields available for inclusion on the report detail grid but not actually include them by default. This can be used in any form, but might not be commonly implemented:
  • In role / application provisioning policies, fields are only shown if the user needs to enter data, so forcing fields to be hidden is not helpful.
  • In workflows, the hideIncompleteFields attribute on the Form object is more likely to be used with the dependencies attribute on Field to defer field display until dependencies are fulfilled.
  • In Identity provisioning policy, fields that should be hidden can be omitted from the form instead, however, this could be used for fields that always contain the same value for all users to set that value and suppress the field from the data entry form. For example,<Field name="status" hidden="true" value="NewHire"
  • Attributes marked hidden are not included in the plan. You must manually add the includeHiddenFields property to the form to include the hidden fields in the plan.
  • <entry key="includeHiddenFields" value="true"/>
    		•
    required Boolean indicating whether a value is mandatory for the field; required="true" marks the field with * on the form to indicate that a value is required, and prevents form submission without a value for the field.
  • Example:<Field name="myfield" displayName="My Field" required="true"/>
    		•
    postBack Boolean that, when true, causes the form to refresh when the field's data value changes, running any rules or scripts that run on form load.
  • <Field name="application" displayName="Application" type="Application" postBack="true"/>
    • Supports conditional display / editing of sections or fields based on other field attributes values, automatic population of fields based on other fields, and validation of fields based on actions taken on the form. It only runs when a field loses focus, so it can be used on selection fields or text entry fields.
    columnSpan Used when the section is configured with multiple columns; specifies the number of columns the field should span.
  • <Section columns="2" label="Identity Info" name="identInfo">
  • <Field name="fname" displayName="First Name" columnSpan="2"/>
    		•
    filterString Used for fields where type is a SailPointObject class to specify a filter to restrict the set of selectable objects presented in the drop-down list. filterString is specified according to the filter string syntax and should be specified in single quotes, so that double quotes can be used within the string. Example:
  • <Field displayName="Role" name="role" type="Bundle" filterString='name.startsWith("TRAKK")' />
    		•
    section Statically defined fields in a form's XML are defined within a section element, so any section attribute specified on those fields is ignored. However, the section attribute can be used to organize fields in an application or role provisioning policy or on a dynamically rendered form. Application and role provisioning policy forms do not have section elements, so the section attribute can be used to force fields to be grouped differently than the default (default is by application or by role). Example: These two fields are put on the form in separate sections, labeled "Important Items" and "Optional Items" respectively.
  • <Field name="myField" displayName="My Field" section="Important Items"/>
    • <Field name="optField" displayName="Optional Field" section="Optional Items"/>
  • The section attribute on fields is also used in dynamically created forms (such as in Reports where fields are added to the form programmatically through an initialization script). This attribute enables the code to specify the section of the form into which the field should be added.
    		•
    displayType Forces string fields to display as specified, used only for string fields. Valid displayTypes are: radio, combobox, textarea, and label. displayType="radio" and "combobox" are used to override the default display format for permitted-values fields (radio is the default for 2 options while >2 options is rendered as comboBox by default). textarea is used to make a string field display as a text area instead of a regular entry field. For label, you can use the field displayName for the text / message key of the label.
  • <Field name="dept" displayName="Department" displayType="radio"></li><li></li><li>Accounting</li><li>Manufacturing</li><li>Engineering</li><li></li><li></li><li>`
    		•
    value Sets the default / initial value for the field. This can be overwritten on the form in most cases, as long as the field is not marked readOnly. This is used within sections of type="text" to specify the text to display. For application or role provisioning policies, setting a value (whether with this attribute or through a nested <Value>, <RuleRef>, or <Script> element) prevents the field from being included on the form unless reviewRequired is specified since provisioning policies only collect values from a user that they cannot determine or calculate independently. In workflow approvals, value can be specified by string, rule, script, call, or reference (string is default). In reports forms, the value is a reference to the report taskDefinition's input parameter from which to retrieve the starting / default value for the field, for example, value="ref:applications". Example: <Field name="role" displayName="Role" type="Bundle" value="TRAKK Basic"/>
    dynamic This attribute performs two separate functions:
  • For fields with an AllowedValuesDefinition, delays running of allowed values scripts / rules until the field is clicked, instead of running at form load, so it can make use of other data entered on the form instead of just data available on initial form load.
  • During form refresh in response to a value change of a field marked for postBack, only fields marked as dynamic (dynamic="true") have their value scripts / rules re-run; otherwise, the initial value calculated for the field on form load remains in effect as the field's default value.
    • Example:
  • <Field name="fullName" displayName="Full Name" dynamic="true">
  • <Script>
  • <Source>
  • return (firstName + " " + lastName);
  • </Source>
  • </Script>
  • </Field>
    • Field value recalculations for fields marked as dynamic are not processed on postBack if a value has been entered manually in the field, based on the assumption that if a user manually enters a value, they generally do not want that overridden by an automatic process. To override this behavior, manually clear the fields using a hidden script elsewhere in the form like this:
  • <Section>
  • <Attributes> <Map>
  • <entry key="hidden">
  • <value> <Script> <Source>
  • boolean hidden = false;
  • // Null out field - add condition here if desired
  • form.getField("nickname").setValue(null);
  • return hidden;
  • </Source> </Script> </value>
  • </entry></li><li></Map> </Attributes>
  • <Field displayName="Nickname" dynamic="true" name="nickname" type="string">
  • <Script><Source>
  • if ("Robert".equal(firstName))</li><li>return "Bob";
  • </Source></Script>
  • </Field>
  • </Section>
    		•

    Attributes that only apply to the application and role provisioning policies

    Field Attributes Description
    dependencies List (CSV) of other fields that must be evaluated before this field. Dependencies on the provisioning policy (form) field cause that field to be deferred to a subsequent form that is presented after the form on which its dependencies are presented. The field might also be calculated based on those dependencies instead of presenting it on a later form. This attribute can also be used with dynamic / allowedValues fields. Values of dependencies fields are made available to the allowedValues script or rule, even if the field is presented on a different form.
    reviewRequired Enables a default value to be assigned to the field while still including the field on the form displayed to a user. This enables the default to be edited. If reviewRequired="true" is not specified, the provisioning policy form fields with a default value (or value script / rule that returns a value) are omitted from the user-facing form and the default value is automatically used.
    authoritative Boolean that specifies whether the field value should replace the current value rather than be merged with it. Valid for multi-valued attributes only: <Field name="costCenter" displayName="Cost Center" multi="true" authoritative="true"/>

    Fields can also contain nested elements that help control the display or use of the field

    Nested Elements within Field Elements Description
    Description Field description, used for XML self-documentation. Not displayed in user interface.
  • <Description>This field stores the Identity's first name.</Description>
    		•
    Attributes Attribute map used to control field rendering, specific to the field type. The most common attributes are height and width which are usually specified for textarea fields and for entry boxes that need to be other than the default rendering size. Units for height and width are in pixels.<Attributes><Map><entry key="height" value="200"/><entry key="width" value="100"/></Map></Attributes>\
    Value Alternative to "value" attribute on . This is required when specifying complex datatypes such as Map or List.
  • <Value><List><String>Thing 1</String><String>Thing 2</String></List></Value>
    • Also needed for fields of type Date, which are specified as the utime representation of the date:
  • <Value><Date>1231971297</Date></Value>
    • Can be used to specify simpler types like String, Boolean, etc. but not commonly done because value attribute is simpler.
    Script Script used to initialize the value of the field, alternative to the value element / attribute. Automatically created for fields whose value is set by script through user interface specification. Example:
  • <Script><Source>[BeanShell code goes here]return [value or variable that contains value to assign to the field];</Source> </Script>
    		•
    RuleRef Reference to a reusable rule for initializing field value. Alternative to <Script> (and value attribute). Automatically created for fields whose value is set by script through user interface specification.
  • <RuleRef> <Reference class="Rule" name="My Rule" id="402839343985ff930d" /></RuleRef>
    		•
    AllowedValues Specifies a set of values from which the user can select to assign the field value. Automatically created for fields with an allowed values property set to Value (with a list of values specified) through user interface specification.
  • <Field name="dept" ...><AllowedValues><String>Accounting</String><String>Manufacturing</String><String>Engineering</String></AllowedValues></Field>
    • The list renders as radio buttons when only two options exist (and multi is not allowed), as a listbox for more than two options, and as a combobox for multi-selectable fields.
    AllowedValuesDefinition Populates a list of values from which the user can select a value for the field. This field contains either a <Script> block that specifies the list programmatically or a <RuleRef> that points to a rule containing the beanshell for generating the list. Automatically created for fields with an allowed values property set to Script or Rule through user interface specification
  • <AllowedValuesDefinition><Script><Source>import sailpoint.object.*;List l = new ArrayList();for(WorkItem.State enumItem : WorkItem.State.values()) {List l2 = new ArrayList();l2.add(enumItem.toString());l2.add(enumItem.getMessageKey());l.add(l2);}return l;</Source></Script></AllowedValuesDefinition>
    • Alternative to AllowedValues element and more commonly used. The list renders as radio buttons when only two options exist (and multi is not allowed), as a listbox for more than two options, and as a combo box for multi-selectable fields.
    ValidationScript Script used to examine and validate the field value entered by the user. The value entered is passed to the validation script in the variable named "value."
  • <ValidationScript><Source>if (value > 10) {return "Value must be less than or equal to 10";else return null;</Source></ValidationScript>
    • Returns null if no errors and an error message (as string or SailPoint.tools.message object) if validation errors exist.
    ValidationRule Reference to reusable rule for field validation. This is the alternative to ValidationScript.
  • <ValidationRule><Reference class="Rule" name="My Validation Rule" id="4028392342f5ff9301" /></ValidationRule>
    		•
    OwnerDefinition Used only for application and role provisioning policies to determine the Identity to whom the fields should be presented. This enables specification of a RuleRef, script, a Value element or a Value attribute:
  • <OwnerDefinition><RuleRef><Reference class="rule" name="My Owner Rule" id="4038293483598523"/></RuleRef></OwnerDefinition>or<OwnerDefinition><Script><Source>import sailpoint.object.*;Identity myIdentity=context.getObjectByName(Identity,"Walter.Henderson");return myIdentity;</Source></Script></OwnerDefinition>or<OwnerDefinition value="IIQ``ApplicationOwner"/
    • Can provide either the string name of owning Identity or the Identity object. As with Field value, OwnerDefinition value can also be expressed as a nested element. It can be a string Identity name or an Identity object:
  • <OwnerDefinition><Value><String>Walter.Henderson</String></Value></OwnerDefinition>
    • Three special names exist that are translated by IdentityIQ into the appropriate Identity so an OwnerDefinition script is not required for them:
  • IIQParentOwner - owner of the role or application containing the provisioning policy form
  • IIQApplicationOwner - owner of the application associated with the provisioning policy form
  • IIQRoleOwner - owner of the role containing the provisioning policy form
  • <OwnerDefinition value=""/> assigns and presents the field to the access requester. The user interface offers these options for setting field owners: Requester (sets OwnerDefinition to ""), Application Owner (sets to "IIQApplicationOwner"), Role Owner on Role Provisioning Policies(sets to "IIQRoleOwner"), and Rule and Script (save as OwnerDefinition with nested RuleRef or Script, as shown above)
    		•
    AppDependency Applies only to application provisioning policies as part of the ordered provisioning function; sets the value for a field based on the value of an attribute on another application on which it is dependent.
  • <Field displayName="Login ID" name="login" type="string">
  • <AppDependency applicationName="LDAP" schemaAttributeName="employeeNumber"/>
  • </Field>
    • This can only be specified when the application has dependencies declared and can only reference attributes on an application on which the application is dependent. The user interface option for field value named Dependency creates this element in the field definition.