Attribute Modification Approval

This chapter describes how to configure attribute modification approval within Web Center.

Overview

Web Center supports modification approval for a wide range of objects and attributes.The content and layout of the approval pages is controlled by a single forms configuration file.

The configuration allows for:

  • Displaying the attributes to be approved in a defined order.

  • Arranging the attributes in sections with titles.

  • Defining which attributes the approver is allowed to modify.

  • Defining display properties like field width and renderer per attribute.

  • Displaying localized attribute names.

  • Displaying old and new attribute values side by side on the same row, or one below the other on subsequent rows.

  • Displaying non-modified attributes that are somehow related to one of the modified attributes.

  • Defining which modified attributes are hidden from the approver.

  • Assigning checks to attributes.

Form Configuration

The configuration is split into a base form containing the common parts of all approval forms, and of forms specific to object types and/or approval workflows.The specific forms describe the actual attributes to be approved, and are included into the base form at runtime as appropriate.

The forms configuration file is

WEB-INF/config/workflows/modificationApproval/forms-config.xml.

After changes to the file, restart Tomcat to put the changes into effect.

Base Form Configuration

The base approval form configuration is the form-bean element with name approveModificationActivityForm. It is a variation of the usual form configuration. It defines the common fields to be displayed on the top and the bottom of all approval pages, like workflow subject, initiator, expiration time, and reason, as well as the buttons to accept or reject modifications. In addition to that, the base form contains elements that define which forms to include at runtime for which object types and approval workflows

Top and Bottom

Top and bottom are configured as usual. The only thing to pay regard to is that the top fields get sufficiently low y values and the bottom fields get sufficiently high ones, so that the fields in the forms to be included at runtime get y values that lie between the top and the bottom ones.

Includes

Form-include elements are instructions to include a form at runtime into the base form. The element supports the attributes name, objectTypes and workflowPaths.

The name is the name of the form-bean element that is to be included at runtime at the element’s position.

The objectTypes are a comma-separated list of case insensitive object types this include applies to. An include element with an empty objectTypes attribute applies to any object.

The workflowPaths are a comma-separated list of Java regular expressions. An include element applies only to those approval workflows whose path case insensitively matches at least one of the expressions. An include element with an empty workflowPaths attribute applies to any workflow.

Samples:

<form-include
     name="approveUserModificationActivityForm"
     objectTypes="dxrUser"
     workflowPaths=""/>

The include element matches any approval workflow for dxrUser subjects.

<form-include
     name="approvePermissionModificationActivityForm"
     objectTypes="dxrPermission"
     workflowPaths=".*/Modify Permission$"/>

The include element matches any workflow for dxrPermission subjects whose path ends with /Modify Permission.

The path of a workflow is its distinguished name in reversed order, with delimiter “/”, without types and without the workflow root DN:

Workflow DN:

cn=Modify User,cn=Users,cn=Default,
       cn=Definitions,cn=wfRoot,cn=My-Company

Workflow path:

/Definitions/Default/Users/Modify User

Included Forms

The included forms are regular form-bean elements whose child elements define layout and properties of the attributes to be approved, and sections that serve to structure the approval page with titles.

Section

A section is a form-property-group element with a unique name. The message key of its title is by default group.label.<case insensitive group name>, but may be set explicitly in attribute label.

Each section has a level, a non-negative number. The level is specified in attribute level; the default level is 0. A section is regarded to be a logical subsection of the last preceding section with a lower level.

A section title is displayed only if at least one of the attributes in the section or a logical subsection thereof must be approved. A section extends to the next form-property-group element with the same or a lower level, or the end of the form.

Do not define any form-property child elements for sections.

Attributes

Attributes are configured as usual via form-property elements supporting almost any attribute in the familiar way. But there are some differences.

The message key of the attribute label is by default ldap.attribute.<case insensitive form-property name>, but may be set explicitly in attribute label.

For each attribute to be approved, the spanX attribute defines whether old and new values are displayed side by side on the same row (spanX <= 2), or old below new values on two subsequent rows (spanX > 2). In the latter case, old and new values span three columns each.

In case a property does not have any old value and its spanX attribute value is 4, the label for the old property values is displayed anyway, wasting space for a separate row. You can suppress the label display by setting attribute hideOldIfEmpty to true.It is sometimes convenient to display related attributes along with an attribute that must be approved even if the related attributes were not modified or are not subject to approval. For example, if someone changed a user’s disable start date, the approver might prefer to see the disable end date as well. This can be achieved with attribute sets.

A set is identified by an arbitrary unique id and comprises several attributes of the same section. An attribute belongs to all sets whose ids are listed in its form-property attribute sets. If a modification of any of the attributes in a set must be approved, the approval page shows all attributes in that set. A set attribute that was not modified or is not subject to approval is editable for the approver only if the set id in its sets list is prefixed with w:

Sets are esp. useful for defining field checks that affect more than one attribute.

Sample:

<form-property name="dxrStartDate" ... sets="d"/>
<form-property name="dxrEndDate" ... sets="d"/>
<form-property name="dxrDisableStartDate" ... sets="w:d"/>
<form-property name="dxrDisableEndDate" ... sets "w:d"
     fieldRenderer="checkedDate"
     rendererProperties="onChange:dates.checkOrder;
     form:approveModificationActivityForm;
     ids:dxrStartDate,dxrDisableStartDate,dxrDisableEndDate,dxrEndDate"
/>

The attribute set with id "d" consists of four attributes.The approver will see either all four attributes or none at all.If displayed, dxrDisableStartDate and dxrDisableEndDate are always editable for the approver, dxrStartDate and dxrEndDate only if originally modified and subject to approval.

Generic Attribute Display

Web Center will attempt to display attributes subject to approval but not listed in the forms configuration on the approval page in a simple generic way below the other attributes.The generic approach, however, works only for a limited subset of all attributes, and lacks many of the features of the configuration approach.Therefore, we strongly recommend adding each affected attribute to the approval form configuration.

Restrictions

Attribute modification approval is, amongst others, not possible for

  • Naming attributes.

  • The assigned state of group members.

You must not activate approval for these attributes.

Notes

Some modifications affect several attributes of an object.In that case, you must either activate approval for all affected attributes or for none at all.If activated, list each affected attribute in the approval form configuration, and set the visible flags of the implicitly changed attributes to false in order not to confuse the approver.Examples are:

  • Role parameter changes affect attributes dxrRPMatchRule and dxrRoleParamLink.

  • Changes to the group flag “Manage only in target system” sometimes causes the dxrError attribute to be cleared.