21 Developing Workflows for Approval and Manual Provisioning

This chapter describes the concepts, features, and architecture of workflows in Oracle Identity Manager. It provides use cases for workflow, and instructions for designing, implementing, and deploying your first workflow. In addition, this chapter describes how to extend the request management operations by using plug-in points.

This chapter contains the following sections:

Introducing Workflows
Predefined SOA Composites
Creating New SOA Composites
Developing Workflows: Vision Request Tutorial
Configuring Default Request-Level and Operation-Level Approval Composites
Creating and Deploying Custom Task Details Taskflow
Understanding Request Datasets
Extending Request Management Operations
Enabling Auto-Approval for Self Registration Requests

21.1 Introducing Workflows

This section describes the key workflow concepts in the following sections:

Overview of Workflows
Workflow Concepts
Workflow Architecture

21.1.1 Overview of Workflows

Managing user access and orchestrating the business process so that users get the correct access is a key identity governance function. The process of changing users' access can be initiated by the users through events in HR that trigger policies, or by administrators. Irrespective of how the change in access is initiated, organizations require the following:

The business process that is initiated must be flexible, and must be able to meet changing business rules of the organization.
The business process must be able to decide between granting access immediately versus introducing manual intervention steps and seeking approval prior to granting access.
The business process must be able to perform validations, including Segregation of Duties (SoD) checks on what is being requested, by who, for whom, and in what context.
If manual intervention is required, then the business process must have the ability to assign to users or groups of users and escalate, reassign, or expire if no response is received in a timely manner.
For manual intervention, the business process must have the ability to gather information from the approvers, including comments and attachments.
The business process must be able to interact with external systems, such as ticketing systems, when automated access grants are not possible, or the organization's rules require that access is granted manually.
All decisions and actions must be audited and available in a reportable manner to allow the organization to measure performance of the process and also for auditors to fulfill compliance requirements

Oracle Identity Manager provides flexible and powerful access request capabilities that allow organizations to meet these requirements.

21.1.2 Workflow Concepts

The key concept of workflows in Oracle Identity Manager involves the following terminologies:

Request

In Oracle Identity Manager, a request refers to the business process that is invoked when an operation on an identity or an account has to be performed. Examples of these operations include creating a user, provisioning an account, and granting a role to a user. A request can either be fulfilled immediately (also known as direct operation) or can require manual intervention in the form of approvals (also known as request-based operation). When a user tries to perform an operation, Oracle Identity Manager determines whether the operation would be direct or request-based on the authorization policies of the logged-in user.
Request-level approval

A request has to go through two independent approval processes before it can proceed for fulfillment. These are request-level approvals and operational-level approvals. Request-level approvals are invoked first and are followed by operational-level approvals. Request-level approvals are primarily used for bulk requests, which involve multiple target users or multiple requested entities or any combination of both.

For bulk approvals, when the request-level approval has been received, the request engine splits the request into individual target user and requested operation or entity combination, and invokes the operational approval for each combination.
Operation-level approval

Operation-level approval is the second approval process that is invoked as part of approving a request. Operational approvals are always for a single target user and a single operation or requested entity.
Approval policy

An approval policy is a rule that allows the request engine to pick a SOA composite to invoke. Approval policies can be configured at request level or operation level. They can use all the data available at the request and operational levels to construct a rule. The rule helps the request engine determine if the request should be auto-approved or a SOA composite should be invoked.
SOA composite

A SOA composite is an assembly of services, service components, and references designed and deployed together in a single application. Wiring between the service, service component, and reference enables message communication. The composite processes the information described in the messages.
Partner Link

A partner link enables you to define the external services with which the BPEL process service component is to interact. You can define partner links as services or references (for example, through a JCA adapter) in the SOA Composite Editor or within a BPEL process service component in Oracle BPEL Designer.
BPEL process

BPEL processes provide process orchestration and storage of synchronous or asynchronous processes. You design a business process that integrates a series of business activities and services into an end-to-end process flow.
IT provisioner

The IT provisioner, also known as fulfillment user or Help Desk user, is the persona responsible for fulfilling manual provisioning requests.
Request web service

The request web service is a web service that is shipped with Oracle Identity Manager. It allows customers to expose request, user, role, organization, account, entitlement, application instance, and catalog information so that approval workflows can make data-driven routing decisions.
Request callback

The request callback is a web service that is invoked by the SOA composite when an approval outcome (approve/ reject) has been received. When the request engine invokes a SOA composite for the purpose of approval, it suspends the request until the composite invokes the request callback and provides an approve or reject decision. This decision allows the request engine to proceed with fulfilling the request (if approved) or rejecting the request (if rejected).
Provisioning callback

The provisioning callback is a web service that is invoked as part of disconnected provisioning. When the IT provisioner or fulfillment user fulfills a disconnected provisioning request and marks the task as completed, the SOA composite invokes the provisioning callback and sends the provisioning status allowing the provisioning workflow to complete.
Request payload

The request engine invokes the SOA composite and passes it some basic information about the request, requester, and target user. This information is called the request payload.
Human Task

Human tasks provide workflow modeling that describes the tasks for users or groups to perform as part of an end-to-end business process flow.

21.1.3 Workflow Architecture

Workflows are used in Oracle Identity Manager to:

Route requests to approvers for approval
Route manual provisioning tasks to IT provisioners or Help Desk for fulfillment

Figure 21-1 provides an overview of workflows in Oracle Identity Manager:

Figure 21-1 Workflow Architecture

Description of "Figure 21-1 Workflow Architecture"

In Figure 21-1, the following actions occur:

User initiates an operation that results in a request. Examples of such operations include:
- Self-registration
- User profile modification, excluding lock, unlock, and password management operations
- Role grant operations
- Application instance operations, including disconnected provisioning
- Entitlement operations
- Bulk operations
A request is created. After appropriate validation, the request engine evaluates approval policies and selects a SOA composite to be invoked.
If approval policies are not configured, then the default request-level SOA composite is selected for request-level approval, and default operational-level SOA composite is selected for operational-level approval.
The SOA composite involves the Business Process Execution Language (BPEL) process.
The BPEL process invokes a web service to get additional details about the request including:

Note:
This step is optional. This is required only if additional information related to various entities is required in BPEL Process.
- Item details from the catalog
- Target user information
- Requester information
The BPEL process invokes additional logic to calculate properties such as priority, approvers, and notification.
When manual intervention is required, such as during approval and manual fulfillment, the process invokes a Human Task.

A Human Task contains the logic to assign, expire, or escalate the approval task to users or roles. The Human Task can assign the users and roles statically or dynamically. For static assignments, the approvers can be determined in the BPEL process and passed as parameters to the Human Task. For dynamic assignments, rules created using Oracle Business Rules (OBR) are used to dynamically determine the approvers.

Typically, the BPEL process contains one Human Task. In some instances, the BPEL process might invoke a decision point to pick one of multiple Human Tasks.
When the human task completes, a response of approve or reject (for approval) or complete (for manual fulfillment), is returned via a callback service to Oracle Identity Manager, which resumes the operation.

21.2 Predefined SOA Composites

Table 21-1 lists the predefined SOA composites in Oracle Identity Manager that can be used as approval processes.

Table 21-1 Predefined Workflow Composites

Workflow Composite	Description
DefaultRequestApproval	This is the default request-level approval. By default, the request-level approval goes to the SYSTEM ADMINISTRATORS role, for request-level approval. In addition, this composite is invoked by certification use cases. The task will have one of the following states: Assigned to the beneficiary. Later, the task may be assigned to the beneficiary's manager based on the decision of the beneficiary. Auto-approved if the certification requester is beneficiary's manager. Note: For information about the certification use cases, see "Managing Identity Certification" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.
DefaultOperationalApproval	This is the default operation-level approval. By default, the approval task is assigned to the SYSTEM ADMINISTRATORS role for operation-level approval. In addition, the composite is invoked by certification use cases, and the task will be auto-approved.
BeneficiaryManagerApproval	This requires approval from the beneficiary's manager. This can be associated with the following: The request models that have a beneficiary. Examples of such request models are Provision Application Instance and Assign Roles. All user models except Create User and Self-Register User. This composite must be associated at the operational level of approval because a request can have multiple beneficiaries at the request level.
DefaultRoleApproval	This SOA composite creates a single approval task that is assigned to the SYSTEM ADMINISTRATORS role for approval.
RequesterManagerApproval	This SOA composite creates a single approval task that is assigned to the requester's manager for approval. Note: This composite cannot be associated with unauthenticated request models, such as Self-Register User.
DefaultSODApproval	This SOA composite creates an approval task that is assigned to the System Administrator, starts SoD check, and after the SoD result is available, it creates another approval task assigned to the SOD Administrators role. This must be associated with request models to provision or modify resources at the operational level if SoD check is required.
DisconnectedProvisioning	This SOA composite assigns the task to the System Administrator to fulfil the disconnected provisioning.
ProvideInformation	This SOA composite assigns the task to the requester seeking details of account/entitlement. For more information, see "Entitlement and Account Dependencies in Requests" in the Oracle Fusion Middleware User's Guide for Oracle Identity Manager.
CertificationProcess	This is the default Certification composite. This composite takes care of assigning the certification task to the certifier (user). This composite also manages the following certification task events: Expiry Proxy Escalation Re-assignment
CertificationOverseerProcess	This composite assigns a certification task to the certifier (user). In addition, the composite also handles routing the task to the overseer after the certifier completes the task. Oracle SOA Business Rules are used to handle the task routing. This composite handles the following certification task events: Expiry Proxy Routing (Overseer) Escalation Re-assignment

21.3 Creating New SOA Composites

To create a new SOA composite that can be used as an approval process, perform the following steps:

Creating a New SOA Composite
Deploying a SOA Composite in Oracle SOA Server
Prerequisites for Communication to Oracle Identity Manager Through SSL Mode

21.3.1 Creating a New SOA Composite

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.

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, refer to "Configuring Oracle User Messaging Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

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

21.3.2 Deploying a SOA Composite in Oracle SOA Server

For information about deploying the workflow composite in BPEL, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Note:

The composite should be redeployed with a new version. If a composite is redeployed with the same version in SOA, then all the pending approvals in Oracle Identity Manager initiated by the composite becomes stale and are removed from the user's TaskList. See "Deploying an Existing SOA Archive in Oracle JDeveloper" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for information about deploying existing SOA composites.

21.3.3 Prerequisites for Communication to Oracle Identity Manager Through SSL Mode

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

Note:

For a non-SSL connection, skip this section.

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

21.4 Developing Workflows: Vision Request Tutorial

This section describes how to design your first workflow in the following sections:

Introducing the Tutorial
Prerequisites
Creating the Application Instance
Configuring FinApp in the Catalog
Creating and Configuring the SOA Composite for Approval

21.4.1 Introducing the Tutorial

This tutorial is based on the following use case:

Vision Corp uses FinApp, a mainframe-based application. The application does not have APIs that can be remotely invoked. Therefore, accounts are managed manually by the Help Desk.
Vision Corp employees use the Access Request Catalog to request accounts and entitlements in the application.
Approvals are based on the risk level of the access being requested. If the risk level is Low Risk, approval is required only from the beneficiary's manager. If the risk level is Medium Risk, approval is required from either the beneficiary's manager or certifier. If the risk level is High Risk, approval is required from the beneficiary's manager and the Audit Review team.
After approval, the request has to be fulfilled by members of the Asset Management team.

This tutorial describes how to create the application and the workflow, and how to configure the approval and fulfillment for the application.

The result of the tutorial is:

An application instance
A SOA composite for approval consisting of:
- A BPEL process
- Multiple Human Tasks

21.4.2 Prerequisites

The following assumptions are made for this tutorial:

Oracle SOA Suite is installed on a host on which the SOA infrastructure is configured.
JDeveloper 11.1.1.7 with SOA Design Time 11.1.1.7 is available.
Mandatory patches, if any, for SOA Jdeveloper extension have been applied. For information about the mandatory patches, see "Mandatory Patches Required for Installing Oracle Identity Manager" in the Oracle Fusion Middleware Release Notes.
You are familiar with basic BPEL constructs, including BPEL activities and partner links, and basic XPath functions.
You are familiar with the SOA Composite Editor and Oracle BPEL Designer, the environment for designing and deploying BPEL processes. However, for detailed information about SOA composites, refer to Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Two roles, Audit Review Team and Asset Management Team, have been created and members have been assigned.
An organization with name Vision is created.

21.4.3 Creating the Application Instance

This section contains the following topics:

Creating the FinApp Application Instance
Defining Application Instance Attributes and Creating a Form
Publishing the Application Instance to One or More Organizations
Linking Entitlements to the Application Instance
Publishing the Application Instance With Entitlements to the Catalog

21.4.3.1 Creating the FinApp Application Instance

To create the FinApp application instance:

Login to Oracle Identity System Administration.
Click Sandboxes to access sandbox management, create a sandbox, and activate it. See "Managing Sandboxes" for information about sandboxes and how to create, activate, and publish sandboxes.
Under Configuration, click Application Instances. Click Create on the toolbar to open the Create Application Instance page.
Enter Name and Display Name as FinApp.
Select the Disconnected option to specify a disconnected application instance.
Click Save, and then click OK to confirm creation of the FinApp application instance.

21.4.3.2 Defining Application Instance Attributes and Creating a Form

To define the attributes of the application instance and create a form:

Under Configuration, click Form Designer.
Search and select the FinApp form. This form is automatically created when the disconnected application instance is saved.

Note:
You must be in an active sandbox to create and edit a form.

Click the Fields tab, and then click the Edit icon on the toolbar.

By default, the following fields are created and are available for use:

Field	Description
IT Resource	The IT resource instance where the account is being created
Account Login	The login for the application
Password	The password that is used while logging in to the application
Account ID	The unique identifier generated by the application when the account is created
Service Account	A flag that is used during access request only

Note:

Attributes such as Account ID and IT Resource are typically not displayed in the access request user interface. Depending upon the use case, for example a mobile phone request, the attributes might not be relevant. To hide these attributes, you can customize the form. See "Configuring Custom Attributes" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for more information on how to customize the form.

Add additional attributes. In this example, add the following attribute:

Account Description: Data type is Text.

Note:
See "Configuring Custom Attributes" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for more information on creating the custom attributes

After adding the attributes, verify that the configuration in the Fields tab is similar to the following table:

Display Label	Name	Type
Account Description	AccountDescription	Text
Account ID	UD_FINAPP_ACCOUNTID	Text
ITResource	UD_FINAPP_IT	Number
Account Login	UD_FINAPP_LOGIN	Text
Password	UD_FINAPP_PASSWORD	Text
Service Account	serviceaccount	Checkbox

To allow users to request entitlements, you must add a child object and add an attribute that is tagged as an Entitlement. To do so:
1. Click the Child Objects tab, and then click Add on the toolbar.
2. Enter the child object name, and click OK to create the child object.
3. Click the child object just created.
4. Select Action, Create to create a new attribute. From the popup window, select Lookup, and click OK. Enter values for the following fields:
  
  Name: Profile Name
  
  Display Name: Profile Name
5. Select Use in Bulk to allow requesters to specify a value when requesting access for multiple users.
6. Under Lookup Type, click Create a New Lookup Type.
7. Create the new Lookup and specify the values, as shown:
  
  Code: Lookup.FinApp.Profile
  
  Meaning: Lookup.FinApp.Profile
  
  Description: Lookup.FinApp.Profile
8. Create three lookup codes by using the values given in the following table:
  
  Meaning Code
  
  FinApp User FinAppUser
  
  FinApp Administrator FinAppAdministrator
  
  FinApp Operator FinAppOperator
  
  Note:
  You can also populate the lookup definition by using a scheduled task and the lookup APIs.
9. Select the Searchable, Entitlement, and Searchable Picklist options.
Click Save and Close.
Click Back to Parent Object.
Click Regenerate View to re-create the UI form with the new attributes.
Close all tabs.
Publish the sandbox.

Meaning	Code
FinApp User	FinAppUser
FinApp Administrator	FinAppAdministrator
FinApp Operator	FinAppOperator

21.4.3.3 Publishing the Application Instance to One or More Organizations

To publish the application instance to one or more organizations:

Open the FinApp application instance details page, and click the Organizations tab.
Click Assign. In the Select Organizations dialog box, select one or more organizations to publish the application instance to.
Select the Hierarchy option if you want the application instance to be published to the organization and its child organizations.
Click OK.

21.4.3.4 Linking Entitlements to the Application Instance

To link entitlements to the application instance:

Under System Management, click Scheduler.
Search for the Entitlement List scheduled job, and click Run Now.
Under Configuration, click Application Instances, and navigate to the FinApp application instance.
Click the Entitlements tab, and verify that the entitlements are displayed, as shown in Figure 21-2:

Figure 21-2 Entitlements List

Description of "Figure 21-2 Entitlements List"
Select an entitlement, and verify that it is published to the same organizations as the application instance, as shown in Figure 21-3:

Figure 21-3 Entitlement Availability to Organizations

Description of "Figure 21-3 Entitlement Availability to Organizations"
Edit one or more entitlements, and enter a business friendly description. If required, modify the display name as well.

21.4.3.5 Publishing the Application Instance With Entitlements to the Catalog

To publish the application instance and its entitlements to the catalog:

Under System Management, click Scheduler.
Search for the Catalog Synchronization scheduled job, and click Run Now.

21.4.4 Configuring FinApp in the Catalog

To configure the application instance and its entitlements in the catalog:

Login to Oracle Identity Self Service as the Catalog Administrator.
Under Requests, click Catalog.
In the Catalog page, search for the application instance.
Select the application instance, and edit the catalog item details.
Provide values for the default attributes. Because this tutorial involves workflow routing based on risk level and manual fulfillment, you must provide a value for the Risk Level and Fulfillment Role attributes. However, it is recommended that you provide values for other attributes, especially User Defined Tags.

Figure 21-4 shows the attributes of the catalog item.

Figure 21-4 Catalog Item Attributes

Description of "Figure 21-4 Catalog Item Attributes"

21.4.5 Creating and Configuring the SOA Composite for Approval

This section contains the following topics:

Creating the Approval Workflow
Making Request and Catalog Data Available to the BPEL Process
Configuring Workflow Selection
Configuring Human Tasks
Configuring the Human Task and BPEL Mappings
Deploying the SOA Composite
Creating the Approval Policies

21.4.5.1 Creating the Approval Workflow

To create a new approval workflow:

Set the JAVA_HOME environment variable by running the setWLSEnv.sh script in the /server/bin/ subdirectory in the WebLogic Server installation directory.
Set the ANT_HOME environment variable to MIDDLEWARE_HOME/modules/org.apache.ant_1.7.1.
Set the PATH environment variable to $JAVA_HOME/bin:$ANT_HOME/bin:$PATH.
Navigate to OIM_HOME/server/workflows/new_workflow.
Run the following:
```
ant-f new_project.xml
```
Provide the Application Name as AddAccessApprovalApplication.
Provide the Project Name as AddAccessApproval.
Provide the Service Name as AddAccess.
Wait for the utility to finish generating the new JDeveloper Workspace containing the Composite. The workspace is generated in /server/workflows/new-workflow/process-template.
Copy the directory to a location accessible to JDeveloper.

21.4.5.2 Making Request and Catalog Data Available to the BPEL Process

To make request and catalog data available to the BPEL process:

Switch to Design view of the BPEL process.
Drag the Invoke activity from the Component Palette and drop it below the AssignRequestWSURL activity. Rename it to InvokeRequestDetailsOperation.
Right-click InvokeRequestDetailsOperation, and select Edit.
Select partner link from the Partner Link Chooser as RequestWSPartnerLink, and operation as getRequestDetails, as shown in Figure 21-5.

Figure 21-5 Partner Link and Operation

Description of "Figure 21-5 Partner Link and Operation"
Under the Variables section, click the plus (+) icon for the Input and Output fields to create the input and output variables. Name the input and output variables as requestDetails_InputVariable and requestDetails_OutputVariable respectively. Then click Apply and OK.
Drag and drop an assign activity, rename it to AssignRequestInput, and place it above the InvokeRequestDetailsOperation invoke activity, as shown in Figure 21-6.

Figure 21-6 AssignRequestInput

Description of "Figure 21-6 AssignRequestInput"
Right-click AssignRequestInput, and select Edit to map the input of the InvokeRequestDetailsOperation, as shown in Figure 21-7.

Figure 21-7 Input Mapping

Description of "Figure 21-7 Input Mapping"
Add an Invoke activity after the InvokeRequestDetailsOperation, as shown in Figure 21-8. Name the activity InvokeCatalogOperation.

Figure 21-8 InvokeCatalogOperation

Description of "Figure 21-8 InvokeCatalogOperation"
Edit the InvokeCatalogOperation, and configure it as shown in Figure 21-9.

Figure 21-9 InvokeCatalogOperation Configuration

Description of "Figure 21-9 InvokeCatalogOperation Configuration"
Add an Assign activity above InvokeCatalogOperation, as shown in Figure 21-10. Name the activity as AssignCatalogInput.

Figure 21-10 AssignCatalogInput

Description of "Figure 21-10 AssignCatalogInput"
Note:
The following attributes will be returned as custom attributes through the catalog detail method of the request web service:
- APPROVER_USER_FIRSTNAME
- APPROVER_USER_LASTNAME
- APPROVER_USER_DISPLAYNAME
- APPROVER_USER_EMAIL
- CERTIFIER_USER_FIRSTNAME
- CERTIFIER_USER_LASTNAME
- CERTIFIER_USER_DISPLAYNAME
- CERTIFIER_USER_EMAIL
- FULFILLMENT_USER_FIRSTNAME
- FULFILLMENT_USER_LASTNAME
- FULFILLMENT_USER_DISPLAYNAME
- FULFILLMENT_USER_EMAIL
Right-click and edit the assign activity to map the input to the InvokeCatalogOperation, as shown in Figure 21-11.

Figure 21-11 InvokeCatalogOperation Input Mapping

Description of "Figure 21-11 InvokeCatalogOperation Input Mapping"

21.4.5.3 Configuring Workflow Selection

To define the workflow selection rules:

Define a variable called catalogData. To do so:
1. Click the Variables icon, and then click the Create icon on the Variable dialog box.
2. Choose Type as Element and click the Search icon next to the field.
3. In the dialog box, expand Project Schema Files and then CatalogData.xsd and select the CatalogData element. This variable will contain the catalog details returned as an output of the InvokeCatalogDetails step.
Define a variable called workflowtype. To do so:
1. Select type as Element and click on Search icon next to the field.
2. In the dialog box, expand Project Schema Files and then BusinessRule.xsd and select the StageOutput element. This variable will contain the type of workflow to be invoked.
Navigate to the SOA Composite view, and add a Business Rule component, as shown in Figure 21-12.

Figure 21-12 Adding Business Rule Component

Description of "Figure 21-12 Adding Business Rule Component"
In the Create Business Rules dialog box, specify the name of the Rule Dictionary as WorkflowSelection.
Specify Input as CatalogData from CatalogData.xsd in Project Schema Files and Output as StageOutput from BusinessRule.xsd in Project Schema Files
Switch to the BPEL process.
Expand SOA Components and add a Business Rule component between the InvokeCatalogOperation and ApprovalTask_1 components.
Edit the rule and rename it to WorkflowSelection.
In the Rule dialog box, click the Dictionary tab, and select the WorkflowSelection dictionary that you defined in step 4.
Select Assign Input Facts subtab in the Dictionary tab, and click the plus (+) icon.
Map the catalogData variable to the input to the Rule, as shown in Figure 21-13.

Figure 21-13 catalogData Variable Input Mapping

Description of "Figure 21-13 catalogData Variable Input Mapping"
Select Assign Output facts subtab in Dictionary tab.
Map the workflowtype variable to the output to the Rule, as shown in Figure 21-14.

Figure 21-14 workflowtype Variable Output Mapping

Description of "Figure 21-14 workflowtype Variable Output Mapping"
Add an Assign activity before the WorkflowSelection rule and rename it as AssignRuleInput, as shown in Figure 21-15.

Figure 21-15 AssignRuleInput

Description of "Figure 21-15 AssignRuleInput"
Map the output of the InvokeCatalogOperation to the catalogData variable, as shown in Figure 21-16.

Figure 21-16 catalogData Variable Output Mapping

Description of "Figure 21-16 catalogData Variable Output Mapping"
Switch to the SOA Composite view.
Right-click the Business Rule component, and select Edit.
Click Create Rule.
Rename the rule from Rule1 to Auto Approval.
Edit the rule, and specify the stageType property in the Properties dialog box, as shown in Figure 21-17.

Figure 21-17 The stageType Property

Description of "Figure 21-17 The stageType Property"

To specify the stageType property:
1. Click the <insert test> action below IF (click it 3 times to add 3 conditions separated by Logical AND).
  
  Change conditions as:
  
  CatalogDataType.itemRisk != 3 and CatalogDataType.itemRisk != 7 and CatalogDataType.itemRisk != 5
2. Click the <insert action> below THEN.
3. Select assert new.
4. Click <target> that is added next to assert new, and select Stage.
5. Click <edit properties>. The Properties dialog box is displayed, as shown in Figure 21-17.
Similarly, create the Manager, Serial, and Parallel approval rules, as shown in Figure 21-18.

Figure 21-18 Approval Rules

Description of "Figure 21-18 Approval Rules"
Switch to the BPEL process.
Add a switch activity after the WorkflowSelection rule, as shown in Figure 21-19.

Figure 21-19 Switch Activity

Description of "Figure 21-19 Switch Activity"
Select the Switch activity and add two Switch Case steps, as shown in Figure 21-20.

Figure 21-20 Switch Case Steps

Description of "Figure 21-20 Switch Case Steps"
Rename the conditions as Serial Approval, Parallel Approval, and Manager Approval, as shown in Figure 21-21.

Figure 21-21 Renamed Conditions

Description of "Figure 21-21 Renamed Conditions"
Drag the default Human Task into the Manager Switch Case, as shown in Figure 21-22.

Figure 21-22 Dragging Default Human Task

Description of "Figure 21-22 Dragging Default Human Task"
Switch to the SOA Composite view.
Add two Human Tasks, SerialApproval and ParallelApproval, as shown in Figure 21-23.

Figure 21-23 Adding Human Tasks

Description of "Figure 21-23 Adding Human Tasks"
Switch to the BPEL Process.
Edit the Manager Approval Switch case, and add the following expression:
```
bpws:getVariableData('workflowtype','/ns18:StageOutput/ns18:stageType')='Manager'
```
You must first configure the newly added Tasks and then wire them to the BPEL Process.

Note:
Oracle recommends using expression builder to add the expression..

21.4.5.4 Configuring Human Tasks

Configuring the Human Task consists of the following:

Configuring the Parallel Human Task
Configuring the Serial Approval Task
Configuring the Default Approval Task

21.4.5.4.1 Configuring the Parallel Human Task

To configure the parallel Human Task:

Switch to the SOA Composite view.
Edit the Parallel Approval Task.

Click the Data tab, and add the attributes listed in the following table:

Patameter	Data Type
RequestID	{http://www.w3.org/2001/XMLSchema}string
RequestModel	{http://www.w3.org/2001/XMLSchema}string
RequestTarget	{http://www.w3.org/2001/XMLSchema}string
RequesterDetails	{http://xmlns.oracle.com/request/RequestDetails}RequesterDetails
BeneficiaryDetails	{http://xmlns.oracle.com/request/RequestDetails}BeneficiaryDetails
ObjectDetails	{http://xmlns.oracle.com/request/RequestDetails}ObjectDetails
OtherDetails	{http://xmlns.oracle.com/request/RequestDetails}OtherDetails
url	{http://xmlns.oracle.com/request/RequestDetails}url
Catalogdata	{http://xmlns.oracle.com/RequestServiceApp/RequestDataService/CatalogData}CatalogData
RequesterDisplayName	{http://www.w3.org/2001/XMLSchema}string
BeneficiaryDisplayName	{http://www.w3.org/2001/XMLSchema}string
Requester	{http://www.w3.org/2001/XMLSchema}string

Verify the task parameters in the Data tab.
Click the General tab.
Set the Task Title to <%/task:task/task:payload/ns2:BeneficiaryDetails/ns2:DisplayName%> has submitted a request for approval. To do so:
1. Click Edit next to Task Title, and select task:payload, ns2:BeneficiaryDetails, ns2:DisplayName.
2. Click Insert Into Expression. Task Title is displayed as shown in Figure 21-24:
  
  Figure 21-24 The Task Title
  
  Description of "Figure 21-24 The Task Title"
```
<%/task:task/task:payload/ns2:BeneficiaryDetails/ns2:DisplayName%>
```
  This can be edited to configure meaningful title, such as:
```
<%/task:task/task:payload/ns2:BeneficiaryDetails/ns2:DisplayName%> has submitted a request for approval.
```
Set the Task Owner to Group and SYSTEM ADMINISTRATORS.
Click the Notification tab, and then click Advanced.
Select the Make notification actionable option.
Click the Assignment tab.
Add a Parallel stage. To do so, select Stage1 in the flow chart, and click the plus (+) icon, and select Parallel stage.
Select a stage and click Edit. Provide the name as Manager.
Select the other stage, and provide the name as Certifier, as shown in Figure 21-25.

Figure 21-25 Manager and Certifier Stages

Description of "Figure 21-25 Manager and Certifier Stages"
Click the pencil icon after the two stages.
In the Vote Outcome dialog box, set the voted outcome to APPROVE. Set the default outcome to REJECT. This is because when both the approver reject the task, the request moves to completed state based on the default outcome.
Select the Share attachments and comments option.
In the Vote Outcome dialog box, click OK.
Ensure that the Immediately trigger voted outcome when minimum percentage is met option is selected.
Select <edit participant> in Manager Stage, and click Edit.
In the Add Participant Type dialog box, set the Participant type to Single. From the Build a list of participants using list, select Rule-based to build the participant list using Rules.
In List RuleSet field, enter Manager. Also, edit the label as Manager.
In the Add Participant dialog box, click OK. The ParallelApprovalRules.rules tab is displayed.
Create a rule, as shown in Figure 21-26.

Figure 21-26 Manager Participant Rule

Description of "Figure 21-26 Manager Participant Rule"

Note:
In the Create Rule page, the <insert pattern > in the IF clause is not displayed by default. To display <insert pattern>, expand Rule1 by clicking the two down arrows before Rule1 label, and select the Advanced Mode option as shown in Figure 21-26.
Similarly, configure the Certifier stage by specifying the following values in the Add Participant Type dialog box:
- Type: Single
- Label: Certifier
- Build a list of participants using: Rule-based
- List Ruleset: Certifier
- Select Let participants manually claim the task
Create a participant rule, as shown in Figure 21-27.

Figure 21-27 Certifier Rule

Description of "Figure 21-27 Certifier Rule"

21.4.5.4.2 Configuring the Serial Approval Task

To configure the serial approval task:

Switch to the SOA Composite view.
Edit the Serial Approval Task.
Click the Data tab.

Add the parameters listed in the following table:

Parameter	Data Type
RequestID	{http://www.w3.org/2001/XMLSchema}string
RequestModel	{http://www.w3.org/2001/XMLSchema}string
RequestTarget	{http://www.w3.org/2001/XMLSchema}string
RequesterDetails	{http://xmlns.oracle.com/request/RequestDetails}RequesterDetails
BeneficiaryDetails	{http://xmlns.oracle.com/request/RequestDetails}BeneficiaryDetails
ObjectDetails	{http://xmlns.oracle.com/request/RequestDetails}ObjectDetails
OtherDetails	{http://xmlns.oracle.com/request/RequestDetails}OtherDetails
url	{http://xmlns.oracle.com/request/RequestDetails}url
Catalogdata	{http://xmlns.oracle.com/RequestServiceApp/RequestDataService/CatalogData}CatalogData
RequesterDisplayName	{http://www.w3.org/2001/XMLSchema}string
BeneficiaryDisplayName	{http://www.w3.org/2001/XMLSchema}string
Requester	{http://www.w3.org/2001/XMLSchema}string

Verify the task parameters in the Data tab.
Click the General tab.
Set the Task Title to <%/task:task/task:payload/ns2:BeneficiaryDetails/ns2:DisplayName%> has submitted a request for approval.
Set the Task Owner to Group and SYSTEM ADMINISTRATORS.
Click the Notification tab, and then click Advanced.
Select the Make notification actionable option.
Click the Assignment tab.
Add a Sequential stage and rename the stages as Manager and Review Team, as shown in Figure 21-28.

Figure 21-28 Serial Stages

Description of "Figure 21-28 Serial Stages"
Edit the Manager stage.
In the Add Participant Type dialog box, set the Participant type to Single and build the participant list using Rules.
Create the participant list rule as shown in Figure 21-29.

Figure 21-29 Rule for Manager Stage

Description of "Figure 21-29 Rule for Manager Stage"
Similarly, configure the Review Team stage.
Create the participant list rule as shown in Figure 21-30.

Figure 21-30 Rule for Review Team Stage

Description of "Figure 21-30 Rule for Review Team Stage"

21.4.5.4.3 Configuring the Default Approval Task

To configure the default approval task:

Switch to SOA composite view.
Edit the Approval Task.
Click the General tab.
Set the task title, as shown in Figure 21-31.

Figure 21-31 Default Approval Task

Description of "Figure 21-31 Default Approval Task"
Click Assignment.
Select Stage1.Participant1, and click Edit.
In the Add Participant Type dialog box, set the Participant type to Single. From the Build a list of participants using list, select Rule-based to build the participant list using Rules.
Enter Manager in Label and RuleSet, and click OK, which opens the rules.
Create a Participant list rule, as shown in Figure 21-32.

Figure 21-32 Participant List Rule

Description of "Figure 21-32 Participant List Rule"

21.4.5.5 Configuring the Human Task and BPEL Mappings

Configuring the Human Task and BPEL mappings involves:

Configuring the Serial Approval Human Task
Configuring the Parallel Human Task
Configuring Auto Approval

21.4.5.5.1 Configuring the Serial Approval Human Task

To configure the serial approval Human Task:

Switch to BPEL process.

Add the following condition to the Serial Approval switch:

bpws:getVariableData('workflowtype','/ns18:StageOutput/ns18:stageType') = 'Serial'

Drag and drop a Human Task activity from the SOA Components into the Serial Approval switch, as shown in Figure 21-33.

Figure 21-33 Human Task Activity

Description of "Figure 21-33 Human Task Activity"
Edit the Human Task, and in the Human Task dialog box, select the Serial Approval Human Task definition.
Map Initiator to requester login, and map the task parameters to the BPEL variable as shown in Figure 21-34.

Figure 21-34 Task Parameters and BPEL Variable Mapping

Description of "Figure 21-34 Task Parameters and BPEL Variable Mapping"
Click the Advanced tab.
Map the Identification Key to the Request ID as shown in Figure 21-35.

Figure 21-35 Identification Key and Requester ID Mapping

Description of "Figure 21-35 Identification Key and Requester ID Mapping"
Map Iniatator to requester login, and then click Apply and OK.
Select the Switch case for Task outcome is REJECT.

Replace the existing condition script with the following:

bpws:getVariableData('SerialApproval1_globalVariable','payload','/task:task/task:systemAttributes/task:outcome') = 'REJECT'

Select and edit the Assign activity under Task outcome is REJECT.
Delete all the copy rules except one. The copy rule that you retain can be any one so that you can replace it in the Source view.
Save and click the Source tab.
Select the copy activity.

Replace the activity with the following:

<sequence>
   <assign>
      <copy>
                <from expression="string('rejected')"/>
                <to variable="outputVariable"
                    part="payload"
                    query="/ns3:processResponse/ns3:result"/>
      </copy>
      <copy>
                <from expression="ora:getConversationId()"/>
                <to variable="Invoke_1_callback_InputVariable_1"
                    part="parameters"
                    query="/ns1:callback/arg0"/>
      </copy>
      <copy>
               <from expression="string('rejected')"/>
               <to variable="Invoke_1_callback_InputVariable_1"
                   part="parameters"
                   query="/ns1:callback/arg1"/>
      </copy>
   </assign>
</sequence>

Repeat the steps for the Task outcome is APPROVE. Select the Switch Case and copy the following in the Condition field:

bpws:getVariableData('SerialApproval1_globalVariable','payload','/task:task/task:systemAttributes/task:outcome') = 'APPROVE'

Select the Assign activity under the Approve outcome, and replace the copy rules with the following:

<sequence>
          <assign>
            <copy>
                  <from expression="string('approved')"/>
                  <to variable="outputVariable"
                      part="payload"
                      query="/ns3:processResponse/ns3:result"/>
            </copy>
            <copy>
                <from expression="ora:getConversationId()"/>
                <to variable="Invoke_1_callback_InputVariable_1"
                    part="parameters"
                    query="/ns1:callback/arg0"/>
            </copy>
            <copy>
               <from expression="string('approved')"/>
               <to variable="Invoke_1_callback_InputVariable_1"
                   part="parameters"
                   query="/ns1:callback/arg1"/>
            </copy>
          </assign>
</sequence>

Select the Assign activity under the Otherwise outcome, and replace the copy rules with the following:

<sequence>
    <assign>
        <copy>
             <from expression="bpws:getVariableData('SerialApproval1_globalVariable','payload','/task:task/task:systemAttributes/task:state')"/>
             <to variable="outputVariable" part="payload"
                        query="/ns3:processResponse/ns3:result"/>
         </copy>
         <copy>
            <from expression="ora:getConversationId()"/>
            <to variable="Invoke_1_callback_InputVariable_1"
                part="parameters"
                query="/ns1:callback/arg0"/>
         </copy>
         <copy>
            <from expression="bpws:getVariableData('SerialApproval1_globalVariable','payload','/task:task/task:systemAttributes/task:state')"/>
            <to variable="Invoke_1_callback_InputVariable_1"
                part="parameters"
                query="/ns1:callback/arg1"/>
         </copy>
         </assign>
</sequence>

21.4.5.5.2 Configuring the Parallel Human Task

To configure the parallel Human Task:

Add the following condition to the Parallel Approval switch activity:

bpws:getVariableData('workflowtype','/ns18:StageOutput/ns18:stageType') = 'Parallel'

Drag and drop a Human Task activity from the SOA Components into the Parallel Approval switch.
Select the Parallel Approval Human Task.
Map the Human Task parameters in the same way as the Serial Human Task.
Map the Assign activity for the APPROVE outcome in the same way as the equivalent in the Serial Human Task.
Map the Assign activity for the REJECT outcome in the same way as the equivalent in the Serial Human Task.
Map the Assign activity for the Otherwise outcome in the same way as the equivalent in the Serial Human Task.

Note:
You must specify appropriate global variable (ParallelApproval1_globalVariable) in the copy activity.

21.4.5.5.3 Configuring Auto Approval

To configure auto approval:

Drag and drop an Assign activity in the Otherwise switch case.
Select the Assign activity, and switch to Source view.

In the Assign activity, replace the following:

<assign name="Assign1"/>

With:

<sequence>
          <assign>
            <copy>
                  <from expression="string('approved')"/>
                  <to variable="outputVariable"
                      part="payload"
                      query="/ns3:processResponse/ns3:result"/>
            </copy>
            <copy>
                <from expression="ora:getConversationId()"/>
                <to variable="Invoke_1_callback_InputVariable_1"
                    part="parameters"
                    query="/ns1:callback/arg0"/>
            </copy>
            <copy>
               <from expression="string('approved')"/>
               <to variable="Invoke_1_callback_InputVariable_1"
                   part="parameters"
                   query="/ns1:callback/arg1"/>
          </copy>
       </assign>
</sequence>

21.4.5.6 Deploying the SOA Composite

To deploy the SOA composite:

Select File, Save All to save your work.
Right-click the project, and select Deploy, COMPOSITE_NAME, Deploy to Application server. Alternatively, you can deploy to SAR (SOA Archive ), and then deploy it by using Oracle Enterprise Manager.
Note:
- The default version is 1.0. You can also change the version, if you have existing composite instances running.
- If you are redeploying the composite and you have added or removed one or more human tasks, then it is recommended to deploy with a different version.

21.4.5.7 Creating the Approval Policies

The SOA composite that you have created can be used for all requests other than user operations, such as self-registration, create, modify, disable, enable, and delete. To ensure that all requests other than user operations invoke this composite, you must create an approval policy in Oracle Identity Manager. To create the approval policies in Oracle Identity Manager:

Login to Oracle Identity System Administration.
Under Policies, select Approval Policies.
Create a request-level approval policy for Provision Application Instance, and set it to auto approve.
Create an operational-level approval policy for Provision Application Instance, and click Approval Process.
Select the SOA composite that you deployed.
Specify scope type to be All.
Create a default approval rule:

Request.Request Type = Provision Application Instance
Save the approval policy.

Tip:

You can access custom attribute's value of entities, such as catalog, user, role, or organization, supported by the request web service is SOA composite BPEL process. The custom attributes or UDFs are part of the CustomAttribute element. An instance of catalog entity containing UDF is:

<ns12:CustomAttribute Name="ApproverRolePhoneNumber">
    <ns5:Value>1234</ns5:Value>
</ns12:CustomAttribute>
<ns12:CustomAttribute Name="ApproverRoleEmailId">
   <ns5:Value>approver@mydomain.com</ns5:Value>
</ns12:CustomAttribute>

For example, to access the ApproverRolePhoneNumber catalog UDF value in BPEL process, specify the following:

bpws:getVariableData('catalogDetails','CatalogData','/ns22:CatalogData/ns22:CustomAttribute[@Name = string("ApproverRolePhoneNumber")]/ns24:Value')

21.5 Configuring Default Request-Level and Operation-Level Approval Composites

You can configure the default request-level and operation-level composites by setting the DefaultRequestLevelComposite and DefaultOperationLevelComposite properties in the oim-config.xml file. You can edit these properties by using System MBean Browser in Oracle Enterprise Manager. The default values for these properties are default/DefaultRequestApproval!3.0 and default/DefaultOperationalApproval!3.0 respectively.

The values for these properties are in the following format:

NAMESPACE/COMPOSITE_NAME!VERSION

For example:

default/AddAccessApproval!2.0

If you change the default values of the DefaultRequestLevelComposite and DefaultOperationLevelComposite properties, then you must restart Oracle Identity Manager.

Note:

The composites configured as default request-level and operation-level composites would be applicable for all request types. Therefore, these composites must be designed to work with all the request types.

21.6 Creating and Deploying Custom Task Details Taskflow

By default, all tasks are configured to use the default task details page in pending approvals. This taskflow is not customizable. However, you might want to customize the UI or show some other information in the task details page. This section describes how to build your own taskflow, and configure the human task in the DefaultRequestApproval composite to invoke your custom taskflow.

This section contains the following topics:

Prerequisites for Developing Custom Task Details Taskflow
Developing Custom Task Details Taskflow
Developing Custom Task Details for Email Notification (Optional)
Deploying the Task Details Taskflow
Configuring Human Task and Taskflow Permissions
Testing the Custom Taskflow

21.6.1 Prerequisites for Developing Custom Task Details Taskflow

Before developing a custom task details taskflow, you must have the following software installed on your computer:

Oracle Identity Manager 11g Release 2 (11.1.2.2.0)
Oracle SOA 11g (11.1.1.7.0)
JDeveloper 11g (11.1.1.7.0) with Oracle SOA Composite Editor extension

21.6.2 Developing Custom Task Details Taskflow

To build a custom taskflow for the human task in the DefaultRequestApproval composite:

Open Jdeveloper and create a new Generic Application. To do so:
1. Enter Application Name as RequestApprovalTaskDetailsApp, and then click Next.
2. Enter Project Name as RequestApprovalTaskDetails. Do not select any project technologies.
3. Click Finish.
Add Oracle Identity Manager shared library. To do so:
1. Right-click RequestApprovalTaskDetails project, and select Project Properties, Libraries and Classpath.
2. Click Add Library.
3. Click Load Dir.
4. Navigate to the IAM_HOME/server/jdev.lib/ directory, and click Select.
  
  Note:
  IAM_HOME is the path to the Oracle Identity Manager home directory, for example, BEA_HOME/Oracle_IDM1/. Here, BEA_HOME is the path to the middleware directory in Oracle Identity Manager installation.
5. Select OIM View Shared library, OIM Model Shared library, and then click OK.
6. Click OK.
Create task details taskflow. To do so:
1. Navigate to the following directory in shiphome:
  
  IAM_HOME/server/workflows/composites/
2. Unzip the DefaultRequestApproval.zip file.
3. Go back to Jdeveloper, right-click RequestApprovalTaskDetails, and select New.
4. Select Web Tier, JSF, ADF task flow based on human task.
5. In the file browser, navigate to the directory in which you unzipped DefaultRequestApproval.zip. Select the DefaultRequestApproval/ApprovalTask.task file
6. In the Create Task flow dialog box, provide the following values:
  
  File Name: request-approval-details-tf.xml
  
  Task Flow ID: request-approval-details-tf
7. Click OK.
Delete hwtaskflow.xml. To do so, go to Application Sources under RequestApprovalTaskDetails project, and then delete hwtaskflow.xml.

For more information on workflow for multiple human tasks, see "How To Reuse the Task Flow Application with Multiple Human Tasks" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite Guide.
Create the task details page. To do so:
1. Open request-approval-details-tf.xml. Switch to diagram mode.
2. Rename taskdetails1_jspx view activity to request-approval-details.
3. Right-click the request-approval-details view activity, and select Create Page. Provide the following values:
  
  File name: request-approval-details.jspx
  
  Initial Page layout and content: Blank Page
4. Click OK.

Add managed bean for this page. To do so:

Right-click the RequestApprovalTaskDetails project, and select New, Java Class. Provide the following values:

Name: RequestApprovalDetailsStateBean

Package: oracle.iam.ui.custom.view.backing
Click OK.

Add the following code to the managed bean:

package oracle.iam.ui.custom.view.backing;
 
import javax.el.ELContext;
import javax.el.ExpressionFactory;
import javax.el.ValueExpression;
 
import javax.faces.application.Application;
import javax.faces.context.FacesContext;
 
import oracle.iam.ui.platform.model.config.ConstantsDefinition;
 
 
public class RequestApprovalDetailsStateBean implements java.io.Serializable{
    public RequestApprovalDetailsStateBean() {
        super();
    }
    
    private String requestAction = ConstantsDefinition.REQUEST_ACTION_APPROVAL_UPDATE;
    private String requestType = ConstantsDefinition.REQUEST_TYPE_VIEW_DETAIL;
    
    public void setRequestAction(String requestAction) {
        this.requestAction = requestAction;
    }
 
    public String getRequestAction() {
        return requestAction;
    }
 
    public void setRequestType(String requestType) {
        this.requestType = requestType;
    }
 
    public String getRequestType() {
        return requestType;
    }
    
    public String getUserIds() {
        Object benefDisplayName = getValueFromELExpression("#{bindings.DisplayName.inputValue}");
        //benefDisplayName would be "None" if beneficiary does not exist
        if (benefDisplayName != null &&             !ConstantsDefinition.NONE_BENEF_DISPLAY_NAME.equalsIgnoreCase(benefDisplayName.toString()))
            return benefDisplayName.toString();
        
        Object requestTarget = getValueFromELExpression("#{bindings.RequestTarget.inputValue}");
        if (requestTarget != null)
            return requestTarget.toString();
        
        return "";
    }
    
    private Object getValueFromELExpression(String expression) {
        FacesContext facesContext = FacesContext.getCurrentInstance();
        Application app = facesContext.getApplication();
        ExpressionFactory elFactory = app.getExpressionFactory();
        ELContext elContext = facesContext.getELContext();
        ValueExpression valueExp =
            elFactory.createValueExpression(elContext, expression,
                                            Object.class);
        return valueExp.getValue(elContext);
    }
    
    
}

Open request-approval-details-tf.xml in Overview mode. Select Managed Beans sections and register the managed bean with the following details:

Name: requestApprovalDetailsStateBean

Class: oracle.iam.ui.custom.view.backing.RequestApprovalDetailsStateBean

Scope: pageFlow

Create the details page structure. To do so:
1. Open request-approval-details.jspx.
2. From the Component Palette, add a panelStretchLayout to the page. In the Property Inspector, set TopHeght==auto for panelStretchLayout.
3. Go to Data controls in Application Navigator. Expand RequestApprovalTaskDetails_ApprovalTask, getTaskDetails, Return. Drag and drop Task from Data Controls on to the Top Facet of panelStretchLayout, as shown in Figure 21-36. From the context menu, select Human Task, Task Action. The Human task actions are added to the Top Facet.
  
  Figure 21-36 Dragging Task to the Top Facet
  
  Description of "Figure 21-36 Dragging Task to the Top Facet"
4. From the Component Palette, add a panelTabbed layout to the Center Facet of panelStretchLayout.
5. From the Component Palette, add two showdetailItem components to the panelTabbed layout. From property inspector, set the text name for these components as Request Information and Task Information.
6. Click the Request Information tab. From the property inspector, set attribute stretchChildren=first.
7. Add another panelStretchLayout in Request Information tab. Set attribute topHeight=auto for this panelStretchLayout. Figure 21-37 shows the Request Information and Task Information tabs.
  
  Figure 21-37 The panelTabbed Layout
  
  Description of "Figure 21-37 The panelTabbed Layout"
Populate the Request Information tab. To do so:
1. Go to Navigator Display Options, and select Show Libraries, shown in Figure 21-38. This will show OIM View Shared Library in the Application Navigator.
  
  Figure 21-38 OIM View Shared Library
  
  Description of "Figure 21-38 OIM View Shared Library"
2. In the Application Navigator, expand OIM View Shared Library, WEB-INF/oracle/iam/ui/catalog/tfs. Drag and drop request-summary-information-tf.xml to the Top Facet of PanelStretchLayout added in step 7g. The Create context menu is displayed. Select Region.The Edit Task Flow Binding dialog box is displayed. You can provide parameters to the taskflow later. Therefore, click OK.
3. Similarly, drag and drop catalog-tf.xml to the Center Facet of PanelStretchLayout added in step 7g. The Create context menu is displayed. Select Region. The Edit Task Flow Binding dialog box is displayed. Click OK.
4. Click the Bindings tab at the bottom of the page to view the bindings. Click the plus (+) sign to add a binding in the following way:
  
  i) Enter the following and click OK:
  
  Category: Generic Bindings
  
  Item to be created: attributeValues
  
  ii) Click Add Datasource. Select RequestApprovalTaskDetails_ApprovalTask, getTaskDetails, Return, Task, Payload. Click OK.
  
  iii) Specify Attribute as RequestID, and click OK.
5. Under executables, select taskflow-requestsummaryinformationtf1. In the Property Inspector, add a taskflow parameter by clicking the plus (+) sign. Edit the value field, and update it with #{bindings.RequestID.inputValue}, as shown:
  
  ID=requestID, Value= #{bindings.RequestID.inputValue}
6. Click the plus (+) sign to add another binding. This binding will be referenced in RequestApprovalDetailsStateBean.
  
  i) Enter the following and click OK:
  
  Category: Generic Bindings
  
  Item to be created: attributeValues
  
  ii) Click Add Datasource. Select RequestApprovalTaskDetails_ApprovalTask, getTaskDetails, Return, Task, Payload, BeneficiaryDetails. Click OK.
  
  iii) Specify Attribute as DisplayName, and click OK.
7. Click the plus (+) sign to add another binding. This binding will be referenced in RequestApprovalDetailsStateBean.
  
  i) Enter the following and click OK:
  
  Category: Generic Bindings
  
  Item to be created: attributeValues
  
  ii) From the list, select datasource RequestApprovalTaskDetails_ApprovalTask, getTaskDetails, Return, Task, Payload.
  
  iii) Specifiy Attribute as RequestTarget, and click OK.
8. Select taskflow-catalogtf1 in Executables, click Edit on the top-right corner of Executables, and edit the values of the following in the Edit Task flow Binding dialog box:
  - Id=requestId, Value= #{bindings.RequestID.inputValue}
  - Id=requestType, Value=#{pageFlowScope.requestApprovalDetailsStateBean.requestType}
  - Id=requestAction, Value=#{pageFlowScope.requestApprovalDetailsStateBean.requestAction}
  - Id=userIds, Value=#{pageFlowScope.requestApprovalDetailsStateBean.userIds}
Populate the Task Information tab. To do so:
1. Switch to Design mode. Click the Task Information tab.
2. In the Application Navigator, go to Data Controls. Expand RequestApprovalTaskDetails_ApprovalTask, getTaskDetails, Return. Drag and drop Task in the Task Information tab. The Create context menu is displayed. Select Human Task, Complete Task without Payload, as shown in Figure 21-39.
  
  Figure 21-39 Task Details DataControl
  
  Description of "Figure 21-39 Task Details DataControl"
3. A panelHeader wrapped inside panelGroupLayout is added to the Task Information tab. Navigate to the panelHeader and delete the Toolbar Facet of the panelHeader. The task actions have already been in step 7c). In addition, task details, task history, comments, and attachments are also added to the Task Information tab.
4. Save your work.

21.6.3 Developing Custom Task Details for Email Notification (Optional)

By default, for sending email notification, if there is no separate page for email, then the same task details page developed in "Developing Custom Task Details for Email Notification (Optional)" is sent in email notification.

Sometimes, limited information needs to be sent in email notification. In such scenarios, separate page for email notification can be developed. The email page will also be part of the same task details taskflow.

For more information on building custom taskflow for email, refer to "Creating an Email Notification" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

21.6.4 Deploying the Task Details Taskflow

To deploy the task details taskflow:

Deploy the Task Details as an ADF library jar. To do so:
1. Right-click RequestApprovalTaskDetails, Project Properties, Deployment.
2. Click New. The Create deployment profile dialog box is displayed.
3. Provide following values, and click OK.
  
  Archive Type: ADF Library Jar File
  
  Name: adflibRequestApprovalTaskDetails
4. Right-click RequestApprovalTaskDetails, and select Deploy, adflibRequestApprovalTaskDetails.
5. In the deployment action popup, click Finish.
Package the adflibRequestApprovalTaskDetails.jar in custom shared library. To do so:
1. Navigate to the IAM_HOME/server/apps/ directory.
2. Create following directory structure:
  
  WEB-INF/lib/
3. Copy adflibRequestApprovalTaskDetails.jar to the WEB-INF/lib/ directory.
4. Update IAM_HOME/server/apps/ oracle.iam.ui.custom-dev-starter-pack.war to add adflibRequestApprovalTaskDetails.jar. For example:
```
jar uvf oracle.iam.ui.custom-dev-starter-pack.war WEB-INF/*
```
Restart Oracle Identity Manager managed server for the changes to custom shared library to take effect.

21.6.5 Configuring Human Task and Taskflow Permissions

To configure Human Task and taskflow permissions:

Add view permission for custom taskflow by using Authorization Policy Manager (APM). To do so:
1. Login to APM application as WebLogic user.
2. Navigate to Applications, OracleIdentityManager, Resource Types. Click Open.
3. Click New to create a new resource type. Provide following details:
  - Display Name: ADF Taskflows
  - Name: ADFTaskFlows
  - Actions: personalize, customize, grant, view. Click New to add each action.
  - Supports Resource Hierarchy: No
  - Resource Delimiter: Slash(/)
  - Evaluation Logic: Permission Class
  - Permission Class: oracle.adf.controller.security.TaskFlowPermission
  - Action Name Delimiter: Comma(,)
4. Click Save.
5. Navigate to Applications, OracleIdentityManager, Default Policy Domain, Resource Catalog, Resources. Click Open.
6. Click New to create a new resource. Provide the following values, and then click Save.
  - Resource Type: Select the resource type created in step 1(c).
  - Display Name: Provide a display name for your custom taskflow.
  - Name: Provide the name of the custom taskflow in the following format:
```
TASKFLOW_DOCUMENT#TASKFLOW_ID
```
    For example:
```
/WEB-INF/request-approval-details-tf.xml#request-approval-details-tf
```
  - Description: Provide a description for the custom taskflow.
  Note:
  For each custom taskflow, you must create a resource as mentioned in step 1(f). You can use the same resource type that you created in step 1(c) for all your custom taskflows.
7. Navigate to Applications, OracleIdentityManager, Default Policy Domain, Authorization Policies. Click Open.
8. Select Find By Principal, and click Search. If you want to add to a displayed existing policy, then select it and click Open. Otherwise, click New to create a policy.
9. Add name and principals for the new policy.
10. Click Add Targets (+) sign. The Search Targets dialog box is displayed.
11. Click the Resources tab. Provide the resource type as defined in step 1(f), and then click Search.
12. Select the resource created in step 1(f). Click Add Selected.
13. Click Add Targets. The resource is added to the Targets table.
14. Expand the resource that you added to the table. Select the permissions you want to apply to the taskflow.
15. Click Apply.
Configure human task to use the custom taskflow. To do so:
1. Login to Oracle Enterprise Manager as WebLogic user.
2. Navigate to Farm_IAM_DOMAIN, SOA, soa_infra (SOA_SERVER), default, DefaultRequestApproval [4.0].
3. Click Component Metrics, Approval Task.
4. Click the Administration tab.
5. Modify the URI in the existing entry to point to the custom taskflow, as shown:
  - Application Name: ANY_NAME
  - Host Name: OIM_SERVER_HOSTNAME
  - HTTP Port: OIM_HTTP_PORT
  - HTTPS Port: OIM_HTTPS_PORT (Optional)
  - URI: /identity/faces/adf.task-flow?_id=request-approval-details-tf&_document=WEB-INF/request-approval-details-tf.xml

21.6.6 Testing the Custom Taskflow

To test custom taskflow:

Login to Oracle Identity Self Service as an end user.
Go to My Information, and modify the value of the Telephone attribute. A request is created and the task is assigned to the System Administrator.
Login to Oracle Identity Self Service as System Administrator.
Go to Pending Approvals.
Click the Task Details link of the corresponding request. The custom task details page is displayed.

21.7 Understanding Request Datasets

Request datasets are XML files that store the data that can be associated with requests of given types.

Note:

The information in this section is for reference. Oracle recommends that you do not modify, export, or import request datasets. To extend the user and application instance definition, use the Form Designer in Oracle Identity System Administration. See "Managing Forms" in Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager for information about the Form Designer.

Table 21-2 lists the request types and the associated default request dataset file names that are shipped with Oracle Identity Manager.

Table 21-2 Default Request Datasets Shipped with Oracle Identity Manager

Request Type	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
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
Remove from Roles	RemoveRolesDataset.xml	Role

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

Running Custom Code Based on Request Status Change
Validating Request Data
Prepopulation of an Attribute Value During Request Creation

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

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

You can define the dataset validators and prepopulation adapters associated with the given plug-in. The request datasets associated with the plug-ins can be defined at the time of plug-in registration. The plugin.xml file is used to define the association between plug-ins and dataset validator or prepopulation adapters. The <metadata> node attached with the <plugins> element is used to define the association between data validators and prepopulation adapters.

Note:

DataSetValidator plug-in specified for a dataset cannot be overridden by the plug-in enhancement of specifying the validators metadata in the plugin.xml itself. For instance, the predefined dataset 'ModifyUserDataset' shipped with default validator does not get overridden by the custom implementation class. Therefore, the validator in dataset will be given precedence, currently there is no option to override it.

Example 21-1 shows how the plug-ins can be associated with data validators and prepopulation adapters.

Example 21-1 Associating plug-ins With Data Validators and Prepopulate Adapters

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <plugins pluginpoint="oracle.iam.request.plugins.RequestDataValidator">
     <plugin pluginclass= "oracle.iam.plugin.appinst.ApplicationInstanceDataValidator" version="1.0" name="AppInstDataValidator">
     <metadata name="DataValidator">
      <value>AppInstanceDataSet|ADAppDataSet|EBSDataSet</value>
   </metadata>
      </plugin>
  </plugins>
</oimplugins>

In this example, the following line of code indicates defining metadata xml element to indicate that the plug-in is associated with request data validator datasets:

<metadata name="DataValidator">

Note that Attribute name="DataValidator" in the metadata element indicates plug-in associated with request data validators.

Defining the names of the datasets to be associated with the current plug-in is indicated by the following line:

<value>AppInstanceDataSet|ADAppDataSet|EBSDataSet</value>

Note:

Request dataset names must be delimited by the single pipe character (|).

Consider the following scenarios:

Scenario I: Provisioning Users to a Target System
Scenario II: Provisioning or Modifying Entitlement Request

21.8.2.1 Scenario I: Provisioning Users to a Target System

Suppose Oracle Identity Manager is configured for provisioning users to the AD User APAC target. A RequestDataValidator specifies ADUserDataValidator is configured for the corresponding request dataset, as shown:

<plugin pluginclass= "oracle.iam.plugin.appinst.ADUserDataValidator" version="1.0" name="ADUserDataValidator">
<metadata name="DataValidator">
<value>ADUserAPACDataSet</value>
</metadata>
</plugin>

Later, if the System Configurator wants to configure Oracle Identity Manager for provisioning users to the AD User EMEA target, then the System Configurator would create a new application instance, and associate a UI form with it. Request dataset would be auto-generated in the process. If the data-validator is to be re-used for this request dataset, then perform the following:

Edit plugin.xml of the ADUserDataValidator.
In the <metadata> <value> subtag, add the name of the new request dataset separated by a delimiter. For example:
```
<value>ADUserAPACDataSet|ADUserEMEADataSet</value>
```
Re-register the data-validator plug-in.

21.8.2.2 Scenario II: Provisioning or Modifying Entitlement Request

Entitlement data provided as part of Provision Entitlement and Modify Entitlement request can be validated by creating a dataset validator plug-in and specifying the following in the plug-in metadata (plugin.xml):

<metadata name="DataValidator">
      <value>EBSForm.UD_EBS_RESP</value>
</metadata>

Here, EBSForm is the name of the form associated with the application instance on which the account is provisioned, and UD_EBS_RESP is the name of the child form corresponding to the entitlement. UD_EBS_RESP identifies the entitlement type.

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

Defining metadata element to indicate that the plug-in is mapped to request data set attributes for filling up prepopulated data is indicated by the following line:

<metadata name="PrePopulationAdapater">

The association is defined by combining dataset name with attribute name in the following format:

<DATASET_NAME>::<ATTRIBUTE_NAME>

For example:

AppInstanceDataSet::First Name

Multiple attributes can be associated with the same prepopulation plug-in, where each association is separated by the single pipe character (|). For example:

<datasetname1>::<attribute1> | <datasetname2>::<attributename2>|<datasetname3>::<attribute3>

The following is an example of prepopulation plug-in:

<plugins pluginpoint="oracle.iam.request.plugins.PrePopulationAdapter">
  <plugin pluginclass= "oracle.iam.plugin.appinst.ApplicationInstancePrePopulateAdapter" version="1.0" name="AppInstPrepopAdapter">
     <metadata name="PrePopulationAdapater">
   <value>
AppInstanceDataSet::First Name|ADAppDataSet::Last Name
  </value>
   </metadata>
   </plugin>
  </plugins>

Note:

In addition to creating request datasets by using the catalog Form Designer, you can manually upload request datasets to MDS. You can also define DataSetValidator or PrepopulationAdapter elements within the request dataset. These dataset validators or prepoulation adapters configured in the dataset have the highest priority over other configuration.

For example, a plug-in EBSUserDataValidator is registered to associate it with a request dataset EBSUSerDataSet, but the dataset has not been created or uploaded. Another plug-in ADUserDataValidator is registered but not associated with any request dataset. When you later create the request dataset EBSUSerDataSet and use it for creating requests, the plug-in EBSUserDataValidator is called for validating the request data. Then, you add the DataSetValidator element to the request dataset EBSUSerDataSet that you manually created, and specify another plug-in ADUserDataValidator. When you use EBSUSerDataSet to create requests, the plug-in ADUserDataValidator is called. This is because ADUserDataValidator is configured as a part of the request dataset. If the DataSetValidator entry is removed from EBSUSerDataSet, then the plug-in EBSUserDataValidator is invoked to validate the request data.

21.9 Enabling Auto-Approval for Self Registration Requests

Approval policies can be configured at request level or operation level. They can use all the data available at the request and operational levels to construct a rule. The rule helps determine whether the request should be auto-approved or a SOA composite should be invoked. For information about enabling auto-approval for request and operation levels, see "Creating Approval Policies" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

After the approval policies are updated, perform the following steps to enable auto-approval for self registration requests:

To assign the organization automatically, add a preprocess handler that sets the organization value in the orchestration. The order should be set such that it is executed before the approval-related handlers. Set this to be executed soon after the CreateUserPreProcessHandler. See Chapter 28, "Developing Event Handlers" for information about orchestration and event handlers.
By default, the Role/User Type set for the self registration requests is Part-Time Employee. If you want to overwrite this value, then change the plug-in configured in the SelfCreateUserDataset.xml dataset.
You can create a new plug-in implementation for the value/logic required and change the plug-in configured in the dataset to bring the new one in affect. The new plug-in must implement oracle.iam.request.plugins.PrePopulationAdapter.
Register the plug-in that you created by using the Plugin Registration Utility. For details, see "Registering and Unregistering Plug-ins By Using the Plugin Registration Utility".
To update the request dataset:
1. Export the /metadata/iam-features-requestactions/model-data/SelfCreateUserDataset.xml request dataset from the MDS, as described in "Exporting Metadata Files to MDS".
2. Update the name of the plug-in configured for Role attribute, as shown:
```
<AttributeReference name="Role" attr-ref="Role" available-in-bulk="false" 
type="String" length="255" widget="dropdown" lookup-code="Lookup.Users.Role" 
required="true">
<PrePopulationAdapter
classname="oracle.iam.selfservice.uself.uselfmgmt.plugins.RolePrepopulateAdapter" 
name="RolePrepopulateAdapter"/>
</AttributeReference>
```
3. Import the updated request dataset to MDS, as described in "Importing Metadata Files from MDS".