9 Configuring Oracle Enterprise Repository Express Workflows
This chapter describes how to set up and configure Oracle Enterprise Repository (OER) 11g Express Workflows.
This chapter contains the following sections:
This chapter assumes that you are familiar with the following concepts:
-
Assets and Asset Types, Asset submission, Asset Registration Status, Asset Categorizations (Oracle Fusion Middleware User's Guide for Oracle Enterprise Repository)
-
Projects and Users (Oracle Fusion Middleware Configuration Guide for Oracle Enterprise Repository )
-
Oracle SOA Suite application deployment (Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite)
9.1 Introduction to Oracle Enterprise Repository Express Workflow
Express Workflows, as described in this section, require:
-
OER PS6 (11.1.1.7), with Patch 17420982 applied
-
Oracle SOA Suite + Oracle BPM Suite, both 11.1.1.7
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 Part IV of the Oracle® Fusion Middleware Integration 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.
9.2 Configuring Express Workflows
Express Workflows depends on these components:
-
Express Workflows SOA composite application (SCA)
-
OER Event Manager
-
Express Workflows configuration file
Here are the steps involved for the configuration:
-
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 10.3.2. It contains the following topics:
9.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 11g R1+ with BPM Suite. 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.
-
Upload the composite delivered with the ExpressWorkflows patch:
-
Click Next.
-
Select the default SOA partition. Click Next.
-
Click Deploy.
9.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. For detailed information on options for other applications to access OER events, see [Chapter 9.4 of the Oracle Fusion Middleware Configuration Guide for Oracle Enterprise Repository].
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"
9.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 in the OER installation at <oer webapp name>\WEB-INF\classes\EndPointEventSubscription.xml
e.g. C:\ofm_wls1036\user_projects\applications\oer_domain\applications\oer_11.1.1.7.0\oer-app\WEB-INF\classes\ EndPointEventSubscription.xml
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:
In this file, the host, port, username, and password of the Express Workflows SOA composite endpoint, must be configured manually, as shown in Example 1 above. The comments on the rest of the tags are self explanatory. The above example is available in the Express Workflows patch, located in the sample file <OERHome>\repository111\core\express-workflows-config\EndPointEventSubscription.xml
Note:
Passwords must be encrypted, using either of the two encryption tools provided with OER. See Section 5.2 Generating Encrypted Passwords in the Oracle Fusion Middleware Configuration Guide for Oracle Enterprise Repository.
Changes to this file will not take effect until the OER 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.
9.2.2.2 Enabling the Event Manager
With the Event Manager configuration done, now the Event Manager must be enabled 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.
9.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. In the OER installation, this sample file is at <OERHome>\repository111\core\express-workflows-config\expressWorkflow.xml
A more detailed explanation of the different elements of this XML is provided in the Modifying the Sample Workflow section further. For now, we will configure the file and enable the sample workflow.
Setting up the configuration file and enabling the sample workflow
-
Create a new OER user with the access to launch the Asset Editor, edit assets, and approve tabs. See Section 1.3 of the Oracle® Fusion Middleware Configuration Guide for Oracle Enterprise Repository for information on users, roles and Basic Access Settings.
-
Save the original sample ExpressWorkflow.xml with a new filename.
-
Edit ExpressWorkflow.xml: Enter the host: 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 Section 5.2 Generating Encrypted Passwords in the Oracle® Fusion Middleware Configuration Guide for Oracle Enterprise Repository.
-
Save file.
-
Verify the OER server is running, then run the Express Workflows validation script (<OERHome>\repository111\core\express-workflows-config\validateWorkflow.sh) 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:
<SOAHome>\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 the next section and run the sample.
9.3 Running the Sample Workflow
With your OER and SOA servers running, create a new asset of type Service in the repository.
-
Login to OER as admin or any user with asset creation rights
-
From the Asset Editor, select File>New.
-
In the Create a New Asset, enter the asset name.
-
Select type, Service and initial state: Unsubmitted.
-
Click OK. The new asset tabs display.
-
On the Overview tab, select Common Project for Producing Project. Click Save.
-
Login to OER as an admin user.
-
Go to "MyStuff", 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 as the new user you just created.
-
Go to MyStuff, 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.
9.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.
9.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
9.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 ExpressWorkflow only if they have one and only one producing project specified in the ExpressWorkflow.xml file.
9.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>
-
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".
-
Tier name identifies a combination of asset tabs.
-
Tier approver indicates an existing OER user to whom the asset will be assigned, either upon asset acceptance for the first specified tier, of upon approval of all tabs of a previous tier.
-
Tier tab name indicates specific asset tabs, which must exist for the specified asset types, which will be approved within a particular tier.
9.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 producing project:
<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 assetType 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.
-
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
-
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.