16 Managing Asynchronous Execution

This chapter describes the AsyncService provided by the Oracle Identity and Access Management (IAM) platform and contains the following topics:

Section 16.1, "Overview of AsyncService"
Section 16.2, "Async Routing and Configuration"
Section 16.3, "Troubleshooting Failed Async Tasks"
Section 16.4, "Working with the Diagnostic Dashboard UI"

16.1 Overview of AsyncService

The AsyncService is one of the services provided by the IAM platform to run tasks asynchronously. Tasks are executed asynchronously to improve performance and throughput.

Some Identity Management operations take a long time to complete. So, it makes sense to split these operations into two parts, a short synchronous interaction followed by a long asynchronous process. The user is provided a response at the end of the synchronous interaction, and the remaining operation is performed asynchronously.

The AsyncService allows the Oracle Identity Manager component to submit tasks for asynchronous execution. The caller then performs other tasks. It is the responsibility of the AsyncService to execute this task whenever the computing resources are available.

16.2 Async Routing and Configuration

The AsyncService uses a configuration file, async-messaging.xml, to route and configure Async tasks. This configuration file is stored in the MetaData Store (MDS) schema in Oracle Identity Manager database. The MDS path of the file is /file/async-messaging.xml.

Example 16-1 shows a snippet of the configuration file.

Example 16-1 Sample Configuration File

<tns:async-config>
<task-config>
<class>oracle.iam.reconciliation.impl.ActionTask</class>
<destination>queue/oimReconQueue</destination>
</task-config>
<task-config>
<class>com.thortech.xl.schedule.jms.messagetype.AttestationTaskMessage</class>
<destination>queue/oimAttestationQueue</destination>
<priority>NORMAL</priority>
<maxRetries>2</maxRetries>
</task-config>
<task-config>
<class>com.thortech.xl.schedule.jms.messagetype.AttestationRequestMessage</class>
<destination>queue/oimAttestationQueue</destination>
<priority>HIGH</priority>
</task-config>
<default-config>
<destination>queue/oimDefaultQueue</destination>
<maxRetries>3</maxRetries>
</default-config>
</tns:async-config>

To modify the configuration file, import it by using the MDS import utility, make changes in the file, and then export the modified file by using the MDS export utility. For more information about the MDS utilities, see "MDS Utilities and User Modifiable Metadata Files" in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager.

16.2.1 Configuration Parameters

The System Administrators can configure the following parameters in the configuration file for Async tasks:

Destination: You can assign high-volume tasks to their own dedicated queues. For instance, in Example 16-1, all the Async tasks are assigned to the same destination queue attestationQueue. You can decide where to send each massage by creating separate destination queues for each Async task.

Note:

You must ensure that the queue exists in the Application Server before assigning a task to it. For information about creating queues, see Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.
Priority: You can set a priority when multiple types of Async tasks are assigned to the same destination queue. Its value can be one of the following:
- NORMAL
- HIGH
- LOW
Max Retries: Async task execution error recovery is handled in two ways, automated and manual. The automated retry mechanism uses a scheduled task to retry all failed tasks at specific intervals. Max Retries parameter allows the System Administrator to specify the maximum number of times a task can be retried in the event of an execution failure. See "Troubleshooting Failed Async Tasks" for detailed information about error handling and recovery mechanisms.

16.3 Troubleshooting Failed Async Tasks

Errors may occur during execution of tasks or messages. The Async task execution error recovery is a combination of automated retries and manual intervention. If a task encounters an error during task execution, then it is added to a FailedTasks table and the System Administrator is notified. See "Automated Retry Error Handling Mechanism" and "Manual Retry Error Handling Mechanism" for detailed information about error handling mechanisms.

16.3.1 Automated Retry Error Handling Mechanism

A scheduled task is provided to automate retries of failed tasks at periodic intervals. The maximum number of times a task is retried by the scheduled task can be configured by using the max-retries property of the async task, as shown in Example 16-2.

Example 16-2 Configuring Max Retries

<async-task>
    <class>oracle.iam.reconciliation.impl.ActionTask</class>
    <destination>reconQueue</destination>
    <max-retries>2</max-retries>
</async-task>

16.3.2 Manual Retry Error Handling Mechanism

The System Administrator can use the Oracle Identity Manager Diagnostic Dashboard User Interface (UI) to view the failed tasks and retry a task after taking the appropriate remedial action. See "Working with the Diagnostic Dashboard UI" for more information on Oracle Identity Manager Diagnostic Dashboard UI.

16.4 Working with the Diagnostic Dashboard UI

The Diagnostic Dashboard provides a UI for the System Administrator to view and retry failed Async tasks. This section contains the following topics:

Starting the Diagnostic Dashboard UI
Viewing Failed Async Tasks
Retrying Failed Async Tasks
Resubmitting Failed Async Tasks
Purging Failed Async Tasks

16.4.1 Starting the Diagnostic Dashboard UI

To start the Diagnostic Dashboard UI:

Access the Diagnostic Dashboard home page by using the following URL:

http://host:port/XIMDD
Click the Manage Failed Tasks link on the left menu pane.
Enter the user name and password. The Manage Failed Tasks page is displayed.

Note:

You need System Administrator privileges to access the Diagnostic Dashboard UI.

16.4.2 Viewing Failed Async Tasks

The System Administrator can view the details of each failed task, for instance the cause for the task to fail and the remedial action to be undertaken.

The user can view the details of the failed tasks by either providing the filter criteria or by clicking the Search button.

16.4.2.1 To view failed async tasks

Log in to the Diagnostic Dashboard main page. See "Starting the Diagnostic Dashboard UI" for more information.
Perform one of the following to view a list of failed tasks.
- Click Search to view a list of all the failed tasks.
- Search for the failed task based on the following filter criteria.
  - Task Name: Type the name of the failed task.
  - Category: Type the category of the failed task.
  - Between: Specify the date range.
  - Select the Exclude if retries are remaining option if you do not want to view the tasks for which automated retries are still pending.
  Click Search after providing the filter criteria. The list of failed async tasks are displayed, as shown in Figure 16-1:
  
  Figure 16-1 Failed Async Tasks
  
  Description of "Figure 16-1 Failed Async Tasks"
Click the Identifier link to view detailed information about the failed task. In this scenario, click 222. The following information is displayed:
- Task Name
- Instance ID
- Category
- Last Execution Time
- Cause
- Action
- Stack Trace

16.4.3 Retrying Failed Async Tasks

The System Administrator can retry a specific failed task directly from the Diagnostic Dashboard UI and then view the results of the retry.

16.4.3.1 To retry failed Async task

Search for the failed task that you want to retry. See "To view failed async tasks" for more information.
Click the Retry link. The retry status for the task is displayed. The following details are provided.
- Retry Status
- Task Summary
- Stack Trace
- Cause
- Resolution

16.4.4 Resubmitting Failed Async Tasks

All the failed tasks are resubmitted to the Async queue. These are later executed asynchronously.

To resubmit failed tasks, click ResubmitAll.

16.4.5 Purging Failed Async Tasks

There are situations when there are numerous failed Async tasks. The System Administrator might feel that there is no use retrying these tasks. In such a scenario, the failed tasks can be purged. The action purge removes all the failed Async tasks from the database. In other words, there no more tasks to retry.

16.4.5.1 To purge failed Async tasks

Search for the failed task that you want to retry. See "To view failed async tasks" for more information.
Click PurgeAll.