22 Using the Form Version Control Utility

Process forms and child forms are used to hold account data of OIM Users. You can upgrade a form by adding, modifying, or removing fields on the form. For example, as part of an upgrade operation, you might add the Hire Date field and remove the Country of Origin field from a form. In addition, fields might be moved from the parent form to the child form. The Oracle Identity Manager Form Version Control (FVC) Utility facilitates the management of form data changes after a form upgrade operation.

The FVC Utility is a command-line utility that works directly on the Oracle Identity Manager database. When you install the Oracle Identity Manager Design Console, the utility is present in the OIM_DC_HOME directory. You use a properties file to specify the form data updates that the utility must perform.

The utility supports field mapping and data updates on a provisioning process form and its associated child forms.

Note:

The FVC Utility cannot perform the following functions:

• Manage data updates on object forms

• Move rows across forms

In addition, you need not run the FVC Utility if there are no form-related changes from one release to the next release.

This chapter contains the following sections:

• Use Cases Supported by the FVC Utility

• Use Cases That Are Not Supported by the FVC Utility

• Summary of the Form Version Control Process

• Components of the FVC Utility

• Using the FVC Utility

• Troubleshooting

22.1 Use Cases Supported by the FVC Utility

In a single run, the FVC Utility can be used to manage form data updates corresponding to the following form changes:

See Also:

"Summary of the Form Version Control Process" provides information about the validation performed by the utility before it starts processing form data.

• A field on the parent form is renamed.

• A field on the child form is renamed.

• A field is moved from the parent form to a child form.

• A field is moved from the parent form to a parent form.

• A field is moved from a child form to the parent form. This scenario is supported only if the child form contains a single record.

• A field is moved from a child form to another child form of the same parent form. This scenario is supported only if the source child form contains a single record.

• A field is moved from one child form to another child form of the same parent form. This scenario is supported only if the child form contains a single record.

• A field is moved from a child form to the parent form and also the data type of the moved field is changed from Lookup Field or Combo Box type to Check Box type in parent form.

• In any of the above use cases, the data type of the field in parent form is changed from Lookup Field or Combo Box type to Check Box type.

• In any of the above use cases, the case of a field name is changed. For example, the field name is changed from MyField to myfield.

• The data type of a field is changed from Lookup Field or Combo Box type to Check Box type, without any other change being made to the form.

• For a particular OIM User, the utility proceeds with updating account data only if the status of the user's record in the USR table is not Deleted.

  For an OIM User whose status in the USR table is not Deleted, the utility updates account data in a UD_ table only if the status of the account is not Revoked.

22.2 Use Cases That Are Not Supported by the FVC Utility

The FVC Utility cannot be used to update form data in the following scenarios:

• Fields are modified across multiple process (parent) forms.

• A field is mapped to multiple fields on the same form.

• A field is mapped to multiple fields on different child forms.

• The data type of a field is changed from any type other than the Lookup Field or Combo Box type.

• The data type of a field is changed from Lookup Field or Combo Box type to any type other than a Check Box type.

• Multiple fields are combined into a single field.

22.3 Summary of the Form Version Control Process

The following steps take place during each run of the FVC Utility:

1. The properties file holds information about the data conversion actions to be performed by the FVC Utility. The utility reads the contents of this properties file.

2. The utility checks the object status of the record in the USR table. The next step depends on the status of the record:

   • If the user's record is in the Deleted state, then the utility moves on to the next user's record.

   • If the user's record is not in the Deleted state, then the utility checks the status of the account records in the connector-specific (UD_) tables for that user. For each account record, the next step depends on the status of the account record:

     • If the account record is in the Revoked state, then the utility moves on to the next account record for that user.

     • If the account record is not in the Revoked state, then the utility performs the updates specified in the properties file.

3. For a particular account record, the utility first updates the version of the record and then updates the data as specified in the properties file.

   Note:

   If an error is encountered, then an error message is displayed in the command window. After you fix the cause of the error and rerun the utility, records that have been updated before the error was encountered are not processed again.

22.4 Components of the FVC Utility

The following are components of the FVC Utility:

Note:

When you install the Design Console, these files are copied into the OIM_DC_HOME directory.

• Properties file: You use a file with the ".properties" extension to provide details of the process form, child forms, and resource object on which you want to run the utility. The fvc.properties file is provided as a sample. If a new properties file is used, then the name of the file must be changed in fvcutil.sh or fvcutil.cmd.

• xlFvcUtil.jar: This JAR file contains the utility classes required to run the FVC Utility.

• fvcutil.sh and fvcutil.cmd: You use this script to run the utility.

22.5 Using the FVC Utility

The following sections describe the procedure to use the FVC Utility:

• Preparing the Properties File

• Addressing Prerequisites for Using the FVC Utility

• Running the Utility

• Setting Up the Association Between Fields and Their Error-Handling Adapters

22.5.1 Preparing the Properties File

As mentioned earlier in this chapter, you use a properties file to define the data conversion actions that you want the FVC Utility to perform. Whether you must create or update the properties file depends on the upgrade scenario:

• If you are upgrading from a predefined release to a predefined release of a connector, then look for a properties file in the connector deployment package.

• If you are upgrading from a custom release or upgrading to a custom release, then you must add the required entries in the properties file.

• If you are upgrading from a custom release to a predefined release of a connector, then see if the connector guide provides information about changes to the process form and child forms of the connector. You can use this information to determine the entries that you must add in the properties file.

The following are sample entries for the properties file:

ResourceObject;OID User
FormName;UD_OID_USR
FromVersion;8
ToVersion;9
Parent;UD_OID_USR_DEFTVAL;ABC
Child;UD_OID_GRP_NORMALFIELD;XYZ;Update
ParentChild;UD_OID_USR_FNAME;UD_OID_GRP_NORMALFIELD
ChildChild;UD_OID_GRP_GROUP_NAME;UD_OID_GRP_NORMALFIELD
ChildParent;UD_OID_GRP_NORMALFIELD;UD_OID_USR_LNAME
ParentParent;UD_OID_USR_FNAME;UD_OID_USR_LOGIN;
ParentParentLookupOrComboToCheckBox;UD_OID_USR_PREF_LANG;UD_OID_USR_CHKBOXTEST
ChildParentLookupOrComboToCheckBox;UD_OID_GRP_GROUP_NAME;UD_OID_USR_CHKBOXTEST
ChildDiffChild;UD_OID_GRP_NORMALFIELD;UD_OID_ROLE_DIFFFIELD

Apply the following guidelines while adding or modifying entries in the properties file:

Note:

See the sample entries listed earlier to get a better understanding of the guidelines.

• In the properties file, each line consists of the use case name, followed by old field name and the new field name. Each of these are separated by semicolon.

  For Example consider following entry in properties file:

  ParentChild;UD_OID_USR_FNAME;UD_OID_GRP_NORMALFIELD
  

  ParentChild: represents that the fields of the parent have been renamed/moved to be in the new child form

  UD_OID_USR_FNAME: represents the old field name in parent form

  UD_OID_GRP_NORMALFIELD: represents the new name of the field to be upgraded in the new form.

  Note:

  There can be spaces in the value as long as a space does not appear immediately after the semicolon.

• You must include the following lines in the properties file:

  Note:

  The location and order of these 4 lines in the properties file does not matter.

  • ResourceObject;RESOURCE_OBJECT_NAME

    In this line, replace RESOURCE_OBJECT_NAME with the name of the resource object.

    Sample line:

    ResourceObject;OID User

  • FormName;FORM_NAME

    In this line, replace FORM_NAME with the name of the process (parent) form.

    Sample line:

    FormName;UD_OID_USR

  • FromVersion;CURRENT_VERSION_OF_FORM

    In this line, replace CURRENT_VERSION_OF_FORM with the current version of the form.

    Note:

    When you run the FVC Utility, only records whose version is the same as CURRENT_VERSION_OF_FORM are updated by the utility.

    Sample line:

    FromVersion;8

  • ToVersion;NEW_VERSION_OF_FORM

    In this line, replace NEW_VERSION_OF_FORM with the new version of the form.

    Note:

    If you want to update form data on a form whose version has not changed, then set NEW_VERSION_OF_FORM to the same value as CURRENT_VERSION_OF_FORM.

    Sample line:

    ToVersion;9

• You can include any combination of the following lines in the properties file:

  • Parent;FIELD_NAME;DEFAULT_FIELD_VALUE;Update

    For all records on the parent form, the utility updates the value of the FIELD_NAME field with DEFAULT_FIELD_VALUE.

    Note:

    If a mandatory (required) field has been added on the parent form, then you must include this line in the properties file for the mandatory field.

    Sample line:

    Parent;UD_OID_USR_DEFTVAL;MyString;Update

  • Child;FIELD_NAME;DEFAULT_FIELD_VALUE;Update

    For all records on the child form, the utility updates the value of the FIELD_NAME field to DEFAULT_FIELD_VALUE.

    Note:

    If a mandatory (required) field has been added on the child form, then you must include this line in the properties file.

    Sample line:

    Child;UD_OID_GRP_NORMALFIELD;XYZ;Update

  • ParentParent;OLD_FIELD_NAME;NEW_FIELD_NAME

    On the parent form, the utility moves data from the OLD_FIELD_NAME field to the NEW_FIELD_NAME field.

    Sample line:

    ParentParent;UD_OID_USR_FNAME;UD_OID_USR_DEFTVAL;

  • ParentParentLookupOrComboToCheckBox;OLD_FIELD_NAME;NEW_FIELD_NAME;

    On the parent form, for a Lookup Field or Combo Box type field that has been changed to a Check Box type field and also renamed, the utility sets the check box for each record to the selected state if the field value is True (case insensitive). For all other values, the utility sets the check box to the deselected state.

    Sample value:

    ParentParentLookupOrComboToCheckBox;UD_OID_USR_PREF_LANG;UD_OID_USR_CHKBOXTEST

  • ChildChild;OLD_FIELD_NAME;NEW_FIELD_NAME

    On the child form, the utility copies data from the OLD_FIELD_NAME field of the earlier version to the NEW_FIELD_NAME field of the new version.

    Sample line:

    ChildChild;UD_OID_GRP_GROUP_NAME;UD_OID_GRP_NORMALFIELD

  • ParentChild;OLD_FIELD_NAME;NEW_FIELD_NAME

    The OLD_FIELD_NAME field was moved from the parent form to the child form and renamed to NEW_FIELD_NAME. The utility moves data from the OLD_FIELD_NAME field to the NEW_FIELD_NAME field.

    Sample line:

    ParentChild;UD_OID_USR_FNAME;UD_OID_GRP_NORMALFIELD

  • ChildParent;OLD_FIELD_NAME;NEW_FIELD_NAME

    The OLD_FIELD_NAME field was moved from the child form to the parent form and renamed to NEW_FIELD_NAME. The utility moves data from the OLD_FIELD_NAME field to the NEW_FIELD_NAME field.

    Sample line:

    ChildParent;UD_OID_GRP_NORMALFIELD;UD_OID_USR_DEFTVAL

  • ChildParentLookupOrComboToCheckBox;OLD_FIELD_NAME;NEW_FIELD_NAME

    From a child form, a Lookup Field or Combo Box type field (OLD_FIELD_NAME) has been changed to a Check Box type field and moved to the parent form. On the parent form, the utility sets the check box for each record to the selected state if the field value is True (case sensitive). For all other values, the utility sets the check box to the deselected state.

    Sample line:

    ChildParentLookupOrComboToCheckBox;UD_OID_GRP_GROUP_NAME;UD_OID_USR_CHKBOXTEST

  • ChildDiffChild;OLD_FIELD_NAME;NEW_FIELD_NAME

    The utility moves data from the OLD_FIELD_NAME field on the source child form to the NEW_FIELD_NAME field on the target child form.

    Note:

    This update is carried out only if the source child form contains a single row. A scenario in which the source child form contains more than one row is not supported.

    Sample line:

    ChildDiffChild;UD_OID_GRP_NORMALFIELD;UD_OID_ROLE_DIFFFIELD

22.5.2 Addressing Prerequisites for Using the FVC Utility

Before you run the utility:

1. Set the Java home directory path in the FVC Utility script as follows:

   1. Depending on the operating system and application server that you are using, open one of the following files in a text editor:

      fvcutil.sh

      fvcutil.cmd

   2. Search for set JAVA_HOME.

   3. Set the Java home directory path as shown in the following example:

      set JAVA_HOME=C:\Java\
      

   4. Save and close the file.

2. Verify that the version of the process (parent) form on which you want to run the utility is the Active version.

   To check if the version of a form is the Active version:

   1. Log in to the Design Console

   2. Expand the Development Tools folder, and then double-click Form Designer.

   3. Search for and open the form.

   4. Active Version field of the form displays the active version of the form.

3. The utility cannot update a form field if the field is associated with error-handling adapters. If any field is associated with error-handling adapters, then dissociate the adapters as follows:

   Note:

   After you run the utility, you can again set up the association between the field and its error-handling adapters. The procedure is described later in this chapter.

   1. Log in to the Design Console

   2. Expand the Process Management folder, and then double-click Process Definition.

   3. Search for and open the process definition of the connector.

   4. Make a note of the name of the task that updates the field.

   5. Double-click the task. For example, if the userID field has an error-handling adapter, then double-click the updateUserID task.

   6. On the Integration tab of the Editing Task dialog box, make a note of the adapter variable names and their descriptions.

   7. Click Remove.

   8. To confirm that you want to remove the event-handler adapter, click OK in the message that is displayed.

   9. Click Save.

22.5.3 Running the Utility

Note:

You must execute the FVC utility every time the form version is changed.

Run the following script:

For Unix:

sh fvcutil.sh 

For Windows:

fvcutil.bat

This will prompt you to enter the following details:

1. Enter Oracle Identity Manager admin username: Enter Oracle Identity Manager administrator username.

2. Enter Oracle Identity Manager admin password: Provide Oracle Identity Manager administrator password.

3. Enter logger level: Enter the logger level. It can be DEBUG, WARN, INFO, or ERROR.

4. Enter logger location: Provide the location and name of the log file that you want the utility to create at the end of each run. For example, <Path name>/FVC.log.

22.5.4 Setting Up the Association Between Fields and Their Error-Handling Adapters

If you removed the association between a field and its error-handling adapters before running the utility, then set up the association as follows:

Note:

This is an optional procedure. Perform this procedure only if you removed the association between a field and its error-handling adapters before running the utility.

1. Log in to the Design Console

2. Expand the Process Management folder, and then double-click Process Definition.

3. Search for and open the process definition of the connector.

4. Double-click the task that updates the field. For example, if the userID field has an error-handling adapter, then double-click the updateUserID task.

5. On the Integration tab of the Editing Task dialog box, click Add.

6. In the Handler Selection dialog box, select Adapter, double-click the handler, and then click the Save icon.

   Close the dialog box.

7. In the Adapter Variables region of the Editing Task dialog box, use the Map button to re-map adapter variables and then click the Save icon.

8. Close the Editing Task dialog box.

9. Click the Save icon to save the changes to the process definition.

22.6 Troubleshooting

Table 22-1 lists the error messages that you might encounter in the log file and the corresponding actions that you can take to fix the issues:

Table 22-1 Error Messages and Solutions

Error Message	Solution
Could not find objects with name=OBJECT_NAME	Check the name of the resource object provided in the properties file. Ensure that it is spelled correctly.
Could not find form with name=FORM_NAME	Check the name of the form provided in the properties file. Ensure that it is spelled correctly.
Could not find active version of the form.	A newly created form might not have been committed and set to the Active state. Ensure that the form is in the Active state.
ToVersion value and active version of the form do not match.	Ensure that the ToVersion value is the same as the version of the form that is currently active.
Either ToVersion or FromVersion values are not valid versions.	Ensure that the ToVersion and FromVersion values are correct.
FIELD_NAME field does not exist in the Oracle Identity Manager database.	Ensure that the name of the field is spelled correctly.