17 Using the AIA Message Resubmission Utility

This chapter provides an overview and describes how to use the AIA Message Resubmission Utility. The AIA Message Resubmission Utility enables users to resubmit error messages based on these integration milestones: Queue, Topic, Resequencer, or AQ.

This chapter includes the following sections:

Section 17.1, "Introduction to the AIA Message Resubmission Utility"
Section 17.2, "Using the AIA Message Resubmission Utility User Interface"
Section 17.3, "Using the Command Line AIA Message Resubmission Utility"

17.1 Introduction to the AIA Message Resubmission Utility

To use the AIA Message Resubmission Utility, you must implement error handling and recovery for the asynchronous message exchange pattern.

For more information, see "Configuring Oracle AIA Processes for Error Handling and Trace Logging" in Oracle Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack.

According to this implementation method, when a message cannot be delivered to a service or component in the flow of a global transaction, the message is rolled back to the appropriate source milestone. This source milestone corresponds to a Queue or a Topic, a Resequencer, or AQ. It is here that the message will be persisted until it can be resubmitted for delivery to the service or component.

At the same time, a fault is raised by the Error Handling framework and, if enabled, error notifications and Oracle BPM Worklist tasks regarding the fault are created to alert administrators.

For more information about the Oracle BPM Worklist, see Chapter 16, "Using the Oracle BPM Worklist."

For more information about error notifications, see Chapter 15, "Using Error Notifications."

Once notified, the most natural course of action is for the administrator to bring up the failed service or component. After the service or component is back up and running, the administrator can use the AIA message resubmission utility to recover the faulted message from the source milestone. The AIA message resubmission utility changes the state of the faulted message to the Ready state, enabling it to be picked up by the consumer process.

Messages can be resubmitted by user interface or by command line in these ways:

UI-based AIA Message Resubmission. For more information, see Section 17.2, "Using the AIA Message Resubmission Utility User Interface".
Command line AIA Message Resubmission:
- Oracle AQ store-based resubmission. For more information, see Section 17.3.1, "AQ Store Based Resubmission".
- WLS JMS store-based (can be configured with file system or database). For more information, see Section 17.3.2, "WLS JMS based Resubmission".
- Resequencer-based. For more information, see Section 17.3.3, "Resequencer Based Resubmission".

Figure 17-1 displays the architecture of the AIA message resubmission utility.

Figure 17-1 AIA Message Resubmission Utility Architecture

17.2 Using the AIA Message Resubmission Utility User Interface

This section discusses how to use the message resubmission utility user interface (UI) to resubmit faulted messages. The UI is integrated into the AIA Home page.

The AIA message resubmission utility figures out the milestone that is involved in an integration flow, based on the AIA Fault (canonical) and then resubmits any failed messages by connecting to the actual milestone whether it is a WLS Queue, Topic, Resequencer, or AQ.

The AIA message resubmission UI enables you query the error queue and filter for failed messages of interest, helping you to choose candidates for resubmission.

You can search for faults based on filters like Execution Context ID, Message ID, ErrorCode, Composite Name, Resource Type and other AIA context-related parameters. The ability to search and filter based on ErrorCode, for example, distinguishes system faults from business faults.

The UI also enables bulk resubmission of messages, and lets you quickly re-start a set of integration flows and track their status.

You can still use the command line utility for error resubmission. For more information, see Section 17.3, "Using the Command Line AIA Message Resubmission Utility".

To search for and resubmit faults:

Access the Oracle Application Integration Architecture (AIA) Home Page. In the AIA Message Resubmission Utility area, click the Go button. The Search Error Messages page displays, as shown in Figure 17-2 and Figure 17-3.

Figure 17-2 Search Error Messages Page (1 of 2)

Figure 17-3 Search Error Messages Page (2 of 2)
On the Search page, use the page elements discussed in Table 17-1 to search for faults.

Tip:

You can submit a single row or multiple rows at a time. You can also submit multiple rows of the same resource type at a time. To select multiple rows, press the Ctrl key and click your mouse.

Table 17-1 Search Error Messages Page Elements

Element	Description
Match	Click the All or Any radio button if you want to match all or any of the search criteria.
Advanced	Click Advanced to open the advanced search window, shown in Figure 17-6.
Saved Search	You can save your own search criteria at any time, enabling you to quickly search on status and other criteria, such as failed messages, messages in process, ready for resubmission, or resubmitted messages.
Execution Context ID	A unique identifier used to correlate individual events as being part of the same request execution flow.
Message ID	A string value that uniquely identifies each message sent by a WLS JMS provider/AQ/Resequencer.
Resource Type	Choose from the list of available resource types: Queue, Topic or Resequencer.
Resource Name	Click the Resource Name lookup icon to see all of the available Resource Names and Resource Types. The dialog box shows the milestones that are configured in WLS and are automatically fetched, making it easy to choose the correct resource.
Reported Date	The reported date of an error message. You can filter error messages from a specific date using this field.
Error Code	For BPEL and Mediator process system error notifications, this is the fault code. For business errors using catch blocks, this is the business error code you are catching. This is user-defined, for example, OUT_OF_INV.
System Code	This is the system code of the participating application.
Process Name	This is the business process in which the service is participating.
Service Name	For BPEL and Mediator services, this is the name of the service that experiences the error for which you are defining error notification details. For example, SampleBPELProcess.
Composite Instance ID	Click the Composite Instance ID link to open the Enterprise Manager (EM) flow trace page. The EM drill down page displays the integration flow stack and all of the composites involved in the process orchestration.
Status	Statuses are: Ready for resubmission, Message is in process of resubmission, Resubmitted, Failed.
Search Key	Click the Search Key lookup icon to see all of the available application context keys. The application context correlation fields are automatically fetched and displayed. The context information comes from the source participating applications, for example, Siebel where an order is placed and an OrderID is available. This field tracks and correlates the faulted message in the integration layer.
Search Value	This is the value for a selected application context key. For example, "1001"(value of OrderID).
Search	Click Search to see results in the Search Result page, shown in Figure 17-3.
Reset	Click Reset to clear all search fields.
Save	Click Save to save your search criteria.

Search Results

Use the page elements on the Search Results page to view, submit, or delete messages. Available elements are discussed in Table 17-2.

Table 17-2 Search Results Page Elements

Element	Description
View	Click View and choose Columns, Manage Columns to add or remove columns to your Search Result view.
Delete	Select a fault and click the Delete button.
Submit	Select a fault and click the Submit button.
Detach	Click Detach to separate search the criteria pane and the Search result pane.
Go Up or Go To Top	Click the Go Up or Go to Top buttons to move through the list.
Show as Top button	Click a message and then click Show as Top to move the message to the top of the list.
Last Modified Date	The the last modified date of an error message.
Message Order	The order of an error message that is logged (the sequence number).
Error Stamping	This is the Error Type value used to stamp the JMSCorrelationID. The JMSCorrelationID is used by the custom error listener to identify fault messages that require its custom error handling. For example: AIA_EH_DEFAULT, ORDER_FO
Composite Version	The version of the composite that is deployed and active.
Service Engine	The type of service engine. It can be a BPEL process, human workflow, a decision service, Oracle mediator, or spring that executes the business logic of their respective components within the SOA composite application.
Composite Instance ID	Click the Composite ID field to see the trace flow in Oracle Enterprise Manager (EM). You must be logged in to EM to see the trace flow.
Message ID	Click the Message ID link to open a brand new page.
Business Context	Click the Business Context button to open the search details dialog which provides a search key and search value.
Status	Statuses are: Ready for resubmission, Message is in process of resubmission, Resubmitted, Failed.
Status Message	The Status Message is displayed based on the status of the error message. Ready for resubmission - Message is in error state. Resubmitted - Message is resubmitted to main queue. Failed - Exception stack trace.

Finding Messages of Interest

You can use the Oracle EM Flow Trace page to review the integration flow stack and all of the composites involved in a process orchestration, enabling you to narrow down messages of interest.

You must already be logged in to Oracle EM.

Click the Composite Instance ID link to open the Flow Trace page in EM. This page shows the flow of the message through various composite and component instances as in Figure 17-4.

Figure 17-4 EM Flow Trace Page
After determining a message of interest, close this window. In the AIA Message Resubmission Utility Search Results page, click on the message and then click the Submit button. The Status changes to In Progress as in Figure 17-5.

Figure 17-5 Search Result Page
After the message has been submitted, click Composite Instance ID again to see the EM page where you can see that resubmission has happened--notice that a new set of activities were triggered in the flow trace.

Using the Advanced Search:

Click the Advanced button to open the Search Error Messages window, shown in Figure 17-6. You can search on different criteria and click Search to initiate a search. Click Reset to clear the criteria. Click Add Fields to add search fields.

Figure 17-6 Advanced Search

Viewing Message Detail:

From the Search Result page, click the Message ID to open the specific message and get more detail, as in Figure 17-7.

Figure 17-7 Message ID Detail

17.3 Using the Command Line AIA Message Resubmission Utility

Messages can be resubmitted by user interface or by command line.

For more information about using the UI, see Section 17.2, "Using the AIA Message Resubmission Utility User Interface".

17.3.1 AQ Store Based Resubmission

For message resubmission scenarios that involve Oracle Advanced Queue, Topic, internally the MSG_RESUBMIT stored procedure is used. This procedure assumes that the message type is SYS.AQ$_JMS_MESSAGE.

If the message type being used is not SYS.AQ$_JMS_MESSAGE, change the data type for the MSG variable in the MSG_RESUBMIT stored procedure and then recompile the procedure. You can then use the Message Resubmission Utility for resubmission based on message ID.

For more information about configuring a queue with AQ to support resubmission, see "Configure AQ JMS Foreign Server Destinations" in Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.
Access the Oracle AIA log file, <DOMAIN_HOME>/servers/<SOA Server Name>/logs/aia-error.log to look up the following values included in the IntermediateMessageHop element for the message that requires resubmission:
- SenderResourceTypeCode
- SenderResourceID
- SenderMessageID
For more information about these values in the context of the Oracle AIA fault message schema, see "Configuring Oracle AIA Processes for Error Handling and Trace Logging" in Oracle Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack.

Alternatively, you can also look up the aia-error.log in the Oracle Enterprise Manager.
1. Under WebLogic Domain, <domain name>, right-click the manage server entry (usually soa_server1).
2. Navigate to Logs, View Log Messages. On the Log Message page, provide search criteria (optional) and click the Search button.
For more information about viewing the Oracle AIA log in Oracle Enterprise Manager, see Chapter 18, "Using Trace and Error Logs."

AIAResubmissionUtility is available under $AIA_HOME/util, so browse to $AIA_HOME/util/AIAResubmissionUtility. Set all the required values in ResubmissionParams.properties file.

Note:

The messageID should be in normal format, and should not start with ID : < >

Example 17-1 Sample ResubmissionParams.properties for AQ based Resubmission

jms.app.admin.hostName=example.oracle.com
jms.app.admin.port=7001
jms.app.soa.url=t3://example.oracle.com:8001
jms.app.userName=weblogic
jms.app.password=password
isCluster=true
jms.resourceCFJndi=jms/aia/aiaResourceCF
jms.errorResourceCFJndi=jms/aia/aiaErrorQueueCF
resourceType=1
resourceName=AIA_SiebelCustomerJMSQueue
messageID=7109EDC5FFD9BA25E04014908FC62C90
forceResubmit=false

For Windows, execute $AIA_INSTANCE\bin\aiaenv.bat.

For Linux, source $AIA_INSTANCE/bin/aiaenv.sh.
Navigate to $AIA_HOME/util/AIAMessageResubmissionUtil and execute the following:
```
ant –f MessageResubmit.xml -logfile $AIA_HOME/util/AIAResubmissionUtility/MessageResubmit.log
```
The MessageResubmit.xml script references the edited ResubmissionParams.properties file. Based on the results of the command line execution, the status for a specific message will be set in the back end. Statuses are: Ready for resubmission, Message is in process of resubmission, Resubmitted, Failed.

Note:

All of these properties are self explanatory in the ResubmissionParams.properties file. For security reasons the "Password" property should be deleted from the properties file after the execution of the command line AIA Message Resubmission Utility.

Multiple message IDs of a particular composite can be set for the messageID property with comma “,” as a delimiter. For example: 7109EDC5FFD9BA25E0401, 9EDC5FFD9BA25E04014908F.

17.3.2 WLS JMS based Resubmission

Access the Oracle AIA log file, <DOMAIN_HOME>/servers/<SOA Server Name>/logs/aia-error.log, to look up the following values included in the IntermediateMessageHop element for the message that requires resubmission:
- SenderResourceTypeCode
- SenderResourceID
- SenderMessageID
For more information about these values in the context of the Oracle AIA fault message schema, see "Configuring Oracle AIA Processes for Error Handling and Trace Logging" in Oracle Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack.

Alternatively, you can also look up the aia-error.log in the Oracle Enterprise Manager.
1. Under WebLogic Domain, <domain name>, right-click the manage server entry (usually soa_server1).
2. Navigate to Logs, View Log Messages. On the Log Message page, provide search criteria (optional) and click the Search button.
For more information about viewing the Oracle AIA log in Oracle Enterprise Manager, see Chapter 18, "Using Trace and Error Logs."
You may optionally define jms.resourceCFJndi= and jms.errorResourceCFJndi= property values in the ResubmissionParams.properties file. The default values for the error jndi are fetched based on the resourceName that is provided in the properties file by using the mbean infrastructure. The connection factories are derived based on the naming standards. See the second list item below.
- The jms.resourceCFJndi= property defines a resource-specific ConnectionFactory that will be used to connect to the resource error queue. In this context, a resource is a JMS queue or topic. This property cannot have multiple values, even if you have multiple connection factories. You must specify one ConnectionFactory to be used by the resubmission script.
- If the resource name is AIASamples_Queue and the JNDI is jndi/aia/AIASamples_Queue, the ConnectionFactory property value would be jndi/aia/AIASamples_QueueCF.
- The jms.errorResourceCFJndi= property defines a generic ConnectionFactory that will be used to connect to all resource error queues that are not explicitly defined using the jms.resourceCFJndi= property. If you do not define this value, it automatically uses jms/aia/aiaErrorQueueCF which is created during AIA Foundation Pack installation.
AIAResubmissionUtility is available under $AIA_HOME/util, so browse to $AIA_HOME/util/AIAResubmissionUtility. Set all the required values in ResubmissionParams.properties file.

Note:

The messageID should be in the format ID : < >

Multiple message IDs of a particular composite can be set for the messageID property with comma “,” as a delimiter. For example: ID:<7109EDC5FFD9BA25E0401>, ID:<9EDC5FFD9BA25E04014908F>.
Example 17-2 Sample ResubmissionParams.properties for WLS JMS based Resubmission
```
jms.app.admin.hostName=example.oracle.com
jms.app.admin.port=7001
jms.app.soa.url=t3://example.oracle.com:8001
jms.app.userName=weblogic
jms.app.password=password
isCluster=true
jms.resourceCFJndi=jms/aia/aiaResourceCF
jms.errorResourceCFJndi=jms/aia/aiaErrorQueueCF
resourceType=1
resourceName=AIA_SiebelCustomerJMSQueue
messageID=ID:<983029.1264581138423.0>
forceResubmit=false
```
For Windows, execute $AIA_INSTANCE\bin\aiaenv.bat.

For Linux, source $AIA_INSTANCE/bin/aiaenv.sh.
Navigate to $AIA_HOME/util/AIAMessageResubmissionUtil and execute the following:

ant -f MessageResubmit.xml -logfile $AIA_HOME/util/AIAResubmissionUtility/MessageResubmit.log

The MessageResubmit.xml script references the edited ResubmissionParams.properties file. Based on the results of the command line execution, the status for a specific message will be set in the back end. Statuses are: Ready for resubmission, Message is in process of resubmission, Resubmitted, Failed.

Note:

17.3.3 Resequencer Based Resubmission

Faults/rejected messages which are marked as Recovery Needed in the EM Console can only be resubmitted using AIAResubmissionUtility. To get the list of faulted/rejected messages in the EM Console, navigate to SOA, click on corresponding domain and navigate to Faults and Rejected messages tab in the middle pane.
Make a list of all faulted instances (which are marked as Recovery Needed).
Get the composite name and messageID/GroupID (xpath of the messageID is defined at the design time of the resequencer) of the faulted instances.
AIAResubmissionUtility is available under $AIA_HOME/util. Navigate to $AIA_HOME/util/AIAResubmissionUtility and set all the required values in ResubmissionParams.properties file.

Note:

The resourceName should be in the format default/<compositeName>!<version>.

Multiple message IDs of a particular composite can be set for the messageID property with comma “,” as a delimiter. For example: 7109EDC5FFD9BA25E0401, 9EDC5FFD9BA25E04014908F.
Example 17-3 Sample ResubmissionParams.properties for Resequencer based Resubmission
```
jms.app.admin.hostName=example.oracle.com
jms.app.admin.port=7001
jms.app.soa.url=t3://example.oracle.com:8001
jms.app.userName=weblogic
jms.app.password=password
isCluster=true
jms.resourceCFJndi=jms/aia/aiaResourceCF
jms.errorResourceCFJndi=jms/aia/aiaErrorQueueCF
resourceType=3
resourceName=default/JMSConsumer!1.0
messageID=7109EDC5FFD9BA25E0
forceResubmit=false
```
For Windows, execute $AIA_INSTANCE\bin\aiaenv.bat.

For Linux, source $AIA_INSTANCE/bin/aiaenv.sh.
Navigate to $AIA_HOME/util/AIAMessageResubmissionUtil and execute the following:

ant –f MessageResubmit.xml -logfile $AIA_HOME/util/AIAResubmissionUtility/MessageResubmit.log

The MessageResubmit.xml script references the edited ResubmissionParams.properties file. Based on the results of the command line execution, the status for a specific message will be set in the back end. Statuses are: Ready for resubmission, Message is in process of resubmission, Resubmitted, Failed.

Note: