Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite
11g Release 1 (11.1.1.7)

Part Number E10226-20
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

8  Managing SOA Composite Application Instances

This chapter describes how to manage SOA composite application instances, including initiating a test instance of an application, monitoring and deleting instances, recovering from faults, deleting rejected messages, and migrating instances between different SOA composite application revisions.

This chapter includes the following sections:

Note:

The procedures in this guide describe how to access Oracle Enterprise Manager Fusion Middleware Control pages from the SOA Infrastructure menu, soa-infra icon in the navigator, SOA Composite menu, and SOA Partition menu. You can also access many pages from the Farm home page. For more information, see Section 2.2.6, "Navigating to the SOA Infrastructure or SOA Composite Application Home Page from the Farm Home Page."

8.1 Initiating a SOA Composite Application Test Instance

This section describes how to initiate a test instance of a deployed SOA composite application.

To initiate a SOA composite application test instance:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator... From the Composite Menu...
    1. Select Home.

    2. Select the Deployed Composites tab.

    3. In the Composite section, select a specific SOA composite application.

    4. At the top of the page, click Test.

    1. Under soa-infra, expand the partition.

    2. Select a specific SOA composite application.

    3. At the top of the page, click Test.

    1. Select Test Service > client.


    Note:

    The Test button is disabled in the following situations:

    • The SOA composite application revision is stopped or retired.

    • There are no web services available for the application. Only composites having services with web service bindings can be tested from this page.

  2. If the composite includes multiple services, the Test button has a drop-down list to select the service to test.

    The Test Web Service page for initiating an instance appears.

    This page provides many options for initiating an instance. At a minimum, you must specify the XML payload data to use in the Input Arguments section.

    The WSDL file and endpoint URL are populated automatically based on the service you selected to test. The endpoint URL is derived from the WSDL and can be overridden to invoke that service at a different location. If the service selected has multiple ports, a drop-down list is displayed. Otherwise, the port of the current service is displayed.

    Description of sca_test_payload.gif follows
    Description of the illustration sca_test_payload.gif

  3. Accept the default values for these fields or provide values appropriate to your test environment.

  4. If you change the WSDL file, click Parse WSDL to reload the WSDL file.

    If the WSDL URL does not contain the revision number, it is processed by the default composite application. For example, if there are two revisions of a composite application named HelloWorld, then the following endpoints are exposed by them:

    • http://host:port/soa-infra/services/default/HelloWorld!1.0/client

    • http://host:port/soa-infra/services/default/HelloWorld!2.0/client

    However, if the WSDL specified for web service invocation does not contain the revision details (for example, http://host:port/soa-infra/services/default/HelloWorld/client), it is processed by the composite revision that is set as default.

  5. Select the operation that you want to test from the Operation menu. The available operations are determined from the WSDL.

    To test a RESTful web service, select the GET or POST service port operation.

  6. If you want to edit the endpoint URL, click Edit Endpoint URL and make appropriate changes.

    The lower part of the Test Web Service page consists of the Request tab. This tab enables you to specify security, quality of service, HTTP transport, stress testing options, and XML input arguments:

    Description of sca_test_payload2.gif follows
    Description of the illustration sca_test_payload2.gif

    The Security section includes the following fields for passing security properties with messages:

    Field Description

    OWSM Security Policies

    Inserts a WS-Security SOAP header. The Username field is required, and the Password field is optional.

    HTTP Basic Auth

    Inserts the username and password credentials in the HTTP transport header. Both the Username and Password fields are required.

    Advanced

    Uses a custom policy to authenticate the user (specifies the URI for the custom policy). The Username and Password fields are optional.

    None

    Select to not specify security credentials. This is the default selection.


    When testing RESTful Web services, because the SOAP protocol is not used, the only security options are HTTP Basic Auth or None.

  7. Accept the default values for these fields or provide values appropriate to your test environment.

    The Quality of Service section includes the following fields. Oracle Fusion Middleware uses a policy-based model to manage web services. A policy applies behavior requirements to the delivery of messages. This section is not available when testing RESTful web services. For additional details about using the Test Web Service page, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

    Field Description

    WS-RM

    Select one of the following options for testing WS-Reliable Messaging (RM) protocol policies. Reliable messaging policies support this protocol, which guarantees the end-to-end delivery of messages.

    • WSDL Default: Executes the default behavior of the WSDL. For example, if the WSDL contains a reference to a WS-RM policy, then the policy is enforced. If the WSDL does not contain a reference to a WS-RM policy, then reliable messaging is not tested.

    • None: No policy for WS-RM is tested even if the WSDL contains a reference to a policy.

    • Custom: Enforces a custom policy. Specify the URI of the custom policy in the Policy URI field. If a WS-RM policy is referenced in the WSDL, it is ignored, and the policy specified in the Policy URI field is used instead.

    MTOM

    Select one of the following options for testing Message Transmission Optimization Mechanism (MTOM) policies. MTOM policies ensure that attachments are in MTOM format, a format for efficiently sending binary data to and from web services.

    • WSDL Default: Executes the default behavior of the WSDL. For example, if the WSDL contains a reference to an MTOM policy, then the policy is enforced. If the WSDL does not contain a reference to an MTOM policy, then MTOM is not tested.

    • None: No policy for MTOM is tested, even if the WSDL contains a reference to a policy.

    • Custom: Enforces a custom policy. Specify the URI of the custom policy in the Policy URI field. If an MTOM policy is referenced in the WSDL, it is ignored, and the policy specified in the Policy URI field is used instead.

    WS-Addressing

    Select one of the following options for testing WS-Addressing policies. WS-Addressing policies verify that SOAP messages include WS-Addressing headers in conformance with the WS-Addressing specification.

    • WSDL Default: Executes the default behavior of the WSDL. For example, if the WSDL contains a reference to a WS-Addressing policy, then the policy is enforced. If the WSDL does not contain a reference to a WS-Addressing policy, then WS-Addressing is not tested.

    • None: No policy for WS-Addressing is tested even if the WSDL contains a reference to a policy.

    • Custom: Enforces a custom policy. Specify the URI of the custom policy in the Policy URI field. If a WS-Addressing policy is referenced in the WSDL, it is ignored, and the policy specified in the Policy URI field is used instead.


  8. Accept the default values for these fields or provide values appropriate to your test environment.

    The HTTP Transport Options section includes the following fields:

    Field Description

    Enable SOAP Action

    Specifies whether the WSDL soap:operation has a soapAction attribute. This flag is enabled if a soapAction attribute exists. If you do not want to send a request with the SOAP action HTTP header, then clear the checkbox.

    SOAP Action

    Displays the soapAction attribute of the WSDL soap:operation, if one exists. You may specify a different SOAP action in this text box.


    This section is not available when testing RESTful web services.

  9. Accept the default values for these fields or provide values appropriate to your test environment.

    The Additional Test Options section includes the following fields. This section provides a simple stress test that simultaneously invokes multiple instances.

    Note:

    This is not a real stress test tool. Therefore, do not enter huge values for both concurrent threads and the number of times to invoke the operation. Doing so can result in errors.

    Field Description

    Enable Stress Test

    Click Enable to create a simple stress test. With this enabled, no conversation ID is displayed.

    Concurrent Threads

    Enter the number of concurrent threads on which to send the invocations. The default is 5 threads.

    Loops per Thread

    Enter the number of times to invoke the operation. The default is 10 times.

    Delay in Milliseconds

    Specify the delay of milliseconds to wait between operation invocations. The default is 1000 milliseconds (1 second).


  10. Accept the default values for these fields or provide values appropriate to your test environment.

    The Input Arguments section includes the following fields for entering XML payload data.

    Field Description

    Tree View

    Displays a graphical interface of text fields in which to enter information. This field automatically generates the required headers and XML structure.

    XML View

    Displays the XML file format for inserting values. You can paste the raw XML payload of your message into this field.


    Note:

    If you are using Oracle Enterprise Manager Grid Control, you can save the payload you enter. This feature is not available with Oracle Enterprise Manager Fusion Middleware Control.

  11. Click Test Web Service.

    The test results appear in the Response tab upon completion.

    Description of soaapp_testresult.gif follows
    Description of the illustration soaapp_testresult.gif

    Note:

    The Response tab does not display payload data if you are performing a stress test or are testing an asynchronous service.

  12. Click Launch Message Flow Trace to access the flow trace of the instance.

  13. To return to the composite home page, click the name of the composite that appears at the top of the page or select Home from the composite target menu.

  14. Return to the Dashboard page of the SOA composite application.

    The Recent Instances table lists recent SOA composite application instances. Each created instance has its own unique ID.

For more information, see the following sections:

8.1.1 Specifying RPC/Literal-Style WSDL Files on the Test Web Service Page

If you are specifying an RPC/literal-style WSDL file with a message defined by "element=" in the Test Web Service page in Oracle Enterprise Manager Fusion Middleware Control, use the XML View option of the Input Arguments section to modify the SOAP message. The SOAP body should look as shown in Example 8-1.

Example 8-1 SOAP Body

<soap:Body>
    <ns:initiate>
        <payload>
          <value xmlns="...">3</value>
        </payload>
    </ns:initiate>
</soap:Body> 

where initiate is the operation name, payload is the part name, and value is the element defined in the WSDL message/part.

8.2 Monitoring and Deleting SOA Composite Application Instances from the Application Home Page

Section 7.5, "Managing the State of Deployed SOA Composite Applications" describes how to manage the lifecycle state of SOA composite applications. You can also monitor and delete specific SOA composite application instances from the Instances page of the application home page.

To monitor and delete SOA composite application instances from the application home page:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...
    1. Select Home.

    2. Select the Deployed Composites tab.

    3. Select a specific SOA composite application.

    1. Under soa-infra, expand the partition.

    2. Select a specific SOA composite application.


  2. Click the Instances tab.

    The Instances page displays the following details:

    • A utility for searching for a specific instance by specifying criteria and clicking Search. By default, instances are not displayed the first time you access this page. You must click Search to display any instances.

    • SOA composite application instance ID, name, conversation ID, most recent known state of each instance since the last data refresh of the page (for example, completed successfully, running, unknown, and so on), instance start time, and a log file describing any faults. A unique instance ID is created whenever a new instance of a SOA composite application is initiated either automatically by an external consumer of the application, or manually by an administrator from the Test Web Service page.

      If a ? icon is displayed, the Capture Composite Instance State checkbox was not enabled on the SOA Infrastructure Common Properties dialog. Therefore, the instance state was not evaluated. Determining the composite instance state requires evaluating the states of the underlying component. Therefore, this option can be disabled to improve performance.

    Description of soaapp_instance.gif follows
    Description of the illustration soaapp_instance.gif

    Note:

    It is possible to generate orphaned service component instances. These instances are generated without any associated composite application instances. The orphaned component instances are generated under the following circumstances:

    • The SOA Infrastructure audit level is set to Off or the composite audit level is set to Off. Even in such cases, the BPEL process service engine can generate instance data for the service components that are included in the SOA composite application.

    • The SOA Infrastructure audit level is set to Off. However, the BPEL process or Oracle Mediator service engine audit level is set to a value other than Off.

    • All the audit levels are set to Off, but some faults are generated in one of the service engines. In these cases, the component instance is generated.

    To delete orphaned instances or large numbers of instances, use the purge script described in Section 10.3, "Deleting Large Numbers of Instances with the Purge Scripts." Selecting the Delete All Instance options in the Delete with Options dialog does not delete orphaned component instances.

    If composite sensors are included in your SOA composite application, the Instances tab has the following differences:

    • The Add Fields button appears next to Search and Reset in the search utility. This button enables you to add sensor values to your search criteria.

    • A Composite Sensors column appears in the Instances table. Click the sensor icon in that column to display the details about sensor values available in a given instance of the composite.

  3. From the Add Fields list, select composite sensors to add to the search criteria. In this example, three have been selected (CustomerForOrder, OrderProcessingStart, and CreditCardAuthResultSensor).

  4. Input specific values by which each sensor searches. Only the composite instances in which the sensor values match your specified criteria are returned.

    Description of soaapp_instance2.gif follows
    Description of the illustration soaapp_instance2.gif

    The Composite Sensors column indicates that this SOA composite application includes composite sensors.

    Description of soaapp_instance3.gif follows
    Description of the illustration soaapp_instance3.gif

  5. Click Reset to remove all composite sensor fields from the search criteria or click the Remove icon to the right of the field to remove an individual sensor.

    You can also search for composite sensors in the instances of SOA composite applications in the SOA Infrastructure. You specify the sensor name and value for which to search using a [sensor name]=[sensor value] format. For information, see Section 8.3, "Monitoring and Deleting SOA Composite Application Instances at the SOA Infrastructure Level."

  6. Select a specific instance to delete by clicking a row in the Instances table. To select multiple instances, press Ctrl-Click or Shift-Click for the rows you want to select.

  7. Select a specific action to perform.

    Action Description

    Filter By

    Specify criteria for displaying composite instance states:

    • Execution State

      Filter the display of instances by execution state (running, completed, terminated, or stale).

    • Fault State

      Filter the display of instances by fault state (with or without faults). You can further customize the faulted state by selecting to display faults requiring recovery or nonrecoverable faults. It you select Stale from the Execute State list, the Fault State list is disabled.

    • BPEL Recovery

      Filter the display of instances by whether a recovery action is required. By default, this filter excludes all messages and instances created in the last five minutes, and displays the rest. You can control the number of minutes with the excludeBpelMaxCreationTime key of the AuditConfig property in the System MBean Browser. This property is available in the More SOA Infra Advanced Configuration Properties section of the SOA Infrastructure Common Properties page. For more information, see Section 3.1, "Configuring SOA Infrastructure Properties."

    Delete Selected

    Deletes the selected instance.

    After deleting an instance, instance details are no longer available for review.

    Delete With Options

    Prompts you to first specify criteria for deleting the selected instance directly from the database.

    Use this option to delete running, rolled back instances. However, this option does not delete the associated invoke messages that are awaiting recovery. As a result, there are orphaned messages pending in BPEL message recovery. To delete these messages, go to the Recovery page of the BPEL process service engine.

    • Common Delete Options: Select a preset range of instances to delete from a list (for example, older than 24 hours).

    • Delete All Instances Of This Composite: Select to delete all instances of the composite. This option deletes the rejected messages associated and all component, service, and reference instances associated with the composite, including those not associated with any composite instance ID.

      Note: If this composite has thousands of instances to delete, do not use this option. Instead, use the purge script described in Section 10.3, "Deleting Large Numbers of Instances with the Purge Scripts."

    • Delete All Instances That Match These Criteria: Specify criteria for deleting instances, including the start and stop times, and instance state.

    Any selections you may have made in the Instances page (such as specifying and executing a search criteria) are ignored for this operation.

    To monitor the progress of instance deletion, you must check the log files. For information about log files, see Section 3.4, "Configuring Log Files."

    Abort

    Terminates the selected instance. However, instance details are still available for review.


  8. From the View list, select Columns > Partition to display the partition in which the instance of the SOA composite application revision is contained.

  9. From the View list, select Columns > ECID to display execution context IDs (ECIDs). The ECID enables you to track a message flow that crosses instances of different composites.

  10. In the Instances table, perform the following additional tasks:

    1. In the Instance ID column, click a specific instance ID to show the message flow through the various service components and binding components. If an instance ID is listed as unavailable, you can click the Unavailable link for details.

    2. In the State column, if an instance state is marked as Unknown, click it to display more details.

    3. If the Composite Sensors column is available, click a sensor icon to display details about composite sensors included in the instance, such as name, location, and value.

    4. In the Logs column, click a specific log to access the Log Messages page with filtered messages specific to that instance.

    Note:

    Multiple revisions of a SOA composite application that includes inbound JCA adapters are displayed as running. However, only the most recent revision (the default version) is considered active. All previous revisions are not considered active. This is because for inbound JCA adapters, there can only be one active revision of a SOA composite application at any time. The JCA adapter endpoints in all previous revisions are de-activated.

For more information, see the following sections:

8.2.1 Mismatch Between the Number of SOA Composite Application Instances and Service Component Instances

The number of SOA composite application instances may not always match the number of service component instances displayed in Oracle Enterprise Manager Fusion Middleware Control.

A SOA composite application instance is first created when the composite is invoked. When the service components within the composite receive a subsequent invocation, a corresponding service component instance is created that refers to the composite instance ID previously created.

There can be scenarios under which the composite instance is created, but the underlining service component instance is not created. For example:

  • The composite instance is created, but the invocation has not yet reached the service component due to a system failure.

  • The composite instance is created, but the invocation fails payload validation and is rejected. In this case, invocation does not reach the underlining service components.

You can also have orphaned service component instances for which no SOA composite application instance has been created.

8.2.2 Instance States of Service Components and SOA Composite Applications

Assume you have a SOA composite application with multiple service components (for example, two BPEL process service components). If these service components are marked with the following instance states:

  • Instance state of one BPEL process is marked as completed.

  • Instance state of the other BPEL process is marked as faulted.

This results in the overall composite instance state being marked as faulted. This behavior differs from 11g Release 1 (11.1.1.2), in which the same scenario resulted in the overall composite instance state being marked as completed.

Assume you have a parent SOA composite application that calls a child SOA composite application, and a fault occurs in the child composite (and is handled by the parent composite). This results in the following instance states:

  • The instance state of the child composite is marked as faulted.

  • The instance state of the parent composite is marked as completed.

8.3 Monitoring and Deleting SOA Composite Application Instances at the SOA Infrastructure Level

Section 7.5, "Managing the State of Deployed SOA Composite Applications" described how to manage the lifecycle state of all instances of a specific SOA composite application. You can also monitor and delete any number of instances across all deployed SOA composite applications by using the Instances page of the SOA Infrastructure home page. You can also search for composite sensors in the instances of all SOA composite applications. This page lists all SOA composite application instances deployed to the SOA Infrastructure.

To monitor and delete SOA composite application instances at the SOA infrastructure level:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator... From the SOA Composite Menu...
    1. Select Home.

    1. Click soa-infra.

    1. Select SOA infrastructure.


  2. Click the Instances tab.

    The Instances page displays the following details:

    • A utility for searching for a specific instance by specifying criteria and clicking Search. By default, instances are not displayed the first time you access this page. You must click Search to display any instances.

    • All SOA composite application instances in the SOA Infrastructure, including instance and conversation IDs, composite name and revision, SOA composite application instance state, and instance start time.

    Description of sca_instanceids.gif follows
    Description of the illustration sca_instanceids.gif

    You can also terminate and delete instances from this page.

  3. Select a specific instance by clicking a row in the Instances table. To select multiple instances, press Ctrl-Click or Shift-Click for the rows you want to select.

  4. Select a specific action to perform.

    Action Description

    Composite sensor search in Search utility

    You can search for composite sensors in the instances of SOA composite applications in the SOA Infrastructure. Specify the sensor name and value for which to search using a [sensor name]=[sensor value] format (the brackets are required). The format to specify is also displayed when you click the Sensor field. The search results display instances that include the specified sensor name and value.

    If the sensor pattern specified does not match any composite sensors in the SOA composite applications, no instances are displayed. If matches are found, instances of the composites are displayed.

    Note the following composite sensor search conventions:

    • An equal sign (=) is the only supported operator.

    • Sensor names and string values are case sensitive and must be entered exactly as they appear in the Composite Sensors column of the Instances page for a SOA composite application or the Sensors table of the Flow Trace page for an instance.

    • Filtering based on the date type of sensors is not supported.

    • To specify a numeric sensor value, you must input the exact value without any trailing zeros. For example, if the value of a numeric sensor is displayed as 3.230 in the Instances page of the SOA composite application, input the sensor string without the 0:

      [numeric_sensor]=[3.23]
      
    • Do not enter the commas of composite sensor values that are displayed with commas in the Instances page or Flow Trace page (for example, enter 2011 instead of 2,011).

    For information about obtaining sensor names and values at the SOA composite application level, see Section 8.2, "Monitoring and Deleting SOA Composite Application Instances from the Application Home Page" and Section 14.1, "Monitoring the Audit Trail and Process Flow of a BPEL Process Service Component."

    Filter By

    Specify criteria for displaying composite instance states:

    • Execution State

      Filter the display of instances by execution state (running, completed, terminated, or stale).

    • Fault State

      Filter the display of instances by fault state (with or without faults). You can further customize the faulted states by selecting to display faults requiring recovery or nonrecoverable faults. It you select Stale from the Execute State list, the Fault State list is disabled.

    • BPEL Recovery

      Filter the display of instances by whether a recovery action is required. By default, this filter excludes all messages and instances created in the last five minutes, and displays the rest. You can control the number of minutes with the excludeBpelMaxCreationTime key of the AuditConfig property in the System MBean Browser. This property is available in the More SOA Infra Advanced Configuration Properties section of the SOA Infrastructure Common Properties page. For more information, see Section 3.1, "Configuring SOA Infrastructure Properties."

    Delete Selected

    Deletes the selected instance.

    Delete With Options

    Prompts you to first specify criteria for deleting the selected instance directly from the database.

    Use this option to delete running, rolled back instances. However, this option does not delete the associated invoke messages that are awaiting recovery. As a result, there are orphaned messages pending in BPEL message recovery. To delete these messages, go to the Recovery page of the BPEL process service engine.

    • Common Delete Options: Select a preset range of instances to delete from a list (for example, older than 24 hours).

    • Delete All Instances That Match These Criteria: Specify criteria for deleting instances, including the start and stop times, and instance state.

    Any instance state selections you made at the top of the Instances page are ignored for this operation.

    To monitor the progress of instance deletion, you must check the log files. For information about log files, see Section 3.4, "Configuring Log Files."

    Notes:

    Abort

    Terminates the selected instance. However, instance details are still available for review.

    Note: If you delete an instance with faults, those faults are no longer displayed in the Faults and Rejected Messages page. In addition, if a terminated instance (shown as aborted) had a fault, it is not added to the fault count.


  5. In the Instances table, perform the following additional tasks:

    1. From the View list, select Columns > Partition to display the partition in which the instance of the SOA composite application revision is contained.

    2. From the View list, select Columns > ECID to display ECIDs. An ECID enables you to track a message flow that crosses instances of different composites.

    3. In the Instance ID column, click a specific instance ID to show the message flow through the various service components and binding components. If the instance ID is unavailable, the message flow cannot be accessed. However, you can still click the link for details.

    4. In the Composite column, click a specific SOA composite application to access its home page.

    5. In the Instance State column, click the Recovery icon to access the Faults and Rejected Messages page with faults filtered based on the composite instance ID. There can be multiple faults for a composite instance ID.

    6. In the Logs column, click a specific log to access the Log Messages page with filtered messages specific to that instance.

8.4 Recovering from SOA Composite Application Faults at the SOA Infrastructure Level

You can monitor and perform individual and bulk fault recoveries for BPEL process and Oracle Mediator service components across any number of SOA composite applications. For BPEL process faults to be identified as recoverable, there must be a fault policy defined that is bound to the fault (through the fault-bindings.xml file) and which triggers the action ora-human-intervention. However, without defining any fault policies, the fault takes its standard course as either a recoverable or nonrecoverable fault. Examples of performing both individual and bulk recovery are provided in this section. Human task service component or human workflow service engine faults are recovered from Oracle BPM Worklist.

You can also perform a manual recovery of undelivered BPEL process invoke or callback messages. For more information, see Section 15.4, "Performing BPEL Process Service Engine Message Recovery."

To recover from SOA composite application faults at the SOA Infrastructure level:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator... From the SOA Composite Menu...
    1. Select Home.

    1. Click soa-infra.

    1. Select SOA Infrastructure.


  2. Click the Faults and Rejected Messages tab.

    The Faults and Rejected Messages page displays the following details for all SOA composite application faults:

    • A utility for searching for a specific fault by specifying criteria and clicking Search. Click the Help icon for details. By default, faults are not displayed the first time you access this page. You must click Search to display any faults.

    • Options for selecting instance recovery actions (for example, retry, abort, replay, and others), deleting rejected messages, and performing bulk message recovery.

    • Faults and rejected messages, including the error message, whether you can recover from the fault, the time of the fault, if the fault message is classified as a rejected message (if so, a checkmark is displayed), the SOA composite application in which the fault occurred, the fault location, the instance ID, and a link to log files describing the fault.

    Description of sca_faultandmanage.gif follows
    Description of the illustration sca_faultandmanage.gif

    Note:

    You cannot search for human workflow error messages by entering details in the Error Message Contains field because these faults do not persist in the dehydration store.

    Faults identified as recoverable can be recovered.

  3. Select faults for recovery using one of the following options. Fault recovery selection at the SOA Infrastructure level matches the SOA composite application level and BPEL process and Oracle Mediator service component levels.

    For... Then...

    Single fault recovery

    There are three options from which to choose for single fault recovery:

    1. Click the row of the fault that has been identified as recoverable. With the row highlighted, select a specific action from the Recovery Action list, as described in Step 4.

    2. In the Recovery column, click the Recover link to access the Faults page of the instance audit trail to perform fault recovery.

    3. In the Error Message column, click the message of a fault that has been identified as recoverable. This displays complete fault details, including the fault ID, fault time, fault location, fault type, and error message text. A Recover Now option is displayed for recoverable faults. Click Recover Now to access the Faults page of the instance audit trail to perform fault recovery.

    Bulk fault recovery

    There are two options from which to choose for bulk fault recovery:

    1. Use Shift+Click or Control+Click to select specific faults in the rows.

      or

    2. From the Select menu, choose Select All Recoverable. Then use Shift+Click or Control+Click to deselect the faults to not include in the recovery operation.

      Then:

    3. Select an action from the Recovery Action list, as described in Step 4.

      Note: Only the actions applicable to all selected faults are available.

    Recovery of all faults

    1. From the Select menu, choose Select All Recoverable.

    2. Select an action from the Recovery Action list, as described in Step 4.

      Note: Only the actions applicable to all selected faults are available.


  4. Select an action from the Recovery Action list.

    Action Description Action is Available for...

    Retry

    Retries the instance directly. An example of a scenario in which to use this recovery action is when the fault occurred because the service provider was not reachable due to a network error. The network error is now resolved.

    BPEL process and Oracle Mediator

    Abort

    Terminates the entire instance.

    BPEL process and Oracle Mediator

    Replay

    Replays the entire scope again in which the fault occurred.

    BPEL process

    Rethrow

    Rethrows the current fault. BPEL fault handlers (catch branches) are used to handle the fault. By default, all exceptions are caught by the fault management framework unless an explicit rethrow fault policy is provided.

    BPEL process

    Continue

    Ignores the fault and continues processing (marks the faulted activity as a success).

    BPEL process


    Note:

    In most cases, fault policy actions are automatically executed. The only exception is if you defined a fault policy that uses the action ora-human-intervention. This action creates a recoverable fault that can be recovered from Oracle Enterprise Manager Fusion Middleware Control.

  5. If you want to delete rejected messages for all composites in the SOA Infrastructure, see Section 8.6, "Deleting Rejected Messages at the SOA Infrastructure Level."

  6. If you want to perform a bulk recovery of messages, click Recover with Options.

    This displays the Recover with Options dialog for specifying criteria for recovering BPEL and Oracle Mediator messages of all composites directly from the database. Human workflow messages can be recovered manually from Oracle BPM Worklist. Business event and business rule messages cannot be recovered.

    Description of soaapp_recovwithopts.gif follows
    Description of the illustration soaapp_recovwithopts.gif

  7. Specify criteria. Retry and Abort are the only recovery actions permitted.

    Note:

    For bulk fault recovery at the SOA Infrastructure level, a check of the state of composites cannot be performed. If the state of a composite is set to off, a recovery of its faults cannot be performed. However, no error or warning message is displayed. Upon submission of the bulk fault recovery request, the server checks if the originating composite's state is set to off. That fact is then noted in the log, and the fault is skipped.

    You are also not notified when a fault has been skipped during recovery for any other reason (for example, an unsupported service engine, an unrecoverable fault, and so on).

  8. Click Recover. Depending upon the number of messages, recovery can take some time.

  9. Perform the following additional tasks from within the Faults table:

    1. From the View list, select Columns > Fault ID to display the fault IDs for each error message. The fault ID is automatically generated and uniquely identifies a fault. The fault ID is also displayed when you click an error message.

    2. In the Composite column, click a specific SOA composite application to access its home page.

    3. In the Fault Location column, click a specific location to access the faults page for the location of the fault. The location can be a service, service component, or reference.

    4. In the Composite Instance ID column, click a specific ID to access the flow trace of the instance.

    5. In the Logs column, click a specific log to access the Log Messages page with filtered messages specific to that instance.

  10. See the following sections for examples of single and bulk fault recovery with BPEL processes and Oracle Mediator.

For more information about concepts and instructions on designing a fault policy, see the following documentation:

8.4.1 Examples of Fault Recovery for BPEL Processes

This section provides examples of how to define a fault policy that enables human intervention on a BPEL process fault and perform single and bulk fault recovery on a BPEL process service component.

In this example, you define a fault policy by specifying that a fault can be manually recovered through human intervention. If an invalid social security number is submitted from a loan broker BPEL process to a credit rating service, the credit rating service returns a negative credit fault. This human intervention action is defined with the ora-human-intervention action in the fault-policies.xml file. Without fault policies, BPEL instances do not generate recoverable faults (instead they are nonrecoverable); the ora-human-intervention action makes the fault recoverable. Example 8-2 shows the fault policy file.

Example 8-2 Fault Policy FIle

<faultPolicies xmlns="http://schemas.oracle.com/bpel/faultpolicy">
<faultPolicy version="2.0.1"
           id="CRM_ServiceFaults"
           xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://schemas.oracle.com/bpel/faultpolicy"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <Conditions>
               <faultName xmlns:credit="http://services.otn.com" 
               name="credit:NegativeCredit">
               <!-- get this fault when SSN starts with 0-->
                  <condition>
                     <test>$fault.payload="Bankruptcy Report"</test>
                     <action ref="ora-human-intervention"/>
                  </condition>
               </faultName>
            </Conditions>
</faultPolicy>
</faultPolicies>

The fault-bindings.xml file shown in Example 8-3 associates the fault policies defined in the fault-policies.xml file with the CRM_ServiceFaults composite application.

Example 8-3 Fault Policy Bindings File

<faultPolicyBindings version="2.0.1"
 xmlns="http://schemas.oracle.com/bpel/faultpolicy"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <composite faultPolicy="CRM_ServiceFaults"/>
</faultPolicyBindings>

Because human intervention is defined as an action, you perform BPEL process fault recovery in Oracle Enterprise Manager Fusion Middleware Control.

For more information about creating and designing fault-policies.xml and fault-bindings.xml files, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

For information about BPEL process message recovery, see Section 15.4, "Performing BPEL Process Service Engine Message Recovery."

8.4.1.1 Example: Single Fault Recovery for BPEL Processes

This example assumes the following:

To perform single fault recovery for BPEL processes:

  1. From the SOA Infrastructure menu, select Home.

  2. Click the Faults and Rejected Messages tab.

  3. In the Faults table, locate the fault that has been identified as recoverable. You can use the search utility to locate the specific fault.

  4. In the Recovery column, click Recover. If you first want to see details about the fault, click the error message. Then, click Recover Now.

    The Faults page for that BPEL process instance is displayed.

  5. In the Recovery column, click Recoverable.

    The page refreshes to display the fault recovery section at the bottom of the page.

    Description of sca_faults2.gif follows
    Description of the illustration sca_faults2.gif

  6. From the Recovery Action list, select Retry.

  7. Select None from the Chain Action Upon Successful Retry list. This list enables you to select Java callout recovery actions. For more information, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

  8. Select a variable from the Variable list. The content of this variable is displayed in the Value field. For this example, the variable crInput is selected. This variable is used in an invoke activity and contains an incorrect social security number value.

  9. Enter the correct value in the Value field. For this example, the social security number is edited to begin with 1:

    <ssn xmlns="http://service.otn.com">123456789</ssn>
    
  10. Click Set Value, and click Yes when prompted to continue.

  11. Click Recover to recover from the fault, and then click Yes when prompted to continue.

    The page refreshes to indicate that no faults occurred.

8.4.1.2 Example: Bulk Fault Recovery for BPEL Processes

For the social security number example, selecting Retry is not an option for performing a bulk recovery, because the value for the social security number is incorrect and requires correction. An example of performing a bulk recovery with the Retry option is if the social security number is correct, but the system providing the credit rating service was temporarily unavailable and caused a composite reference fault. This prevents the messages from being delivered. Once the credit rating service is available again, selecting Retry attempts the invocation to the credit rating service through the composite reference again.

To perform bulk fault recovery for BPEL processes:

  1. Perform Step 1 and Step 2 of Section 8.4.1.1, "Example: Single Fault Recovery for BPEL Processes."

  2. In the search utility, enter criteria based on known fault parameters (for example, the time range, composite name, component type (BPEL process), and so on).

  3. If the search returns too many results, limit it by selecting the Show only recoverable faults checkbox.

  4. From the Select list, choose Select All Recoverable.

  5. From the Recovery Action list, select Abort.

    All selected faults are manually terminated.

8.4.2 Examples of Fault Recovery for BPMN Processes

This section provides examples of how to define a fault policy that enables human intervention on a BPMN process fault and perform single and bulk fault recovery on a BPMN process service component.

Note:

When a multi-instance process has met the conditions for its completion, it raises a nonrecoverable system fault (to cancel remaining instances). Although this fault appears in Oracle Enterprise Manager Fusion Middleware Control, you do not need to take any action. It appears simply to notify you that the multi-instance process was finalized because the condition was completed.

In this example, you define a fault policy specifying that a fault be manually recovered through human intervention. If an invalid social security number is submitted from a loan broker BPMN process to a credit rating service, the credit rating service returns a negative credit fault. This human intervention action is defined with the ora-human-intervention action in the fault-policies.xml file. Without fault policies, BPMN instances do not generate recoverable faults (instead they are nonrecoverable); the ora-human-intervention action makes the fault recoverable. Example 8-4 shows the fault policy file.

Example 8-4 Fault Policy FIle

<faultPolicies xmlns="http://schemas.oracle.com/bpmn/faultpolicy">
<faultPolicy version="2.0.1"
           id="CRM_ServiceFaults"
           xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://schemas.oracle.com/bpmn/faultpolicy"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <Conditions>
               <faultName xmlns:credit="http://services.otn.com" 
               name="credit:NegativeCredit">
               <!-- get this fault when SSN starts with 0-->
                  <condition>
                     <test>$fault.payload="Bankruptcy Report"</test>
                     <action ref="ora-human-intervention"/>
                  </condition>
               </faultName>
            </Conditions>
</faultPolicy>
</faultPolicies>

The fault-bindings.xml file shown in Example 8-5 associates the fault policies defined in the fault-policies.xml file with the CRM_ServiceFaults composite.

Example 8-5 Fault Policy Bindings File

<faultPolicyBindings version="2.0.1"
 xmlns="http://schemas.oracle.com/bpmn/faultpolicy"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <composite faultPolicy="CRM_ServiceFaults"/>
</faultPolicyBindings>

Because human intervention is defined as an action, you perform BPMN process fault recovery in Oracle Enterprise Manager Fusion Middleware Control.

For more information about creating and designing fault-policies.xml and fault-bindings.xml files, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

8.4.2.1 Example: Single Fault Recovery for BPMN Processes

This example assumes the following:

To perform single fault recovery for BPMN processes:

  1. From the SOA Infrastructure menu, select Home.

  2. Click the Faults and Rejected Messages tab.

  3. In the Faults table, locate the fault that has been identified as recoverable. You can use the search utility to locate the specific fault.

  4. In the Recovery column, click Recover. If you first want to see details about the fault, click the error message. Then, click Recover Now.

    The Faults page for that BPMN process instance is displayed.

  5. In the Recovery column, click Recoverable.

    The page refreshes to display the fault recovery section at the bottom of the page.

    Description of sca_faults2.gif follows
    Description of the illustration sca_faults2.gif

  6. From the Recovery Action list, select Retry.

  7. From the Chain Action Upon Successful Retry list, select None. This list enables you to select Java callout recovery actions. For more information, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

  8. From the Variable list, select a variable. The content of this variable is displayed in the Value field. For this example, the variable crInput is selected. This variable is used in an invoke activity and contains an incorrect social security number value.

  9. In the Value field, enter the correct value. For this example, the social security number is edited to begin with 1:

    <ssn xmlns="http://service.otn.com">123456789</ssn>
    
  10. Click Set Value, and click Yes when prompted to continue.

  11. Click Recover to recover from the fault, then click Yes when prompted to continue.

    The page refreshes to indicate that no faults occurred.

8.4.2.2 Example: Bulk Fault Recovery for BPMN Processes

For the social security number example, selecting Retry is not an option for performing a bulk recovery because the value for the social security number is incorrect and requires correction. An example of performing a bulk recovery with the Retry option is if the social security number is correct, but the system providing the credit rating service was temporarily unavailable and caused a composite reference fault. This prevents the messages from being delivered. Once the credit rating service is available again, selecting Retry re-attempts the invocation to the credit rating service through the composite reference.

To perform bulk fault recovery for BPMN processes:

  1. Perform Steps 1 through 2 of Section 8.4.2.1, "Example: Single Fault Recovery for BPMN Processes."

  2. In the search utility, enter criteria based on known fault parameters (for example, the time range, composite name, component type (BPMN process), and so on).

  3. If the search returns too many results, limit it by selecting the Show only recoverable faults checkbox.

  4. From the Select list, choose Select All Recoverable.

  5. From the Recovery Action list, select Abort.

    All selected faults are manually terminated.

8.4.3 Examples of Fault Recovery for Oracle Mediator

This section provides an example of how to perform single and bulk fault recovery on an Oracle Mediator service component.

In this example, a service binding component for an inbound Siebel adapter submits a payload message to Oracle Mediator for transformation. The processed payload message is then delivered to a reference binding component for an outbound file adapter. However, the outbound directory into which to write the payload message is not configured with write permissions. This causes a fault to occur. The fault policy defined during design time specifies that the fault be manually recovered through human intervention. Three retries are attempted, as defined with the retryCount attribute. The condition and action are defined as follows in the fault-policies.xml file.

Recoverable Oracle Mediator faults do not require a fault policy (though it is one way to make faults recoverable, as described through an ora-human-intervention action). Any parallel routing rule that receives a remote fault from the outbound endpoint also creates a recoverable fault (in this specific example, the fault policy is not required if the Oracle Mediator uses a parallel routing rule to invoke the outbound file adapter). Example 8-6 shows the fault policy file.

Example 8-6 Fault Policy File

<faultPolicies xmlns="http://schemas.oracle.com/bpel/faultpolicy">
<faultPolicy version="2.0.1"
           id="ConnectionFaults"
           xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://schemas.oracle.com/bpel/faultpolicy"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
              <Conditions>
                <faultName xmlns:medns="http://schemas.oracle.com/mediator/faults"
                name="medns:mediatorFault">
                   <condition>
                      <test>contains($fault.mediatorErrorCode, "TYPE_FATAL_
                         MESH")</test>
                      <action ref="ora-retry"/>
                   </condition>
                </faultName>
              </Conditions>
. . .
. . .      <Action id="ora-retry">
        <retry>
          <retryCount>3</retryCount>
          <retryInterval>5</retryInterval>
          <retryFailureAction ref="ora-human-intervention"/>
          <retrySuccessAction ref="ora-terminate"/>
        </retry>
      </Action>
   </Actions>
</faultPolicy>
</faultPolicies>

Processing is set to retry 3 times before terminating.

The fault policies are associated with the ConnectionFaults composite application in the fault-bindings.xml file shown in Example 8-7:

Example 8-7 Fault Policy Bindings File

<faultPolicyBindings version="2.0.1" xmlns="http://schemas.oracle.com/bpel/fault
policy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <composite faultPolicy="ConnectionFaults"/>
</faultPolicyBindings>

8.4.3.1 Example: Single Fault Recovery for Oracle Mediator

For this example, the sap output directory is set to read-only. An inbound file adapter retrieves the sender.xml file from the siebel directory and the message is routed through Oracle Mediator to an outbound file adapter reference for placing a file in the sap directory.

To perform single fault recovery for Oracle Mediator:

  1. Change the directory permissions at the operating system command prompt.

    chmod 000 sap
    cp sender.xml siebel/
    
  2. From the SOA Infrastructure menu, select Home.

  3. Click the Faults and Rejected Messages tab.

    Three faults appear, based on three retries being attempted. In this case, you see three retries only because the fault policy on the Oracle Mediator interaction with the outbound file adapter defines three retries. Without the fault policy, there is only one fault (no automated retries).

  4. Click the specific instance ID in the Composite Instance ID column.

    The Flow Trace appears. The faults table at the top of the page displays the fault messages. If you want to see where the faulted Oracle Mediator instance is located in the overall message flow, select the fault in the Faults table. This highlights the associated instance in the trace table. You can then click the instance to access its audit trail to see more details about the faulted flow.

    Note:

    Steps 4 through 10 represent one way to recover this single fault. The fault can also be recovered directly from the Oracle Mediator Faults page through the Recovery Action list.

  5. Locate the Oracle Mediator component instance fault you want to recover in the Faults table and click Recover in the Recovery column.

  6. From the Payload Part list, select Sender.

    The payload is automatically displayed in the Payload field. If necessary, payload modifications can be performed in this field. For this example, payload modification is not necessary.

  7. Change the sap directory to be writable at the operating system command prompt.

    chmod 777 sap
    
  8. Return to the Faults tab and click the Refresh icon in the upper right corner of the page.

  9. Click Retry.

  10. Click Yes when prompted to resubmit the selected fault for recovery.

    The page refreshes to indicate that no faults occurred.

  11. Click the Audit Trail tab.

    The final message indicates that manual recovery was successful and the message payload was written to the sap directory.

    Description of bp_flt29.gif follows
    Description of the illustration bp_flt29.gif

8.4.3.2 Example: Bulk Fault Recovery for Oracle Mediator

Assume the sap directory to which to write the sender.xml payload message is again configured with read-only permissions at the operating system command prompt. Three copies of the sender.xml file are placed in the siebel directory of the service binding component for the inbound Siebel adapter. This creates three instances.

chmod 000 sap
cp sender.xml siebel/
cp sender.xml siebel/
cp sender.xml siebel/

To perform bulk fault recovery for Oracle Mediator:

  1. Change the sap directory to be writable.

  2. From the SOA Infrastructure menu, select Home.

  3. Click the Faults and Rejected Messages tab.

  4. In the search utility, enter criteria based on known fault parameters (for example, the time range, composite name, and so on).

  5. If the search returns too many results, limit it by selecting the Show only recoverable faults checkbox.

  6. Change the sap directory to be writable at the operating system command prompt.

    chmod 777 sap
    
  7. Select all the faults to be recovered.

  8. Select Retry from the Recovery Action list.

  9. Select Yes when prompted to perform fault recovery.

  10. Click the Audit Trail tab.

    The final message indicates that manual recovery was successful and the message payload was successfully written to the sap directory.

8.5 Recovering from SOA Composite Application Faults in the Application Home Page

You can monitor and perform individual and bulk fault recoveries in a SOA composite application. For BPEL process faults to be identified as recoverable, there must be a fault policy defined that is bound to the fault (through the fault-bindings.xml file) and which triggers the action ora-human-intervention. However, without defining any fault policies, the fault takes its standard course as either a recoverable or nonrecoverable fault. Human workflow faults can also be recovered, but not directly from Oracle Enterprise Manager Fusion Middleware Control. Instead, the audit trail provides a link to Oracle BPM Worklist, from which the fault can be addressed.

To recover from SOA composite application faults in the application home page:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...
    1. Select Home.

    2. Select Deployed Composites.

    3. In the Composite section, select a specific SOA composite application.

    1. Under soa-infra, expand the partition.

    2. Select a specific SOA composite application.


  2. Click the Faults and Rejected Messages tab.

    The Faults and Rejected Messages page displays the following details for the selected SOA composite application:

    • A utility for searching for a specific fault by specifying criteria and clicking Search. Click the Help icon for details. By default, faults are not displayed the first time you access this page. You must click Search to display any faults.

    • Options for selecting instance recovery actions (for example, retry, abort, replay, and others), deleting rejected messages, and performing bulk message recovery.

    • Faults and rejected messages in SOA composite application instances, including the error message, whether you can recover from the fault, the time of the fault, if the fault message is classified as a rejected message (if so, a checkmark is displayed), the fault location, the composite instance ID, and links to log files that describe the fault.

    Description of sca_soaapp_search.gif follows
    Description of the illustration sca_soaapp_search.gif

    Note:

    You cannot search for human workflow error messages by entering details in the Error Message Contains field because these faults do not persist in the dehydration store.

    Faults identified as recoverable can be recovered.

  3. Select faults for recovery. As with fault recovery at the SOA Infrastructure level and BPEL process and Oracle Mediator service component levels, you can perform single fault recovery, bulk fault recovery, and recovery of all faults. See Step 3 of Section 8.4, "Recovering from SOA Composite Application Faults at the SOA Infrastructure Level" for instructions on selecting faults to perform these types of recovery.

  4. Select an action from the Recovery Action list.

    Action Description Action is Available for...

    Retry

    Retries the instance directly. An example of a scenario in which to use this recovery action is when the fault occurred because the service provider was not reachable due to a network error. The network error is now resolved.

    BPEL process and Oracle Mediator

    Abort

    Terminates the entire instance.

    BPEL process and Oracle Mediator

    Replay

    Replays the entire scope again in which the fault occurred.

    BPEL process

    Rethrow

    Rethrows the current fault. BPEL fault handlers (catch branches) are used to handle the fault. By default, all exceptions are caught by the fault management framework unless an explicit rethrow fault policy is provided.

    BPEL process

    Continue

    Ignores the fault and continues processing (marks the faulted activity as a success).

    BPEL process


    Note:

    In most cases, fault policy actions are automatically executed. The only exception is if you defined a fault policy that uses the action ora-human-intervention. This action creates a recoverable fault that can be recovered from Oracle Enterprise Manager Fusion Middleware Control.

  5. If you want to delete rejected messages for the current SOA composite application, see Section 8.7, "Deleting Rejected Messages from the Application Home Page."

  6. If you want to perform a bulk recovery of messages, click Recover with Options.

    This displays the Recover with Options dialog for specifying criteria for recovering BPEL and Oracle Mediator messages of the current composite directly from the database. Human workflow messages can be recovered manually from Oracle BPM Worklist. Business event and business rule messages cannot be recovered.

    Description of soaapp_recovwithopts.gif follows
    Description of the illustration soaapp_recovwithopts.gif

  7. Specify criteria. Retry and Abort are the only recovery actions permitted.

    Note:

    For bulk fault recovery at the SOA composite application level, a check of the state of the composite is performed. If the state of the composite is set to off, a message is displayed warning you that a recovery cannot be performed.

    You are not notified when a fault has been skipped during recovery for any reason (for example, an unsupported service engine, an unrecoverable fault, and so on).

  8. Click Recover. Depending upon the number of messages, recovery can take some time.

  9. Perform the following additional monitoring tasks from within the Faults table:

    1. From the View list, select Columns > Fault ID to display the fault IDs for each error message. The fault ID is automatically generated and uniquely identifies a fault. The fault ID is also displayed when you click an error message.

    2. In the Fault Location column, click a specific location to access the faults page for the location of the fault. The location can be a service, component, or reference.

    3. In the Component Instance ID column, click a specific service component ID to access task details about the instance (for example, the current state of a task). Rejected messages do not have a component instance ID.

    4. In the Logs column, click a specific log to access the Log Messages page with filtered messages specific to that instance.

For more information, see the following sections:

8.6 Deleting Rejected Messages at the SOA Infrastructure Level

You can delete rejected messages for all composites in the SOA Infrastructure directly from the database by specifying a criteria in the Delete: Rejected Messages dialog.

To delete rejected messages for all composites at the SOA Infrastructure level:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator... From the SOA Composite Menu...
    1. Select Home.

    1. Click soa-infra.

    1. Select SOA Infrastructure.


  2. Click the Faults and Rejected Messages tab.

    The Faults and Rejected Messages page displays the following details for all SOA composite application faults:

    • A utility for searching for a specific fault by specifying criteria and clicking Search. Click the Help icon for details. By default, faults are not displayed the first time you access this page. You must click Search to display any faults.

    • Options for selecting instance recovery actions (for example, retry, abort, replay, and others), deleting rejected messages, and performing bulk message recovery.

    • Faults and rejected messages, including the error message, whether you can recover from the fault, the time of the fault, if the fault message is classified as a rejected message (if so, a checkmark is displayed), the SOA composite application in which the fault occurred, the fault location, the instance ID, and a link to log files describing the fault.

    Description of sca_faultandmanage.gif follows
    Description of the illustration sca_faultandmanage.gif

  3. Click Delete Rejected Messages.

    Note:

    Oracle recommends that you run the purge scripts to delete composite instances in production environments. The purge scripts have better performance and scalability. Only use the Delete Rejected Messages option to manage exceptions not covered by the purge scripts. For more information about the purge scripts, see Section 10.3, "Deleting Large Numbers of Instances with the Purge Scripts."

    This displays the Delete: Rejected Messages dialog for specifying criteria for deleting rejected messages of all the composites directly from the database.

    Description of bp_delrejmess.gif follows
    Description of the illustration bp_delrejmess.gif

  4. Specify criteria and click Delete.

For information about recovering from faults at the SOA Infrastructure level, see Section 8.4, "Recovering from SOA Composite Application Faults at the SOA Infrastructure Level."

8.7 Deleting Rejected Messages from the Application Home Page

You can delete rejected messages for the current SOA composite application directly from the database by specifying a criteria in the Delete: Rejected Messages dialog.

To delete rejected messages for the current SOA composite application:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...
    1. Select Home.

    2. Select Deployed Composites.

    3. In the Composite section, select a specific SOA composite application.

    1. Under soa-infra, expand the partition.

    2. Select a specific SOA composite application.


  2. Click the Faults and Rejected Messages tab.

    The Faults and Rejected Messages page displays the following details for all SOA composite application faults:

    • A utility for searching for a specific fault by specifying criteria and clicking Search. Click the Help icon for details. By default, faults are not displayed the first time you access this page. You must click Search to display any faults.

    • Options for selecting instance recovery actions (for example, retry, abort, replay, and others), deleting rejected messages, and performing bulk message recovery.

    • Faults and rejected messages, including the error message, whether you can recover from the fault, the time of the fault, if the fault message is classified as a rejected message (if so, a checkmark is displayed), the SOA composite application in which the fault occurred, the fault location, the instance ID, and a link to log files describing the fault.

    Description of sca_soaapp_search.gif follows
    Description of the illustration sca_soaapp_search.gif

  3. Click Delete Rejected Messages.

    Note:

    Oracle recommends that you run the purge scripts to delete composite instances in production environments. The purge scripts have better performance and scalability. Only use the Delete Rejected Messages option to manage exceptions not covered by the purge scripts. For more information about the purge scripts, see Section 10.3, "Deleting Large Numbers of Instances with the Purge Scripts."

    The Delete: Rejected Messages dialog is displayed for specifying criteria for deleting rejected messages of the current composite directly from the database.

    Description of bp_delrejmess.gif follows
    Description of the illustration bp_delrejmess.gif

  4. Specify criteria and click Delete.

For information about recovering from faults on the SOA composite application home page, see Section 8.5, "Recovering from SOA Composite Application Faults in the Application Home Page."

8.8 Migrating Instances Between Different SOA Composite Application Revisions

You can migrate running SOA composite application instances from one revision of a composite to another revision (for example, migrate an instance of the deployed CreditRatingService revision 1.0 composite to an instance of the deployed CreditRatingService revision 2.0 composite). This action migrates instances without impacting the old revision, and enables the instances of both revisions to run side by side. The migrated instance is visible under the target revision of the SOA composite application. All service component instances in the SOA composite application instance are also migrated.

The reasons for migrating instances include the following:

The following restrictions apply to instance migration:

Two migration methods are supported:

8.8.1 Migration Compatibility

Composite migration compatibility depends on the service components defined inside the application. If changes to any service component are not compatible, then the entire instance is not eligible for migration. The SOA composite application instance is only migrated if the associated service component instances can be migrated.

The following service components are eligible for migration:

  • Nondurable BPEL processes

  • Oracle Mediator

  • Human workflow

  • Business rules

  • Oracle BPMN

The participating service engines are coordinated to migrate their respective instances. Instance tracking data is migrated to the new revision.

Table 8-1 describes how the following service component instances are migrated to a new instance. If not compatible, the overall composite instance migration is reported as incompatible, and you cannot migrate it.

Table 8-1 Service Component Instance Migration Details

Service Component Supported Migration Types Migration Restrictions

BPEL process

Automatic migration of BPEL process instances to a new revision

  • Only nondurable BPEL processes are supported (processes without checkpoint or breakpoint activities). Durable processes include asynchronous processes or synchronous processes with timers or activities that dehydrate before completing.

  • Only completed component instances are migrated.

Oracle Mediator

Automatic migration of Oracle Mediator instances to a new revision

Request-only, request-response, and sequential routing rules are the only supported message patterns. This means that only one-way and synchronous Oracle Mediator components are eligible for migration.

Human workflow

Automatic migration of human workflow instances to a new revision

Running and completed human workflow instances can be migrated if they are part of the running composite instance.

Business rules

Automatic migration of business rules to a new revision (there is no concept of rules instances)

None.

Oracle BPM

Both manual (through use of a migration plan) and automatic migration of Oracle BPM instances to a new revision

You cannot migrate instances between incompatible models. Examples of incompatible instances include:

  • Removing or changing the behavior of a subprocess

  • Changing the levels of any activities

  • Removing gateways (except exclusive gateways)

  • Changing the interface

  • Adding or removing a boundary event on any activity

Adding or removing activities means you must manually migrate them with a migration plan.


Notes:

Instance migration fails for a composite instance that includes an Oracle Mediator service component with parallel routing rules and an Oracle BPMN service component. The following values are returned:

  • For the instance migration as a whole, CompositeInstanceMigrationResult.migrated() returns a value of false.

  • For the Oracle Mediator service component, ComponentInstanceMigrationResult.migrated() returns a value of false.

However, for the Oracle BPMN service component, ComponentInstanceMigrationResult.migrated() returns a value of true, even though migration was unsuccessful.

There are two instance migration methods:

8.8.2 Migrating Instances with the Facade API

You can migrate instances with the Facade API.

Two basic API categories are provided:

  • For generating a migration report that provides the following information:

    • Feasibility of migrating some sets of composite instances before attempting a migration

    • Number and feasibility of composite instances to migrate

    • Number and feasibility of associated service component instances to migrate

    • Overall feasibility of instance migration: manual migration is required, automatic migration is required, or migration is incompatible

    • Reason that manual migration is required or migration is incompatible

  • For providing the results of instance migration:

    • Result of migration attempt: which composite and service component instances were successfully or unsuccessfully migrated

    • Reasons for any failures

Both synchronous and asynchronous versions are provided by the Facade API.

For more information about the Facade API, see Oracle Fusion Middleware Infrastructure Management Java API Reference for Oracle SOA Suite and Chapter 11, "Programmatically Managing SOA Composite Applications with the Facade API."

8.8.2.1 Bulk Migration Evaluation

Example 8-8 shows the Façade API that obtains a composite instance migration summary. The summary describes the potential for migration of composite instances that match a specified filter criteria.

Example 8-8 Bulk Migration Evaluation

/**
* Synchronously generates a migration report. The results would be limited to some
* fixed number of composite instances to avoid EJB time-outs.
* We should probably provide a way for the client to specify an even smaller
* maximum number of instances.
*
* @param filter - The composite instance selection criteria
* @param targetRevision - The revision to which the composite instances should be
* migrated
*
* @return A MigrationReport
*/
MigrationReport generateMigrationReport(CompositeInstanceFilter filter, String
 targetRevision);
/**
* Asynchronously generates a migration report. There is no limit on the number of
* composite instances included in the result.
*
* @param filter - The composite instance selection criteria
* @param targetRevision - The revision to which the composite instances should be
* migrated
* @return A unique report identifier, which can be used to subsequently retrieve
* the report.
*/
String initiateMigrationReport(CompositeInstanceFilter filter, String
 targetRevision);
/**
* Retrieves an asynchronously-generated migration report.
*
* @param reportId - A unique report identifier; the result of the
* initiateMigrationReport method.
*
* @return The MigrationReport for the specified report identifier
*/
MigrationReport getMigrationReport(String reportId);

The report includes the following information:

Composite instance details:

  • Component instance name

  • Component instance ID

  • Component instance state

  • Migrate status: automatic or a migration plan is required (and the required change plan, where applicable)

  • Component instance data details:

Summary data:

  • The target revision

  • Total number of matching composite instances

  • Number of composite instances that can be automatically migrated

  • Number of composite instances that cannot be automatically migrated

  • If the results were truncated, then there must be some indication of that fact

8.8.2.2 Migration Report

The migration report describes the migration feasibility of composite instances. Example 8-9 provides details.

Example 8-9 Migration Report

package oracle.soa.management.facade;

public interface MigrationReport {
/**
* @return The detailed migration feasibility description
*/
MigrationFeasibility getFeasibility();
/**
* @return The revision to which the composite(s) will be migrated.
*/
String getTargetRevision();
/**
* @return The number of composite instances matching the criteria for which
* this report was generated.
*/
long getCompositeInstanceCount();
/**
* @return The composite instances matching the criteria for which this
* report was generated.
*/
List<CompositeInstanceMigrationReport> getCompositeInstances();

8.8.2.3 Bulk Migration Execution

The Façade API migrates the instances (with a configurable batch size). Example 8-10 provides details.

Example 8-10 Bulk Migration Execution

/**
* Asynchronously attempt to migrate the composite instances described in the
* specified migration report.
* @param report - A MigrationReport, describing which composite instances should
* be migrated.
* @param plan - A MigrationPlan, specifying how those instances that cannot be
* automatically migrated should be handled.
*
* @return A unique migration result identifier, which can be used to subsequently
 retrieve the migration result.
*/
String migrateCompositeInstances(MigrationReport report, MigrationPlan plan).
/**
* Retrieves the migration result for the specified migration attempt.
*
* @param resultId - The unique identifier for a particular migration attempt; the
* result of invoking migrateCompositeInstances
* @return A MigrationResult, describing the results of the migration attempt.
*/
MigrationResult getMigrationResult(String resultId);
/**
* Synchronously attempts to migrate those composite instances that match the
* specified filter criteria
* to the specified target revision, applying the specified migration plan.
*
* The number of composite instances for which migration is attempted will be
* limited to some fixed number,
* unless a lesser maximum is otherwise specified. (TBD, can this be specified via
* the filter?)
*
* @param filter - The composite instance selection criteria
* @param targetRevision - The revision to which the composite instances should be
* migrated
* @param plan - The plan for handling those composites that cannot be
* automatically migrated
*
* @return A MigrationResult, describing the results of the migration attempt.
*/
MigrationResult migrateCompositeInstances(CompositeInstanceFilter filter, String
 targetRevision,MigrationPlan plan);

8.8.2.4 Migration Results

The MigrationResult interface describes the outcome of the attempt to migrate composite instances. Example 8-11 provides details.

Example 8-11 Migration Result

package oracle.soa.management.facade;
public interface MigrationResult extends Serializable {
/**
* @return The revision to which the composite instances were to be migrated.
*/
String getTargetRevision();
/**
* @return The total number of composite instances included in the migration
* attempt.
*/
long getCompositeCount();
/**
* @return The number of composite instances for which migration succeeded.
*/
long getMigratedCount();
/**
* @return The number of composite instances for which migration failed.
*/
long getFailedCount();
/**
* @return The list of composite instances that were successfully migrated.
*/
List<CompositeInstanceMigrationResult> getMigratedInstances();
/**
* @return The list of composite instances for which migration failed.
*/
List<CompositeInstanceMigrationResult> getFailedInstances();
}

8.8.2.5 Migration Plan

The MigrationPlan interface provides the XML description of what to do with nontrivial composite or component changes. Example 8-12 provides details.

Example 8-12 Migration Plan

public interface MigrationPlan extends Serializable {
/**
* @param componentDN A component distinguished name (less any label)
*
* @return The migration plan element for the specified componentDN
*/
org.w3c.dom.Element getComponentPlan(String componentDN);
/**
* @return The migration plan for the composite instances
*/
org.w3c.dom.Element getCompositePlan();
}

8.8.2.6 Migration API

The CompositeInstance Facade type includes methods to support the migration of a single composite instance. The bulk operations available directly from the Locator interface invoke the methods on individual composite instances. Example 8-13 provides details.

Example 8-13 Migration API

CompositeInstanceMigrationReport checkCompatibility(String revision);
/**
* Calls suspend on all the associated component instances
* Calls migrate for those same component instances
* Calls resume on all those same component instances
* The migration plan may contain component-specific directives.
*/
CompositeInstanceMigrationResult migrate(MigrationPlan plan);
public interface CompositeInstanceMigrationReport extends Serializable {
String getPartition();
String getCompositeName();
String getCompositeId();
String getRevision();
String getTargetRevision();
MigrationFeasibility getFeasibility();
long getComponentInstanceCount();
List<ComponentInstanceMigrationReport> getComponentInstances();
String getIncompatibilityReason();
}
public interface ComponentInstanceMigrationReport extends Serializable {
String getComponentName();
String getComponentId();
MigrationFeasibility getMigrationFeasibility();
String getIncompatibilityReason();
}
public class MigrationFeasibility implements Serializable {
public static MigrationFeasibility Automatic;
public static MigrationFeasibility MigrationPlanRequired;
public static MigrationFeasibility Incompatible;
public boolean isAutomatic();
public boolean isMigrationPlanRequired();
public boolean isIncompatible();
}
public interface CompositeInstanceMigrationResult extends Serializable {
/**
* @return true, if the composite instance and all its components were
* successfully migrated; otherwise, false.
*/
boolean migrated();
/**
*
* @return The name of the partition to which the composite is deployed
*/
String getPartition();
/**
* @return The composite name
*/
String getName();
/**
* @return The composite instance identifier
*/
String getId();
/**
* @return The previous revision
*/
String getRevision();
/**
* @return The revision to which the instance was to be migrated
*/
String getTargetRevision();
/**
* @return The migration results for the associated component instances
*/
List<ComponentInstanceMigrationResult> getComponentInstances();
/**
* @return The reason why the migration failed, if it failed; otherwise, null
*/
String getFailureReason();
}
public interface ComponentInstanceMigrationResult extends Serializable {
/**
* @return true, if the component instance was successfully migrated; otherwise,
* false.
*/
boolean migrated();
/**
* @return The component name
*/
String getName();
/**
* @return The component instance identifier
*/
String getId();
/**
* @return The reason why the migration failed, if it failed; otherwise, null
*/
String getFailureReason();
}
8.8.2.6.1 Retrieving the List of Failed Migration Components

When migration fails, you use the Java code shown in Example 8-14 to retrieve the list of failed components. If a composite instance state is marked as completed faulted and migration of the composite instance to another revision fails, f.getComponentInstances() returns a list of ComponentInstanceMigrationResult objects that can retrieve details about the component instances.

Example 8-14 Retrieving the List of Failed Migration Components

private static void validateMigrationResult(MigrationResult mr)
{
if (mr != null)
{
List<CompositeInstanceMigrationResult> failed =
 mr.getFailedInstances();
  
for (CompositeInstanceMigrationResult f: failed)
{
List<ComponentInstanceMigrationResult> failedComponents =
f.getComponentInstances();
System.out.println("Failed components list size: " +
failedComponents.size() + " Failed components list: " +
 failedComponents);
}
}
}

8.8.3 Migrating Instances with the ant Script

You can migrate instances using the $Middleware_Home/SOA_Suite_Home/bin/ant-bpm-migration.xml script shown in Example 8-15.

Example 8-15 ant-bpm-migration.xml Script

<?xml version="1.0" encoding="iso-8859-1"?>
<project name="ant-migration" basedir=".">
    <property environment="env"/>
    <property name="name" value="${ant.project.name}"/>
    <dirname property="imported.basedir" file="${ant.file.ant-migration}"/>
    <property name="mw.ora.home" location="${imported.basedir}/.."/>
    <property name="mw.home" location="${imported.basedir}/../.."/>
<!--
    <path id="ant-extensions.classpath">
        <pathelement
 path="${bpm.home}/generated/lib/oracle.bpm.runtime.public-tools.jar"/>
        <pathelement path="${bpm.home}/../pcbpel/fabric/lib/soa-infra-mgmt.jar"/>
        <pathelement path="${bpm.home}/../pcbpel/fabric/lib/fabric-common.jar"/>
        <pathelement path="${bpm.home}/../pcbpel/fabric/lib/xmlparserv2.jar"/>
        <pathelement path="${bpm.home}/main/libraries/batik-1.7/lib/xerces_2_5_
         0.jar"/>        <pathelement
         path="${bpm.home}/../pcbpel/fabric/lib/fabric-runtime.jar"/>
        <pathelement path="${bpm.home}/tools/lib/apb-ext/wlfullclient.jar"/>
        <pathelement path="${bpm.home}/../pcbpel/generated/jrf/wsclient_
extended.jar"/>
     </path>
-->
    <path id="ant-extensions.classpath">
        <pathelement
 path="${mw.ora.home}/soa/modules/oracle.bpm.runtime.public-tools.jar"/>
        <pathelement path="${mw.home}/oracle_common/soa/modules/oracle.soa.mgmt_
11.1.1/soa-infra-mgmt.jar"/>
        <pathelement path="${mw.home}/oracle_common/modules/oracle.fabriccommon_
11.1.1/fabric-common.jar"/>
        <pathelement path="${mw.home}/oracle_common/modules/oracle.xdk_
11.1.0/xmlparserv2.jar"/>
        <pathelement path="${mw.ora.home}/soa/modules/oracle.soa.fabric_
11.1.1/fabric-runtime.jar"/>
        <pathelement path="${mw.home}/wlserver_10.3/server/lib/wlfullclient.jar"/>
        <pathelement path="${mw.home}/oracle_common/webservices/wsclient_
extended.jar"/>
     </path>
    <!--
 ================================================================== -->
    <typedef name="locatorConfig"
 classname="oracle.bpmn.engine.tools.pub.migration.LocatorConfig"
 loaderRef="soa-infra-tools-loader">
        <classpath refid="ant-extensions.classpath"/>
    </typedef>
    <taskdef name="locatorSession"
 classname="oracle.bpmn.engine.tools.pub.migration.LocatorSession"
 loaderRef="soa-infra-tools-loader">
        <classpath refid="ant-extensions.classpath"/>
    </taskdef>
    <typedef name="compositeInstanceFilterDef"
 classname="oracle.bpmn.engine.tools.pub.migration.CompositeInstanceFilterDef"
 loaderRef="soa-infra-tools-loader">
        <classpath refid="ant-extensions.classpath"/>
    </typedef>
    <typedef name="generateMigrationReport"
 classname="oracle.bpmn.engine.tools.pub.migration.GenerateMigrationReport"
 loaderRef="soa-infra-tools-loader">
        <classpath refid="ant-extensions.classpath"/>
    </typedef>
    <typedef name="migrateCompositeInstances"
 classname="oracle.bpmn.engine.tools.pub.migration.MigrateCompositeInstances"
 loaderRef="soa-infra-tools-loader">
        <classpath refid="ant-extensions.classpath"/>
    </typedef>
    <!--<taskdef name="secure-input"
 classname="oracle.fabric.management.deployedcomposites.ant.TempInputTask">-->
        <!--<classpath>-->
            <!--<pathelement path="${handler.class.path}"/>-->
        <!--</classpath>-->
    <!--</taskdef>-->
    <!--<target name="...">-->
        <!--<secure-input message="Please enter password:"
 addproperty="password">-->
            <!--<handler
classname="oracle.fabric.management.deployedcomposites.ant.SecureInputHandler">-->
                <!--<classpath refid="handler.class.path"/>-->
            <!--</handler>-->
        <!--</secure-input>-->
    <!--</target>-->
    <!-- -->
    <!--
=============================================================-->
    <target name="help">
        <echo message="res=${myresource}"/>
        <echo
 message="mw=${mw.ora.home}/soa/modules/oracle.bpm.runtime.public-tools.jar"/>
        <echo message="
============================================================================="/>
        <echo message="Usage : "/>
        <echo message="===================================================================="/>    </target>
</project>

The ant-bpm-migration.xml script requires the wlfullclient.jar file in the $Middleware_Home/wlserver_10.3/server/lib directory. You can generate this client library JAR by performing the following tasks:

  1. Change to the following directory:

    cd $fmw.home/wlserver_10.3/server/lib
    
  2. Run the following command to build the client library JAR.

    java -jar wljarbuilder.jar
    

8.8.4 Example of Migrating a Revision Instance for Oracle BPM

This section provides an example of migrating a revision instance of the ReviewProcess composite that includes Oracle BPM. Because a human workflow approval task is removed in this example, a migration plan is required.

Figure 8-1 shows the instance flow for revision 1.0 of the composite. There are two human tasks in this revision of the composite, including VeryExpensiveUserReview, which is a time-consuming, user approval task.

Figure 8-1 Oracle BPM Instance Flow for Revision 1.0

Description of Figure 8-1 follows
Description of "Figure 8-1 Oracle BPM Instance Flow for Revision 1.0"

Figure 8-2 shows revision 1.0 of the composite in the SOA Composite Editor.

Figure 8-2 Composite Application for Revision 1.0

Description of Figure 8-2 follows
Description of "Figure 8-2 Composite Application for Revision 1.0"

Figure 8-3 shows the improved instance flow for revision 2.0 of the composite application.

The time-consuming VeryExpensiveUserReview human approval task has been removed. Instead, an automatic review with a service task is used. The service task delegates the review approval to an external web service.

Figure 8-3 Oracle BPM Instance Flow for Revision 2.0

Description of Figure 8-3 follows
Description of "Figure 8-3 Oracle BPM Instance Flow for Revision 2.0"

Figure 8-4 shows revision 2.0 of the composite application in the SOA Composite Editor.

Figure 8-4 Composite Application for Revision 2.0

Description of Figure 8-4 follows
Description of "Figure 8-4 Composite Application for Revision 2.0"

The following tasks occur during migration:

  • A new 2.0 revision is deployed, with an improved definition of ReviewProcess.

  • The new 2.0 revision runs side-by-side with the old 1.0 revision.

  • In-flight instances are migrated from one revision to another, as required.

To migrate a revision instance for Oracle BPM:

  1. Generate a migration feasibility report that decides:

    • Whether the selected composite instances are feasible to migrate.

    • Whether migration is automatic or manual with a migration plan. Since instances running in an activity are being removed, a migration plan is required.

    The migration plan specifies:

    • A flow update from the VeryExpensiveUserReview task in the old revision to the LegacyReview task in the new component.

    • An instance data update with a new value, later used in the LegacyReview task title.

  2. Create a migration plan in which the following tasks are performed:

    • The data object is updated.

    • The instance title value is updated.

    • The VeryExpensiveUserReview task flow is replaced with the LegacyReview task flow.

    You can place the migration plan in any directory location. A sample migration plan is provided at the following URL.

    http://java.net/projects/oraclebpmsuite11g/pages/Samples
    

    You can use the sample or create your own migration plan based on the XSD. You specify the path to the file when running the build.xml file to migrate the instance.

    Description of soa_instancemigr5.gif follows
    Description of the illustration soa_instancemigr5.gif

  3. Execute the Facade APIs in either of two ways:

    • Run the Facade APIs directly. For more information, see Section 8.8.2, "Migrating Instances with the Facade API."

    • Create a build.xml file for use with ant. For this example, ant is used. You can place the build.xml file anywhere in the directory structure. You must run ant from the same directory or run ant -f and specify the directory path location for build.xml.

      <property name="migrationPlanPath" value="${basedir}/migration_plan.xml"/>
      
      locatorConfig id="c1" host="${wls.host}" port=${wls.port}"
       user="{wls.user}" password="${wls.password}"/>
      compositeInstanceFilterDef id="f1" domainName="default" 
       compositeName="Project3" compositeInstanceId="40001"/>
      
      <target name="test">
         <locatorSession configId="c1">
            <generateMigrationReport filterId="f1" revision="2.0">
               <migrateReportedCompositeInstances migrationPlanPath=
                "${migrationPlanPath}"/>
            </generateMigrationReport>
         </locatorSession>
      </target>
      
  4. Create an instance of revision 1.0 of the SOA composite application. To migrate instances, both revisions 1.0 and 2.0 must be deployed. For more information about creating an instance, see Section 8.1, "Initiating a SOA Composite Application Test Instance."

    Description of soa_instancemigr7.gif follows
    Description of the illustration soa_instancemigr7.gif

  5. Click the instance ID of revision 1.0 (for this example, 40007).

  6. Click the ReviewProcess instance.

    Description of soa_instancemigr8.gif follows
    Description of the illustration soa_instancemigr8.gif

  7. Click the Flow tab.

    Description of soa_instancemigr9.gif follows
    Description of the illustration soa_instancemigr9.gif

    Revision 1.0 of the flow is shown. The instance is waiting on the parallel approval of the two instance tasks.

    Description of soa_instancemigr10.gif follows
    Description of the illustration soa_instancemigr10.gif

  8. Go to the location for the build.xml file.

  9. Change the compositeInstanceId value to migrate to 40007.

    Description of soa_instancemigr11.gif follows
    Description of the illustration soa_instancemigr11.gif

  10. In the upper right corner, run the ant script.

    Description of soa_instancemigr12.gif follows
    Description of the illustration soa_instancemigr12.gif

  11. View the ant build report to see that migration was successful.

    Description of soa_instancemigr13.gif follows
    Description of the illustration soa_instancemigr13.gif

  12. Return to the Instances page in Oracle Enterprise Manager Fusion Middleware Control.

  13. Click the Refresh icon, and note that the old instance is no longer displayed. This is because it was migrated to the new instance.

    Description of soa_instancemigr14.gif follows
    Description of the illustration soa_instancemigr14.gif

  14. In the navigator, click revision 2.0.

  15. Note that the migrated instance is displayed for the revision.

    Description of soa_instancemigr15.gif follows
    Description of the illustration soa_instancemigr15.gif

  16. Click the instance.

  17. In the Trace table, click ReviewProcess.

    The LegacyReview human workflow component is shown as running and the VeryExpensiveUserReview human workflow component is shown as withdrawn.

  18. Click the Flow tab.

  19. View the new flow with LegacyReview.

    Description of soa_instancemigr16.gif follows
    Description of the illustration soa_instancemigr16.gif

  20. Log in to Oracle Business Process Workspace.

    Description of soa_instancemigr17.gif follows
    Description of the illustration soa_instancemigr17.gif

  21. Click Process Tracking to refresh the page.

    Description of soa_instancemigr18.gif follows
    Description of the illustration soa_instancemigr18.gif

  22. Note that version ReviewProcess 2.0 is running.

    Description of soa_instancemigr19.gif follows
    Description of the illustration soa_instancemigr19.gif

  23. Go to the task to approve, and select Approve.

    Description of soa_instancemigr20.gif follows
    Description of the illustration soa_instancemigr20.gif

  24. Return to the instance in Oracle Enterprise Manager Fusion Middleware Control.

  25. Click the Flow tab.

  26. Note that the activity is displayed as approved.

    Description of soa_instancemigr21.gif follows
    Description of the illustration soa_instancemigr21.gif

8.8.5 Example of Migrating a Revision Instance with All Service Components

This example describes how to migrate a revision with a variety of service components:

  • Oracle Mediator

  • BPEL process

  • Human workflow

  • Business rules

  • Oracle BPM

To migrate a revision instance with all service components:

  1. Go to the Instances page in Oracle Enterprise Manager Fusion Middleware Control. For this example, there are three deployed revisions of the composite. Revision 1.0 has one instance (for this example, 40005).

    Description of soa_instancemigr22.gif follows
    Description of the illustration soa_instancemigr22.gif

  2. Click the instance ID and note the different service components in the revision.

    Description of soa_instancemigr23.gif follows
    Description of the illustration soa_instancemigr23.gif

  3. Invoke the Facade API to perform the following tasks:

    • Generate a migration report for migrating an instance from revision 1.0 to 2.0.

    • Attempt the actual migration.

    For this example, a simple JavaServer Page (JSP) interface is used to invoke the Facade APIs. You can create your own JSP interface. For information about the Facade API, see Section 8.8.2, "Migrating Instances with the Facade API."

  4. In the Target Revision field, enter a revision to which to migrate (for this example, 2.0).

    Description of soa_instancemigr24.gif follows
    Description of the illustration soa_instancemigr24.gif

  5. Click Submit.

    The report is completed and displayed in the following sections:

    • The Migration Report section indicates that all service components are eligible for automatic migration.

    • The Migration Result section indicates that all service components were successfully migrated.

    Description of soa_instancemigr25.gif follows
    Description of the illustration soa_instancemigr25.gif

  6. Return to the Instances page in Oracle Enterprise Manager Fusion Middleware Control.

  7. Refresh the page and note that the revision 1.0 instance is no longer available.

  8. Click revision 2.0 of the composite and note that instance 4005 is running.

    Description of soa_instancemigr26.gif follows
    Description of the illustration soa_instancemigr26.gif

  9. Click the instance ID and note that all service components were migrated. The Oracle BPMN service component is awaiting approval.

    Description of soa_instancemigr27.gif follows
    Description of the illustration soa_instancemigr27.gif

  10. Log in to Oracle Business Process Workspace.

  11. From the Actions list, select Approve.

    Description of soa_instancemigr28.gif follows
    Description of the illustration soa_instancemigr28.gif

  12. Return to the instance in Oracle Enterprise Manager Fusion Middleware Control and note that the service component instances have completed.

    Description of soa_instancemigr29.gif follows
    Description of the illustration soa_instancemigr29.gif

8.8.6 Example of Migrating a Revision with Incompatible Service Components

This example shows how migration is not possible because the BPEL process is using a durable wait activity.

  1. Using the Facade API, attempt to migrate an instance of revision 3.0 to 1.0. For this example, the JSP page used in Section 8.8.5, "Example of Migrating a Revision Instance with All Service Components" is again used.

  2. In the Target Revision field, enter a revision number (for this example, 1.0).

  3. Click Submit.

    Description of soa_instancemigr30.gif follows
    Description of the illustration soa_instancemigr30.gif

    The report is completed and displayed in the following sections:

    • The Migration Report section indicates that migration is incompatible due to an unsupported, durable BPEL process.

    • The Migration Result indicates that the subsequent migration attempt has failed.

    Description of soa_instancemigr31.gif follows
    Description of the illustration soa_instancemigr31.gif

  4. Return to the Instances page in Oracle Enterprise Manager Fusion Middleware Control.

  5. Click the Refresh icon, and note that the old instance was not migrated to the new instance.