36 Managing Oracle BPMN Service Components and Engines

This chapter describes how to manage BPMN process service components and service engines.

This chapter includes the following topics:

36.1 Managing BPMN Process Service Component Policies

You can attach and detach policies to and from BPMN process service components in currently deployed SOA composite applications. Policies apply security to the delivery of messages. Oracle Fusion Middleware uses a policy-based model to manage web services.

Note:

Before attaching policies, see Administering Web Services for definitions of available policies and details about which ones to use in your environment.

To manage BPMN process service component policies:

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

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...

    Select Service Engines > BPMN.

    1. Select soa-infra.

    2. Right-click and select Service Engines > BPMN.

  2. Go to the Composites column of the View table and select a specific SOA composite application to access its Dashboard page.

  3. Click Policies.

    The Policies page enables you to attach and detach policies to and from BPMN process service components. The policies table displays the attached policy name, the policy reference status (enabled or disabled) that you can toggle, the category (Management, Reliable Messaging, MTOM Attachment, Security, or WS Addressing), the violations, and the authentication, authorization, confidentiality, and integrity failures since the SOA Infrastructure was last restarted.

    Description of GUID-B070CA4E-A9A1-4E20-9C27-FDE90CB522F9-default.png follows
    Description of the illustration GUID-B070CA4E-A9A1-4E20-9C27-FDE90CB522F9-default.png

  4. Click Attach/Detach.

    If multiple components are available, you are prompted to select the service or component for which to perform the attachment or detachment.

  5. Select the service or component to which to attach or detach a policy.

    This invokes a dialog for attaching or detaching policies.

    Policies currently attached appear in the Attached Policies section. Additional policies available for attachment appear in the Available Policies section.

  6. Select to attach policies appropriate to your environment.

  7. Click Attach.

  8. When you are finished attaching policies, click Validate.

  9. If an error message appears, make the necessary corrections until you no longer have any validation errors.

  10. Click OK.

    The attached policy is displayed in the policies table.

For more information, see the following documentation:

36.2 Performing BPMN Process Service Engine Message Recovery

You can perform a manual recovery of undelivered invoke or callback messages due to a transaction rollback in the process instance. Recovery of invoke messages applies to asynchronous BPMN processes only. Synchronous BPMN processes return an error to the calling client and are not recoverable from this page. Recoverable activities are activities that failed and can be recovered. For example, if you are using the file adapter to initiate an asynchronous BPMN process and your system crashes while the instance is processing, you can manually perform recovery when the server restarts to ensure that all message records are recovered.

Note:

If you encounter the error message ORA-01000: maximum open cursors exceeded, then do the following:

  1. Shut down the Oracle database.

  2. Increase the value of OPEN_CURSORS to 1500.

  3. Restart the Oracle database.

To perform BPMN process service engine message recovery:

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

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...

    1. Select Service Engines > BPMN.

    1. Right-click soa-infra.

    2. Select Service Engines > BPMN.

  2. Click Recovery.

    The Recovery page displays the following details:

    • A utility for searching for a specific message failure by specifying criteria and clicking Search. Click the Help icon for details.

    • Message failure in the service engine, including the conversation ID, whether you can recover from the message failure, the service component and composite application in which the failure occurred, and the time at which the fault occurred.

    Description of GUID-9A8A5400-0C66-497F-8B9E-2071F0BAED2A-default.png follows
    Description of the illustration GUID-9A8A5400-0C66-497F-8B9E-2071F0BAED2A-default.png

  3. Select a fault in the table.

  4. Select one of the following options:

    Action Description

    Recover

    Retries the message in which the fault occurred.

    If an asynchronous BPMN process encounters a transaction rollback scenario because of any underlying exception error, it rolls back to the last dehydration activity. If this is a new instance, and a receive activity was the first dehydration activity, the BPMN process service engine creates a recoverable invoke. When you click Recover to recover the invoke, the service engine creates a new instance. This instance may run to completion with no exception error. However, you continue to see the older instance identified as faulted.

    Mark Cancelled

    Marks the message so it is never delivered.

Once a message is submitted for recovery, the BPMN process service engine may take time to complete the action. This typically takes less than several seconds. During this time, the message remains visible in the Recovery page. Duplicate attempts to recover the same message in that period are ignored. Refresh the page every few seconds to receive the latest recovery status.

36.3 Migrating Instances Between Different Composite Application Revisions

Note:

This feature is only applicable to Oracle BPMN projects that do not include asynchronous BPEL processes.

In Release 12.1.3, instance migration between revisions is based on flow instances instead of composite instances. For a set of flow instances and a composite type, all instances of the composite in each flow are migrated. A flow migration first obtains the component instances for the flow instance and composite type from each of the composite's associated service engines. The service engine is then requested to migrate each of those component instances, one at a time.

The reasons for migrating flow instances include the following:

  • Design or implementation errors are discovered in the initial revision of the process or potentially invalid data provided by external services has placed the process in a bad state.

  • Processes are taking too long to complete. For example, you may have flow instances that run for months or years. Because of this:

    • Changes may need to be applied while the flow instances are in-flight.

    • Changes are unknown beforehand so they cannot always be modeled as rules or short-lived subprocesses.

    • Regulation or policy changes (applying new or modified enforcement of policies) require additional steps to be added to all processes.

The following restrictions apply to flow instance migration:

  • Both composite revisions must be deployed.

  • Only running flow instances can be migrated. You cannot migrate completed, suspended, or faulted flow instances, except for Oracle Mediator, which can be in a faulted state and still successfully migrated.

  • Only compatible flow instances can be successfully migrated. Compatibility depends upon the compatibility of the associated service component in the composite. Nontrivial changes cannot be migrated.

  • There is a transaction boundary per flow instance. You typically operate on batches of flow instances related to a specific composite. Each flow instance is bound to a single transaction. Migration of one or more flow instances can fail without failing the entire batch.

Two migration methods are supported:

  • Automatic migration: For trivial changes between revisions. Each flow instance is bound to a single transaction. You can migrate a batch of flow instances.

  • Manual migration using a migration plan (Oracle BPM only): This is for nontrivial changes between revisions. The migration plan describes how to perform the migration.

36.3.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 flow instance is not eligible for migration. The SOA composite application flow instance is only migrated if the associated service component flow 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 flow instances. Flow instance tracking data is migrated to the new revision.

The flow instance must have at least one active component instance of the following states:

  • Running

  • Recovery required

  • Suspended

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

Table 36-1 Service Component Flow Instance Migration Details

Service Component Supported Migration Types Migration Restrictions

BPEL process

Automatic migration of BPEL process flow 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 flow instances are migrated.

Oracle Mediator

Automatic migration of Oracle Mediator flow 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.

Instances must be in one of the following states: completed successfully, faulted, or terminated by user.

Human workflow

Automatic migration of human workflow flow instances to a new revision

None (all running and completed instances are migrated).

Business rules

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

None.

Oracle BPM

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

You cannot migrate flow instances between incompatible models. Examples of incompatible flow 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.

Note:

Flow instance migration fails for an instance that includes an Oracle Mediator service component with parallel routing rules and an Oracle BPMN service component.

36.3.2 Migrating Instances with the ant Script

You must create an ant script to perform a migration. The script must import the $Middleware_Home/soa/bin/ant-flow-instance-migration.xml script.

You can get help to create your ant script with the following command:

ant -f $Middleware_Home/soa/bin/ant-flow-instance-migration.xml help

The following elements are supported:

  • locatorConfig: defines locator configuration

  • locatorSession: represents locator session

  • flowInstanceFilterDef: filter that selects the flow instances to migrate. This element supports the following attributes:

    • id (required)

    • compositeDN (required)

    • flowId

    • pageStart

    • pageSize

    • tenantId

    • maxCreationDate

    • minCreationDate

    • maxModifyDate

    • minModifyDate

    • like

    • ecid

    • conversationId

    • compositeName

    • domainName

    • label

    • revision

    • title

  • generateFlowMigrationReport: synchronously generates flow migration report

  • migrateFlowInstances: synchronously migrates flow instances

The code sample below shows an example of the ant-flow-instance-migration.xml script.

<?xml version="1.0" encoding="iso-8859-1"?>
<project name="migration-test1" basedir="." default="test">
    <property name="env" environment="env" value="env"/>
    <property name="mw.ora.home" value="${env.MW_ORA_HOME}"/>
    <import file="${mw.ora.home}/bin/ant-flow-instance-migration.xml"/>
    <property name="reports.dir" value="${baseDir}/reports"/>
    <locatorConfig id="c1" host="localhost" port="7001" user="weblogic"
 password="weblogic1"/>
 
    <target name="test">
        <flowInstanceFilterDef
            id="f3"
            compositeDN="default/SubProcess!1.0"/>
        <locatorSession configId="c1">
            <generateFlowMigrationReport  filterId="f3"
                                          revision="2.0"
                                          outputFile="${reports.dir}/
                                           migrationReport.html"/>
            <migrateFlowInstances  filterId="f3"
                                   revision="2.0"
                                   migrationPlan="${basedir}/ 
                                    TaskRemovedInSubprocess-plan.xml"
                                   outputFile="${reports.dir}/ 
                                    migrationResult.html"/>
        </locatorSession>
    </target>
</project>

36.3.3 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 36-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 36-1 Oracle BPM Instance Flow for Revision 1.0

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

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

Figure 36-2 Composite Application for Revision 1.0

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

Figure 36-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 36-3 Oracle BPM Instance Flow for Revision 2.0

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

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

Figure 36-4 Composite Application for Revision 2.0

Description of Figure 36-4 follows
Description of "Figure 36-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.

36.3.3.1 Migrating a Revision Instance

To migrate a revision instance for Oracle BPM:

  1. Generate a migration feasibility report that decides:

    • Whether the selected 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.

    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 GUID-158B3907-8BF7-4780-8FC5-015B098465D9-default.gif follows
    Description of the illustration GUID-158B3907-8BF7-4780-8FC5-015B098465D9-default.gif
  3. 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">
      <generateFlowMigrationReport filterId="f1" revision="2.0">
         <migrateReportedCompositeInstances migrationPlanPath=
          "${migrationPlanPath}"/>
      </generateFlowMigrationReport>
   </locatorSession>
</target>
  4. Create a business flow 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 Initiating a Test Instance of a Business Flow.
  5. On the Flow Instances page, click the flow ID of revision 1.0 (for this example, 40007).
  6. In the Trace table, click the ReviewProcess instance.
  7. Click the Flow tab.

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

    Description of GUID-D40DC514-DD48-443C-B4AB-8928AA0C8EF4-default.gif follows
    Description of the illustration GUID-D40DC514-DD48-443C-B4AB-8928AA0C8EF4-default.gif
  8. Go to the location for the build.xml file.
  9. Change the flowId value to migrate to 40007.
  10. In the upper right corner, run the ant script.
  11. View the ant build report to see that migration was successful.
  12. Return to the Flow 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.
  14. In the navigator, click revision 2.0.
  15. Note that the migrated instance is displayed for the revision.
  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.
  20. Log in to Oracle Business Process Workspace.
  21. Click Process Tracking to refresh the page.
  22. Note that version ReviewProcess 2.0 is running.
  23. Go to the task to approve, and select Approve.
  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.