13 Configuring Oracle Enterprise Repository Express Workflows

This chapter describes how to set up and configure Oracle Enterprise Repository (OER) Express Workflows.

This chapter assumes that you are familiar with the following concepts:

Assets and Asset Types, Asset submission, Asset Registration Status, Asset Categorizations. See Oracle Fusion Middleware Concepts Guide for Oracle Enterprise Repository for more information.
Projects and Users. See Chapter 1, "Basic Configuration" for more information.
Oracle SOA Suite application deployment. See Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for more information.

Note:

A restricted-use license for Oracle BPM Suite is included with OER. This license allows you to modify existing workflows that are supplied with OER. You can also create new OER-centric workflows using this license. If you want to create workflows that do not include OER, you must acquire a full license for the Oracle BPM Suite.

This chapter contains the following sections:

Section 13.1, "Introduction to Oracle Enterprise Repository Express Workflow"
Section 13.2, "Configuring Express Workflows"
Section 13.3, "Running the Sample Workflow"
Section 13.4, "Modifying the Sample Workflow"

13.1 Introduction to Oracle Enterprise Repository Express Workflow

Express Workflows, as described in this section, require Oracle SOA Suite and Oracle BPM Suite, both version 11.1.1.7 or higher.

Note:

It is recommended to have your SOA Suite, on which the Express Workflows SCA will be deployed, in its own managed server. Express Workflows might not function correctly on a Developer edition of SOA Suite, which deploys SOA Suite in the Admin Server.

Express Workflows in Oracle Enterprise Repository is a mechanism for automating the common asset lifecycle approval processes. OER provides a set of features and options for moving an asset from an initial to a final state. Express Workflows requires an asset approval process to include a combination of actions provided by the OER Asset Editor:

Asset Submission
Asset Acceptance
Asset Tab Approvals
Asset Registration

Value changes to the AssetLifeCycleStage and Classification categorizations are also necessary.

Organizations that need more complex workflow automation can also develop external workflows with other tools, such as Oracle Business Process Management Suite, and use the REX API interface described in the "Using the Repository Extensibility Framework" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle Enterprise Repository to access OER functions.

Express Workflows includes the following components:

Assets
Projects
Users
Approval Flows
Events and Actions

These components are related by an Express Workflow as follows:

An asset is submitted into the repository with a producing project. Note that Express Workflows require assets to have one and only one producing project.
The asset will automatically enter the flow upon submission or acceptance, if the indicated producing project has an approval flow assigned, and if the asset's type is identified for the approval flow. A project can have only one approval flow, and that gets kicked off only when relevant assets in that project are submitted or accepted.
An approval flow consists of groups, tiers, of asset tabs. Each tier has an assigned approver. The asset moves to the next tier, when the assigned approver has approved all the tabs in the tier.

An approval flow has settings determining if:

the flow begins on asset submission or acceptance
the asset is automatically registered when specified tabs are approved.

An OER administrator can create any number of approval flows and an approval flow can be assigned to any number of projects. Assets are manipulated by mappings of specific actions to discrete events, such as applying a custom access setting to an asset when it is registered or notifying subscribers when an asset's Life Cycle Stage categorization value changes.

13.2 Configuring Express Workflows

Express Workflows depends on these components:

Express Workflows SOA composite application (SCA)
OER Event Manager
Express Workflows configuration file

To configure Express Workflows:

Install the OER Express Workflow SOA Composite Application (SCA)
Configure OER Event Manager to deliver events to the deployed SCA
Define and configure your Express Workflow(s)

This section describes how to install the Oracle Enterprise Repository Workflow into Oracle BPM 11g and 12c. It contains the following topics:

Section 13.2.1, "Step 1: Install the OER Express Workflows SOA Composite Application"
Section 13.2.2, "Step 2: Configure OER Event Manager to deliver events to the deployed SCA"
Section 13.2.3, "Step 3: Define and Configure your Express Workflows"

13.2.1 Step 1: Install the OER Express Workflows SOA Composite Application

The Express Workflows SOA composite application listens for events delivered by the OER Event Manager to its web service endpoint. Installing this application requires an installed instance of Oracle SOA Suite and Oracle BPM Suite, both version 11.1.1.7 or higher. No additional configuration is required in your SOA Suite and BPM Suite servers.

Note:

Ensure that payload validation under soa-infra-->SOA Administration-->Common Properties is set to false before you proceed.

Deploying the Express Workflows SOA composite application on WebLogic Server

Log into the SOA Suite Enterprise Manager console, typically on, http://<soaserver_hostname>:<soaserver_port>/em .
On the left-side menu, expand SOA.
Click soa-infra.
Select Deployed Composites tab.
Click Deploy….
The Select Archive window appears.
Select the appropriate option in the Archive or Exploded Directory region.
Upload the composite delivered with the ExpressWorkflows zip file:
1. Navigate to the <FMW_Home>/oer/modules/tools/solutions/ directory.
2. Expand the 12.1.3.0.0-ExpressWorkflows.zip file.
3. Select the sca_OERWorkflows_rev1.0.jar file.
Click Next.
Select the default SOA partition. Click Next.
Click Deploy.

13.2.2 Step 2: Configure OER Event Manager to deliver events to the deployed SCA

The Event Manager is a component embedded within Oracle Enterprise Repository that manages event subscriptions, event persistence, event filtering, and event delivery.

External applications subscribe to the events generated as assets move through a lifecycle. For Express Workflows, a SOA composite application, deployed to an Oracle SOA Suite server instance, accesses these events via a web service endpoint defined in the OER configuration file.

Express Workflows supports the following events:

Asset submitted
Asset unsubmitted
Asset accepted
Asset unaccepted
Asset tab approved: value=<tab name>
Asset all tabs approved
Asset registered
Asset unregistered
Asset status changed: value="DELETED/INACTIVE/RETIRED"
Policy Assertion changed: value="pass/fail"
Categorization changed: AssetLifecycleStage (act on any change)
Categorization changed: AssetLifecycleStage: value="stage name"
Categorization changed: Classification (act on any change)
Categorization changed: Classification: value="stage name"

13.2.2.1 Configuring Web Service Endpoints

The Event Manager uses a configuration file to load information about the Web Service endpoints, where events are delivered. This file is delivered in the ExpressWorkflows.zip file at <FMW_HOME>oer/modules/tools/solutions. The EndPointEventSubscription.xml file should be extracted from ExpressWorkflows.zip, modified appropriately, and pasted into the <FMW_HOME>/oer/applications/oer/oer-app/WEB-INF/classes directory.

In this file, to add your SCA endpoint to receive events, create a new instance of the <sub:eventSubscription> element as in the example below:

        <sub:eventSubscription>
                <!--The name should be unique within this file since this name is passed as the Durable subscriber name to the JMS Server-->
                <sub:endPoint name="SOACompositeEndpoint">
 
                        <!--The host of the SOA Server hosting the composite -->
                        <sub:host>localhost</sub:host>
                        <!--The SOA Server listener port -->
                        <sub:port>9000</sub:port>
                        <!--The URI of the deployed composite -->
                        <sub:uri>soa-infra/services/default/OERWorkflows/HandleStatusChange.service</sub:uri>
                        <!--Unless a custom WSDL Contract is used, the namespace should not be changed -->
                        <sub:targetNamespace>http://www.bea.com/infra/events</sub:targetNamespace>
 
                        <!--The Webservice operation that is invoked. Please refer to the WSDL in WEB-INF\lib\eventNotifier.jar for all the available operations-->
                        <!--Unless a Custom Webservice is implemented, the operation should not be changed if it's ALBPM -->
                        <sub:operationName>newEvent</sub:operationName>                   
                        <!--Protocol for the SOA Suite server.  Use HTTPS if SSL-enabled  -->
                        <sub:protocol>HTTP</sub:protocol>
                        <!--The user and password to authenticate the composite deployed on the SOA Suite server. -->
                        <sub:authenticationData>
                                <sub:basicAuthentication>
                                        <sub:username>oer_workflow_user</sub:username>
                                        <sub:password></sub:password>
                                </sub:basicAuthentication>
                        </sub:authenticationData>
                </sub:endPoint>
 
                <!--The Java class that serializes the Event Data. Unless a custom class is written, this value should not be changed.-->
                <sub:notifierClass>com.bea.infra.event.notifier.plugin.http.DefaultHTTPEventNotifier</sub:notifierClass>
 
                <!--This expression filters the Event data and only the matched events are delivered to the Endpoint. The dafault is all the events are delivered. -->
                <!--Example:- asset_id BETWEEN 50000 AND 50100 -->
                                <sub:expression></sub:expression>
        </sub:eventSubscription>

In this file, the host, port, username, and password of the Express Workflows SOA composite endpoint must be configured manually, as shown in the example above. The above example is available from EndPointEventSubscription.xml, delivered in the 12.1.3.0.0-ExpressWorkflows.zip file located in the <FMW_HOME>oer/modules/tools/solutions directory.

Note:

Passwords must be encrypted, using either of the two encryption tools provided with OER. See Chapter 12, "Password Encryption".

Changes to this file will not take effect until the OER managed server is stopped and restarted, which you will be doing after enabling the Event Manager next. If the Event Manager is already enabled, you can restart the OER server now.

13.2.2.2 Enabling the Event Manager

With the Event Manager configuration completed, you must enable the Event Manager in Oracle Enterprise Repository to allow it to send events to external Web Service endpoints.

Click System Settings in the sidebar of the Oracle Enterprise Repository Admin screen.
Enter event in the System Settings Search to view all the Event Manager related settings.
Click True next to the Enable Event Manager property, cmee.eventframework.enabled.
Click Save.
Restart Oracle Enterprise Repository for the configuration changes to take effect.

13.2.3 Step 3: Define and Configure your Express Workflows

The Express Workflows components and their relationships are defined and configured in an XML file, which is read by the Express Workflows SOA composite application whenever an OER event is delivered to the application's web service endpoint.

A sample version of this file (and it's XSD) is provided with a sample workflow preconfigured to run when the configuration steps are completed. This sample file is at <FMW_HOME>/oer/modules/tools/solutions/12.1.3.0.0-ExpressWorkflows.zip

A more detailed explanation of the different elements of this XML is provided in Section 13.4, "Modifying the Sample Workflow".

Setting up the configuration file and enabling the sample workflow

Create a new OER user with the required permissions to launch the Asset Editor, edit assets, and approve tabs. See Chapter 1, "Basic Configuration" for information on users, roles and Basic Access Settings.
Save the original sample ExpressWorkflow.xml with a new filename.

Edit ExpressWorkflow.xml by entering the host and port of your OER server and the clear text password of your admin user in the <oerConnection> tag:

<oerConnection> 
  <uri>http://[OERHOST:PORT]/oer/services/FlashlineRegistry</uri>
            <registrar>
                <username>admin</username>
                <password>[your admin password]</password>
            </registrar>

Enter the username of your new OER user as the approver of tier2:

<approvalFlow name="Flow1" acceptOnAssetSubmission="true" registerOnFlowCompletion="true">
        <tiers>
            <tier name="Tier1">
                <approvers>
                    <oeruser>
                        <username>admin</username>
                              </oeruser>
                </approvers>
                <tabs>
                    <tab name="Overview"/>
 <tab name="Technical"/>
 <tab name="Documentation"/>
                </tabs>
            </tier>
            <tier name="Tier2">
                <approvers>
                                 <oeruser>
                        <username>[Your New Username]</username>
                                 </oeruser>
                </approvers>
                <tabs>
                    <tab name="Taxonomy"/>
                </tabs>
            </tier>

Encrypt the passwords in the file as per Chapter 12, "Password Encryption".
Save the file.
Verify the OER server is running, then run the Express Workflows validation script, delivered in <FMW_Home>/oer/modules/tools/solutions/12.1.3.0.0-ExpressWorkflows.zip, to check your expressWorkflow.xml file:

validateWorkflow.sh -settings [your expressWorkflow.xml file]
Create a new folder in your Oracle SOA Suite domain called oerconfig as follows:

<FMW_Home>\user_projects\domains\<SOAdomain>\oerconfig
Copy the validated file to the oerconfig folder with the name ExpressWorkflow.xml.

Your Express Workflows are now set up and configured with an enabled sample. You are now ready to move on to section Section 13.3 and run the sample.

13.3 Running the Sample Workflow

With your OER and SOA servers running, create a new asset of type Service in the repository.

Create a New Asset

Login to OER as admin or any user with asset creation rights.
From the Asset Editor, select New from the File menu.
In the Create a New Asset field, enter the asset name.
Select type of Service and initial state of Unsubmitted.
Click OK. The new asset tabs display.
On the Overview tab, select Common Project for Producing Project. Click Save.

Run the Sample

Login to OER as an admin user.
Go to My Stuff, where you see the newly created and submitted asset in your queue.
Open the asset editor and approve the Overview, Technical and Documentation tabs. Exit the Asset Editor.
Log out and log back into OER.
Go to My Stuff, find the Service asset and edit it to approve the Taxonomy tab. Exit the Asset Editor.
In the OER console, search for the Service Asset by name, with Registration Status set to Registered.

You will see the asset in the search results.

Description of expresswfsearch.gif follows

Description of the illustration ''expresswfsearch.gif''

13.4 Modifying the Sample Workflow

Once you have successfully run the sample workflow, you can modify it and/or create new workflows as follows:

Copy the installed ExpressWorkflow.xml to a new location and edit it to add new projects, users, asset types, event/action mappings and approval flows.
Run the validation script to ensure your changes are compatible with your running OER instance.
Replace the installed ExpressWorkflow.xml file with your new version.

Note:

Note the Express Workflows SOA composite reads the installed file every time it receives an event from the OER event manager, so any changes in a newly installed ExpressWorkflow.xml version will take effect immediately without a need to restart.

13.4.1 Modifying the Express Workflows Configuration File

Previously, you modified the ExpressWorkflow.xml file to:

identify your OER Server instance,
supply an encrypted password for the OER admin user,
modify the approver name for the second tier of asset tabs in the approval flow Flow1

13.4.1.1 Producing Projects

Here is an excerpt from the default ExpressWorkflow.xml file for producing project Common Project:

        <producingProject name="Common Project" approvalFlow="Flow1"/>
                <assetTypes>
                  <assetType name="Business Process"/>
                  <assetType name="Composite"/>
                  <assetType name="Service"/>
                </assetTypes>
           </producingProject>

name refers to an existing OER project. The validation script will generate an error if the specified project does not exist in the OER instance.
approvalFlow is an optional attribute which specifies a tiered tab approval, or governance flow, for assets created within this project. A producing project can have one approvalFlow or none.
assetType refers to existing types. All assets of the specified types, submitted within the producing project, will follow the project's specified approvalFlow and any event/action mappings specified for that asset type

Note:

Assets can be governed by Express Workflows only if they have one and only one producing project specified in the ExpressWorkflow.xml file.

13.4.1.2 Approval Flows

Express Workflows approval flows determine the behavior of specified assets as the assets tabs are approved during the governance process. Here is the ExpressWorkflow.xml excerpt, which you modified previously:

<approvalFlow name="Flow1" acceptOnAssetSubmission="true" registerOnFlowCompletion="true">
        <tiers>
            <tier name="Tier1">
                <approvers>
                    <oeruser>
                        <username>admin</username>
                              </oeruser>
                </approvers>
                <tabs>
                    <tab name="Overview"/>
 <tab name="Technical"/>
 <tab name="Documentation"/>
                </tabs>
            </tier>
            <tier name="Tier2">
                <approvers>
                                 <oeruser>
                        <username>[Your New Username]</username>
                                 </oeruser>
                </approvers>
                <tabs>
                    <tab name="Taxonomy"/>
                </tabs>
            </tier>

approvalFlow name identifies the flow and is used in the approvalFlow attribute of producingProject. This attribute is not used outside the expressWorkflow.xml file.
acceptOnAssetSubmission is an optional attribute which determines whether a specified asset will be accepted automatically when it is submitted (value="true") or whether the asset will be manually accepted by an OER user with sufficient access rights (value="false"). If this attribute is not specified, the default value is "false".
registerOnFlowCompletion is an optional attribute which determines whether a specified asset will be registered automatically when all of the tabs specified in the approval flow have been approved (value="true"). If this attribute is not specified, the default value is "false".
In the <tier> element, tier name identifies a combination of asset tabs.
In the <tier> element, approver indicates an existing OER user to whom the asset will be assigned, either upon asset acceptance for the first specified tier, or upon approval of all tabs of a previous tier.
In the <tier> element, tab name indicates specific asset tabs that must exist for the specified asset types, which will be approved within a particular tier.

13.4.1.3 Event-to-Action Mappings

Event-to-Action mappings offer an alternative method to specifying an approval flow for automatically accepting and registering an asset. These mappings apply only to the specified asset types. Different asset types within a project can have different (or the same) mappings.

Express Workflows recognizes a number of asset lifecycle events generated by the Event Manager and provides a mechanism for associating these events with specific actions on specific assets. The full list of supported events and actions are included further below in the syntax required for the ExpressWorkflow.xml file.

Examine the following sample producingProject element:

<producingProject name="Project1"/>
  <assetTypes>
    <assetType name="Service">
      <events>
        <event name="urn:com:bea:aler:events:type:AssetSubmission">
                  <actions>
                        <action name="AcceptAsset" />
                  </actions>
                </event>
                <event name="urn:com:bea:aler:events:type:AssetTabApproved">                  
                        <actions>
                          <action name="RegisterAsset" />
                                <tabs>
                                        <tab name="Management Review" />
                                </tabs>                        
                          </action>
                        </actions>
                </event>
          </events>
        </assetType> 
  </assetTypes>
</producingProject>

In the above example, Project1 does not have an approval flow specified. It does, however, have event-to-action mappings specified for assets of type Service. The first mapping will automatically accept any asset of type Service when it is submitted. The second will register the asset when the "Management Review" tab is approved.

In the following example, we automatically apply a Custom Access Setting to assets of type Service when they are registered by the approval flow, Flow1 from the default expressWorkflow.xml file:

<producingProject name="Project2" approvalFlow="Flow1"/>
  <assetType name="Service">
    <event name="urn:com:bea:aler:events:type:AssetRegistered">
        <action>ChangeCAS</action>
        <customAccessSettings>
         <customAccessSetting>[YourSetting]<customAccessSetting/>
        </customAccessSettings>
        <assetLifecycle/>
    </event>
  </assetType>       
</producingProject>

Custom Access Settings can be used to control the visibility of an asset within a governance community, so the setting in this example would most likely be used to expose an asset to potential consumers after the approval process was complete.

In general, producing projects can either specify approval flows, or specify event-to-action mappings for specific asset types, or both. When both are used, however, you must take care to avoid overlapping or confusing rules, for instance specifying tabs for approval in an approval flow tier and specifying an Approve Tab action within the an event-to-action mapping.

Following is a list of events and actions supported by Express Workflows.

Supported Events

urn:com:bea:aler:events:type:AssetSubmission
urn:com:bea:aler:events:type:AssetUnSubmission
urn:com:bea:aler:events:type:AssetAccepted
urn:com:bea:aler:events:type:AssetUnAccept
urn:com:bea:aler:events:type:AssetTabApproved
urn:com:bea:aler:events:type:AssetAllTabApproved
urn:com:bea:aler:events:type:AssetRegister
urn:com:bea:aler:events:type:AssetUnregister
urn:com:bea:aler:events:type:PolicyAssertionChanged
urn:com:bea:aler:events:type:CategorizationChanged:assetLifecycleStage
urn:com:bea:aler:events:type:CategorizationChanged:classification

Supported Actions

ChangeCAS: applies one or more Custom Access settings to an asset
ChangeAssetLifecycle: sets the Asset Lifecycle Stage of an asset
ChangeClassification: sets the classification of an asset
ReAssignAssetToRegistrar: assigns the asset to Registrar
NotifySubscriber: notifies the Subscribers about the Metadata Change
ApproveTab: approves one or more tab
UnapproveTab: unapproves one or more tab
AcceptAsset: accepts the asset
UnacceptAsset: unaccepts the asset
RegisterAsset: Unregisters the Asset if the asset is in registered state.
UnRegisterAsset: Unregisters the Asset if the asset is in registered state.
PublishAssetToUddi: Moves individual services and their metadata to Oracle Service Registry by wiring the events that get triggered when these services are registered or a lifecycle of a service is changed.