A Configuring Requests

Note:

The procedure described in this section is applicable only if you are using Oracle Identity Manager release 11.1.1.x.

This section describes how to configure a custom request workflow to cater to the specific requirements in your organization. Configuring a custom request workflow involves the following steps:

The following section describes how to extend the request management operations by using plug-in points:

Extending Request Management Operations

A.1 Step 1: Creating a Request Dataset for the Resources

This section describes the request datasets in the following sections:

A.1.1 About Request Datasets

Request dataset is an XML definition file that dictates what data needs to be collected during various phases of the request lifecycle. In the request dataset, you can define what attributes need to be submitted by the requester and approver, whether or not an attribute is mandatory, and how UI should render the attribute to the user. Every attribute defined as a part of the dataset is associated with a set of properties that define the behavior of the attributes. Request dataset also allows you to define additional attributes, which exist only in the context of the request.

Every request is raised by using a request template. Each request template is associated with a request type. Each request type is associated with a request model. There is a one-to-one correspondence between request model and request type. A request model is a specification or configuration that instructs the request engine to work in a specific way for a particular request type. Request models are broadly associated with three types of entities: user, resource, and role. All request models are shipped with Oracle Identity Manager and cannot be configured.

The request model associates the appropriate request dataset when a request is raised for a specific request type. For example, generic Provision Resource request model deals with request for provisioning of any resource objects. Every time a resource is defined, if that resource is expected to be provisioned through a request, then a new dataset can be created with the attributes that need to be collected during request lifecycle. The request datasets that are associated with a nongeneric entity, which is user, has predefined or default request datasets.

Request models that are associated with generic entities does not have default request datasets. For example, the Provision Resource request model is associated with a generic entity, which is resource. For the request models that are associated with non-generic entities, such as user, a default request dataset is available because the user entity has fixed set of default attributes.

A.1.2 Default Request Datasets

configuring-requests.htm#GUID-5DD0ECDB-940E-4DE3-B83D-827031171C0D__CIHCFIAE lists the request models and the associated default request dataset file names that are shipped with Oracle Identity Manager.

Table A-1 Default Request Datasets Shipped with Oracle Identity Manager

Request Model	Default Dataset File Name	Entity
Create User	CreateUserDataSet.xml	User
Delete User	DeleteUserDataset.xml	User
Enable User	EnableUserDataset.xml	User
Disable User	DisableUserDataset.xml	User
Modify User Profile	ModifyUserDataset.xml	User
Self-Register User	SelfCreateUserDataset.xml	User
Modify Self Profile	ModifyUserDataset.xml	User
Create Role	CreateRoleDataSet.xml	Role
Modify Role	ModifyRoleDataSet.xml	Role
Delete Role	DeleteRoleDataSet.xml.	Role
Assign Roles	AssignRolesDataset.xml	Role
Self Assign Roles	AssignRolesDataset.xml	Role
Self Remove Roles	RemoveRolesDataset.xml	Role
Remove from Roles	RemoveRolesDataset.xml	Role
Provision Resource	No request dataset	Resource
Self-Request Resource	No request dataset	Resource
Enable Provisioned Resource	No request dataset	Resource
Modify Provisioned Resource	No request dataset	Resource
Self Modify Provisioned Resource	No request dataset	Resource
Disable Provisioned Resource	No request dataset	Resource
De-provision Resource	No request dataset	Resource
Self De-Provision Resource	No request dataset	Resource

Note:

It is not mandatory to have a request dataset for each request model. For example, a request dataset is not required for the De-provision Resource request model because there is no specific data to be collected as a part of request submission or approval. But for the Provision Resource request model, if it involves collection of resource-specific data as a part of request submission or approval, then there must be a dataset defined for that model, which dictates what and how the data is to be collected.

Default request datasets can be customized or configured, such as adding new attributes. The following metadata contains the request model and dataset definitions for default request types:

/metadata/iam-features-requestactions/model-data/AssignRolesDataset.xml/metadata/iam-features-requestactions/model-data/CreateRoleDataSet.xml/metadata/iam-features-requestactions/model-data/CreateUserDataSet.xml/metadata/iam-features-requestactions/model-data/DeleteRoleDataSet.xml/metadata/iam-features-requestactions/model-data/DeleteUserDataset.xml/metadata/iam-features-requestactions/model-data/DeleteUserRequest.xml/metadata/iam-features-requestactions/model-data/DisableUserDataset.xml/metadata/iam-features-requestactions/model-data/DisableUserRequest.xml/metadata/iam-features-requestactions/model-data/EnableUserDataset.xml/metadata/iam-features-requestactions/model-data/EnableUserRequest.xml/metadata/iam-features-requestactions/model-data/ModifyRoleDataSet.xml/metadata/iam-features-requestactions/model-data/ModifyUserDataset.xml/metadata/iam-features-requestactions/model-data/RemoveRolesDataset.xml/metadata/iam-features-requestactions/model-data/ResourceCommonDataset.xml/metadata/iam-features-requestactions/model-data/SelfCreateUserDataset.xml

A.1.3 Elements and Properties

Request dataset is defined by using the following elements and their associated attributes:

A.1.3.1 The request-data-set Element

The request-data-set element is the root element of the request dataset with the following mandatory attributes:

name: The name of the dataset, such as CreateUserDataSet
entity: The underlying entity, such as user, with which the dataset is associated
operation: The operation associated with the dataset, such as CREATE

The following example shows the request-data-set element:

<request-data-set xmlns="http://www.oracle.com/schema/oim/request/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.oracle.com/schema/oim/request/" name="CreateUserDataSet" entity="User" operation="CREATE">

This root element is shown without any child elements.

To create request datasets for the resource entity, refer to configuring-requests.htm#GUID-60FCAF09-8573-494B-B881-7A66F3A6BE2F__CIHCFBDH that lists the request dataset name format and operation for each request type.

Table A-2 Request Datasets for Resource Entity

Request Type	Request Dataset Name Format	Operation
Provision Resource	ProvisionResource${ENTITY-NAME}	PROVISION
Self-Request Resource	ProvisionResource${ENTITY-NAME}	PROVISION
Modify Provisioned Resource	ModifyResource${ENTITY-NAME}	MODIFYRESOURCE
Self Modify Provisioned Resource	ModifyResource${ENTITY-NAME}	MODIFYRESOURCE

The following is a sample dataset tag for the Provision Resource dataset for the E-Business RO resource:

<request-data-set xmlns="http://www.oracle.com/schema/oim/request/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.oracle.com/schema/oim/request/" name="ProvisionResourceE-Business RO" entity="E-Business RO" operation="PROVISION">

Here:

For name, the ProvisionResource${ENTITY-NAME} format specified in configuring-requests.htm#GUID-60FCAF09-8573-494B-B881-7A66F3A6BE2F__CIHCFBDH is replaced by the resource name E-Business RO. Replace ${ENTITY_NAME} with the resource name.
Specify operation as shown in configuring-requests.htm#GUID-60FCAF09-8573-494B-B881-7A66F3A6BE2F__CIHCFBDH.
Values for the properties are:
- name: ProvisionResourceE-Business RO
- entity: E-Business RO
- operation: PROVISION

A.1.3.2 The DataSetValidator Element

The DataSetValidator element is an optional element in request dataset. It is one of the child elements of the request-data-set element that describes the user-defined plug-in details meant for validating the dataset attribute values. The request engine runs the implemented plug-in to validate request data during submission. If the validation is successful, then the request gets created. Otherwise, the request is not created. You must implement the plug-in logic. Each dataset can have only one DataSetValidator defined. Following are the attributes:

name: This attribute specifies a logical name of the DataSetValidator plug-in.
classname: This attribute specifies the fully qualified name of the implemented plug-in class.

The following example shows the DataSetValidator element:

<DataSetValidator name="CreateUserDataValidator" classname="oracle.iam.requestactions.plugins.datavalidator.CreateUserDataValidator"/>

In each default request dataset mentioned in configuring-requests.htm#GUID-5DD0ECDB-940E-4DE3-B83D-827031171C0D__CIHCFIAE, the default DataSetValidator element is defined and the corresponding implementation is provided by default. The classname in the DataSetValidators in these default request datasets can be changed to a customized class to have customized validation.

A.1.3.3 The AttributeReference Element

This child element is used to define the entity attributes at request end that take part in data-flow between request dataset and underlying entity attribute or process-form fields. All the data corresponding to AttributeReference are collected as request data at various stages of the request life cycle based on the configuration.

Multiple AttributeReference elements can be provided in a dataset, one for each attribute.

This section contains the following topics:

A.1.3.3.1 Mandatory Properties

The following mandatory properties are used to configure AttributeReference:

name: This is the unique name to identify the element. The request refers to an AttributeReference by using this name. Its value is of type String.
attr-ref: This is the mapping property between the data set value and process form field or underlying entity attribute. For example, the definition <AttributeReference name="Organization" attr-ref="act_key"> in the Create User dataset specifies that the request collects the data as Organization corresponding to the new user being created and gets populated in the act_key data field of the user entity.

Similarly, with the AttributeReference name="Domain" attr-ref="domain" definition associated with a Provision Email resource dataset, the request collects the data as Domain corresponding to the resource being provisioned, and the data is populated to the domain field of the process form. Therefore, for provision resource models, attr-ref attribute value must be the same as the value of the field label (SDC_LABEL) of the process form. For other models, the attr-ref attribute value must be the entity attribute of the underlying entity defined by the feature. Its value is of type String.

DataFlows is required to map the request dataset attributes to the underlying entity attributes. For example, in some request models, such as provision resource, you might need to define a data flow mapping between the request dataset and the process form data fields. The data flow mapping can be achieved by specifying the following in the dataset:
```
<AttributeReference name="ATTRIBUTE_NAME" attr-ref="DATA_FIELD_NAME_IN_PROCESS_FORM" available-in-bulk="false" />
```
For user-based and role-based request datasets, attr-ref value is the attribute name specified in user and role entity definitions. For resource-based request models, attr-ref value must be the label name of the process form attribute. But for a child form, attr-ref value must be the child table name.
type: This property specifies the data type of the value. For example, type="String" for the First Name attribute specifies that the First Name field in the Create User request UI accepts String type input. The supported data types are:
- Byte
- Double
- Integer
- String
- Short
- Long
- Date
- Boolean
- ByteArray
- Clob
  
  Note:
  
  Out of all the supported types, only Clob data is not displayed in the request management UI.
  
  Attributes of type Clob must not be made as approver-only.
widget: This property is used to specify how the data attribute is to be displayed in the UI at the time of data collection. The value of this property is of type String. The following widgets are supported:
- text: Specifies a text box that allows the user to enter text in a single line. For example, widget="text" for the First Name attribute specifies that the First Name field in the Create User UI is a text box.
- date: Specifies a date and time type field. For example, widget="date" for the Start Date attribute specifies that the Start Date field in the Create User UI accepts a date as input.
- entity: Specifies an entity type field. When you specify widget="ENTITY", you must specify a value for the entity-type property, such as entity-type="ORGANIZATION". This means that the Organization field in the Create User request UI provides the organization lookup from which you can search and select an organization that is present in Oracle Identity Manager. When widget=ENTITY, then the value of entity-type must be USER, ORGANIZATION, or ROLE.
  
  Note:
  
  You must specify a value for the attr-ref element, which is the attribute name for organization in the user entity definition. For example, attr-ref="act_key" in the User.xml, which contains the entity definition of the user entity.
- textarea: Specifies a large text field for entering multiple lines of text.
- dropdown: Specifies a List of Values (LOV). When you specify widget="dropdown", you must specify values for a list of lookupValues encoded-value and decoded-value elements, such as lookupValues encoded-value="End User" decoded-value="Identity Only" and lookupValues encoded-value="End-User Administrator" decoded-value="End-User Administrator". This means that the User Type field in the Create User request UI is displayed as an LOV from which the user types Identity Only or End-User Administrator can be selected. However, if the lookup-code property is defined, as described later in this chapter, then you do not have to specify lookupValues.
  
  The list of values can come from either of the following:
  
  - Static list of lookupValues specified in the dataset itself. For example:
```
lookupValues encoded-value="End User" decoded-value="Identity Only" and lookupValues encoded-value="End-User Administrator" decoded-value="End-User Administrator"
```
  - List of lookup values based on the lookup-code property defined, as described later in this chapter.
- radio: Specifies a radio button.
- checkbox: Specifies a checkbox field. This widget can be associated with attribute references only with Boolean type.
- lookup: Specifies a lookup field that allows you to select a value from a large number of values. If this is used, then the lookup-code property must be specified.
- lookup-query: Specifies a search and select widget that is associated with the lookupQuery element.
- itresource-lookup: Specifies a search and select widget that is associated with an IT resource and shows available IT resource instances. For more information about this widget, see the example listed in Child Data.
length: This attribute specifies the length of the data value. For example, length="80" for the First Name attribute specifies that the First Name field in the Create User request UI accepts an input of maximum 80 characters. Its value is of type positive integer.
available-in-bulk: Its value is of type Boolean. This property indicates whether or not the attribute reference is to be displayed during bulk request creation.

You can always hide the fields related to single user context, such as first name, user ID, and password, from the request dataset by marking these fields as available-in bulk="false" in a bulk request scenario. This is because the bulk request is applicable for multiple users and the single user fields does not make sense to be displayed on the request UI. For provisioning requests, these single user fields can be populated by the prepopulation adapters filling the process forms directly. If an attribute is specified as available-in-bulk="false", then that attribute cannot be made mandatory. If you create request datasets by using prepopulation adapters, then you cannot have mandatory constraints assigned to any of these single user fields such as first name, user ID, and password. If you want to assign mandatory constraints to single user fields for usability when a singe user is requesting for the resource by using self service, then use the PrePopulationAdapter element in the request dataset for populating user specific data. See "The PrePopulationAdapter Element" for information about using the PrePopulationAdapter element in request datasets.

A.1.3.3.2 Optional Properties

The following optional attributes can be used to configure AttributeReference:

required: This is a flag property to indicate that data value must be supplied at the time of request submission. Value is of type Boolean. If this property is not specified, then the default value taken is false.

Any attribute reference for which the corresponding attr-ref field is mandatory in the underlying entity, must be specified as required="true". Forexample, Organization is a mandatory attribute in the user entity. Therefore, the corresponding attribute reference in SelfCreateUserDataset.xml or CreateUserDataSet.xml is specified as required="true" reflecting that this field is mandatory in underlying entity as well.
Masked: This is a flag property used to specify if the data value is masked. If the value is set to masked, the request engine always displays it as asterisks. Value is of type Boolean. If this property is not specified, then the default value taken is false.
approver-only: This is a flag property used to specify that data value has to be supplied, edited by approver. By setting this flag, requester is never allowed to supply the corresponding data value. Value is of type Boolean. If this property is not specified, then the default value taken is "false".

If an attribute specified as required="true" and approver-only="true", then approver has to provide the value for this attribute before approving the request.

The approval process does not support adding child table data, and therefore, only one value can be provided for a child table (multivalued) field during the approval process.
entity-type: This property is used to associate an entity from which supported data value is derived for selection from the request UI. For example:
```
<AttributeReference name="Organization" attr-ref="act_key" available-in-bulk="false" type="Long" length="20" widget="ENTITY" required="true" entity-type="ORGANIZATION"/>
```
With this definition, UI displays a lookup widget by using which user can search and select an organization in Oracle Identity Manager.

If entity-type property is defined, then the widget must be defined as ENTITY, and UI displays a lookup widget by using which user can search and select an entity.
lookup-code: This property is used to associate available LKU/LKV values as supported data based on a defined lookup-code. Example:
```
<AttributeReference name="Responsibility Name" attr-ref="Name" type="String" length="30" widget="lookup" required="false" available-in-bulk="true" lookup-code="Oracle.Responsibility.Name"/>
```
This definition renders all the encoded/decoded values for the lookup-code Oracle.Responsibility.Name.

If the lookup-code property is defined, then widget can be defined as lookup, and UI displays a lookup widget by using which user can search and select a lookup value.

If lookup-code is defined, the widget can be dropdown as well. For example:
```
<AttributeReference name="Role" attr-ref="Role" available-in-bulk="false" type="String" length="20" widget="dropdown" lookup-code="Lookup.Users.Role" required="true"/>
```
Here, the User types will be displayed as a dropdown, and user can select any of the values.

If the lookup code is associated with limited number of values, then you can use dropdown. But if the lookup code is associated with large number of values, then use the lookup widget, which allows search and selection of value.
itresource-type: This property is used to associate available itresource instance for a defined itresource-type. Example:
```
<AttributeReference name="Server" attr-ref="Server Name" type="String" widget="itresource-lookup" required="true" itresource-type="EBIZServer" available-in-bulk="true" length="20"/>
```
This definition renders all IT resource instances for the EBIZServer itresource-type.

If the itresource-type property is defined, then widget must be defined as itresource-lookup, and UI displays a lookup widget by using which user can search and select an itresource instance.
primary: This is a flag property used to specify if the dataset attribute can have more than one value. This flag can be set for a dataset attribute only in the context of child table. See "Child Data" for more information about the primary property.
mls: This is a flag property used to specify if the dataset attribute is of type Multi-Language Support (MLS). Value is of type Boolean. If this property is not specified, then the default value taken is false.
entitlement: This is a flag property used to specify if the dataset attribute is of type entitlement. Value is of type Boolean. If this property is not specified, then the default value taken is false.
hidden: This is a flag property used to specify if the data value is hidden from the approver. This data value is not visible only to the approver but data can be collected from the requester at the time of submitting the request or by other means. Value is of type Boolean. If this property is not specified, then the default value taken is false.

A.1.3.3.3 The PrePopulationAdapter Element

This child element is used to define an associated Oracle Identity Manager plug-in class that helps in generating data values for the corresponding attribute. Each attribute can have a maximum of one PrePopulationAdapter element associated for an AttributeReference definition. An attribute value is prepopulated during request creation from UI with the value returned by the prepopulation adapter plug-in. The attributes are:

name: This attribute is used to specify a logical name of the adapter.
classname: This attribute is used to specify the fully qualified classname of the plugin class.

Note:

Even if a request dataset attribute is configured with a PrePopulationAdapter, its values can be restricted in a request template. As a result, prepopulation does not happen and the values restricted in the template are displayed in the request creation UI.

The following example shows how to associate PrePopulateAdapter for an AttributeReference:

<AttributeReference name="Organization" attr-ref="act_key" available-in-bulk="false" type="Long" length="20" widget="ENTITY" required="true" entity-type="ORGANIZATION"/>
<PrePopulationAdapter name="prepopulateOrg" classname="my.sample.package.SamplePrePopulateOrg" />
</AttributeReference>

The my.sample.package.SamplePrePopulateOrg class must be registered as a plug-in with Oracle Identity Manager.

The following example shows a sample data set for provisioning the Active Directory (AD) resource, in which prepopulation is used:

<?xml version="1.0" encoding="UTF-8"?>
<request-data-set xmlns="http://www.oracle.com/schema/oim/request/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.oracle.com/schema/oim/request/" name="ProvisionResourceAD" entity="AD" operation="PROVISION">
<AttributeReference name="Domain" attr-ref="domain" available-in-bulk="true" type="String" length="20" widget="text">
<PrePopulationAdapter classname="oracle.iam.request.DomainPrepopulateAdapter"/>
</AttributeReference>
<AttributeReference name="Login" attr-ref="login" available-in-bulk="true" type="String" length="20" widget="text"/>
<AttributeReference name="Organization" attr-ref="organization" available-in-bulk="true" type="String" length="20" widget="text" required="true">
<PrePopulationAdapter name="org" classname="oracle.iam.request.OrgPrepopulateAdapter"/>
</AttributeReference>
<AttributeReference name="EmployeeType" attr-ref="EmployeeType" available-in-bulk="true" approver-only="true" type="String" length="20" widget="text"
required="true">
</AttributeReference>
<AttributeReference name="Role" attr-ref="role"available-in-bulk="true" type="String" length="20" widget="text"><AttributeReference name="RoleName" attr-ref="role"available-in-bulk="true" type="String" length="20" widget="text" entitlement="true">
</AttributeReference>
<AttributeReference name="Description" attr-ref="description" available-in-bulk="true" type="String" length="20" widget="text">
</AttributeReference>
</AttributeReference>
</request-data-set>

Here, Role is a child form with child attributes RoleName and Description.

The dataset for provisioning AD resource shows that the Organization attribute has a prepopulation adapter associated with it. The organization attribute value will be prepopulated during request creation with the value returned by the prepopulation adapter plug-in.

The value returned by the prepopulate method of the plug-in must be of type corresponding to the type configured in the request dataset. For example, for the Organization attribute listed in the example documented in Child Data, the prepopulate method of OrgPrepopulateAdapter returns a value of type java.lang.String because the type for Organization attribute is configured as String in the dataset.

A.1.3.3.4 The lookupValues Element

The lookupValues element, which is a child element of AttributeReference, is used to define a set of allowable data values for an entity attribute associated with the AttributeReference definition. The attributes of this element are:

decoded-value: This is the data value that is shown to the requester during request creation from UI.
encoded-value: This is the actual data value stored in the request data, and is used for the dataflow. Based on the selected decoded value from the request creation UI, the corresponding encoding value is stored in the request data.

The following sample code snippet shows the AttributeReference that uses lookupValues for the User Type entity attribute:

<AttributeReference name="User Type" attr-ref="Xellerate Type" available-in-bulk="false" type="String" length="30" widget="dropdown" required="true">
<lookupValues encoded-value="End-User Admin" decoded-value="End-User Administrator"/>
<lookupValues encoded-value="Identity" decoded-value="Identity"/>
<lookupValues encoded-value="End-User" decoded-value="End-User"/>
</AttributeReference>

The User Type attribute can have one of the three possible values: End-User Admin, Identity Only, and End-User. But the corresponding decoded values are displayed in the dropdown list to the requester at the time of data collection: End-User Administrator, Identity, and End-User respectively. The encoded value is populated into the mapped entity attribute fields as a part of data flow.

A.1.3.3.5 The lookupQuery Element

This child element of AttributeReference used to derive a set of data value dynamically based on a SQL. Request UI shows all the values based on defined lookupQuery in a lookup widget.

<AttributeReference name="adminlogin" attr-ref="adminlogin" type="String" length="20" widget="lookup-query" available-in-bulk="true">
            <lookupQuery lookup-query="SELECT USR_KEY as UKEY, USR_LOGIN as ULOGIN FROM TEMP_USR where USR_TYPE='$Form Data.admintype'" display-field="ULOGIN" save-field="UKEY"/>
            </AttributeReference>

In this example, user key and user login is queried from a table temp_usr based on a SQL query. Following are the properties of this element:

lookup-query: This property value is a generic SQL query supported by the Oracle Identity Manager database. This query can be dependent on another attribute reference of the same dataset. In the example, there is a reference to '$Form Data.admintype'. This means that the attribute reference 'adminlogin' depends on the attribute reference 'admintype'. The value provided by requester to attribute 'admintype' is used for fetching values for the attribute 'adminlogin' in lookup.
display-field: This property value is one of the alias name from the selected column that needs to be shown to the end-user in the UI attribute, after user selects a value from lookup-widget.
save-field: This property value is one of the alias name from the selected column that needs to be saved internally to the system, after user selects a value from lookup-widget.

The display-field and save-field can be same for an UI attribute.

Note:

In the lookup query, it is mandatory to have aliases for the columns that are used as save-field and display-field.

A.1.3.4 The Attribute Element

As part of request creation, collection of data that does not refer to the underlying entity might be required. The Attribute element can be used to achieve this. An Attribute defined in the request dataset does not require mapping to the underlying entity. These attributes do not require any mapping, and therefore, can be defined in the following way:

<Attribute name="ATTRIBUTE_NAME" length="10" type="integer" widget="text" available-in-bulk="false"/>

The attributes are shown in the request details. These can be viewed by the approver so that these can be used for approval decisions.

The Attribute element is similar to the AttributeReference element with a difference. The Attribute element data values are available only in context of request and cannot take part in dataflow. All other properties available with AttributeReference are also available with attribute, except attr-ref attribute.

A.1.4 Sample Request Dataset

The data that needs to be collected by the request is defined in the request dataset XML file. The following is the sample XML code for the Create User dataset:

<?xml version="1.0" encoding="UTF-8"?>
<request-data-set xmlns="http://www.oracle.com/schema/oim/request/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xsi:schemaLocation="http://www.oracle.com/schema/oim/request/" name="CreateUserDataSet" entity="User" operation="CREATE">
    <DataSetValidator name="CreateUserDataValidator" classname="oracle.iam.requestactions.plugins.datavalidator.CreateUserDataValidator"/>
    <AttributeReference name="First Name" attr-ref="First Name" available-in-bulk="false" type="String" length="80"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="Middle Name" attr-ref="Middle Name" available-in-bulk="false" type="String" length="80"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="Last Name" attr-ref="Last Name" available-in-bulk="false" type="String" length="80"
                widget="text" required="true" mls="false"/>
    <AttributeReference name="User Login" attr-ref="User Login" available-in-bulk="false" type="String" length="256"
                widget="text" required="false"/>
    <AttributeReference name="Password" attr-ref="usr_password" available-in-bulk="false" type="String" length="128"
                widget="text" required="false" masked="true"/>
    <AttributeReference name="Password Generated" attr-ref="Password Generated" available-in-bulk="false" type="Clob" length="1"
                widget="text" required="false"/>              
    <AttributeReference name="Organization" attr-ref="act_key" available-in-bulk="false" type="Long" length="256"
                widget="ENTITY" required="true" entity-type="ORGANIZATION"/>
    <AttributeReference name="User Type" attr-ref="Xellerate Type" available-in-bulk="false" type="Boolean" length="30"
                widget="checkbox" required="false"/>
    <AttributeReference name="Role" attr-ref="Role" available-in-bulk="false" type="String" length="255"
                widget="dropdown" lookup-code="Lookup.Users.Role" required="true"/>
    <AttributeReference name="User Manager" attr-ref="usr_manager_key" available-in-bulk="false" type="Long" length="382"
                widget="ENTITY" required="false" entity-type="USER"/>
    <AttributeReference name="Country" attr-ref="Country" available-in-bulk="false" type="String" length="100"
                widget="text" required="false"/>
    <AttributeReference name="Common Name" attr-ref="Common Name" available-in-bulk="false" type="String" length="240"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="Display Name" attr-ref="Display Name" available-in-bulk="false" type="String" length="382"
                widget="text" required="false" mls="true"/>          
    <AttributeReference name="Department Number" attr-ref="Department Number" available-in-bulk="false" type="String" length="80"
                widget="text" required="false"/>
    <AttributeReference name="Description" attr-ref="Description" available-in-bulk="false" type="String" length="2000"
                widget="text" required="false"/>
    <AttributeReference name="Employee Number" attr-ref="Employee Number" available-in-bulk="false" type="String" length="80"
                widget="text" required="false"/>
    <AttributeReference name="Fax" attr-ref="Fax" available-in-bulk="false" type="String" length="20"
                widget="text" required="false"/>
    <AttributeReference name="Generation Qualifier" attr-ref="Generation Qualifier" available-in-bulk="false" type="String" length="20"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="Home Phone" attr-ref="Home Phone" available-in-bulk="false" type="String" length="20"
                widget="text" required="false"/>
    <AttributeReference name="Hire Date" attr-ref="Hire Date" available-in-bulk="false" type="Date" length="50"
                widget="date" required="false"/>
    <AttributeReference name="Home Postal Address" attr-ref="Home Postal Address" available-in-bulk="false" type="String" length="256"
                widget="text" required="false"/>
    <AttributeReference name="Locality Name" attr-ref="Locality Name" available-in-bulk="false" type="String" length="80"
                widget="text" required="false"/>
    <AttributeReference name="Email" attr-ref="Email" available-in-bulk="false" type="String" length="256"
                widget="text" required="false"/>
    <AttributeReference name="Mobile" attr-ref="Mobile" available-in-bulk="false" type="String" length="20"
                widget="text" required="false"/>
    <AttributeReference name="Pager" attr-ref="Pager" available-in-bulk="false" type="String" length="20"
                widget="text" required="false"/>
    <AttributeReference name="Postal Address" attr-ref="Postal Address" available-in-bulk="false" type="String" length="256"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="PO Box" attr-ref="PO Box" available-in-bulk="false" type="String" length="20"
                widget="text" required="false"/>
    <AttributeReference name="Postal Code" attr-ref="Postal Code" available-in-bulk="false" type="String" length="30"
                widget="text" required="false"/>
    <AttributeReference name="usr_locale" attr-ref="usr_locale" available-in-bulk="false" type="String" length="80"
                widget="text" required="false"/>
    <AttributeReference name="State" attr-ref="State" available-in-bulk="false" type="String" length="80"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="Street" attr-ref="Street" available-in-bulk="false" type="String" length="80"
                widget="text" required="false"/>
    <AttributeReference name="Telephone Number" attr-ref="Telephone Number" available-in-bulk="false" type="String" length="20"
                widget="text" required="false"/>
    <AttributeReference name="Title" attr-ref="Title" available-in-bulk="false" type="String" length="80"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="Initials" attr-ref="Initials" available-in-bulk="false" type="String" length="10"
                widget="text" required="false"/>
    <AttributeReference name="Start Date" attr-ref="Start Date" available-in-bulk="false" type="Date" length="50"
                widget="date" required="false"/>
    <AttributeReference name="End Date" attr-ref="End Date" available-in-bulk="false" type="Date" length="50"
                widget="date" required="false"/>
    <AttributeReference name="LDAP Organization Unit" attr-ref="LDAP Organization Unit" available-in-bulk="false" type="String" length="80" 
                widget="text" required="false" mls="false"/>
    <AttributeReference name="LDAP Organization" attr-ref="LDAP Organization" available-in-bulk="false" type="String" length="80"
                widget="text" required="false" mls="false"/>
    <AttributeReference name="usr_timezone" attr-ref="usr_timezone" available-in-bulk="false" type="String" length="100"
                widget="text" required="false" mls="false"/>
 
        <AttributeReference name="Number Format" attr-ref="Number Format" available-in-bulk="false" type="String" length="30"
                widget="dropdown" lookup-code="Lookup.Users.NumberFormat"  required="false" mls="false"/>
    <AttributeReference name="Currency" attr-ref="Currency" available-in-bulk="false" type="String" length="20"
                widget="dropdown"  lookup-code="Lookup.Users.Currency"  required="false" mls="false"/>
    <AttributeReference name="Date Format" attr-ref="Date Format" available-in-bulk="false" type="String" length="20"
                widget="dropdown"  lookup-code="Lookup.Users.DateFormat"  required="false" mls="false"/>
        <AttributeReference name="Time Format" attr-ref="Time Format" available-in-bulk="false" type="String" length="20"
                widget="dropdown" lookup-code="Lookup.Users.TimeFormat"  required="false" mls="false"/>
    <AttributeReference name="Embedded Help" attr-ref="Embedded Help" available-in-bulk="false" type="String" length="10"
                widget="dropdown" lookup-code="Lookup.Users.EmbeddedHelp" required="false" mls="false"/>
    <AttributeReference name="Font Size" attr-ref="Font Size" available-in-bulk="false" type="String" length="10"
                widget="dropdown" lookup-code="Lookup.Users.FontSize" required="false" mls="false"/>
    <AttributeReference name="Color Contrast" attr-ref="Color Contrast" available-in-bulk="false" type="String" length="10"
                widget="dropdown" lookup-code="Lookup.Users.ColorContrast" required="false" mls="false"/>
    <AttributeReference name="Accessibility Mode" attr-ref="Accessibility Mode" available-in-bulk="false" type="String" length="20"
                widget="dropdown" lookup-code="Lookup.Users.AccessibilityMode" required="false" mls="false"/>
    <AttributeReference name="FA Language" attr-ref="FA Language" available-in-bulk="false" type="String" length="100"
                widget="text" required="false"/>
    <AttributeReference name="FA Territory" attr-ref="FA Territory" available-in-bulk="false" type="String" length="100"
                widget="text" required="false"/>
    <AttributeReference name="User Name Preferred Language" attr-ref="User Name Preferred Language" available-in-bulk="true" type="String" length="20" widget="lookup-query" required="false">
        <lookupQuery lookup-query="select mls_locale_code as USR_NAME_PREFERRED_LANG from mls_locale where ( locale_flag=0 OR locale_flag=1 ) order by mls_locale_code asc" display-field="USR_NAME_PREFERRED_LANG" save-field="USR_NAME_PREFERRED_LANG"/>
    </AttributeReference>
 
    <Attribute name="Roles   " available-in-bulk="false" type="Clob" length="2048" widget="text" required="false"/>
    <Attribute name="Policy Name" available-in-bulk="false" type="Clob" length="1024" widget="text" required="false"/>
    <Attribute name="RequestorID" available-in-bulk="false" type="Clob" length="1024" widget="text" required="false"/>
    <Attribute name="FAOpData" available-in-bulk="false" type="Clob" length="4096" widget="text" required="false" />
</request-data-set>

A.1.5 Child Data

You might need attributes to store multiple values or attributes that are made up of other attributes. To do so, you can configure one or more child attributes. For example, an Email ID attribute of an entity type User needs to store multiple values. Therefore, you can configure it in the request dataset in the following way:

<Attribute name="Email">
      <Attribute name="ID" length="20" type="string" widget="text" /> 
</Attribute>

You might also require an attribute to be composed of multiple attributes. For example, a Oracle Apps User Responsibilities attribute needs to be made up of three attributes: Responsibility Start Date, Responsibility End Date, and Responsibility Name. You can configure this attribute in the request data set in the following way:

<AttributeReference name="Oracle Apps User Responsibilities" attr-ref="UD_RESPONS" type="String" length="20" widget="text" available-in-bulk="true">
    <AttributeReference name="Responsibility Start Date" attr-ref="Responsibility Start Date" type="Date" widget="date" required="false" available-in-bulk="true" length="100" />
    <AttributeReference name="Responsibility End Date" attr-ref="Responsibility End Date" type="Date" widget="date" required="false" available-in-bulk="true" length="100" />
    <AttributeReference name="Responsibility Name" attr-ref="Responsibility Name" type="String" length="30" widget="lookup" required="false" available-in-bulk="true" lookup-code="Oracle.Responsibility.Name" primary="true"/>.

</AttributeReference>

Here, the association of Responsibility Start Date, Responsibility End Date, and Responsibility Name are maintained and the three attributes together constitute a value of the Oracle Apps User Responsibilities child attribute.

Note:

Only one level of child attributes are supported in Oracle Identity Manager. Therefore, in the example, the Responsibility Start Date, Responsibility End Date, or Responsibility Name attributes cannot be composed of other attributes. Similarly, attribute references cannot have child attributes.
The values for AttributeReference name and attr-ref must be the same for child table attributes. For instance, in the Oracle Apps User Responsibilities attribute example in this section, the value for both AttributeReference name and attr-ref is Responsibility Start Date.

During request creation, child data is shown in a table and child data can added from a popup window. In this scenario, the requester might want to add multiple responsibilities with same start date and end date. You can allow the requester to select multiple responsibilities with same start date and end date by specifying the Responsibility Name as primary.

The primary property allows the requester to select multiple values to the Responsibility Name attribute in the window displayed when the requester tries to add a child row. For the Responsibility Start Date and Responsibility End Date attributes, only single value can be provided. With this multiple rows will be added to the child table one for each responsibility name selected with same value of start date and end date.

The following example shows the sample XML code for a request dataset for provisioning an E-Business resource:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request-data-set
    xmlns = "http://www.oracle.com/schema/oim/request/"
    xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
    operation = "PROVISION"
    entity = "eBusiness Suite User"
    name = "ProvisionResourceeBusiness Suite User"
    xsi:schemaLocation = "http://www.oracle.com/schema/oim/request/">
    <AttributeReference
        itresource-type = "eBusiness Suite UM"
        available-in-bulk = "true"
        required = "true"
        length = "20"
        widget = "itresource-lookup"
        type = "Long"
        attr-ref = "EBS Server"
        name = "EBS Server"/>
    <AttributeReference
        available-in-bulk = "true"
        length = "240"
        widget = "text"
        type = "String"
        attr-ref = "Description"
        name = "Description"/>
      <AttributeReference
        available-in-bulk = "false"
        length = "240"
        widget = "text"
        type = "String"
        attr-ref = "Email"
        name = "Email"/>
      <AttributeReference
        available-in-bulk = "true"
        length = "80"
        widget = "text"
        type = "String"
        attr-ref = "Fax"
        name = "Fax"/>
<AttributeReference
        available-in-bulk = "false"
        length = "256"
        widget = "text"
        type = "String"
        attr-ref = "SSO User ID"
        name = "SSO User ID"/>
    <AttributeReference
       available-in-bulk = "false"
        length = "30"
        widget = "text"
        type = "String"
        attr-ref = "Person ID"
        name = "Person ID"/>
 <AttributeReference
        available-in-bulk = "true"
        length = "10"
        widget = "text"
        type = "String"
        attr-ref = "UD_EBS_RESP"
        name = "eBusiness Suite Responsibilities">
        
        <AttributeReference
            name = "Application Name"
            attr-ref = "Application Name"
            type = "String"
            length = "256"
            widget = "lookup-query"
            available-in-bulk = "true"
            required = "true">
            <lookupQuery
                lookup-query = "select lkv_encoded as Value,lkv_decoded as Description from lkv lkv, lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.EBS.Application' and instr(lkv_encoded,concat('$Form data.EBS Server', '~'))>0"
                display-field = "Description"
                save-field = "Value"/>
        </AttributeReference>
        <AttributeReference
            name = "Responsibility Name"
            attr-ref = "Responsibility Name"
            type = "String"
            length = "256"
            widget = "lookup-query"
            available-in-bulk = "true"
            required = "true"
            primary = "true">
            <lookupQuery
                lookup-query = "select lkv_encoded as Value,lkv_decoded as Description from lkv lkv,lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.EBS.Responsibility' and instr(lkv_encoded,concat('$Form data.Application Name','~'))>0"
                display-field = "Description"
                save-field = "Value"/>
        </AttributeReference>
<AttributeReference
            available-in-bulk = "true"
            length = "20"
            widget = "date"
            type = "Date"
            attr-ref = "Effective Start Date"
            name = "Effective Start Date"/>
    </AttributeReference>
<AttributeReference
        available-in-bulk = "true"
        length = "10"
        widget = "text"
        type = "String"
        attr-ref = "UD_EBS_RLS"
        name = "eBusiness Suite User Role Grants">
         <AttributeReference
            name = "Application Name"
            attr-ref = "Application Name"
            type = "String"
            length = "256"
            widget = "lookup-query"
            available-in-bulk = "true"
            required = "true">
            <lookupQuery
                lookup-query = "select lkv_encoded as Value,lkv_decoded as Description from lkv lkv, lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.EBS.Application' and instr(lkv_encoded,concat('$Form data.EBS Server', '~'))>0"
                display-field = "Description"
                save-field = "Value"/>
        </AttributeReference>
        <AttributeReference
            name = "Role Name"
            attr-ref = "Role Name"
            type = "String"
            length = "256"
            widget = "lookup-query"
            available-in-bulk = "true"
            required = "true"
           primary = "true">
            <lookupQuery
                lookup-query = "select lkv_encoded as Value,lkv_decoded as Description from lkv lkv,lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.EBS.UMX.Roles' and instr(lkv_encoded,concat('$Form data.Application Name','~'))>0"
                display-field = "Description"
                save-field = "Value"/>
        </AttributeReference>
<AttributeReference
            available-in-bulk = "true"
            length = "20"
            widget = "date"
            type = "Date"
            attr-ref = "Start Date"
            name = "Start Date"/>
    </AttributeReference>
</request-data-set>

In the sample XML code for provisioning an E-Business resource dataset:

The Oracle Apps User Responsibilities attribute is defined as a parent attribute for the Responsibility Start Date, Responsibility End Date, and Responsibility Name child attributes. Users can specify one or more values the Oracle Apps User Responsibilities. In request creation UI, this is shown as a table with header "Oracle Apps User Responsibilities" and with the Responsibility Start Date, Responsibility End Date, and Responsibility Name columns.

For the parent attribute, value of attr-ref should be the child table name in the process form. In this example it is "UD_RESPONS".

The Responsibility Start Date, Responsibility End Date, and Responsibility Name attributes are the columns of the child table "UD_RESPONS".

For the child attributes, the attr-ref value must be the Field Label value in the child table of the process form.

Oracle Identity Manager allows you to define a child process form and associates it to a parent process form for a resource. The attributes in the parent form are modeled as attribute references in the request dataset. The attributes in the child form are modeled as attribute references in the child data.

Consider the example of a request based on the Provision Resource request model for a E-Business resource. The following table shows details of the parent process form definition along with child process form details:

Child Form Attribute Name

UD_RESPONS

Responsibility Start Date

Responsibility End Date

Responsibility Name

See above example for the Provision E-Business Resource request dataset.
For AttributeReference name="Server", the value of widget is specified as itresource-lookup. This indicates that for the Server field, a lookup with available IT resource parameters will be available to the user. If widget="itresource-lookup", then a value for the itresource-type element must be specified. For example, itreource-type="EBIZServer" indicates that for the Server lookup field, all the IT resource parameters for the EBIZServer IT resource type must be available for selection. User can search and select an it resource instance by using this lookup.

Note:

IT resource type is a template for all IT resource definitions associated with the connector. An IT resource type specifies the parameters that are common to all IT resource instances, such as host servers and computers, of that particular IT resource type. See Managing Connector Lifecycle for more information about IT resources and IT resource types.

Child Form	Attribute Name
UD_RESPONS	Responsibility Start Date
	Responsibility End Date
	Responsibility Name

A.1.6 Common Request Dataset

Oracle Identity Manager has a default dataset that is common for all the resources. The common request dataset defines an attribute that is common to all the resources.

ResourceCommonDataset is the default common dataset that is common for all the resources. This defines the Service Account attribute, which is common across all resources.

As a result, even if the selected resource does not have a dataset, the attribute from the common dataset is shown in request data collection during request creation. During the request data collection, attributes from both common dataset and the resource specific dataset are shown. In other words, the request collection data is a union of the common dataset and the dataset associated with the entity.

Note:

The common request dataset is shipped with Oracle Identity Manager, and it cannot be customized.

A.1.7 Configuring Localized Values for Request Datasets

All default request datasets have translations for dataset attributes. But for custom request datasets that you create, localization for those dataset attributes must be added to custom resource bundles.

This section describes the configuration of localized values for request datasets and dataset attributes in the following sections:

A.1.7.1 Localization for Request Dataset Attributes

This section describes the conventions for enabling localization support for dataset attributes. As an example, the CreateUserDataSet.xml defines the role attribute as follows:

<AttributeReference name="Role" attr-ref="Role" available-in-bulk="false" type="String" length="20" widget="dropdown" lookup-code="Lookup.Users.Role" required="true"/>

The translation for this attribute is configured as:

request.dataset.User.Role=USER_TYPE

Here, request.dataset.User.Role is the translation key, and USER_TYPE is the actual translation or translation value. Framing the translation key decides the actual translation. Any translation key that is related to request dataset attributes must start with request.dataset. This is followed by an object name, such as an entity type, entity subtype if present, parent attribute name if present, attribute name, and predefined value for attribute. The types of translation keys are divided into the following categories:

A.1.7.1.1 Request Dataset Attributes for Nongeneric Request Models

The translation key for request datasets of nongeneric request models must not contain an entity subtype because as it is not present in the dataset. For example, the Role attribute in CreateUserDataSet.xml is defined as follows:

<AttributeReference name="Role" attr-ref="Role" available-in-bulk="false" type="String" length="20" widget="dropdown" lookup-code="Lookup.Users.Role" required="true"/>

The translation key is:

request.dataset.User.Role

Here:

request.dataset is the fixed string that must be present at the beginning of any dataset attribute.
User corresponds to the entity type. This must be same as the entity-type property of request-model element in the CreateUserRequestModel.xml file. It can be Resource or Role depending on the request model.
Role corresponds to the actual attribute for which translation is being added. This corresponds to the name property of the Role attribute reference in the dataset.

A.1.7.1.2 Request Dataset Attributes for Generic Request Models

The translation key for request datasets of generic request models must contain entity subtype. For example, for EBS Server attribute in ProvisionResourceeBusiness Suite User.xml, the following must be defined:

<AttributeReference name="EBS Server" attr-ref="EBS Server" type="Long" widget="itresource-lookup" required="true" available-in-bulk="true" itresource-type="eBusiness Suite UM" length="40"/>

The translation key is:

request.dataset.Resource.eBusiness\ Suite\ User.EBS\ Server=EBS Server

Here:

request.dataset is the fixed string that must be present at the beginning of any dataset attribute.
Resource corresponds to the entity type in the ProvisionResourceRequest.xml file.
eBusiness\ Suite\ User is the entity subtype, which is the same as entity property of request-data-set element in ProvisionResourceeBusiness Suite User.xml. This is optional and is present in this example because the Provision Resource request model is of generic type.
EBS\ Server corresponds to the actual attribute for which translation is being added. This corresponds to name property of EBS Server attribute reference in the dataset.

A.1.7.1.3 Child Attributes

For child attributes, the translated key additionally contains the parent attribute name that is necessary to uniquely identify the attribute. For example, the Application Name attribute in ProvisionResourceeBusiness Suite User.xml, as shown:

<AttributeReference available-in-bulk="true" length="10" widget="text" type="String" attr-ref="UD_EBS_RESP" name="EBS_RSO">
    <AttributeReference name="Application Name" attr-ref="APPLICATION_NAME" type="String" length="256" widget="lookup-query" available-in-bulk="true" required="true"> 
        <lookupQuery lookup-query="select lkv_encoded,lkv_decoded from lkv lkv, lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.EBS.Application' and instr(lkv_encoded,concat('$Form data.EBS Server', '~'))>0" display-field="lkv_decoded" save-field="lkv_encoded"/>
                 </AttributeReference>
</AttributeReference>

APPLICATION_NAME is a child attribute of EBS_RSO attribute. The translation key for APPLICATION_NAME consists of:

request.dataset.Resource.eBusiness\ Suite\ User.EBS_RSO.Application\ Name = APPLICATION_NAME
request.dataset is the fixed string that must be present at the beginning of any dataset attribute.
Resource corresponds to the entity type in the ProvisionResourceRequest.xml file.
eBusiness\ Suite\ User is the entity property of request-data-set element in ProvisionResourceeBusiness Suite User.xml . This is also referred as entity subtype. This is optional and is present in this example because Provision Resource request model is of generic type.
EBS_RSO is the parent attribute of Effective Start Date attribute, which identifies it uniquely. This corresponds to the name property of EBS_RSO attribute reference.
Application\ Name corresponds to the actual attribute for which translation is being added. This corresponds to the name property of APPLICATION_NAME attribute reference.

A.1.7.1.4 Predefined Values for Attributes

You can have attributes that have predefined set of values, such as lookup values or lookup-code values. Translations can be added for these values as well because these values are displayed on the user interface. The translation key for this type of value is similar to that of child attributes. For example, the Role attribute in the CreateUserDataSet.xml request dataset has predefined set of values, including Employee, Full-Time Employee, and Part-Time Employee. These values are displayed as drop-down in the UI for Create User Request. These values are predefined by configuring a Lookup Definition with code Lookup.Users.Role. This is specified as lookup-code="Lookup.Users.Role" in the Role AttributeReference, as shown in the following example:

<AttributeReference name="Role" attr-ref="Role" available-in-bulk="false" type="String" length="20" widget="dropdown" lookup-code="Lookup.Users.Role" required="true"/>

Translation for Employee value of Role attribute is:

request.dataset.User.Role.LOV.Employee=Employee

Here:

request.dataset is the constant part which must be prefixed to every dataset attribute.
User corresponds to the entity type.
Role corresponds to the actual attribute for which Employee is a predefined value. This corresponds to name property of Role AttributeReference in the dataset.
LOV is to be added to specify that the string following LOV is the predefined value for Role.
Employee is the predefined value for which the translation is being added. This must be the value in Decode column of lookup definition.

Note:

The lookup definitions have Code Key and Decode columns. For example, Code Key = EMP, Decode=Employee.

The attributes in the default request datasets are already present. However, if you want to add any new attributes to the dataset, then you can also add translations for these attributes in the same way as described in this section, depending on which category they fall into.

A.1.7.2 Localization of Column Names in LookupQuery for Dataset Attributes

In request datasets, there might be attributes that are of type lookup-query. For example:

<AttributeReference name="Application Name" attr-ref="APPLICATION_NAME" type="String" length="256" widget="lookup-query" available-in-bulk="true" required="true"> 
        <lookupQuery lookup-query="select lkv_encoded as Application Key,lkv_decoded as Application Name from lkv lkv, lku lku where lkv.lku_key=lku.lku_key and lku_type_string_key='Lookup.EBS.Application'" display-field="APPLICATION_NAME" save-field="APPLICATION_KEY"/>
</AttributeReference>

The columns mentioned in the query are displayed on the UI in a data collection step during request creation. You can localize the lkv_encoded and lkv_decoded column names by adding the column aliases as keys in resource bundle. For example, in the above query, Application Key and Application Name are the aliases for lkv_encoded and lkv_decoded columns respectively. They can be localized by adding translation to custom resource bundles, as follows:

Application\ Key=APPLICATION_KEY

Application\ Name=APPLICATION_NAME

A.2 Step 2: Uploading Request Datasets into MDS

After creating a request dataset XML file, it must be uploaded to MDS, which can be done by using the MDS import/export utility tools provided by Oracle Identity Manager. When the upload is done, request engine loads the dataset during request creation, the attribute references and attributes are shown in data collection step. Similarly, you can delete or export any dataset file from MDS repository by using similar tools.

To upload the request datasets to MDS:

Note:

The dataset must be updated from time to time based on the resource requirement changes.
For updating an existing dataset, make sure that there are no pending requests that use that dataset.

The metadata_from_loc property in the weblogic.properties file specifies the top-level directory from which to import XML files. Create a subdirectory to keep the request datasets in, and copy the dataset into this directory. It is recommended that you create a subdirectory structure such as /custom/RESOURCE_NAME. For example, if the metadata_from_loc property is set to /scratch/datasets/upload and you are creating a dataset for the EBS resource, then the dataset is to be placed in the /scratch/datasets/upload/custom/EBS/ directory.

Note:

Make sure that this directory contains only the required datasets and no other files.

Go to the OIM_HOME/bin directory and run weblogicImportMetadata.sh or weblogicImportMetadata.bat script. To do so, set up the environment for the MDS utilities as follows:

Set the OIM_ORACLE_HOME environment variable to the Oracle Identity Management Oracle home directory inside the Middleware home directory. For example, for Microsoft Windows, set the OIM_ORACLE_HOME environment variable to C:\Oracle\Middleware\Oracle_IDM1\ directory.
Set the necessary properties in the weblogic.properties file, which is located in the same folder as the utilities.

Table A-3 Parameters in the Properties File

Property Name	Description	Notes
wls_servername	Name of the Oracle WebLogic Server on which Oracle Identity Manager is deployed
application_name	The application name	Value is: `oim` if importing/exporting an out-of-the-box event handler. `OIMMetadata` for customizable metadata. If importing or exporting custom data, set application_name to `OIMMetadata`.
metadata_from_loc	Directory location from which an XML file should be imported. This property is used by weblogicImportMetadata.sh script.	Microsoft Windows paths include // as file or directory separator.
metadata_to_loc	Directory location to which an XML file should be exported. This property is used by the weblogicExportMetadata.sh script.	Microsoft Windows paths include // as file or directory separator.
metadata_files	Full path and name of an XML file. This property is used by weblogicExportMetadata.sh and weblogicDeleteMetadata.sh scripts.	For example, you may specify /file/User.xml to export a user entity definition. You can indicate multiple xml files as comma-separated values.

Using the Import utility: When you run the weblogicImportMetadata.sh utility, all files specified in metadata_from_loc will be imported.

For example, you want to import User.xml which exists in /scratch/johnny/temp/oim/file/User.xml. You must define metadata_from_loc as /scratch/johnny/temp/oim.

WARNING:

Make sure no other files exist in the directory specified by metadata_from_loc or its subdirectories. The import utility tries to recursively import all the files under the directory.

All the Import, Export, and Delete utilities are located in the OIM_ORACLE_HOME/server/bin/ directory.
Using the Export utility: When you run the weblogicExportMetadata.sh utility, the files specified in metadata_files will be exported to the folder specified by metadata_to_loc.

Note:

If the file name contains spaces, then you must specify the file name as is, without quotes or any escape characters. For example, to export a file named ProvisionResourceeBusiness Suite User.xml, where the path is /db/ProvisionResourceeBusiness Suite User.xml, you must specify the metadata files property as follows:

metadata_files=/db/ProvisionResourceeBusiness Suite User.xml
Using the Delete utility: When you run the weblogicDeleteMetadata.sh utility, the files specified in metadata_files will be deleted from MDS.

Note:

If the file name contains spaces, then you must specify the file name as is, without quotes or any escape characters. For example, to delete a file named ProvisionResourceeBusiness Suite User.xml, where the path is /db/ProvisionResourceeBusiness Suite User.xml, you must specify the metadata files property as follows:

metadata_files=/db/ProvisionResourceeBusiness Suite User.xml

A.3 Step 3: Creating SOA Composites Required for Approval

The primary goal of any provisioning system is to manage requests submitted by users and provision resources to users. Request completion involves execution of associated approval processes. These approval processes are deployed as Service Oriented Architecture (SOA) composites running on the SOA Server. Request service is responsible for execution and management of such approval processes.

This section contains the following topics:

A.3.1 Using SOA Composites for Approval

The interaction between Oracle Identity Manager and SOA Server is explained in the following steps:

The user creates a request by using the Oracle Identity Manager Self Service. The request can be of any one of all the request types supported by Oracle Identity Manager.
Request service evaluates the approval policy, and the SOA composite to be instantiated is selected.

Note:

The composites must be registered with Oracle Identity Manager in order for them to be kicked off when the request is submitted. For information about registering workflows with Oracle Identity Manager, see "Step 4: Registering the SOA Composites in Oracle Identity Manager".
Request service contacts SOA Server to instantiate the selected SOA composite. Instantiates selected composite instance on SOA server.
SOA composite run starts and human approval task is assigned for approval.
The approver logs in to the Task List in the Oracle Identity Manager Self Service console, and approves the request.
After the approval, the composite instance run is completed, which is notified to the request service.
Request service moves the request to the next stage.

Oracle Identity Manager provides a few predefined SOA composites. However, you can define your own composites and use them in request approvals.

To use a SOA composite as an approval process, it must adhere to certain standards. These standards ensure that the request service is able to instantiate and manage such composites correctly. These standards are:

The following attributes are mandatory for BPEL process:
- RequestID of type String
- RequestModel of type String
- RequestTarget of type String
- URL of type String
- RequesterDetails of XML Element
- BeneficiaryDetails of XML Element
- ObjectDetails of XML Element
- OtherDetails of XML Element
The RequestID, RequestModel, RequestTarget, and URL attributes are always set with valid values for all types of requests.

RequesterDetails is an XML element. This element is filled up with valid values for all requests that requires authentication. Requester details is empty for the requests of type Self-Register User because the requester is anonymous user.

BeneficiaryDetails is an XML element. This element is filled up with valid values for all requests that have a beneficiary, for example, Provision Resource and Assign Roles. This is filled up only if the request is associated with single beneficiary. If the request is associated with multiple beneficiaries, then BeneficiaryDetails is empty. BeneficiaryDetails element always has valid value for simple requests and child requests that have a beneficiary. Therefore, it is recommended to use this XML element in SOA composites that are used as approval processes at the operational level of approval. This is because at the operational level of approval, the request is associated with only one beneficiary.

ObjectDetails is an XML element. This element is filled up with valid values for all requests that are associated with the Resource entity. This is filled up only if the request is associated with single resource. If the request is associated with multiple resources, then ObjectDetails is empty. The ObjectDetails element always has valid value for simple and child requests that are associated with resource. Therefore, it is recommended to use this XML element in SOA composites that are used as approval processes at the operational level of approval. This is because at the operational level of approval, the request is associated with only one resource.
All the attributes that are mandatory for the BPEL process are referred from RequestDetails.xsd and ApprovalProcess.xsd. These files are present in the template SOA composite, which must not de modified or deleted.

A.3.2 Creating a SOA Composite

Oracle Identity Manager provides a helper utility for creating custom SOA composites. This utility creates a template SOA project that adheres to all the necessary standards. This utility is located in the OIM_HOME/workflows/new-workflow directory.

Note:

JAVA_HOME environment variable must be set before running this utility.
This utility requires Apache Ant version 1.7 or later.

To create a custom SOA composite by running the helper utility:

Run the following commands:

cd OIM_HOME/workflows/new-workflow
ant -f new_project.xml

Enter the JDeveloper application name when the following prompt is displayed:

Please enter application name
Enter the JDeveloper project name when the following prompt is displayed:

Please enter project name
Enter the name of the ADF binding service for the composite when the following prompt is displayed:

Please enter the service name for the composite. This needs to be unique across applications

The new application is created in the OIM_HOME/workflows/new-workflow/process-template/ directory. You can open the new application in JDeveloper for modification.

Human task in the template SOA composite is configured to send notifications to the assignee of the human task. In the custom composite that is created, the notification message can be modified based on the requirement. All the notifications to be sent to the approver must be configured in the SOA composite. For configuring Oracle SOA server to send notifications, see Installing and Configuring SOA and User Messaging Service in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Human task in the template SOA composite is configured to be assigned to the SYSTEM ADMINISTRATORS role.

A.4 Step 4: Registering the SOA Composites in Oracle Identity Manager

Note:

If the communication to Oracle Identity Manager is through the SSL mode, then you must perform the following prerequisites for communication to Oracle Identity Manager through SSL mode:

Set the TRUSTSTORE_LOCATION environment variable, where TRUSTSTORE_LOCATION is the trusted key store file location.
Use t3s protocol instead of t3. For example, the URL for Oracle Identity Manager is:

t3s://HOST_NAME:PORT

The SOA composite must be registered with Oracle Identity Manager before it can be used as an approval process. To register a SOA composite with Oracle Identity Manager:

Create the COMPOSITE_NAME.props property file in the OIM_HOME/workflows/registration/ directory with the following content:
```
name=COMPOSITE_NAME
category=Approval
providerType=BPEL
serviceName=REQUEST_APPROVAL_SERVICE
domainName=DOMAIN
version=REVISION_ID
payLoadID=PAYLOAD
operationID=OPERATION_ID
listOfTasks=HUMAN_TASK_NAMES
```
Where:
- Replace COMPOSITE_NAME with the name of the SOA composite as specified in the composite.xml file.
- Replace REQUEST_APPROVAL_SERVICE with the name of the service exposed in the composite. This service is invoked while instantiating the composite for approval.
- Replace OPERATION_ID with the name of operation to be invoked on the service mentioned for the serviceName property.
- Replace PAYLOAD with the part name of the operation specified as the value of the operationID property.
- Replace REVISION_ID with the SOA composite revision as specified in the composite.xml file.
- Replace DOMAIN with name of SOA partition in which the composite is deployed. By default, SOA has one partition named default.
- Replace HUMAN_TASK_NAMES with the names of the approval tasks associated with the SOA composite. Separate the names with colon (:).
  
  Note:
  
  Do not add any extra spaces in the properties file.
Run the following command from the OIM_HOME/workflows/registration/ directory:
Note:
- JAVA_HOME environment variable must be set before running this utility.
- This utility requires Apache Ant version 1.7 or later.
```
ant -f registerworkflows-mp.xml register
```
Enter Oracle Identity Manager administrator username when prompted.
Enter Oracle Identity Manager administrator password when prompted.

Note:

When you login to the SOA server by using the Oracle Identity Manager administrator credentials, the login attempt fails if your challenge questions and answers and password are not reset in Oracle Identity Manager. You must reset the challenge questions and answers and password when you first login to Oracle Identity Manager.
Enter Oracle Identity Manager server t3 URL when prompted.
Enter the complete path of the property file name that you created in Step 1 when prompted.

A.5 Step 5: Defining Request Approvals

A request goes through multiple approvals before it is executed. After the request is submitted, it must obtain approvals at different levels. Approvals are controlled and configured by a set of approval policies.

An approver is able to view the request data. Approver cannot change the data provided by the requester. Approver can only provide data for the attributes that are set as approver-only="true" in the request dataset.

This section describes the following topics:

A.5.1 Approval Workflows

After a request is submitted, if any approval needs to be initiated, then the request service starts the workflow process in the backend workflow engine. Oracle SOA is used as workflow engine by the request service.

SOA server hosts SOA composites and human workflow. The integration of the request service and SOA can be explained with the help of configuring-requests.htm#GUID-638F3446-E4BF-4EC7-B2AD-B3F5F8F6DD03__CIHJICEI:

Figure A-1 Request Service and SOA Integration

Description of "Figure A-1 Request Service and SOA Integration"

The following process describes how Oracle SOA works with request service for selecting an approval workflow:

A request is created by using the request management UI, which is Oracle Identity Manager Self Service or Advanced Administration.
When the request is submitted, the request engine calls the SOA composites that are deployed in Oracle SOA.

Note:

Oracle SOA is independent of Oracle identity Manager. The backend Business Process Execution Language (BPEL) service invokes the approval workflow. In addition to the default BPEL workflows shipped with Oracle Identity Manager, you can define your own workflows in BPEL based on your requirement. For information about customizing the BPEL workflows, see Getting Started with Oracle BPEL Process Manager in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Oracle SOA determines whom to assign the request by using the SOA composite logic through Java Platform Security (JPS). Oracle SOA uses the same set of users and roles as in Oracle Identity Manager. This is enabled by the Oracle Identity Manager database provider.
Oracle SOA assigns the task to the assignee based on the information provided by the DB provider.
The list of assigned tasks to the logged in user and role is displayed in the TaskList UI.
Using the TaskList, the approver approves or rejects the requests.
The approval outcome is send back to the request engine through SOA.
If a request has been approved, then the next action is determined based on the request type, beneficiary, or associated resource. If a request has been rejected, then the request processing stops.

After the task is assigned, the user can login to the TaskList UI in Oracle Identity Manager Self Service to get a consolidated view of Human tasks and Oracle Identity Manager requests.

TaskList uses the task query service APIs to communicate with Oracle SOA. These APIs are provided by Oracle SOA server. Oracle Identity Manager uses the SOAP or RMI protocol to communicate with Oracle SOA based on the configuration. RMI is the default protocol.

A.5.2 Approval Levels

Each request may need to go through three levels of approvals: template-level, request-level, and operation-level. SOA composites must be registered with Oracle Identity Manager in order to use those as approval processes in Oracle Identity Manager. Registering means letting Oracle Identity Manager know what approval processes are deployed and can be used at run time.

The approval levels are described in the following sections:

A.5.2.1 Template-Level Approval

These are the approvals defined at the request templates. Each template can define additional approvals on top of what is defined by the approval policy configuration. At this level, either the complete request is approved or rejected. For bulk requests, there is no partial approval or rejection. Each template can define an optional approval process that must be initiated at the template level. If no approval process is defined in the template, then the template level is auto approved.

Note:

Request-level and operation-level approval are associated with approval policies. For template-level approval, there are no approval policies associated. The approval processes are defined at the template and are run directly, without an association with approval policies.

An example of template-level approval can be the approval required by an HR representative for the user creation of all contract employees in addition to the approval required from the employees' managers and IT administrators. The additional approval from the HR representative can be configured as an approval process while creating a template. The template can be used to create and submit the request.

Note:

This level of approval is not required for child requests.

A.5.2.2 Request-Level Approval

These are the approval for the entire request. These are based on the approval policy configuration.

An example of request-level approval is the approval required by the requestor's manager when a request is raised to provision a laptop to a user.

Approval process that needs to be used for the request-level approval for a request is determined by the approval policies defined at the request level. If no approval policies are defined for the request level for the given type of request, then the default request approval process is used. By default, all the request-level approval are assigned to the administrator. Therefore, the default configuration is secure. If multiple approval policies exist, then the approval policy rules are evaluated in the order of approval policy priority to figure out the appropriate approval policy. The approval policy rules indicate the request engine which approval process to pick up for the particular approval. The request engine selects the approval process defined in the approval policy that is selected based on the approval policy rule evaluation.

For example, when a request to create a user is submitted, the approval policy selection methodology finds out how many approval policies exist for the Create User request model in the order of priority. The approval policy rule for the highest approval policy priority is evaluated. An example of approval policy rule is that manager's first name and last name must be John and Doe respectively. If the approval policy rule for the highest priority does not match, then the approval policy rule for the next approval policy priority is evaluated. When the first approval policy rule matches the criteria specified in the approval policy, the corresponding approval process for that approval policy is selected for that request at the request level. If all the approval policy rules do not match, then the default approval process for the request level is selected.

Note:

Request-level approval is not required for child requests because the bulk request is broken down to child requests after successful approval of the bulk request at the request level.
The Self-Register User request template has organization as the approver-only attribute. Therefore, any approval policy associated with this template must not have auto-approval set at request-level because the attribute is mandatory and must be provided by the approver.

A.5.2.3 Operation-Level Approval

These are the approvals for the operation being performed by this request type. This level requires approval selection methodology name and parameters to be passed to the methodology. A methodology suggests which approval workflow is to be used for this operation. The request type and scope may also define the methodology-specific parameters that are required for determining the approval process. Scope is a key associated with the types of request types, as shown in configuring-requests.htm#GUID-3002B685-579E-4FD3-95EE-623765003E56__CIHCFBCI:

Table A-4 Request Types and Associated keys

Request Types	Scope
All request types related to the user entity, such as: Create User Self-Register User Modify Self Profile Modify User Profile Delete user Enable User Disable User	organization
All request models related to resources, such as: Provision Resource Modify Provisioned Resource Self-Request Resource Enable Provisioned Resource Disable Provisioned Resource Modify Provisioned Resource Self Modify Provisioned Resource De-provision Resource Self De-Provision Resource	resource
All request types related to the role entity, such as: Assign Roles Remove from Roles	role

Request Types

Scope

All request types related to the user entity, such as:

Create User
Self-Register User
Modify Self Profile
Modify User Profile
Delete user
Enable User
Disable User

organization

All request models related to resources, such as:

Provision Resource
Modify Provisioned Resource
Self-Request Resource
Enable Provisioned Resource
Disable Provisioned Resource
Modify Provisioned Resource
Self Modify Provisioned Resource
De-provision Resource
Self De-Provision Resource

resource

All request types related to the role entity, such as:

Assign Roles
Remove from Roles

role

Note:

For the Create Role, Modify Role, and Delete Role types, the operation-level approval is auto-approved.

For example, based on the scope, for the request of type Provision Resource, you must select the resource to associate the approval policy at operation level at the time of approval policy creation. Similarly, for a Create User request type, you must select an organization, and for the Assign Roles request type, you must select a role at the operation level during approval policy creation.

The approval policies that you create, along with the approval policy priorities, approval policy rules, and scope, decide which approval process is to be selected for a request at the operation level.

An example of operation-level approval is the approval required by the IT administrator, who is responsible for issuing a laptop to users, after the request-level approval is obtained for provisioning a laptop to a user.

For a bulk request, operation-level approval are required for individual child requests. Each individual child request can be approved or rejected independently. For example, for a provision resource to user request, there can be multiple beneficiaries, multiple resources, or both. Therefore, at the operational level, provisioning of each resource to each user generates a child request, which can be approved or rejected independently.

A.5.3 Creating Approval Policies

Create the required approval policies for selecting appropriate SOA composites for approval. See "Step 5: Defining Request Approvals" for the concepts related to approvals.

To create an approval policy:

In Oracle Identity Manager Advanced Administration, click the Policies tab, and then click Approval Policies. Alternatively, you can click Search Approval Policies under Policies in the Welcome page.
From the Actions menu on the left pane, select Create. You can also start the Create Approval Policy wizard by clicking the icon with the plus (+) sign on the toolbar. The Step 1. Set Approval Policy Details page of the Create Approval Policy wizard is displayed.
Enter values for the following fields, and then click Next:
- Policy Name: Enter a name for the approval policy. This is a mandatory attribute.
- Description: Enter the details about what this approval policy will do.
- Request Type: Select the request type by selecting from the LOV, for example, Assign Roles. This is a mandatory attribute.
- Level: Select the approval level that you want to implement for this approval policy. This is a mandatory attribute.
- Scope Type: Set automatically based on the request type selection. For example:
  - If request type is set to Create User, then Scope Type is automatically set to Organization.
  - If request type is set to Provision Resource, then Scope Type is automatically set to Resource.
  - If request type is set to Assign Roles, then Scope Type is automatically set to Role.
  Note:
  
  The Scope Type, All Scope, and Scope fields are applicable only if the Level field is set to Operation Level. These fields are disabled if the Level field is set to Request Level.
- All Scope: Select this option to specify the approval policy associated with all entities for a particular entity type. For example, for the Create User request type, Scope Type is Organization. If you select All Scope, then this approval policy is applicable to all organizations in Oracle Identity Manager. This is same for Resource and Role scopes.
- Scope: Select this option to specify the approval policy associated with the specific entity for a particular entity type. An approval policy can be associated with a specific Scope based on the Scope Type.
  
  The Scope field is disabled if All Scope field is set. If All Scope field is not set, then this field becomes mandatory and must be set with some value.
- Auto Approval: Select this option to specify automatic approval at the request level or operation level that you select in the Level field.
- Approval Process: Select the workflow that you want to associate with this approval policy. If Auto Approval is selected, then this field is disabled and you cannot set any value. If Auto Approval is not set, then this field becomes mandatory.
On the Step 2. Set Approval Rule and Component page, enter the name of the approval policy rule in the Rule Name field, for example, RuleTest1.
In the Rule Components section, you can define the parameters of the approval policy rule. To do so, click the icon next to the View list. The Add Simple Rule dialog box is displayed. In this dialog box, you must select values for the following fields, and then click Save.
- Entity: Entity, such as Requester, Beneficiary, or Resource, with which the approval policy rule is associated. This varies based on the selected request type and the approval level.
- Attribute: Attribute of the above selected entity.
- Condition: Condition of the approval policy rule, such as Equals, Not Equals, or Starts With.
- Value: Value of the condition.
  
  Note:
  
  If you use the User Login attribute in a rule expression, the corresponding User Login ID value must be entered in all uppercase letters, otherwise the expression will not evaluate to true.
- Parent Rule Container: The rule container with which this approval policy rule needs to be associated with.
  
  Note:
  
  When writing simple rule expressions, if an entity attribute has an encoded value, then create the expression by using the encoded value, not the lookup-code definition. For example, for the account status attribute, create the expression by using the encoded value 1 or 0, not the decoded value Locked or Unlocked.
Rule containers can be used for modeling complex conditions with And and Or combinations. To add a rule container for the approval policy rule, in the Rule Components section, from the Actions menu, select Add Rule Container. The Add Rule Container dialog box is displayed. In this dialog box, enter or select values for the following fields, and then click Add.
- Rule Container Name: The name of the rule container.
- Parent Rule Container: The name of the rule container under which you want to create this rule container. A rule container can hold either another rule container or rule elements with the AND or OR operators in a hierarchical order.
- Operator: The operators are AND and OR.
After the approval rule creation is complete, click Next.
On the Step 3. Review Approval Policy Summary page, verify the information that you have specified for the approval policy. You can click the Back button to modify any information if you want. Click Finish to create the approval policy.
A message is displayed confirming that the approval policy has been created. Click OK.

A.6 Step 6: Creating Request Templates

This section contains the following topics:

A.6.1 About Request Templates

A request template lets you customize a request type for a purpose. In other words, it allows you to control the attributes of the request by controlling the various capabilities in the UI. For instance, if you want to create requests for user creation for all contract employees and specify an attribute to have a particular value, then you can customize the Create User request type to create a request template that allows customization of the request. By creating the request template, you can specify that the organization for all employees must be XYZ Inc. or the user type of all contract employees must be Part-time Employee.

Access to templates for request creation is based on the role assignment defined in the template. After creation of a request template, it is available only to the users with the roles that are assigned to the template.

A default template is shipped predefined for each of the request type. These predefined templates can not be deleted or renamed. Names of these predefined templates is same as corresponding models.

You can use a request template for the following purposes:

Adding template-level approval: You can add an additional level of approval apart from request-level and operation-level while creating the template.
Adding restrictions: This includes:
- Adding entity restrictions: You can specify restrictions of the entity types that can be selected through the request templates. For example, a template for Provisioning Resource request type might specify a number of valid resources that can be selected by using this template. This limits the use of the template to specific type of entities in case of generic requests. For example, the template defined on provisioning request type may specify that this template can only be used for Active Directory, Exchange, and UNIX resources.
  
  Note:
  
  If no entity type is restricted in the template, then all the available entity types are shown to the requester while creating the request by using this template.
  
  However, the data to be collected during various phases of the request lifecycle is controlled by request datasets.
- Restricting data values for an attribute: If you specify a value for attributes, then the default value of the attribute is set, and the attribute is not displayed in the UI. On specifying multiple such values, the values are available to the user as List of Values (LOV), from which the user can select a value.
  
  Attribute restriction can be of the following types:
  - Specifying a default value to an attribute in the request template. During the request creation using this template, this attribute is not shown to the requester. This attribute and the corresponding value is set automatically in the request data.
  - Restricting an attribute with multiple values in request template. On specifying multiple such values, the values are available to the requester as List of Values (LOV), from which the requester can select a value during the request creation by using this template.
  - Restricting an attribute with no value in request template, by selecting the Do not allow users to enter values for this attribute option. This type of restriction is allowed only for the nonmandatory attributes. With this restriction, during the request creation by using this template, this attribute is not shown to the requester. This attribute will not be part of request data.
Adding additional data collection attributes: These attributes are not associated with any entity. Data collected by using such mechanism cannot be used during request execution. However, it can be used for reporting purpose, validations on the request, and postsubmission data action handlers.

You can define new attributes in a request template that are shown to the requester during request creation in the additional data collection step. These attributes are specific to this template and are not associated with any entity.
Assigning roles to template to restrict the use by end users: Only the members of the appropriate roles assigned to the template can create a request by using that template.

To summarize, the following are achieved by using the request template:

The restricted entity types can be specified.
The restricted attributes that are not required to be collected as a part of the request for the entity can be specified.
The attribute can be restricted to one value or list of values. If only one value is specified, then the attribute is not shown to the requester while submitting the request. If a list of values is specified, then the requester has to select one value from the list of values.
Additional data collection attributes can be specified.
Roles can be assigned to templates to restrict the use by end users.

The template management service internally uses Oracle Entitlements Server (OES) for determining who can perform what operations. The OES policy for request template authorization specifies that only users with the REQUEST TEMPLATE ADMINISTRATORS role are authorized to create or clone, search, modify, and delete request templates.

As a user belonging to the REQUEST TEMPLATE ADMINISTRATORS role, you can create a request template by using the Create Request Template wizard in the UI for request management. Steps in the wizard are dynamically generated based on the selection of the request type in the first step and the selection of resource for resource-based request types.

Creation of request templates is described with the help of the following scenarios:

A.6.2 Creating a Request Template Based on the Create User Request Type

To create a request template based on the Create User request type:

Log in to Oracle Identity Manager Administrative and User Console with credentials that have the permission to create a request template.

Note:

The user who is a member of the REQUEST TEMPLATE ADMINISTRATORS role is allowed to create a request template. If the appropriate role is not assigned to the user, then the required UI options for creating a request template will not be available to the user.
Click Advanced to open Oracle Identity Manager Advanced Administration.
Click the Configuration tab, and then click Request Templates. Alternatively, you click the Search Request Templates link under Configuration in the Welcome page.
On the left pane, from the Actions menu, select Create. Alternatively, you can click the Create Request Template icon on the toolbar. The Set request template details page of the Create Request Template wizard is displayed.
Enter values for the following fields, and then click Next.
- Request Template Name: Enter the name of the template that you want to create, for example, Create Contractor.
- Request Type: Select the type of request for which you want to create the request template, for example, Create User.
- Description: Enter a description for the request template that you are creating.
- Template Level Approval Process: Specify the approval workflow name if you want to specify an approval process for the Create User request. This is a template-level approval in addition to the request-level and operation-level approvals. For creating users for contract employees, you can specify that the HR representative, who is responsible for the recruitment of all contract employees, must approve the user creation.
  
  configuring-requests.htm#GUID-FA3DC8DD-F39A-472B-AB23-15B19460C535__BABCGDGA shows the Set request template details page of the Create Request Template wizard:
  
  Figure A-2 The Set Request Template Details Page
  
  Description of "Figure A-2 The Set Request Template Details Page"
On the Select Attributes to Restrict page, select the attributes of the Create User type for which you want the user to enter values. Attributes that are restricted by the request templates are either not shown to the user, or the user is only allowed to select from predefined LOVs. User cannot enter any values. configuring-requests.htm#GUID-FA3DC8DD-F39A-472B-AB23-15B19460C535__BABFFIBC shows the Select Attributes to Restrict page:

Figure A-3 The Select Attributes to Restrict Page

Description of "Figure A-3 The Select Attributes to Restrict Page"

This page displays the attributes based on the dataset for Create User request type. If a request is created by using the Create User request template, then you can specify values for all these default attributes. If you want to restrict some of these attributes and want the requester to enter values for a few attributes, then you can select those attributes in this page. For example, you can select Middle Name because a value for this attribute must be specified. In this example, you can select the Middle Name, Organization, User Type, User Manager, and Country attributes.
Note:
- Even if a dataset attribute is configured with a PrePopulationAdapter, it can be restricted in a request template. In such case, pre-population will not happen and the values restricted in template will be shown in Request creation UI. Hence, if pre-population is required for an attribute, it should not be restricted in the template.
- As mentioned earlier in this section, the steps in the wizard are dynamically generated based on the request type and the resource selection for resource-based request types. The steps are indicated on the top of the tab.
On the Set Attribute Restrictions page, specify restrictions on the attributes that you selected in the Select Attributes to Restrict page. To specify restrictions:

Note:

This step is generated only if there are any attributes specified in the corresponding request data set.
1. For the User Login attribute, select any one of the following:
  
  - Do not allow users to enter values for this attribute: Select this option if you do not want the user to specify a value for the attribute. On selecting this option, the attribute will not be displayed in the UI when creating the user. This option is not displayed for a mandatory attribute because a value must be specified for a mandatory attribute.
  
  - Restrict this attribute to the following values: Select this option if you want to specify one or more values for the attribute. For example, if you specify a value for the Department Number attribute, such as Software Engineering, then the default value of the attribute is set to Software Engineering, and the attribute is not displayed in the UI when creating a request by using this template. You can also specify multiple values for the attribute by using the + (plus) icon. On specifying multiple values, the values are available to the user as LOVs when creating a request by using this template, from which the user can select a value.
  
  Tip:
  
  These options are displayed for the Department Number attribute because the attribute is specified as a text box in the request dataset.
2. Specify one or more values for the Organization attribute. To do so, click the search icon next to the Organization field, select one or more organization names from the Available Organizations list, and clicking the Move button.
  
  Tip:
  
  The Organization attribute is displayed as a field for which you must select a value by searching the existing organization names because this attribute is specified as an entity in the request dataset. This is a dynamic LOV because organizations can be created in Oracle Identity Manager.
3. Specify a value for the User Type attribute. To do so, select one or more values from the Available User Type list, and click the Move button.
  
  Tip:
  
  The User Type attribute is displayed as a static LOV because this attribute is specified as a static LOV in the request dataset. This is a static LOV because the user must select from the available user types and cannot create new user types.
4. Specify values for the User Manager and Country attributes, and click Next.
  
  configuring-requests.htm#GUID-FA3DC8DD-F39A-472B-AB23-15B19460C535__BABGAACF shows the Set Attribute Restrictions page:
  
  Figure A-4 The Set Attribute Restrictions Page
  
  Description of "Figure A-4 The Set Attribute Restrictions Page"
Note:

Steps 5, 6, and 7 are common for all request templates creation.
On the Set Additional Attributes page, you can specify additional information about attributes, which need to be collected based on the template that you are creating but are not used for the purpose of entity mapping.

Note:

The Additional Attribute Data is not used during request execution. This data is also not displayed to the approver.

In this example, specify date of birth as the additional attribute name. Select the Data Type as Number and Display Type as Text Field, and then click Add. You can specify multiple attributes by clicking the Add button. When finished, click Next.

See Also:

"Step 1: Creating a Request Dataset for the Resources" for more information about the additional attributes that are not mapped to the underlying Oracle Identity Manager entity

configuring-requests.htm#GUID-FA3DC8DD-F39A-472B-AB23-15B19460C535__BABDDIIE shows the Set Additional Attributes page:

Figure A-5 The Set Additional Attributes Page

Description of "Figure A-5 The Set Additional Attributes Page"
On the Set Template User Roles page, you can select one or more roles, for example, AD Administrators, whose members are allowed to create requests by using the template that is being created. In this example, from the Available Roles list, select a role such as Contractor Administrators. Click Move to include the selected roles in the Selected Roles list, and then click Next.

Each request template can be associated with a set of roles. Only the users with any of these roles are able to create a request by using this template. When a new request template is created with a list of associated roles, a new authorization policy is created internally. In addition, if the role association with any of the existing request templates is modified (adding new roles or removing existing roles), then the existing authorization policy for this template is modified.

The default authorization policy for creating requests by using request template allows users with the REQUEST TEMPLATES ADMINISTRATORS role to access all operations related to request templates. The policy has the following details:
- Policy name: Request Template Administration Policy
- Assignee: REQUEST TEMPLATE ADMINISTRATORS role
- Functional security: The permissions are:
  - Create
  - Delete
  - Modify
  - Search
  These permissions do not support fine-grained attribute-level controls.
- Data security: None
- Description: Allows users with the REQUEST TEMPLATE ADMINISTRATORS or SYSTEM ADMINISTRATORS role to access all request template actions.
configuring-requests.htm#GUID-FA3DC8DD-F39A-472B-AB23-15B19460C535__BABJAAGA shows the Set Template User Roles page:

Figure A-6 The Set Template User Roles Page

Description of "Figure A-6 The Set Template User Roles Page"
On the Review Request Template Summary page, as shows in configuring-requests.htm#GUID-FA3DC8DD-F39A-472B-AB23-15B19460C535__BABGFJHC, review the data that have been entered for Request Template Name, Request Type, Description, and Template Level Approval Process, and then click Finish.

Figure A-7 The Review Request Template Summary Page

Description of "Figure A-7 The Review Request Template Summary Page"
Click OK to confirm the template creation.

In the Create Request Template wizard, the following steps are common irrespective of the request type that you select or the request dataset that you define:

Request details to be specified in the Set request template details page. See step 5 in the create request templates.
Setting additional attributes in the Set Additional Attributes page. See step 8.
Setting roles for the template in the Set Template User Roles page. See step 9.
Request template information in the Review Request Template Summary page. See step 10.

A.6.3 Creating a Request Template Based on the Provisioning Resource Request Type

The Provision Resource default request template that is based on the Provision Resource request type can be used for provisioning resources to users. But if you want to customize the request creation for provisioning specific resources to users, then you can create a request template, which is based on the Provision Resource request type.

To create a request template based on the Provisioning Resource request type:

In Oracle Identity Manager Advanced Administration, click the Configuration tab, and then click the Request Templates tab. Alternatively, you click the Search Request Templates link under Configuration in the Welcome page.

Note:

The user who is a member of the REQUEST TEMPLATE ADMINISTRATORS role is allowed to create a request template. If the appropriate role is not assigned to the user, then the required UI options for creating a request template will not be available to the user.
On the left pane, from the Actions menu, select Create. Alternatively, you can click the Create a Request Template icon on the toolbar. The Set request template details page of the Create Request Template wizard is displayed.
Enter values for the following fields, and then click Next.
- Request Template Name: Enter the name of the request template, for example, Provision E-Business Resource.
- Request Type: Select a request type, such as Provision Resource.
  
  Note:
  
  The steps in the Create Request Template wizard are dynamically generated on clicking Next after providing the Request Template Basic Information in the first step of the wizard.
- Description: Enter a description for the request template that you are creating.
- Approval Process: Enter the name of the approval workflow. For information about this field, see Step 4 of "Creating a Request Template Based on the Create User Request Type".
In the Select Allowed Resources page, click Search to search for all the available resources.
From the Available Resources list, select one or more resources, and then click Move to include the selected resources in the Selected Resources list. In this example, select the E-Business RO resource, and then click Next.
Note:
- Only the resources that you select in this step are displayed to the requester during request creation by using this template. If you do not select a resource here, then all the resources in Oracle Identity Manager are displayed while creating the request.
- If no entity type is restricted in the template, then all the available entity types are shown to the requester while creating request using this template.
In the Select Attributes to Restrict page, select the attributes associated with the E-Business resource that you want to restrict. These attributes are defined in the request dataset for provisioning the E-Business resource. See "Step 1: Creating a Request Dataset for the Resources" for more information about attributes.

If you select multiple resources in the Select Allowed Resources page, then the attributes associated with all the resources are displayed in the Select Attributes to Restrict page. Select the attributes for all the resources that you want to restrict, and then click Next.
In the Set Attribute Restrictions page, specify values for the attributes whose values you want to restrict. For example, for the Fax attribute, select the Do not allow users to enter values for this attribute option if you do not want the user to specify a value for the attribute. Otherwise, select the Restrict the attribute to the following values option and specify one or more values for the Fax attribute. For information about these options and setting restrictions for attributes, see "Creating a Request Template Based on the Create User Request Type".

Note that the Do not allow users to enter values for this attribute option is not available for the Server and Life Span Type attributes. This is because these attributes are specified as required in the request dataset. For information about the required property, see "Creating a Request Template Based on the Create User Request Type".

Select restriction values for all the attributes, and then click Next.

Tip:

If you are creating a request template for a request to provision multiple resources to users, click the Next Resource and Previous Resource buttons to set attribute restrictions for all the resources.

Note:

Attributes coming up as shuttle on attribute restrictions page will show upto 200 results at a time. You need to provide appropriate search pattern to get relevant search results.
Perform steps 8 through 10 of the procedure in "Creating a Request Template Based on the Create User Request Type" to complete the wizard.

Note:

In the Create Request Template wizard, the steps to select resources and set attribute restrictions vary based on the request type. The rest of the steps are similar.

While creating a request template, if you select a resource that does not have a request dataset defined, then you are not allowed to restrict the attributes to collect from the user. This is because there is no information specified about the data that is to be collected from the user for the selected resource. As a result, the Step 3: Attributes and Step 4: Restrictions in the Create Request Template wizard are not applicable because the attributes in these steps are defined by the request dataset, in the absence of which, there is no data to restrict. However, when you select a resource that does not have a request dataset, the Service Account attribute is displayed in the Step 3: Attributes because this attribute is defined by the common request dataset. See "Common Request Dataset" for information about common request dataset.

A.7 Extending Request Management Operations

You can customize certain aspects of request management operations to allow greater flexibility and implement customized logic for additional functionality. To achieve this, you can use request management plug-ins. There are plug-in points that you can use to implement customization.

This section discusses the plug-in points in the following topics:

A.7.1 Running Custom Code Based on Request Status Change

In Oracle Identity Manager, a request undergoes change in status at each stage of its lifecycle. The request engine exposes a plug-in point that allows running of custom code during request status change. A plug-in with custom code that extends this plug-in point can be implemented and registered for running the code. The plug-in point is the oracle.iam.request.plugins.StatusChangeEvent interface with the public void followUpActions(String reqId) method. This method consists of the request id parameter, using which the request details can be obtained with the help of request management APIs.

Any code that is to be run during the status change must be implemented in the followUpActions() method in a plug-in class that implements the oracle.iam.request.plugins.StatusChangeEvent interface. You must specify at which request status change this plug-in is to be run in the plugin.xml file.

For example, when a request in Oracle Identity Manager moves to the Request Failed status, you want to run a custom code that sends a notification to an administrator. To do so:

Create a new plug-in class with name RequestFailedChangeEvent that implements the oracle.iam.request.plugins.StatusChangeEvent interface. This class must have the logic of sending a notification to the administrator in the followUpActions(String reqId) method.

Define plugin.xml in following standard format, as specified by the plug-in framework:

<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <plugins pluginpoint="oracle.iam.request.plugins.StatusChangeEvent">
        <plugin pluginclass="com.mycompany.RequestFailedChangeEvent" version="1.0" name="RequestFailedChangeEvent">
            <metadata name="status">
                <value>Request Failed</value>
            </metadata>
         </plugin>
</oimplugins>

In this XML definition, the metadata part specifies at which stage the plug-in must be run. This is done by specifying the metadata value as Request Failed, which means that the com.mycompany.RequestFailedChangeEvent plug-in will run when a request moves to the Request Failed status.

Register the plug-in with Oracle Identity Manager using one of the following ways:
- Using the PlatformService.registerPlugin and PlatformService.unRegisterPlugin APIs for registration-related tasks:
  
  Here is an example:
```
ClientPlatform platform = OIMClient.getInstance();
platform.login("username", "password");
PlatformService service = platform.getService(PlatformService.class);
File zipFile = new File(fileName);
FileInputStream fis = new FileInputStream(zipFile);
int size = (int) zipFile.length();
byte[] b = new byte[size];
int bytesRead = fis.read(b, 0, size);
while (bytesRead < size) {
bytesRead += fis.read(b, bytesRead, size - bytesRead);
}
fis.close();
service.registerPlugin(b);
service.unRegisterPlugin(pluginID, version);
```
- Using the Plugin Registration Utility: The utility uses the pluginregistration.xml and ant.properties files. These files are located in the OIM_HOME/plugin_utility/ directory.
  
  Note:
  
  Plug-in registration utilities require Apache Ant version 1.7 or later.
To register the plug-in using the utility, perform the following steps:
1. Set the values for WLS_HOME and OIM_HOME in ant.properties. For example:
```
WLS_HOME =.../middleware/wlserver_10.3
OIM_HOME =..../middleware/Oracle_IDM1/server
```
2. Build the wlfullclient.jar in Oracle WebLogic server by change directories to WLS_HOME/server/lib and running the following command:
```
java -jar ../../../modules/com.bea.core.jarbuilder_1.3.0.0.jar
```
  Note:
  
  The exact JAR file version can be different based on the WLS. Use the corresponding file with the name as com.bea.core.jarbuilder at the WLS_HOME/../modules/ directory.
3. Execute the ant target "register":
```
ant -f  pluginregistration.xml register
```
  This will prompt for the Oracle Identity Manager username and password along with the server information and the location of the plugin zip file.
4. Enter the complete path of the zip file location.

A.7.2 Validating Request Data

You can use the RequestDataValidator plug-in to add custom validation of request data after submission. The plug-in point for this is the oracle.iam.request.plugins.RequestDataValidator interface with public void validate(RequestData requesterData) method. See "The DataSetValidator Element" for information about the DataSetValidator element.

A.7.3 Prepopulation of an Attribute Value During Request Creation

Prepopulation plug-in is associated with an attribute reference or attribute in request dataset. This can be used to prepopulate an attribute value by running custom code during request creation. Requester can modify the value that is prepopulated if required.

The plug-in point for this is oracle.iam.request.plugins.PrePopulationAdapter with public Serializable prepopulate(RequestData requestData) method. Use this plug-in only for the following request types:

Provision Resource, Self-Request Resource, Create User, Self-Register User.

See "The PrePopulationAdapter Element" for more details.