This readme describes the overall design, creation, installation and removal of subforms in the ITIM environment. It also shows you how to install the supplied subform example.
IBM Tivoli Identity Manager (ITIM) provides a number of built-in GUI controls that can be used to edit attributes of persons, business partners, accounts and organizational tree containers. These controls can be used to edit attributes that contain simple text data, dates and links to other ITIM objects. But the built-in controls may not be sufficient when an attribute contains formatted data, such as an XML document.
ITIM provides the ability to define your own HTML pages to use as custom editors for formatted data. These custom editor pages are called subforms. ITIM ships with subform definitions that are used when editing RACF connect groups, SAP roles, etc. This document describes how you can create your own subform definitions
Creating a subform definition requires application server development and deployment skills. This document assumes that the reader is familiar with the following:
IBM Tivoli Identity Manager Information Center
Editing an attribute value with a subform involves activities in both the ITIM application server, and in the user's web browser. The steps involved are shown in the diagram below.
Your subform must be defined as a complete standalone web page. ITIM will display your subform in a separate browser window - not as a part of an ITIM page.
Your subform can be defined using a static HTML file, or the HTML can be generated by a servlet or JSP. There are no requirements regarding the page contents.
Using a static HTML file doesn't eliminate the need to do servlet or JSP programming. The changes to the edited attribute must be saved in the HTTP session. This can only be done by a servlet or JSP, so your static HTML must still use one of these as the action of a submit.
The ITIM UI customization applet offers a control type of "SubForm". When a form contains a subform control, this attribute is rendered as a button with the text "Details". Clicking on this button will open a new browser window and load your subform in it.
To edit an attribute using your custom subform, open the form template for the entity type having the attribute. Find the attribute on the form template, and right click on the attribute. Select "Change To" and then "SubForm" from the context menu. This will open the subform editor window in the applet.
The subform editor allows you to specify a list of name-value pairs. These will be passed to your servlet or JSP as request parameters. The only mandatory entry in this list is the customServletURI parameter. The value of this parameter will depend on whether your subform is implemented using a servlet, JSP or HTML file:
| Servlet | The value must be the "url-pattern" defined in your servlet mapping. |
| JSP or HTML File | The value must be the name of the file, including the suffix. Don't include the path to the file. |
You may also include name-value pairs for any other parameters you want passed in the HTTP request. Note that these parameters will be static. The same values will always be passed whenever the subform referenced by this control is used. These parameters can be used to cause different behavior in a single servlet or JSP depending on how the subform control was created in the parent form.
Additional parameters are automatically included in the first request to your servlet or JSP. These may contain the name of the attribute being edited, the DN of the object owning the attribute, or other context data. You don't need to include these in the subform control's name-value list. The exact list of automatically include parameters will vary depending on the type of object being edited, and whether it is being created or modified. This is described in detail in the next section of this document.
Click the OK button in the subform editor when you are done editing the name-value list.
You can also control the size of the window used to display your subform. With the entity form template still open in the UI customization applet, select the attribute with the subform control type. You can now set the subform's window size using the "Width" and "Height" fields in the "Format" tab at the bottom right of the applet window. These fields set the window size in pixels.
The first HttpServletRequest object passed to your servlet or JSP will contain one parameter for each of the name-value pairs defined in the subform control that opened the subform window, plus an additional 4 automatically included parameters. The values of these automatic parameters will vary depending on the type of object being edited and the context in which the parent form was displayed.
The parameters derived from the subform control's name-value list will have parameter names that are derived from the name of the attribute being edited, the name used in the name-value pair, and a fixed prefix that avoids conflicts with other parameters. The format of the name is:
[prefix].[attribute name].[parameter name]
The prefix is always property.data.. So the mandatory customServletURI entry in the name-value list will result in a request parameter named property.data.accessrights.customServletURI if used to edit an attribute named accessrights.
A request sent to your servlet or JSP will always contain the following parameters:
The fieldname parameter will always contain the name of the attribute being edited with a prefix of "data." The other parameters' values will depend on the entity type being edited, and the context in which the subform was opened. The following tables describe the parameter values for each context in which a subform can be used.
| target_dn | Empty |
| container_dn | DN of organizational tree container where person will be created. |
| search_base | Empty |
| target_dn | DN of person. |
| container_dn | DN of organizational tree container where person is located. |
| search_base | Empty |
| target_dn | DN of account owner. |
| container_dn | DN of account owner. |
| search_base | DN of Service. |
| target_dn | DN of account. |
| container_dn | DN of account owner. |
| search_base | DN of service. |
Your subform should never directly modify the entity being edited. The changes made by the user in your subform must be stored in the HTTP session. The ITIM servlets that process submissions of entity create and modify forms know to look for attribute changes in the session as well as in the submitted form.
The modified value from your subform must be stored as a com.ibm.itim.common.AttributeValue object. This object must be constructed with the name of the attribute being edited by the subform. The attribute name is the fieldname request parameter with the "data." prefix stripped out.
The name of the session attribute you must use is subFormAttrValue.
For example:
AttributeValue av = new AttributeValue(attrName, newValue); session.setAttribute("subFormAttrValue", av);ITIM does not pass the current value of the attribute being edited to your subform. Your servlet or JSP must do this when it generates the HTTP response that will be used to send your subform to the user's browser. This is one of the reasons why static HTML files are not useful as subforms. There is no way for such as subform to be used to modify an existing value.
Your servlet or JSP can lookup the existing value of the attribute to be edited by retrieving it from the session using the key subFormAttrValue. The Object stored in the session under this key is of type AttributeValue.
If your subform requires other ITIM-related services, it can access those via the ITIM application API. Using the application API normally requires that you authenticate to ITIM in order to obtain the Subject object that you must pass to application API constructors. This is not necessary in your subform code. The user is already authenticated, and their subject object can be retrieved from the HTTP session. You can do this using the following code:
Subject subject = (Subject) session.getAttribute("subject");Remember that a servlet's service method is defined as throwing only ServletException and IOException. Any other exceptions that may be thrown by your code or the application API must be caught and wrapped as a ServletException. This is also true if you are using a JSP to generate your subform. All of the code generated by your JSP will be called from within a servlet service method.
It is possible for a user to edit an attribute value with your subform, save their changes, and then open the subform again before they have submitted the parent form. When this happens your subform should display the user's saved changes which will be available in the session
Your servlet or JSP can do this by retrieving the AttributeValue stored in the session under the key subFormAttrValue. ITIM deletes this session attribute when it displays an entity form, so you don't need to worry about stale session attributes left over from edits of a different entity.
You will probably want your subform to act or look differently depending on whether the user has write access to the attribute being edited by the subform. You can get this data from the HTTP session.
For backwards compatibility, the user's attribute permission will be stored in 3 session attributes:
All 3 of these attributes will exist in your session. The value of these attributes will be a java.util.Map object. This map will contain your attribute name as the only key. If the value stored for the attribute you are editing is "r" this indicates that the user has read-only access to the attribute. Any other value (ie: "w") indicates that the user has write permission for the attribute.
You don't need to worry about checking for read access to the edited attribute. ITIM will not display the link to your subform on the entity form if the user doesn't have read access to the edited attribute.
The procedure for installing your subform installation varies depending on whether you have used a servlet, JSP or HTML file.
If you have created a servlet or your Jsp uses a custom set of java libraries then you must:
<servlet> <description>My Custom Subform</description> <servlet-name>MyCustomSubform</servlet-name> <servlet-class>mydevshop.itimextensions.MyCustomSubformServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>MyCustomSubform</servlet-name> <url-pattern>/subforms/mycustomsubform</url-pattern> </servlet-mapping>
Changes to ITIM's class path and ITIM's web.xml will require a restart of the ITIM application server.
If you created a JSP or HTML file then all you need to do is to place it in the subforms directory inside the folder containing the installed ITIM web application. For a self service console installation this will be WAS_HOME/profiles/[profile]/installedApps/[cell]/ITIM.ear/itim_self_service.war/subforms, for an administrative console installation this will be: WAS_HOME/profiles/[profile]/installedApps/[cell]/ITIM.ear/itim_console.war/subforms
For a clustered environment, you will need to repeat the above steps to each cluster member that is running ITIM.
Once you have installed your subform, you must use the Form Designer to configure it. The Form Designer is available in the administrative console under the Configure System heading. Using the Form Designer, select the category in the left pane that you planned to customize. Select the attribute in the form template that will use your subform, right click and select "Change to" and pick Subform as the control type. A popup window will be displayed titled "Subform Editor". The "Subform Editor" consists of a table of keys and values. It starts out empty and it must contain at least one key, the customServletURI key. Add the customServletURI key, and use the Servlet/Jsp name of your subform as your value. If you have any other constants that you need to pass to your subform at runtime, than add them here as well. They will be available in the request object; the key to retrieve the parameter will have this format:
Once you have added all the keys and values using the Subform Editor, click OK to close the Subform Editor and make sure to save your custom form template using the menu "Form" and selecting "Save Form Template". Your subform is now ready to be used.
The steps to uninstall a subform will be a complete reversal of the installation steps. First we should use the Form Designer to change the control type from Subform to the control type that will handle your attribute. If no such control exists then you should remove the attribute from the form template, you can do this by selecting the attribute and pressing the delete button.
Once you have unconfigured the subform you can proceed to remove the source files that comprise the subform from the subforms folder. Refer to the previous section for the exact subforms folder locations.
Remove any custom java libraries that were added to ITIM's classpath during the subform installation. Also, any servlets that were added to ITIM's web.xml file need to be removed, along with their servlet mappings. Note that changes to ITIM's classpath and ITIM's web.xml will require a restart of the ITIM application server.
The sample subform implementation included maintains an attribute containing an XML document defining a user's emergency contact information. The subform is implemented as a JSP.
The attribute is a single-value attribute with a simple xml structure, thus keeping the details of the example simple so we can better focus on the subform infrastructure.
The XML document maintained by the subform consists of an emergency-contact element with the following attributes:
For example:
<emergency-contact name="John Smith" telephone="(205)123-5555" relationship="spouse"/>The subform window is pictured below.
This subform allows a user, in this case Janice, three fields on which to provide emergency contact information. The subform's Jsp than converts this data into an XML document and stores it as a single value as part of Janice's person definition.
It is worth noting that the subform implementer is expected to update the value in the session. Therefore the mechanism for relaying to ITIM that a user has updated the value is not via an html POST request. Instead, it is common for a subform to post to itself when saving values. Then the subform code can set the value in the session and then load an html page that closes the subform pop-up window using the body tag's "onLoad" event.
The example implementation contains 3 parts:
The ITIM web application directory (see section 9, Installation) contains a subforms directory. Create a sample directory in the subforms directory. Copy all 4 (sample.jsp, sample_utils.jspf,sample.js,sample.css) files to the newly created sample folder.
Login to ITIM as an administrator and launch the Form Designer. Open the form template for Person or for your custom person entity type.
Choose an attribute to be edited by the subform. Make sure that you choose an attribute that can hold the resulting XML document. If you are using IDS as your LDAP server you will find that many inetOrgPerson attributes have maximum lengths that are too small to hold an emergency-contact XML document. For example, the initials attribute is one of these. One such attribute is homepostaladdress attribute. Make sure you choose an attribute that is not already populated on any of your users. Any existing values will cause the XML parser to fail when the subform is opened.
In the Form Designer, right click on the chosen attribute and select "Change To" and "SubForm". This will open the subform editor window.
In the subform editor, double click on the empty box under "Name". Enter customServletURI into this box. Double click on the empty box under "Value" and enter sample/sample.jsp. Click the OK button.
Select "Save Form Template" from the applet's "Form" menu, and then close the form designer.
You should now be able to browse to a person and see that your subform attribute is rendered as a "Details" button. Click on this button to open the subform.