19 Configuring Requests

This chapter 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:

19.1 Step 1: Creating a Request Dataset for the Resources

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.

Table 19-1 lists the request models and the associated default request dataset file names that are shipped with Oracle Identity Manager.

Table 19-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 dataset for each resource. 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. See "User Modifiable Metadata Files" for information about the location of the default request datasets in MDS.

This section describes the request datasets in the following sections:

19.1.1 Elements and Properties

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

19.1.1.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 Table 19-2 that lists the request dataset name format and operation for each request type.

Table 19-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

Enable Provisioned Resource

EnableProvisionedResource${ENTITY-NAME}

ENABLE

Disable Provisioned Resource

DisableProvisionedResource${ENTITY-NAME}

DISABLE

De-provision Resource

DeprovisionResource${ENTITY-NAME}

DEPROVISION

Self De-Provision Resource

DeprovisionResource${ENTITY-NAME}

DEPROVISION


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 Table 19-2 is replaced by the resource name E-Business RO. Replace ENTITY_NAME with the resource name.

  • Specify operation as shown in Table 19-2.

  • Values for the attributes are:

    • name: ProvisionResourceE-Business RO

    • entity: E-Business RO

    • operation: PROVISION

19.1.1.2 The DataSetValidator Element

The DataSetValidator element 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 after submission and after each level of approval. 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"/>

See Also:

"Validating Request Data" for information about custom validation of request data after submission.

19.1.1.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.

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. 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.

    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" />
    
  • 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. It 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 column name in the Oracle Identity Manager database table for storing the organization name. For example, attr-ref="act_key".

      In addition, you must set the process form column label names when defining a generic entity resource dataset. For user-based and role-based request models, attr-ref value is the attribute name defined by user and role management. 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.

    • 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.

    • 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 "Provision E-Business Resource Dataset".

    • image: Specifies an image component.

  • 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. See "Bulk Requests and Child Requests" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for information about bulk requests.

    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. These single user fields can be populated by the prepopulation adapters filling the process forms directly. If you create request datasets by using this concept, 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.

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.

  • 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.

  • 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.

  • 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"/>
    

    This definition renders all the Organization entity data defined in Oracle Identity Manager. If entity-type property is defined, then the widget must be defined as ENTITY, and UI displays all available entity data in the lookup widget.

  • 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 all available entity data in the lookup widget.

    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 Role attribute will be displayed as a dropdown, and user can select any of the values.

    For a limited number of values, you can use dropdown. But for a large number of values, use the lookup widget.

  • 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, widget must be defined as itresource-lookup, and UI displays all available entity data in the lookup widget.

  • 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.

  • Read Only: This is a flag property used to specify that the approver can only view and not modify the data value. Value is of type Boolean.

  • 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.

  • entitlement: This is a flag property used to specify if the dataset attribute is of type entitlement. Value is of type Boolean

  • 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.

19.1.1.3.1 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 associated for an AttributeReference definition. 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, it 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.

Example 19-1 shows a sample data set for provisioning the Active Directory (AD) resource, in which prepopulation is used:

Example 19-1 Provisioning AD Resource

<?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 in Example 19-1, 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.

19.1.1.3.2 The lookupValues Element

In some request models, such as create user, you might need to define a mapping from the request dataset attribute to the entity attribute in the underlying entity configuration. For example, a user attribute defined in the request dataset needs to be mapped to the actual user attribute defined by the User Management feature. This mapping can also be achieved in the following way:

<AttributeReference name="ATTRIBUTE_NAME" attr-ref="ATTRIBUTE_DEFINED_BY_THE_FEATURE" available-in-bulk="false" />

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:

  • encoded-value: This is the actual data value corresponding to the decoded value and is populated as a part of data flow.

  • decoded-value: This is a data value that must be collected at the time of request submission.

The following 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.

19.1.1.3.3 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.

19.1.1.4 The Attribute Element

This element is similar to the AttributeReference element with a difference. 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.

The request dataset can also collect data, which may not refer to an 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. For details about approval policies, see "Step 5: Defining Request Approvals".

19.1.2 Sample Request Dataset

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

Example 19-2 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="20"
                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="20"
                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="20"
                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="80"
                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="80"
                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="Full Name" attr-ref="Full Name" available-in-bulk="false" type="String" length="80"
                widget="text" required="false" mls="true"/>
    <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"/>
 
    <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>

The request dataset does not comply with the underlying USER entity because the Organization attribute is mandatory for the User to be created. Therefore, the organization must be provided either as part of request data, or by the approver at request-level approval. Whenever the organization data is provided, required="true" must be specified in the request dataset.

19.1.3 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.

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.

Oracle Identity Manager allows you to define a child process form and associates it to a parent process form. This functionality is used to define child attributes with one-to-many relationship with a parent attribute when multiple data values need to be provided for an entity attribute.

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 Also:

Example 19-3, "Provision E-Business Resource Dataset" for the Provision E-Business Resource request dataset

Example 19-3 shows the sample XML code for a request dataset for provisioning an E-Business resource:

Example 19-3 Provision E-Business Resource Dataset

<?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. An Oracle Apps User Responsibility consists of start date, end date, name. 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.

  • 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.

    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 Also:

"Creating Request Templates" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for information about how the attributes are displayed in the Create Request Template wizard

19.1.4 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, it takes the attribute from the common dataset. The request collection data is a union of the values specified for the dataset-ref and common-dataset-ref properties. 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.

19.1.5 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:

19.1.5.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:

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.

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 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.

Child Attributes

For child attributes, the translated key contains the parent attribute name which 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.

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.

19.1.5.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

19.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. Similarly, you can delete or export any dataset file from MDS repository by using similar tools.

See Also:

"Chapter 30, "MDS Utilities and User Modifiable Metadata Files" for detailed information about the MDS utilities used for importing and exporting files and modifying Oracle Identity Manager metadata

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.

  • After updating an existing dataset, cache for the category MetaData must be purged. This allows request service to load the new version of the dataset. Similarly, if you delete a dataset, then the cache for the category MetaData must be purged. See "Purging the Cache" in the Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager for information about purging cache.

  1. 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.
  2. Go to the OIM_HOME/bin directory and run weblogicImportMetadata.sh script. See "Setting up the Environment for MDS Utilities" for details about running the weblogicImportMetadata.sh script.

19.3 Step 3: Creating SOA Composites Required for Approval

Oracle Identity Manager provides a few predefined Service-Oriented Architecture (SOA) composites. However, you can define your own composites and use them in request approvals. See "Creating New SOA Composites" for information about creating the composites.

19.4 Step 4: Registering the SOA Composites in Oracle Identity Manager

See "Registering a SOA Composite with Oracle Identity Manager" to register the SOA composites in Oracle Identity Manager.

19.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:

19.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.

See Also:

SOA server hosts SOA composites and human workflow. The integration of the request service and SOA can be explained with the help of Figure 19-1:

Figure 19-1 Request Service and SOA Integration

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

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

  1. A request is created by using the request management UI, which is Oracle Identity Manager Self Service or Advanced Administration.

  2. 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. Therefore, the workflow service, which is a part of Oracle Identity Manager, provides a layer of abstraction on top of the backend Business Process Execution Language (BPEL) workflow service and 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 JDeveloper documentation on the Oracle Technology Network (OTN) Web site at the following URL:

    http://www.oracle.com/technology/documentation/jdev.html

  3. Oracle SOA determines whom to assign the request by using the user/role API provider 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. For information about the database provider, see Appendix E, "User and Role API Provider for Oracle Identity Manager".

  4. Oracle SOA assigns the task to the assignee based on the information provided by the DB provider.

  5. The list of assigned tasks for the users and roles is displayed in the TaskList UI.

  6. Using the TaskList, the approver approves or rejects the requests.

  7. The approval outcome is send back to the request engine through SOA.

  8. 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 process for the request 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. For information about the configuration between Oracle Identity Manager and Oracle SOA, see Chapter 21, "Developing SOA Composites".

See Also:

"Managing Tasks" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for information about performing various request-related operations by using the TaskList

19.5.2 Approval Levels

Each request may need to go through three levels of approvals: template-level, request-level, and operation-level. All approval processes that are registered with Oracle Identity Manager are available for configuration of the workflow service. 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:

19.5.2.1 Template-Level Approvals

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 approvals are associated with approval policies. For template-level approvals, there are no approval policies associated. The approval processes are defined at the template and are run directly, without an association with approval policies. For information about approval policies, see "Managing Approval Policies" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager.

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.

19.5.2.2 Request-Level Approvals

These are the approval for the entire request. These are defined at centralized approval management section.

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. In the absence of such an approval policy, the default request approval workflow is used. By default, all the request-level approvals 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 help select 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:

  • For information about creating approval policy rules, see "Creating Approval Policies" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager.

  • 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. See Section 4.3, "Bulk Requests and Child Requests" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for information about bulk requests and child requests.

  • 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.

19.5.2.3 Operation-Level Approvals

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 Table 19-3:

Table 19-3 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

  • Create Role

  • Modify Role

  • Delete Role

role


Note:

For the Create Role, Modify Role, and Delete Role types, the operational-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 approvals are required for individual child requests. Each individual child request can be approved or rejected. 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.

19.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. See "Managing Approval Policies" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for the procedure to create approval policies.

19.6 Step 6: Creating 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. See "Managing Request Templates" in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for details about creating and managing request templates.

19.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.

See Also:

  • "Managing Requests" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for detailed information about the concepts and tasks related to requests

  • "Creating and Searching Requests" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager for detailed information about creating and managing requests in Oracle Identity Manager

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

19.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.

See Also:

Chapter 6, "Developing Plug-ins" for detailed information about plug-ins and plug-in points

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:

  1. 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.

  2. 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.

  3. Register the plug-in with Oracle Identity Manager. See "Registering Plug-ins" for information about registering plug-ins in Oracle Identity Manager.

19.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.

19.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.