Raise and Capture EDN Events for SOA / BPM Human Task Components

The Human Task component offers functionality to raise EDN events when certain actions related to a Task occur. The screenshot below shows the page in JDeveloper where this functionality can be initialised:


It is then your responsibility to implement the functionality that captures the triggered EDN events and process them in a way that fits your requirements.

I will cover an example where:
  • An OnAssigned event is raised
  • Captured by a Mediator in a separate SOA Composite 
  • BPEL in SOA Composite sends out an email notification. 
Lets get started
1. We have a very basic SOA/BPM composite which has 1 BPMN and 1 Human Task component as follows:


2. We want to modify the Human Task component so that it raises EDN Events for specific actions. The below screenshot shows that the Human Task will fire OnAssign and OnCompleted EDN events. 

Once you have completed that, there are no further modifications required for the current project. It has been configured so that an EDN event will be raised. The BPM project can be deployed to the SOA Server.

Now we must implement functionality to capture the specific EDN Events. 

3. We will capture the EDN events in a new SOA composite. Create a new SOA Project SOAReceiveHumanTaskEvents


4. In the SOA Composite, drag on a Mediator component. Select Subscribe to Events as the Mediator Template: 

5. We must define the definition of the EDN event is captured, click on the Green plus icon: 

6. Click on the Magnifying glass and select HumanTaskEvent.edl. This definition is provided by Oracle and is located in MDS (ensure you have a connection to your SOA server MDS in resource palette) - it can be navigated to via the below structure:

7. Click OK and select the specific Event you want your Mediator to subscribe to. Considering we want to subscribe to Assign events, choose OnTaskAssigned from the list:

8. Click OK. In the Mediator Template, you can add further Event subscriptions so that your Mediator can subscribe to multiple events. You can then define the routing that takes place by the Mediator when a specific Event is captured. The below screenshot shows that the Mediator also subscribes to OnTaskCompleted events:

9. Once you click OK, your composite will look like this: 

10. Now we need to implement a component to which the Mediator will route to once a specific EDN event is captured. We will add a simple BPEL component into the composite. There is a TaskNotification.xsd schema that can also be utilised from MDS for the input/output for the BPEL but for this example, it is not a requirement:

11. Inside the BPEL, drag in an Email component and populate the fields as such:

12. Once your BPEL is complete, close it and return to the Composite view. Now we need to add a wire from the Mediator to the BPEL component. Drag a wire from the Mediator to the BPEL - a dialog is displayed asking for the Operation to be triggered for a specific EDN event caught: 

13. Once the Event Mediator has been wired, deploy the Composite to your SOA server so that we can test it.

14. Create a test instance for the BPM Project:

15. Launch the Flow Trace and we can see that an OnTaskAssigned Event was triggered, our SOAReceiveHumanTaskEvents service caught the event and the Mediator routed it to the TaskAssignedBPEL component:

16. To complete the example, the TaskAssignedBPEL sends out an Email Notification:

Further Comments
1. In this example, a separate SOA project was created to capture and process  the EDN events. We could have implemented the Mediator to capture events within the BPM project. However, the separation approach increases abstraction, reduces complexity and improves maintainability. 

2. Sending an Email at the end of the EDN capture event is just an example, but it shows the capabilities available. We can implement auditing mechanisms for each type of action on a Task or further extend the Notification capabilities available such as Sending an SMS, etc.




Configure User holidays or vacations for automatic Human Task assignment in Default and Custom BPM Workspace

This post is demonstrated using 11.1.1.7

Configuring User Holidays/Vacations in BPM is fairly straight forward. The users can set up Holidays and select other Users to reassign tasks to. So if a task is assigned to a specific User and that user is on holiday, then the task is automatically re-assigned to the User the user has chosen.

They can make use of this functionality via the Default BPM Workspace or from a custom BPM Workspace implementation.

Default BPM Workspace (localhost:port/bpm/workspace)
We will perform the User Holiday tests with our good friend jcooper.

1. Log into the BPM Workspace

2. Click on Preferences at the top right:

3. Click on Rules on the left:

4. Click on Vacation Period (disabled)
    - Tick Enable Vacation Period
    - Select the Start and End Date
    - Tick Reassign to and look up the User you would like to reassign tasks to
    - Click Save

Once saved, the Vacation Period rule will change to Vacation Period (enabled) to indicate that a Vacation/Holiday period is active:

5. The above step is the simple quick way to create a holiday period. The functionality offers a further advanced approach to setting up rule based reassignments based on certain conditions e.g. the task name. Multiple rules can be enabled so that assignment of different tasks can be handled in different ways.

To view this functionality, click on My Rules then click on the green plus. The below screenshot shows an example of what a user could enter:

6. To test the functionality, I have used a simple BPM process where the first step is a Human Task component and is assigned to jcooper when initialised.

Once a test case is created, when we drill into the initialised human task instance in the Flow Trace of the EM, we can see that it was firstly assigned to jcooper, then the reassignment vacation rule removed it from jcooper and created the same instance for achrist - our chosen reassignment candidate:

7. We can log into the BPM Workspace with achrist and find an instance of the BPM Process awaiting her attention:



Custom BPM Workspace
If you have a custom BPM application implemented via adflibTaskListTaskFlow.jar, then you can make use of the task flow provided by this jar. The task flow is called rules-task-flow-definition.

Expose this task flow on a page and the user will see the same Rules page from the Default BPM Workspace. Be sure to grant this task flow priviledges in jazn-data.xml before deploying.


Note: I do not think it is possible for an admin to control Vacation rules on behalf of Users using the UI. So if a User comes back from Vacation/Holiday, it is their responsibility to ensure that their Vacation Rules are correct. An admin may be able to modify Vacation Rules on behalf of the user using the BPM API... but that is a separate investigation and would require a separate post! :)

Part 2 - Send emails from Oracle BPM using Mail Activity - Implement Mail Activity in BPM

Before going ahead with this implementation, please ensure you have completed the EM Configuration. This can be completed by following Part 1 of this blog post:
Part 1 - Send emails from Oracle BPM using Mail Activity - Weblogic EM Configuration

Implement a send Mail activity within a BPM Process in JDeveloper BPM Studio

In a BPM Process there is quite often the requirement to send an email to user(s) to keep them updated or to make them aware of an event that has taken place. It is actually straight forward to achieve this.

We will use a very simple BPM process to illustrate:

1. Firstly, we will create a Data Object to store the entire output payload of the worked human task called Task_DO of type TaskExecutionData:

2. Next, select the Mail Activity from the Notification components:

And drag it into the BPM Process:

3.  In the General tab, we populate 2 fields. 
     - Enter Default into the From Account field, this will be obtained from your configuration in EM.
     - Enter the Email address you want to send an email to in the To field. This can also be extracted from a Data Object via XPath. To send to multiple emails, separate each email address with a semi colon (;)

4. In the Content tab, you populate the Subject and Body of the email. This can be made up of static text or from expressions as shown below:
For reference, the expression in the Body is: concat('Task Number ', bpmn:getDataObject('Task_DO')/ns:systemAttributes/ns:taskNumber, ' has been worked by ', bpmn:getDataObject('Task_DO')/ns:systemAttributes/ns:updatedBy/ns:displayName, ' with an outcome of ', bpmn:getDataObject('UserTask_outcome'))

5. We can also add attachments to the mail via the Attachments tab. The value must map to an element of type base64Binary, which holds the document in a binary format. The Mime Type must reflect the type of stored document too.



If you navigate back to your Composite, you will see a new external reference created to a Notification Service Web Service. The WSDL referenced is NotificationService.wsdl and is stored in MDS so you do not have to worry about maintaining it:


6. Now, your implementation from a development perspective is complete. Let's see the project in action.

Deploy the BPM project to your Weblogic SOA server.

7. Create an instance for the deployed BPM Project via EM:


8. Work the running instance of the Human Task:


9. Check the BPM Flow to confirm a successful flow.


10. Check your Email Inbox for the Email address you entered. Voila!


11. You can also monitor the status of instances of the Email User Messaging Driver from the EM:



Part 1 - Send emails from Oracle BPM using Mail Activity - Weblogic EM Configuration

To get sending Emails to work from your SOA/BPM process, there is a mandatory requirement to firstly configure Weblogic Enterprise Manager (EM) so that it registers with your Email server.

Once it has been set up, when a send Email component is implemented, it will use this configuration at run time to Send/Receive emails successfully. Follow below steps to make the required configuration in EM.

Part 2 of this blog post shows how to implement sending Emails in a BPM process (Link)

Assumptions
This post assumes you have an Email Server running successfully in your infrastructure.

Configure Weblogic Enterprise Manager (EM) to register with Email Server

1.
Log into Weblogic Server EM (localhost:7001/em)

2. Click on soa-infra:

3. Navigate to Workflow Properties via SOA Infratructure and SOA Administration:


 4. - Notification Mode: Select Email from the drop down.

     - Email From Address: Enter an email address that ends with your Email Server domain name e.g. bpmadmin@CompanyDomainName.co.uk. This is the email address users will receive emails from.
     - Email Actionable Address: Same as above
     - Email Reply To Address: This is the reply email used when a user clicks reply on a sent email. If you do not support replies, then use something like no_reply@CompanyDomainName.co.uk


5. Click Apply.

6. Next, on the same page, click on Go to the Messaging Driver Page:

Alternatively, you can also get to the same screen via the screenshot below:

7. For the User Messaging Email Driver, click on the pencil to Configure Driver:


8. Now, the main field to populate is OutgoingMailServer. In this field, populate with the Email Server name.

Our test Email Server does not require a Username and Password, however, yours might. If so, populate OutgoingUsername and OutgoingPassword.

The rest can be left as default.Once completed, click Apply:

Note: The above changes will support only sending emails, not receiving emails. If you would like to support receiving emails, then values need to be populated for IncomingMailServer too.

9. Once the above changes have been made, do not forget to restart your Weblogic Server for changes to take effect. 

Once the server is back up, your server should be hopefully configured to support sending emails!




Implementing a software solution is a lot like fitting a new bathroom!

You read it right, implementing a software solution is a lot like fitting a new bathroom! (I have not gone mad, keep reading).

We recently had a new bathroom fitted and when I first used it, I noticed that the sink tap was not completely straight... I'd been dealing with several software bugs at work during the day and automatically thought of the tap as being a software bug!

One thought led to another and eventually, I was in the process of comparing the installation of the new bathroom to a software lifecycle...!

Let's take the following simple diagram of a Software Development Lift cycle for reference:



Now lets look at the similarities of a new software solution vs. a new bathroom:

Budget
Before the decision of installing anything is made, firstly budgets need to be allocated for specific departments
  • Software
    • A company decides a software system requires implementing/upgrading and allocates a budget for the affected department(s)
  • Bathroom
    • A home owner decides a new bathroom requires fitting and allocates a budget for it

Requirements analysis
Vendor 
  • Software
    • A company decides what Software vendor will be used to purchase the software from (if any), and what technologies will be utilised e.g. Oracle - Middleware Stack, IBM - Rational Suite, JAVA etc.
  • Bathroom
    • A home owner decides from what bathroom vendor the bathroom will be purchased from e.g. IKEA, B&Q etc.
Implementor
  • Software
    • A company decides who will implement the software system into the Company systems e.g. Third party software solutions company, internal I.T department, contractors etc.
  • Bathroom
    • A home owner decides who will fit the bathroom e.g. Bathroom fitters, builders, homeowner themselves etc.
Requirements
  • Software
    • A company requires functional/non-functional requirements for the software system to be based on and will use Business analysts, solution architects, business users etc. to design them
  • Bathroom
    • A home owner will make use of bathroom specialists, peers, contacts etc. to review the options available when looking to fit the new bathroom

Design
  • Software
    • A company leaves the chosen implementor to design how the software will be implemented or will internally generate design documents for the the implementor to follow
  • Bathroom
    • A homeowner will make use of the chosen implementor to help design the layout and required components for the design of the bathroom e.g. size estimates of bathroom components, area for tiles/carpet/paper etc.

Implementation
  • Software
    • The implementor will go ahead with the software design and implement the software system
  • Bathroom
    • The implementor will go ahead with the bathroom design and install the components to build the bathroom

Testing
  • Software
    • Internal tests such as unit tests will be carried out by the implementor to ensure the software is in a bug-free state once delivered
  • Bathroom
    • Implementor will carry out tests to ensure the components are fitted and functioning as expected

Deployment
  • Software
    • Once found bugs are resolved and tests are complete, the implementor will deploy the software solution into the companies systems
    • Further testing may take place by the business users e.g. User and Business acceptance tests etc.
  • Bathroom
    • Once the implementor is happy with the fitted bathroom, they will perform tasks such as switching water pipes back on, apply finishing touches etc. and declare the bathroom use-able
    • Further testing will most likely take place by the user to validate installation e.g. Check if sink taps are straight...

Conclusion
So there we have it. Implementing a software solution is exactly like fitting a new bathroom! (With a few changes here and there.. ;) )

I would like to place emphasis on the fact that I have not gone insane! The moral of this post is for readers to take a step back and understand how a software building cycle is actually driven by a powerful framework that is used by many to perform activities within our life where a desired outcome is expected from investment.

This framework is often used subconsciously by many, but the reason it is so important within the I.T industry is because budgets, resources and time are of huge importance. Software life cycles helps keep planned/performed activities documented in a structured manner so that projects are kept on track and everyone, especially management, is kept up-to-date on current activities.

So the next time you expect an outcome from some form of your investment, take a step back and assess the activity cycle that will be exercised for you to obtain your desired, hopefully successful, outcome! :)

Get States of all instances from COMPOSITE_INSTANCE and CUBE_INSTANCE Tables in SOA-INFRA Schema

The following 2 SQL queries have been put together to obtain a useful count of all the instance states from Composite instance and Cube instance tables within the SOA-INFRA schema, which is acting as the SOA Dehydration Database for a given WebLogic SOA server.

Note - The queries below are for a given Composite name. Ensure you replace the 'COMPOSITE_NAME' within the WHERE clause with the composite you would like to target. You can also add further WHERE clauses to return results for multiple Composites.

-- QUERY 1 GET ALL INSTANCE STATES FROM CUBE_INSTANCE TABLE
SELECT (CASE
WHEN STATE=0 THEN 'State 0 - STATE INITIATED'
WHEN STATE=1 THEN 'State 1 - OPEN AND RUNNING'
WHEN STATE=2 THEN 'State 2 - OPEN AND SUSPENDED'
WHEN STATE=3 THEN 'State 3 - OPEN AND FAULTED'
WHEN STATE=4 THEN 'State 4 - CLOSED AND PENDING'
WHEN STATE=5 THEN 'State 5 - CLOSED AND COMPLETED'
WHEN STATE=6 THEN 'State 6 - CLOSED AND FAUTED'
WHEN STATE=7 THEN 'State 7 - CLOSED AND CANCELLED'
WHEN STATE=8 THEN 'State 8 - CLOSED AND ABORTED'
WHEN STATE=9 THEN 'State 9 - CLOSED AND STALE'
WHEN STATE=10 THEN 'State 10 - NON-RECOVERABLE'
ELSE STATE || ''
END) AS CUBE_INSTANCE_STATE, COUNT(*) AS NUM_OF_CUBE_INST
FROM CUBE_INSTANCE  CI
WHERE CI.composite_name = 'COMPOSITE_NAME' --REPLACE WITH YOUR COMPOSITE NAME
GROUP BY STATE;


Query 1 sample result - Ran from Oracle SQL Developer

-- QUERY 2 GET ALL INSTANCE STATES FROM COMPOSITE_INSTANCE TABLE
SELECT (CASE
WHEN STATE=0 THEN 'State 0 - RUNNING'
WHEN STATE=1 THEN 'State 1 - COMPLETED'
WHEN STATE=2 THEN 'State 2 - RUNNING WITH FAULTS'
WHEN STATE=3 THEN 'State 3 - COMPLETED WITH FAULTS'
WHEN STATE=4 THEN 'State 4 - RUNNING WITH RECOVERY REQUIRED'
WHEN STATE=5 THEN 'State 5 - COMPLETED WITH RECOVERY REQUIRED'
WHEN STATE=6 THEN 'State 6 - RUNNING WITH FAULTS AND RECOVERY REQUIRED'
WHEN STATE=7 THEN 'State 7 - COMPLETED WITH FAULTS AND RECOVERY REQUIRED'
WHEN STATE=8 THEN 'State 8 - RUNNING WITH SUSPENDED'
WHEN STATE=9 THEN 'State 9 - COMPLETED AND SUSPENDED'
WHEN STATE=10 THEN 'State 10 - RUNNING WITH FAULTS AND SUSPENDED'
WHEN STATE=11 THEN 'State 11 - COMPLETED WITH FAULTS AND SUSPENDED'
WHEN STATE=12 THEN 'State 12 - RUNNING WITH RECOVERY REQUIRED AND SUSPENDED'
WHEN STATE=13 THEN 'State 13 - COMPLETED WITH RECOVERY REQUIRED AND SUSPENDED'
WHEN STATE=14 THEN 'State 14 - RUNNING WITH FAULTS, RECOVERY REQUIRED, AND SUSPENDED'
WHEN STATE=15 THEN 'State 15 - COMPLETED WITH FAULTS, RECOVERY REQUIRED, AND SUSPENDED'
WHEN STATE=16 THEN 'State 16 - RUNNING WITH TERMINATED'
WHEN STATE=17 THEN 'State 17 - COMPLETED WITH TERMINATED'
WHEN STATE=18 THEN 'State 18 - RUNNING WITH FAULTS AND TERMINATED'
WHEN STATE=19 THEN 'State 19 - COMPLETED WITH FAULTS AND TERMINATED'
WHEN STATE=20 THEN 'State 20 - RUNNING WITH RECOVERY AND TERMINATED'
WHEN STATE=21 THEN 'State 21 - COMPLETED WITH RECOVERY REQUIRED AND TERMINATED'
WHEN STATE=22 THEN 'State 22 - RUNNING WITH FAULTS, RECOVERY REQUIRED, AND TERMINATED'
WHEN STATE=23 THEN 'State 23 - COMPLETED WITH FAULTS, RECOVERY REQUIRED AND TERMINATED'
WHEN STATE=24 THEN 'State 24 - RUNNING WITH SUSPENDED AND TERMINATED'
WHEN STATE=25 THEN 'State 25 - COMPLETED WITH SUSPENDED AND TERMINATED'
WHEN STATE=26 THEN 'State 26 - RUNNING WITH FAULTED, SUSPENDED, AND TERMINATED'
WHEN STATE=27 THEN 'State 27 - COMPLETED WITH FAULTS, SUSPENDED, AND TERMINATED'
WHEN STATE=28 THEN 'State 28 - RUNNING WITH RECOVERY REQUIRED, SUSPENDED, AND TERMINATED'
WHEN STATE=29 THEN 'State 29 - COMPLETED WITH RECOVERY REQUIRED, SUSPENDED, AND TERMINATED'
WHEN STATE=30 THEN 'State 30 - RUNNING WITH FAULTED, RECOVERY REQUIRED, SUSPENDED, AND TERMINATED'
WHEN STATE=31 THEN 'State 31 - COMPLETED WITH FAULTED, RECOVERY REQUIRED, SUSPENDED, AND TERMINATED'
WHEN STATE=32 THEN 'State 32 - UNKNOWN'
ELSE STATE || ''
END) AS COMPOSITE_INSTANCE_STATE, COUNT(*) AS NUM_OF_COMP_INST
FROM COMPOSITE_INSTANCE  CI
WHERE CI.SOURCE_NAME = 'COMPOSITE_NAME' --REPLACE WITH YOUR COMPOSITE NAME
GROUP BY STATE;


Query 2 sample result - Ran from Oracle SQL Developer

Here is a useful link that re-iterates the State values and their descriptions for some of the tables within SOA-INFRA: Click here


Web application URLs for Oracle Fusion Middleware stack components

Here is a useful list of the Oracle Fusion Middleware stack Web Applications that are used to manage each stack component:

WebLogic server
- http://hostname:port/console

Enterprise Manager
- http://hostname:port/em

SOA
- http://hostname:port/soa/composer
- http://hostname:port/soa-infra

BPM
- http://hostname:port/integration/worklistapp
- http://hostname:port/bpm/workspace
- http://hostname:port/bpm/composer

WebCenter Portal
- http://hostname:port/webcenter
- Default port - 8888

WebCenter Content
- http://hostname:port/cs
- Default port - 16200

OSB
- http://hostname:port/sbconsole

BAM
- http://hostname:port/OracleBAM *

Database
- http://hostname:port/apex (default port 8080)

* Case sensitive

Ensure you replace the hostname and port number with the correct server details. E.g. For a local WebLogic server with the default port number, URL would be http://localhost:7001/xxx

I may have missed some URLs out, so let me know if I have!


Modify Hosts file for full access to SOA/BPM Domain on Oracle Virtual Machine Image

Use case:

I installed an Oracle Virtual Machine image on Oracle Virtual Box which consisted of the 11g Fusion Middle ware stack (Oracle DB, WebLogic Server, SOA + BPM Suite, OSB, BAM and WebCenter. Link to image)

I ran all the servers and was able to access the running server Middleware application such as WebLogic Console, Enterprise Manager, BPM Workspace etc through my browser on my local machine.

Issue
However, there was an instance where when I deployed a BPM application and launched a Human Task page, I got the following error:


Why does this happen?
This happens because within the BPM Workspace application, you are opening a Human Task page and it tries to directly reference the address through the domain name, rather than through localhost. The servers in the VM are exposed for access via 'localhost', when opening the human task, instead of accessing the page with 'localhost', it tries to reference it with the direct domain name which in this instance is 'soabpm-vm'. This would only accessible if you was accessing it in a browser inside the server.

Solution
So to resolve this issue, we need to add the domain name it references to your system's hosts file. We insert the name of the domain, and map it to localhost. So when the domain name is requested, it automatically routes and resolves it to 'localhost'.

The location of your hosts file will vary depending on your Operating System. Use this link to find out where your hosts file is located and then open it to edit.

My Operating System is Windows 7 and have opened the hosts file for modification:


1. Add another entry to map the name of your domain name to 127.0.0.1, as shown below:




2. Save the hosts file and close the window.

3. Now, try opening your Human task page again and it should have resolved to the correct address: