Tuesday, February 24, 2015

Oracle BPM 12c Advanced Error Handling and Recovery - Part 1

I'm so happy to announce that my first part of a two series article on "Oracle BPM 12c Advanced Error Handling and Recovery - Part 1" has been published under OTN.

This first part covers the differences in fault handling options between Oracle BPM 11g and 12c and explores the new error handling and recovery features introduced in Oracle BPM 12c from both a developer's angle (covered in part 1) and an administrator's perspective (covered in part 2).

Friday, February 20, 2015

Using ADF BC Declarative Built-in Rules (Part 9 of 10): Script Expression validator


The last set of validators consist of the "Script Expression" validator and the "Method" validator which can be defined either at the entity level or the attribute level to validate either the entire entity object or a specific entity attribute.

The "Script Expression" validator enables you to validate either the entire entity object or a specific entity attribute using a Groovy expression that returns either true, meaning that the validation is successful or false to define that the validation has failed.

The "Script Expression" validator has some very interesting characteristics which we will see in practice using an example by Frank Nimphius (https://blogs.oracle.com/jdevotnharvest/entry/using_groovy_in_entity_validation).

I will be using the HR schema and the employees table to define an attribute level validation using a "Script Expression" to define a departmental salary budget and to ensure that the cumulative salary of employees per department does not exceed their respective departmental salary budget.

I have created an ADF Fusion Web Application and created the basic business components that I will be using in this demo; two entity objects based on the Employees and Departments HR tables, default view objects based on the two entity objects and a default application module.
Next let’s define the validation on the "Salary" attribute of the Employees entity object to ensure that the cumulative salary of employees per department does not exceed their respective departmental salary budget. So on the  “Business Rules” tab of the Employees entity object, right-click on the "Salary" attribute and select "New Validator". This will open the “Add Validation Rule” editor for defining the validation specifics.

In the “Type” combo select “Script Expression” and in the "Expression" I will type in my Groovy expression to implement my business rule. The logic for implementing my departmental salary budget rule is as follows:

DepartmentSalaryBudget – (AllSalariesInDepartment + newEmployeeSalary) + currentEmployeeSalary < 0

To retrieve the current employee salary and the new employee salary we can use the oldValue and newValue Groovy script keywords respectively.

Another nice feature with the "Script Expression" validator is that you can use the ternary operator to implement functionality that is similar to SQL’s NVL() function. We will use this functionality to populate a department's salary budget, for example, "departmentSalaryBudget = (DepartmentId == 10 ? 50000 : 100000)". A better approach would be to create a new database column in the "Departments" table to hold the salary budget for each department.
The last part of the puzzle is to calculate all the salaries in a specific department. To do so we will have to use the default accessors that have been created by the default "EmpDeptFkAssoc" association.

So to calculate the total salary of all employees in a department we have to use the "Departments1" accessor to navigate to from a specific employee to his department and from the department use the "Employees1" accessor to retrieve all department employees and use the "sum" aggregate function on the "Salary" attribute, for example, "Departments1.Employees1.sum('Salary')".

One last point on the "Script Expression" validator is that your expression can either return true or false or use the "adf.error.raise" or "adf.error.warn" functions to display a message that is defined in your message bundle.

Putting it all together, the department salary budget business rule validation should look like the following:

I've decided not to use the build-in Groovy functions for displaying the error message but to use the "tradition" failure handling tab functionality. Therefore, in the "Failure Handling" tab define a failure message and click "OK". In my example I have used a message token expression to construct a dynamic error message, passing to the failure message the salary increase by using again the oldValue and newValue keywords to compute the salary increase.

If you inspect the Employee’s entity source code you will see that JDeveloper added an ExpressionValidatorBean tag to the entity's XML definition file.

Run the Application module to test the "Script Expression" validator and open the "EmployeesView1" view object. By default the first record displayed is "Steven King" that belongs to the "Executive" department (department id 90). Based on our business rule definition, the Executive department has a salary budget of $100,000.

The current Executive department salary total is $58,000 (do a "select sum(salary) from employees where department_id = 90"). If you increase Steven King's salary from $24,000 to $66,000 you should notice that there isn't any error raised (the department's total salary is exactly $100,000).

Do a rollback so that Steven King's salary get's back to $24,000 and try to update his salary to $66,001 (which should total the department's salary to $100,001). The validation should fail and you should see your custom error message.

Download sample application: Script Expression
 

Monday, February 2, 2015

SOA Magazine edition IV

The SOA Magazine 4th edition is out!

It's a great read for both customers and partners consisting of a rich breadth of articles on SOA and BPM, one of which I had the privilege to author, "BPM 12c Gateways".

Make sure you subscribe to the magazine to enjoy all this wealth of information!

Friday, January 30, 2015

Oracle BPM 12c Events (Part 1 of 3): Start Events

Start events, as the name implies, dictate how a process will start. Processes can have more than one start event (or end event as we will see in part 2 or both).

As you can see from the "Order Process" below, Oracle BPM provides us with a variety of start events such as the "None Start" event, the "Message Start" event, the "Timer Start" event and the "Signal Start" event.

Order Process

The "None Start" event is the default start event in a manual process and it is used in conjunction with a user task defined with the initiator pattern to manually start a process.

The "Message Start" event, which is the default start event in a default process, asynchronous process and synchronous process triggers a process based on message sent by either a BPMN or BPEL process or a service.

The "Timer Start" event will instantiate a process based on a specific time condition, for example, trigger a process on a specific date at a specific time or trigger a process at e recurring interval.

The "Signal Start" event, just like the "Message Start" event, will trigger a process based on a message. The difference is that the "Message Start" event will respond to a specific message sent to a specific process (it's a one-to-one relation) while the "Signal Start" response will respond to a signal that has been broadcasted to multiple process. So with a "Signal Start" event you can trigger multiple processes at the same time using the same message.

Let's see all this in practice.

Create the basic BPM application and BPM project (named both application and project "StartEventsDemo") and select "Composite with BPMN Process" in step 3.

In the "BPMN 2.0 Process Wizard" specify a process name, for example OrderProcess and select "Manual Service" as the service type and click "Finish" (for the purpose of this demo you don't need to create any input or output arguments).

Let's first create the "Message Start" event. Drop the "Message Start" event onto the default "Role" swimlane just below the "None Start" event. This will pop up the  "Properties" window of the "Message Start" event component. Optionally update the default name given (I updated it to "Initiate Order Process using Message Start Event") and in the "Implementation" tab select "Define Interface" in the "Type" and click "OK".

The "Message Start" event is created onto your process canvas, however, it's showing an error. This is because it doesn't have an outgoing default sequence flow. Create an outgoing default sequence flow connecting the "Message Start" event to the "None End" event.

You should also notice a warning on the user task. This is because it doesn't have an implementation defined. Before we go on with the next event, let's implement the user task. Go to the user task properties and from the implementation tab click on the "Add" button to create a new human task.

In the "Create Human Task" window just leave the defaults and click "OK" (just for demo purposes. In reality you will have to define a proper definition).

Next let's define a "Timer Start" event to trigger our Order process based on a specific time condition. Drop a "Timer Start" event just below the "Message Start" event. This will dispaly the  "Properties" window of the "Timer Start" event component. Optionally update the default name given (I updated it to "Initiate Order Process using Timer Start Event") and in the "Implementation" tab select the appropriate timer definition.

There are three timer definition types. You can use the "Time Cycle" type to configure the "Timer Start" event to use an interval (fire multiple times). You can use "Time Date" to configure the "Timer Start" event to fire on a specific date and time or you can use "Time Schedule" to configure the "Timer Start" event to run periodically (daily, weekly or monthly).

For the purpose of this demo I have selected the "Time Cycle" timer definition type and picked an appropriate date and time to trigger my Order process.

The "Timer Start" event is missing an outgoing default sequence flow, so create one connecting the "Timer Start" event to the "None End" event.
We are left with the last start event, the "Signal Start" event which can be used to trigger a process based on a message broadcasted to multiple processes. Before we go on with creating the "Signal Start" event, we need to mock a service that will broadcast such events.
The easiest way to do that is via a mediator component. So drop a mediator onto the composite canvas and in the "Create Mediator" window give your mediator a name and select the "Synchronous Interface" template.
Edit the mediator component and create a new routing rule and in the "Target Type" select "Publish Event".
In the "Published Events" window click on the green plus icon to create a new event and in the "Event Chooser" window click on the green plus icon to create a new event definition file. This will bring up the "Create Event Definition" window where you can specify your event definition file and attach one or more events to your event definition file. For demo purposes I just created an event called "OrderEvent" with it's type set to a simple string.
If you inspect your project files you should notice that a new "edl" file has been created under the events folder.
 Now we are ready to create the "Signal Start" event. So drop a "Signal Start" event just below the "Timer Start" event. In the "Properties" window give your "Signal Start" event a meaningful name and in the "Implementation" tab select the browse icon to select the order event that will be broadcasted by the mediator component.
Wire the "Signal Start" event to the "None End" event and deploy your process. We are now ready to test our Order process. SO our Order process has various ways to get triggered. Let's start first with the "None Start" event and the manual initiation. 

Go to the BPM worspace and from the applications click on the OrderProcess link to initiate the process (if you can't see your process under the "Applications" it means that you didn't map your current logged in user to the process default role). Don't worry if you get a warning that the process initiation task has no payload. If you go to the flow instances and inspect your instance you should notice that it used the "None Start" event to trigger the process.
Now let's try to initiate a process via the Enterprise Manager (make sure you use the "OrderProcess.service" service). If you have a look at your process instance you should see that this time it used to the "Message Start" event to initiate the process.
Inspecting my flow instances I noticed that there was an process instance that I didn't explicitly trigger. If you inspect the instance details you should notice that this instance was triggered by the "Timer Start" event.
To test the "Signal Start" event we will have to broadcast a signal. To do that you need to invoke the "
BroadcastEvent_ep" order process service from EM. This will publish an order event on EDN. Since our order process has been configured with a "Signal Start" event that subscribes to order events it will get triggered.
Download sample application: Start Events


Monday, January 26, 2015

Oracle Fusion Middleware Partner Community Forum 2015

Hi everyone,

This year Oracle is organizing its Oracle Fusion Middleware Partner Community Forum in Budapest. The event is going to be held on March 3rd and 4th 2015 with hands-on training on March 5th & 6th 2015.

The event is a great opportunity to learn about:
  • SOA Suite 12c & Integration Cloud Service
  • BPM Suite 12c & Process Cloud Service
  • Mobile & Development tools & Mobile Cloud Service
  • WebLogic 12c & Java Cloud & Developer Cloud Service
Oracle will be running the following hands-on bootcamps:
  • Java Cloud Service hands-on
  • Mobile Application Framework hands-on
  • Multichannel enablement of Oracle Applications
  • SOA 12c ICS, adapter & sdk, API management, Stream explorer & BAM
You can register here!

See you all in Budapest!

Monday, January 12, 2015

Using ADF BC Declarative Built-in Rules (Part 8 of 10): Regular Expression validator

The last validator in the entity attribute validator set is the "Regular Expression" validator. The "Regular Expression" validator allows you to validate whether an entity attribute either matches or does not matches a regular expression.

You can either use one of the predefined expressions such as the "Email" regular expression or the "Phone" regular expression to validate whether a specific attribute conforms to a specific pattern.

For example, ensure that an email consists of a specific number of predefined characters followed by the "at sign" (@) followed by a specific number of predefined characters followed by the "dot character" (.) followed by a specific number of predefined characters.

So let's see how we can use one of the predefined regular expressions, how you can create your own regular expression and how you can register your custom expressions for re-usability.

For the purpose of demoing the "Regular Expression" validator I have created an ADF Fusion Web Application and created the basic business components that I will be using in this demo; an entity object based on the Employees HR table, a default view object based on the Employees entity object and a default application module.

Next let’s define a "Regular Expression" validator on the Employees entity object to ensure that an employee's email conforms to a specific pattern (<character(s)>@<character(s)>.<characters(s)>). So on the  “Business Rules” tab of the Employees entity object, click on the green plus icon “Create new validator”.  This will open the “Add Validation Rule” editor for defining the validation specifics.

In the “Type” combo select “Regular Expression”, select the attribute that you want to define the validator, in my demo it's the "Email" attribute and then select an operator, either "Matches" or "Not Matches". In my demo I have selected the "Matches" operator.

Under the regular expression section you can either select one of the predefined expressions (currently two, "Email" and "Phone Number(US)") or type your own regular expression. I've selected the "Email" regular expression and clicked on the "Use Pattern" button to generate the pattern.

In the "Failure Handling" tab define a failure message and click "OK". In my example I have used a message token expression to construct a dynamic error message, passing to the failure message the  email value.
If you inspect the Employee’s entity source code you will see that JDeveloper added a RegExpValidationBean tag to the XML entity definition file.

Run the Application module to test your "Regular Expression" validator and try to update an employee's email, for example update Steven King's email from "SKING" to "SKING1". The "Regular Expression" validator should have fired displaying your error message.

Change the email to "SKING@demo.com". The validation should succeed.

You can of course create your own custom regular expressions. As with the example below, I have defined a regular expression to ensure that an employee's first name consists of only alpha characters and that the first name always starts with an upper case.

What if you wanted to re-use this custom regular expression in other attributes or in other ADF applications? It would be a really bad practice to just copy and paste the same expression in different attributes. What if you wanted to apply a change to your custom expression. It would require you to go through all occurrences and apply the change one by one.

A much better approach would be to register your custom regular expression into the PredefinedRegExp.properties file and your custom regular expression will appear into the list of "Predefined Expressions". This file is located in the o.BC4J subdirectory of the JDeveloper system directory (in my case it's system12.1.3.0.41.140521.1008), which is a subdirectory of JDeveloper’s user directory (the file in my case is located in "/home/oracle/apps/.jdeveloper/system12.1.3.0.41.140521.1008/o.BC4J").

Edit the file and add your own custom regular expression.

Restart JDeveloper and go to the Employees entity and create a new regular expression validation on the first name attribute. In the predefined expressions list you should see your own custom regular expression. Select it and click on the use expression button to populate your expression into the "Enter Regular Expression" text area.
Define a failure message and test your custom expression. If you followed my exact steps, try to update an employee's first name to start with a lower case alpha character. The validation should fail.

Download sample application: Regular Expression

Saturday, December 27, 2014

Oracle BPM 12c Gateways (Part 5 of 5): Event-based Gateway

My last article on gateways is on the event-based gateway, another type of gateway supported by Oracle BPM 12c to provide divergence in processes.

The event-based gateway is very similar, conceptual wise, to the exclusive gateway in the sense that we can have various outgoing sequence flows but only one branch is followed. The operational difference though is that, as its name suggests, the event-based gateway uses events for defining the branching conditions and decisions rather than data-specific conditions.

An event-based gateway can consist of multiple events; however the first event that occurs will determine the execution path that will be followed.

Using the order process as an example, once an order is received and validated it needs to be processed. Assuming that we have multiple warehouses, the order will be processed by the warehouse that can process all inventory items ordered and responds first. The process will wait until one of the warehouses responds to the request for processing the order. However, the process cannot wait indefinitely.

So let's see how we can implement the above scenario using the event-based gateway.

Let's start with creating the basic BPM application and BPM project (named both application and project "EventBasedGatewayDemo") and selecting "Composite with BPMN Process" in step 3.

This will bring up the "BPMN 2.0 Process Wizard" where you are prompted to specify a process name and the service type. Give your process a name, for example OrderProcess and select "Asynchronous Service" as the service type.

In step 3 of the BPMN 2.0 Process Wizard you are prompted to specify the input and output process arguments. A typical order definition would consist of an order id, a collection of order items, the order total, customer details and bill and ship address details. For simplicity reasons my demo process will only consist of the order id (of type int) and the order total (of type decimal) as input arguments and a status argument of type string as output.

The event-based gateway is composed of the event-based split gateway and two or more target events. These events can be either message catch events, timer catch events or receive tasks. Please note that you cannot mix message catch events and receive tasks within the same event-based gateway. 

Select and drop the "Event Based" gateway on the default sequence flow between the "Start" and "End" activities. You should notice that JDeveloper automatically has added three activities; an event based split gateway activity, a catch message activity and a timer catch activity.

There is an error on the Timer activity because it doesn't have an outgoing default sequence flow. Give the event based gateway split activity and the catch message activity some meaningful names and add a new catch message activity just below the default created catch message activity and define default sequence flows for all activities.

Next set the timer activity to wait for 30 seconds for a reply from the warehouses and define an implementation on the two catch message activities. Again for simplicity and demo reasons I have used the "Define Interface" message exchange type and created only a single argument, order id of type int. The implementation of both catch message activities are exactly the same, the only difference is the operation name.

So we have a process that expects some events to arrive from the two warehouses while its being executed. This means that the main process, which in our case its the order process needs to find a way to correlate these intermediate events with the itself. To do that we need to create a correlation property (an attribute to correlate the main process with the intermediate events) and a correlation key (which defines the properties to use in the correlation which consists of one or more correlation properties).

I will use the order id to correlate the events that will be flowing from the warehouses into the main order process, therefore I have created a correlation property named "orderId" and of type int and a correlation key named "ck_orderId" with the orderId correlation property selected.

We now need to instruct the process and intermediary events to use the orderId correlation property we created. The main process will be responsible for initiating the correlation and matching events that will be coming in from the warehouses with the main process. Therefore on the message start activity select under "Implementation" select "Correlations" and select the orderId correlation property and map it to the orderId process input argument. Ensure that you have selected the "Initiates" option to instruct the process to correlate an instance of the order process with the supplied order id.

The same correlation definitions need to be applied on the two catch message activities. Please ensure that the "Initiates" option is not selected since this will be done upon the instantiation of the process.

Deploy your process and run a test instance using the "start" operation. If you inspect the audit trail you should see that the instance is waiting at the event-based split gateway activity.

Run a new test instance of your order process but this time use one of the warehouse operations (for example, use the "warehouseB" operation). If you inspect the audit trail you should notice that the order is now completed and that the process followed the second branch.

Download sample application: Event-based Gateway