Services

The activities contained in the BPD describe the overall flow of the process and the diagram as a whole provides a readable description of the process. Although the BPD provides a great deal of information, it doesn't capture how the process is implemented. Consider the simple process of making a cup of tea in the morning. A simple process for this might look as follows:

Reading this, we can quickly see the steps and their sequence. However, this diagram says nothing about how these steps are implemented. Since IBPM is not simply a diagramming tool but is also a powerful execution engine for running instances of such processes, we must also describe how each of the activities are implemented.

IBPM utilizes the concept of a service to perform each step. A service provides a reusable implementation of a piece of function. How the server achieves its task is hidden from the caller. Mapping this idea to BPDs, each Activity in the BPD diagram will be mapped to a service and when that step in the process is reached, the associated service will be invoked.

A service is a piece of implemented function of one of the following IBPM types:


The Service is usually called from the Activity step in a BPD. The identity of the Service to be invoked is defined in the Implementation tab:

Note that the Implementation type is defined as a System Task. From there, the selection of the Service to be called can be selected.

The Task Header area controls what is shown in the Process Portal for this step and what data is maintained after the activity completes.

The Subject entry contains a textual description of this step in the process. This is shown in the Process Portal. It is used to provide the end user an indication or summary of what is expected. The Subject line can contain JavaScript and hence access the variables in the process to supply more details of what is needed.

For example, if a step in the process has the following Subject line:

When it is shown in the Process Portal, it could look as follows:

If the Clean Slate check box is selected then at the conclusion of the activity, state data about the activity is discarded.

Each of the service types has a diagram in which the artifacts which implement that service can be placed and visually wired together. The service editors have a feature within them to "tidy" their appearance by lining up activities to smooth out the sequence connection lines. This option can be found when right-clicking on the diagram canvas with nothing else selected. From the resulting context menu, the Tidy Layout option may be selected.

After having selected that entry, the diagram will be reworked to tidy it. An example after a tidy looks as follows:

Caching the results of a service

When a service is executed, it is passed in a set of parameters and returns a set of results. If the service is executed over and over again with the same input parameters, it is likely that the result will be the same even though the work of executing the logic of the service will still be performed. As an optimization and as a way to improve performance, we have the ability to flag that a service is eligible to cache its results. This means that for a given service with a given set of inputs, the service will be executed but the results stored. If a subsequent request for the same service with the same set of inputs should arrive, the previously calculated results will be returned without having to execute the logic of the service itself.

This feature can be turned on or off on a per service basis. In the Overview tab of the service definition, we find an entry called "Service Result Cache":

By default, the caching of the service is disabled. If we enable it by clicking on the check box, the results of that service will be cached. We also have the ability to specify how long cached results should be maintained before we consider them "stale". We can supply an interval value after which a previously returned entry will be considered out of date and the real service will again be executed.

The implementation of the caching mechanism in IBM BPM has a default cache size of 4096 entries. This can be changed through the <service-result-cache-size> property in the configuration files.

|| |Notes:

    1. |

Human Service

The Human Service is arguably the most important service type in IBPM. A Human Service is a component that, when executed, creates a task for a human being to work upon. The BPD process is suspended until the conclusion of that task. The Human Service type provides the inclusion of Coach components which are the descriptions of screen data to be presented to users and data to be retrieved from users.

With the arrival of IBM BPM 8.5.5, the Human Service implementation was massively revamped. This saw the introduction of a new type of Human Service which IBM calls "Client-Side Human Services". To maintain backwards compatibility for solutions built prior to 8.5.5, the previous Human Services implementation was left intact and has been renamed to be "Heritage Human Services".

A new Human Service is created from the User Interface category.

It is extremely common to associate the Human Service definition with a User Task on a BPD.

See also:

Exposing the Human Service for starting

In the Overview panel of the Human Service definition, the Exposing section allows us to select how the service should be exposed for starting in a manner other than being explicitly called by a BPD.

The choices available to us are:

With this option, the Human Service is not exposed any further. It can only be invoked by a direct Human Service call from a BPD activity. This is the default setting.

This option allows a new instance of the Human Service to be started from the Process Portal.

This option exposes the Human Service as an entry in the Dashboards menu found on the IBM Process Portal:

When the menu is pulled-down, the name of the exposed Human Service can be found here:

For Human Services selected to be exposed through the Dashboard, we have an addition option which allows us to export a JSR-286 compliant portlet.

See also:

With this option, the Human Service is exposed as a directly invokable URL. If the URL is entered into a browser, the user can go directly to the Human Service.

The format of the URL is:

http://[host]:[port]/teamworks/executeServiceByName?processApp=[

If the user has no login session established with that browser then a prompt for a login will occur. If the Human Service is exposed as an Administration Service, a Startable Service or a Project Page then it is also exposed through the URL in addition to the other selected mechanism.

For each of the exposing options, a Team must be selected to determine if the requesting user is authorized to access the service. This Team is set in the Exposed to start: area.

Canceling outstanding Human Tasks

Consider the notion that we have multiple Human Tasks being executed in parallel as illustrated in the following process diagram. These tasks may consist of approvals where in order to make progress, both tasks have to result in an approved outcome.

If a person reviewing the task work decides to reject the request then we don't want the other person to waste time reviewing. Even if they approve their part, the process as a whole says that the work will be rejected. What we want to achieve is a pattern where we can cancel a task before it is completed if it is no longer warranted that the task be performed.

The way this can be achieved is to add Message Intermediate Events to the tasks that are eligible for being canceled. Here is a new diagram that illustrates this:

The definition of the Message Intermediate Events looks as follows:

Note the properties carefully as they are important. The first is that the attached activity (which is the Human Service) is flagged to be closed when the event arrives. This is what ends the associated task. Notice also that Consume Message is unchecked. We want the same event to be propagated to all the tasks that may be waiting for a cancel. Finally notice that we are using the current process instance identifier as the correlation value. We don't want to cancel tasks that belong to other processes.

The Human Service that is shown is defined as follows:

In this example, the user interface shows a check box that allows the user to define if a cancel is needed:

If cancel is checked, then the UCA is triggered which terminates the other task.

Informing a user that their task has been canceled

Imagine a scenario where a user can be given a task and they can look at that task and then signal it completed later. This is not uncommon. For example, imagine a task arrives that says "Go build a green widget". This might take a few days. Having looked at the task, I now go away and start building the widget. What then if the customer cancels the order. Presumably I don't want to continue building the widget so now I have to be notified that I should be interrupted.

When a task is assigned to a user, either the user has looked at the task or they haven't. In our story, we want to send an email to a user if they have looked at the task and it is then canceled. If they haven't yet looked at it, there is nothing for them to stop doing when it is canceled and hence no email needs to be sent.

Let us start by looking at a high level story:

In this story, we can Build a Widget and also the Manager can cancel the request. If the manager selects to Cancel, the exception end event is reached and the sub-process is terminated. That handles the termination, but what about informing the user? The logic of Build Widget handles some of this for us.

When a user claims a task, a step in the solution called "Set Identity" remembers the identity of the user who worked on the task. When the user reads the task, we assume that they hit a button called "Complete Later". This is our indication that they have seen the task. We then set a flag that they have viewed the task.

This however seems to leverage data that appears to be private to the service. Where is the identity saved? Where are the flags saved? The answer to this puzzle is the use of the IBM BPM Shared Business Object concept. Using this technology we can pass in a reference to the shared business object into the service. This business object can then be examined in a calling process.

For example, if we catch an exception, we can use what was previously set in the global shared object as indicators of "where we have been" and "what we should do".

Timing out a Human Service

When a process reaches a step which is a Human Service, we are saying that we want a staff member to perform some work. But what if that staff member takes too long or is otherwise away? The process will simply pause or hang at this point. Instead of hanging, we may wish the process to time-out the Human Service and perform an alternative task such as dispatch the work to someone's manager or an alternative person.

We can achieve this through the use of a Timer Event attached to the activity of the Human Service.

See Timer Events for a discussion on the mechanics of Timer Event additions.

If a Human Task has been claimed by a user but has not yet been run, if the activity is timed-out and the user then tried to run it, the following will be shown:

If a Human Task been claimed and run but not completed but a Timer Event has fired and closed the attached activity, the user will not be notified that their input was discarded.

Escalating a Human Task

When a task is submitted to a person for completion, we have the opportunity for that task not to be completed within a prescribed amount of time. Work submitted for human processing can be "lost in the shuffle". People fall sick, take vacation, get distracted, get preempted by other work and a myriad of other possible reasons why work is not completed on time. The ramifications of not completing work vary. In some cases, it is unimportant, in others it can mean a poor perceived quality of service and in the worst case can result in loss of business or penalties for non-compliance with some set contract or expectation. To address this potentiality, we now turn our attention to the concept of escalation. Escalation is the detection that a task has not reached a processing state we expected by a given time and then taking some remedial action. Ideally, we want to notice that the work state is not where we want it to be before it is too late and we can still do something about it to complete the work before it becomes a problem.

Once we detect that work has not reached the state we are expect it to be, we need to perform some action to move the work onwards. From these notions, we find that escalation has two distinct ideas. The first is the detection that an escalation needs to happen because we have not reached the work state we want to reach. The second is we want to perform some escalation action to make further progress. We can separate out these two concepts.

The detection of when a task needs escalated can be achieved by attaching a timer event to an activity. The following BPD fragment illustrates a timer event attached to an activity that will cause a handler for the escalation to be executed.

The mechanical details of using a timer event can be found here: Timer Events and won't be repeated. For this discussion, we will simply assume that a timer will fire when a task is late or about to be late and the original task will not be stopped.

This pretty much takes care of detecting that a task needs to be escalated, so what action should we perform once escalation is required? There are many choices here. Some of the more common patterns include:


Any of these could utilize the creation of new tasks, sending emails or invoking arbitrary services which could in turn use other technologies such as text messaging, web service calls, paging etc.

For each of these choices, we now need a mechanism that will enable to to determine which task needs attention. When a task is created, it is created by an Activity in the BPD. There is thus an association between the Task that is created and the Activity which caused it to be created.

In the environment of a BPD there is a system variable called

tw.system.currentProcess.tasks

This is a list of TWTask objects. Each entry in the list corresponds to a task currently associated with the BPD. By walking this list and looking at the processActivityName attribute of the task, we can look for tasks that were started by the Activity we are looking for. An example code fragment that achieves this is:

var task = null; for (var i=0; i<tw.system.currentProcessInstance.tasks.length; i++) { if (tw.system.currentProcessInstance.tasks[i].processActivityName == activityName) { task = tw.system.currentProcessInstance.tasks[i]; break; } }

An alternative is to add a post-assignment to the Timer Event to obtain the tw.system.step.task.id information. This will be the id of TWTask associated with the activity that was timed out. We can't save the actual task itself, this produces a not-serialized exception if we try to assign to "ANY". However, once we know the task's id, we can use the tw.system.findTaskByID() method to retrieve the TWTask by its id.

We can change the priority of the task by setting the task.priority field which is writable. Allowable values include:


If a task needs to be escalated, we may need to know to whom the escalation should be sent. From the Task we can get the TWUser (or TWRole) from the assignedTo property.

Notifying a user that a task is ready for work

When a Human Task is created by a process, it is ready for someone to work upon it. Typically, the user will be informed that the work is available to them as a result of them looking in their in-box in the Process Portal or through REST API calls. There is also the ability to have IBPM automatically send an email to the user when a task is created. This is set in the Process Portal preferences section.

Within a current task, the current Task ID can be retrieved from the variable tw.system.task_id. This can be used by a service or code in the Human Service to send an email to the target user to tell them the task upon which they should work.

To use the built-in email notification system supplied with IBM BPM, we must perform some initialization. From the 99Local.xml, copy the relevant section to 100Custom.xml and restart. A suitable example would be:

<server merge="mergeChildren"> <email merge="mergeChildren"> <!-- SMTP server that mail should be sent to --> <smtp-server merge="replace">smtp.example.com</smtp-server> <valid-from-required merge="replace">true</valid-from-required> <default-from-address merge="replace">username@example.com</default-from-address> <send-external-email merge="replace">true</send-external-email> <send-email-notifications-to-list>false</send-email-notifications-to-list> <send-email-notifications-async>false</send-email-notifications-async> </email> </server>

The key parts to this are:

Once these changes have been made and put into effect by restarting the server, we need to login to process portal and ensure that the users who are to receive emails have an email attribute value and also that the option called "Send me an email when I have a new task assignment" is checked. If both of these are enabled, then when a task is created and associated with a user then an email will be delivered. The user does NOT need to the assigned owner but merely a potential owner for the email to arrive.

An example email might look as follows:

Unfortunately, there is no supported or documented way to modify the structure or content of the email template.

See also:

Semantics of closing a browser window

Consider the following Human Service:

Imagine that it is started as a task by a process. When a user claims the task, the step called "Step 1" is executed and then the Coach described by "My Coach" is shown to the end user. What happens if the user simply closes the browser? What becomes of the task?

By experimentation, it appears that the state of the service/task is maintained at the point where the Coach was reached. The task remains in existence in a claimed state. If the task is re-executed, the Coach is again displayed without re-running "Step 1". This implies that the state of the service is hardened and restarted when a browser window showing a Coach is closed and then re-opened.

Human Service (Client Side)

As mentioned previously, with the arrival of IBM BPM 8.5.5, Human Services radically changed. The plain concept of a Human Service was split into two distinct concepts. The original Human Service was renamed as a Heritage Human Service and a new concept called the "Client Side Human Service" was introduced. To understand the difference, we need to consider how IBM BPM prior to 8.5.5 dealt with Human Services and then we will be in a position to discuss the new notions. We will use the new 8.5.5 names to describe this story.

The execution of a heritage human service is a mixture of logic running within IBM BPM and logic running in the browser. If there are server scripts or other data manipulation steps being executed, these always occurred in the BPM run-time. When a Coach is reached, the HTML for that Coach is generated (along with its corresponding JavaScripts) and sent to the browser. At this point, the Heritage Human Service suspends its operation until such time as the user submits data from the Coach web page. The Heritage Human Service again gets control and carries on. If a second Coach within the Heritage Human Service is reached then the story repeats with a new page of data being sent back to the browser and the run-time code of the Heritage Human Service again suspends. What we see here is that there is a back-and-forth between the browser and the BPM run-time environment. This is depicted in the following diagram which shows the execution of a Heritage Human Service:

A Heritage Human Service that may have resulted in this set of flows might have been:

With this notion under our belts, let us now contrast this story with the architecture of the Client Side Human Service. With a Client Side Human Service, everything runs within the context of the browser without returning to the BPM server. This is shown in the following diagram:

This might be the flow of the following Human Service:

Hopefully you are now starting to understand the major difference between Client Side Human Services and Heritage Human Services. With Client Side, as much work as possible is performed within the browser. This has a number of advantages, almost all to do with performance or perceived performance.

When working with screens, we want them to be as responsive as possible. This means that when the user clicks on a button or enters data, feedback should be as quick as possible. With Client Side Human Services, everything that is needed to show data to the user and interact with him is already loaded within the browser. As such, there is no need to make a round-trip back to the server simply to load the next screen to be shown. The reduction in this latency improves the overall experience.

The BPM Server is a "scarce" resource. If we have significant numbers of users working with screens, the BPM Server could be a bottleneck if each interaction had to include it. This might be perceived as poor performance which could only be alleviated by increasing the numbers or capacity of the BPM Servers. Desktop and mobile browsers are highly optimized and commonly run on a user's environment where there is little contention for machine resources. Moving as much work as possible into the user's own computing devices just makes sense and has been a classic paradigm for decades (think "client-server" computing).

However, life is never as simple as the shown in the sample Human Services. It is not uncommon for a BPM design to include work items beyond data manipulation (scripting) and Coach presentations. Examples of this include requests for additional data from other systems such as Web Service providers or databases. Other examples include the initiation of events through the Under Cover Agent (UCA) technology.

In a Heritage Human Service, these components are simply inserted into the Human Service diagram and execute. They are able to execute because everything other than Coaches executes within the BPM server side run-time.

Within a Client Side Human Service, we can include "Service" components. These are then configured with the identity of a server side service that we wish to call. When these are reached within the Client Side Human Service flow, a call is made back to the server to execute the desired service:

See also:

Scripting in Client Side Human Services

Scripting in IBM BPM commonly allows one to use a variety of IBM supplied classes and functions. For example, when we wish to create a new Business Object instance, we would code:

var myVar = new tw.object.MyBusinessObject();

or if we wanted to create a list we might code:

var myList = new tw.object.listOf.MyBusinessObject();

Within client side Human Services and other client side scripting, the story has changed. In the client side environment, we code as though we were coding native JavaScript that runs in a browser. That shouldn't be too odd since that is in fact what we are doing. What that means is that we no longer create these specialized objects when we construct. Instead we use regular JavaScript types.

For example:

var myVar = {};

and

var myList = [];

When working with lists in the server side scripting environment, the lists have additional properties such as which (if any) items are currently selected. This is also true in the client side human service but the manipulation is different. In the client side, a list has a single property to indicate which items in the list are selected. This is a property called "listAllSelectedIndices" which is an array of index values into the list (array). The entries here are the ones considered to be selected.

For example, to see if any items are selected we could code:

if (myList.listAllSelectedIndices.length \> 0) {
 // Do something ...
 }

It is important to note that most properties available on server side list scripting are not available in the client side. Specifically, the following are not available:


Another difference of interest to us is that we can now do full source level debugging. Since the JavaScript we place within the scripting nodes runs in the browser, if we insert "debugger" statements in the JavaScript code, this will interrupt the execution of the browser.

On a negative side, the Process Designer web editor has chosen to use a proportional font as opposed to a fixed width font which is not great.

Saving state in a Client Side Human Service

Consider the following simple Human Service:

We should read this as first we show Coach 1 and then we show Coach 2. What would happen if the user claimed the task and started working upon it but when they were shown Coach 2 simply closed the browser. What would happen to the work/data entered in Coach 1? The default answer is that it would be lost. When a Human Service is closed before it has ended, its state may not have been saved and when we started the task again, we would be back at Coach 1.

However, we can alter that behavior. If we click on a link between activities, we will find that there is an option called "Save execution context for task implementation". This can be found in the Implementation tab for the wire link:

If enabled, then the state of the Human Service will be saved back to the BPM runtime. This will include the current values of variables as well as the next activity to be executed. Think of this as a "checkpoint". If the Human Service is terminated before it ends (such as when a user is looking at a Coach and closes the browser) then when the task is restarted, we will restart at the last checkpoint and progress from there.

This capability is, of course, only available for Human Services associated with tasks. Putting it another way, it is only available for Human Services associated with User Activities within a BPD or case.

End Event Navigation

Within a Human Service, there will (of course) come a time when the Human Service comes to an end. This is ideally because a navigation to an end event is reached.

When the end of the Human Service is encountered, that is the end of the interaction between the user and the process (for this stage). We can imagine a screen being presented to the user which contains fields that the user is expected to fill out, the user enters data and the Human Service ends … but what should now be shown to that user at the completion?

The End activity in a Human Service has options not found in other service definitions. Specifically, we have the following:

In the Implementation tab we have an option called "Navigation type" that can take one of a few predefined values. These values include:


Differences between Heritage and Client Side Human Services

IBM's direction is for the Client Side Human Services to eventually replace the use of Heritage Human Services. However, there is a problem. As of the 8.5.5 release, the Client Side Human Services does not yet support all of the features found in Heritage Human Services. Because of this, it is vital to understand what is missing or different. Here we present such a list of features not present in Client Side Human Services:

Ajax Service

Ajax (which is an acronym for Asynchronous JavaScript and XML) is a description for the practice of constructing web pages that have dynamic content with call-outs to external services to obtain additional data. This technique started when the web browsers provided a function called XMLHttpRequest which allowed the browser to make an HTTP request to obtain data while the page was already loaded but without the page as a whole having to be refreshed.

An Ajax service is used in conjunction with Human Services and coaches. It provides the ability to source data dynamically for the coach by running a IBPM service on the server with the data returned from the server used within the coach.

An Ajax service is defined from the User Interface category within the Library.

When created, it is given a name.

At this point, we must not lose sight of how this service is going to be called. It will be called when a component on the form is selected and changed. When the change occurs, the Ajax service will be called and data will be returned. The returned data will be used to populate the content of a different component. If we think in terms of inputs and outputs to this service, we find that it will have a single input which is the value of the component that triggered the invocation of this service. The new value of that component is passed in as an input variable to the Ajax service. The implementation in IBPM requires that the name of the input variable be fixed and be called inputVar. You must define an input variable of type String with this name.

The data that is returned is dependent on what kind of control the response data from the Ajax service is associated with. For here, let us assume it is a Single Selection list. A Single Selection list is defined by a list of NameValuePair data structures. The NameValuePair is a IBPM predefined data structure that contains two fields. One called name and the other called value. When a list of these structures is associated with a Single Selection list control, each element in the list data contributes one row to the visual list control. The name field is used as the visual in the row.

Let us examine this by example. Imagine our business is split into two regions. The East and the West. When we wish to ship product, we ship from the East region or the West region. In each region, we have the choice of possible shipping warehouses from which to ship. If we want to present a Coach to select a warehouse, we might want to be smart and allow the user to first select a region and once the region is selected, then select a warehouse. The allowable warehouse values should be displayed based on the region selected. This is illustrated in the following diagrams.

To achieve this, we might build a Coach that looks as follows:

With the body of the Coach looking like:

<Needs updated for IBPM>

The Shipping Location section contains two Single Select controls. The first which has the label "Region:" contains static choices:

The second control is the more interesting one. Looking at its definition we see that it invokes an Ajax defined service.

Notice three things:

Now let us look at the definition of the Ajax service. As a high level diagram, it contains only one Server Script activity:

The variables defined in the service look as follows:

Note that there is an input variable that must be called inputVar. The output variable has no restriction on its name but result is a suggested choice. The data type of the output variable is a List of NameValuePair data types.

Finally, there is the JavaScript logic contained in the Server Script:

tw.local.result = new tw.object.listOf.NameValuePair();
 if (tw.local.inputVar == "East")
 {
 tw.local.result[0] = new tw.object.NameValuePair();
 tw.local.result[0].name = "Boston";
 tw.local.result[0].value = "Boston";
 tw.local.result[1] = new tw.object.NameValuePair();
 tw.local.result[1].name = "New York";
 tw.local.result[1].value = "New York";
 tw.local.result[2] = new tw.object.NameValuePair();
 tw.local.result[2].name = "Miami";
 tw.local.result[2].value = "Miami";
 }
 if (tw.local.inputVar == "West")
 {
 tw.local.result[0] = new tw.object.NameValuePair();
 tw.local.result[0].name = "Seattle";
 tw.local.result[0].value = "Seattle";
 tw.local.result[1] = new tw.object.NameValuePair();
 tw.local.result[1].name = "San Francisco";
 tw.local.result[1].value = "San Francisco";
 tw.local.result[2] = new tw.object.NameValuePair();
 tw.local.result[2].name = "Phoenix";
 tw.local.result[2].value = "Phoenix";
 }

This script won't be explained in detail other than to say that depending on the value of the input data which is the value of the region selection control, one of two different lists of data are built and returned.

Not all components support Ajax service binding, the ones that do are:


In practice, the data that is returned from the Ajax service call may be dynamically sourced such as through a DB lookup.

See also:

Integration Service

The integration service allows a process to invoke an external entity such as a Web Service or a piece of Java Code. It is the integration service which provides the one of the components for interacting with logic outside of the BPMN environment including true SOA external service.

See also:

Advanced Integration Service

The Advanced Integration Service gives us the ability to define a service that is implemented by an IBM BPM Advanced SCA Module.

See also:

General System Service

A general system service is used when the BPD needs to work with the data in the process but does not need to invoke either a Web Service or Java Code. The General System Service is the simplest of the service implementation environments.

Decision Service

During the execution of a process, we may wish to have rules executed. Commonly, rules are decision points in a process where the values of variables in the process are used to determine what to do next. An illustrative example would be to determine the discount to apply for volume orders. We may have the following notion:

|| |Order Value|Discount| |$0-$999|0.00%| |$1000-$1999|5.00%| |>$2000|10.00%|

Looking at this table we see that the discount amount is a function of the order value and hence there is a decision to be made on the discount based on the value of the order. This is the type of function that is ideally suited to Decision Services.

A Decision Service is added to the Library by selecting decisions and adding a Decision Service.

When selected, a new dialog appears into which the decision service name can be entered:

Upon completion of the decision service creation, a panel is shown allowing us to specify the details of the decision:

Similar to other service descriptions, we now have the ability to create a service implementation using the building blocks of service creation. For a decision service, we have three items that are specific to this type of service. These are:


Business Action Language (BAL) Rule

The Business Action language (BAL) Rule mechanism allows us to define a series of if/then/else conditions based on the current values of the variables in the process. When a BAL rule is added to the service canvas it looks as follows:

Switching to the Decisions tab allows us the ability to enter the details of the rule using BAL.

The structure of a business rule is generically:


In the definitions section we can define local variables/values that are used in the remainder of the rules. For example:

definitions set low_discount to 5;

The full language of BAL is described as part of the JRules product and can be found in the InfoCenter article called Business Action Language (BAL).

Decision Table

IBPM has a concept it calls Decision Tables. To understand what this is about, consider the following concept in a programming language:

if (expression A) { some code; } else if (expression B) { some code; } else { some code; }

What this describes is a set of expressions and associated code. When the first expression reached evaluates to true, the associated code is executed. In summary, that is what TeamWorks rules describe. The rules allow us to build expressions based on the values of a set of variables that are in scope. A table is visually constructed. The columns in the table represent the variables and the rows represent possible values for those variables. The rows are then evaluated at runtime from top to bottom and if the overall expression evaluates to true, the associated JavaScript code is executed. Commonly that JavaScript code will assign a value to another variable.

When a Decision Table is added to the canvas, it looks as follows.

Pattern matching

A special pattern of "-" (just the dash character) can be used to match any pattern. It is a wild card.

Strings

|| |"string value"|Matches the exact string value| |{"string value 1", "string value 2"}|Matches either of the string values| |!{"string value 1", "string value 2"}|Matches anything except the supplied string values|

Numerics

|| |number|Matches exactly the number.| |numberLow..numberHigh|Matches anything between numberLow and numberHigh (inclusive)| |> number|Matches anything greater than number| |< number|Matches anything less than the number| |>= number|Matches anything greater or equal to the number| |<= number|Matches anything less than or equal to the number| |{number1, number2}|Matches either number1 or number2| |!{number1, number2}|Matches anything other than number1 or number2|

Booleans

|| |TRUE|Matches the boolean true| |FALSE|Matches the boolean false|

Integrating with WODM

In addition to the previous options, we can also integrate with an instance of WODM. The first task is to define the location of the Rule Execution Server to the Process App. In the Process App Settings we can define a new server of type "ILOG Rules Server" and define the hostname and port on which it can be found:

By dragging a component called "JRules Decision Service" into the canvas area we can connect to WODM.

External Service

With the arrival of BPM 8.5.7 2016-09 cumulative fix, a significant new capability was added. This is the concept of the "External Service". The notion here is that without a service flow, we can "call out" to an external service provider by invoking it through either REST or Java APIs. Within process designer we can click on "Services" and see the entry called "External Service":

When we click upon it, we are presented with the following:

If we select the first option, we are taken here:

Now we get to select whether our service that we are going to call is either implemented as a remote REST provider described in OpenAPI (Swagger) or a Java class.

Let us assume OpenAPI to start … from here we select an OpenAPI description file described in "yaml". Once selected, we are taken to the next page to select from the operations contained within:

And we conclude with the following:

After having followed these steps, we end up with a new service instance:

This artifact exposes a signature which contains the names of the operations that can be called including their input and output parameters.

Additional tabs include "Binding" which shows the type of binding (eg. REST) and the identity of the server hosting the service.

The "Source" tab shows the OpenAPI specification used to create the definition:

To illustrate this technique, let us look at a sample REST exposed service:

var express = require("express");
  var app = express();
  app.use(function(req, res, next) {
  res.header("Access-Control-Allow-Origin", "\*");
  res.header("Access-Control-Allow-Headers",
    "Origin, X-Requested-With, Content-Type, Accept, Authorization");
  next();
  });
 app.get("/myapp/test", function(req, res) {
 res.set("Content-Type", "application/json");
 res.send(JSON.stringify({
   greeting: "hello, " + req.query.name
 }));
 res.end();
 });
 app.listen(3000, function() {
   console.log("Express app started on port 3000");
 });

Next we can create ourselves an OpenAPI specification. We can use IBM APIConnect (for example) to create this. Here is the corresponding file:

swagger: '2.0'
 info:
 x-ibm-name: test-service
 title: Test Service
 version: 1.0.0
 schemes:
 - http
 host: 'localhost:3000'
 basePath: /myapp
 consumes:
 - application/json
 produces:
 - application/json
 securityDefinitions:
 basic-1:
 type: basic
 description: ''
 x-ibm-configuration:
 testable: true
 enforced: false
 cors:
 enabled: false
 assembly:
 execute:
 - invoke:
 target-url: \$(target-url)\$(request.path)
 paths:
 /test:
 get:
 operationId: Hello
 responses:
 '200':
 description: 200 OK
 schema:
 \$ref: '\#/definitions/Greeting'
 parameters:
 - name: name
 type: string
 required: true
 in: query
 description: "Person's name"
 tags: []
 definitions:
 Greeting:
 properties:
 greeting:
 type: string
 additionalProperties: false
 security:
 - basic-1: []

See also:

External Service from JavaScript

Beyond making REST requests to external REST providers using the external service definition, we can also invoke those services from the context of JavaScript. Within a BPM server, we can have a JavaScript component which allows us to inline JavaScript. Within that code, we can use the tw.system.invokeREST() API. Making this call results in a REST request being made. The details of the request including its target are specified as a parameter that is an instance of the BPMRESTRequest() object. The return from the call is an instance of BPMRESTResponse.

Before making the call, you must have created the External Service definitions as described earlier.

The content of an instance of a BPMRESTRequest object is:

  • externalServiceName – The string name of the definition previously made of the imported OpenAPI definition file.
  • operationName – The name of an operation contained within the OpenAPI definitions.
  • httpMethod – The HTTP method to use.
  • path – The path relative to the base path.
  • parameters – A JavaScript object that provides the input parameters to the request.
  • endpointAddress – A URL that supplies the protocol, host, port and root path for a service request to over-ride what is associated with the External Service definition.
  • httpHeaders – A JavaScript object providing the headers to send with the request.
  • invocationCredential – Security credentials to send with the request is not using Basic Auth.
  • username – The username to send with a Basic Auth request.
  • password – The password to send with a Basic Auth request.
  • requestTimeout – The timeout in milliseconds to try and send a request.
  • responseTimeout – The timeout in milliseconds to wait for a response.
  • sslConfiguration – The SSL configuration to be used.

The BPMRESTResponse is returned from a call to tw.system.invokeREST(). It contains:

  • httpStatusCode – The status code returned from the REST service provider. 200 normally indicates a good response.
  • httpStatusMessage – The HTTP status message. Normally "OK".
  • httpHeaders – A JavaScript object containing the name/value pairs for the header properties on the response HTTP message.
  • content – The content of the payload of the response. This is a text string. You may have to use JSON.parse() on the data if it is a JSON string.

We can debug the request using a number of distinct techniques. One that I use is to setup an Eclipse TCP monitor and then change the server definition to point to the monitor. Then when I run the request, we can see the actual data that is delivered to the service in the TCP trace.

Some useful low level BPM traces include:

  • com.ibm.bpm.externalservice.rest.swagger.SwaggerParameterConverter=all

See also:

Service Components

Definitions of services exist as part of a Process Application. Each definition for of a service has a name and associated "coding". The service is "associated" with a BPD activity in a BPD process diagram. The service can either be created (from new) from the BPD activity or an existing service can be "linked" to that activity. The definition of the service is an "implementation" part of the solution.

Similar to a BPD, a Service has its own visual editor and palette:

The palette is composed of the following parts some of which are only applicable to certain types of service:

Integration Service

Human Service (Heritage)

Rule Service

Other Service Types

Coach

Heritage Coach

Server Script

Server Scriptlet

Modify Task

Postpone Task

Content Integration

Decision Gateway

End Event

Note

Error End Event

Invoke UCA

Error Intermediate Event

Intermediate Tacking Event

Stay On Page Event

Nested Service

Send Alert

Web Service Integration

Java Integration

JRules Decision Service

BAL Rule

Decision Table

After dragging and dropping the elements onto the diagram, the elements can be visually wired together with Sequence Lines in the same fashion that BPD elements are also wired together with Sequence Lines. The remainder of this section will walk us through the different types of service components available to be included in the implementation of a service.

See also:

Coaches

When added to a Heritage Human Service diagram, the Coach looks as follows:

From the palette, the icon is:

The idea of a Coach is that it describes a screen layout that is to be shown to a user. The screen will contain output data that is populated and shown to the user as well as input data that can be entered by the user and returned to the service. Coaches are such an important area of IBPM that they have their own section in the book found here:

Server Scripts

When added to a Service diagram, the Server Script step looks as follows:

On the palette, the icon representing this step looks like:

The purpose of this type of step is to allow the developer to enter a JavaScript fragment of code to be executed at runtime within the Process Server. The properties section of the Step provides a code entry area where the script can be coded:

Full entry assist is available to help in building the script.

Server Scriptlet

The purpose of this element is to assign text to a variable but provides an easy entry text input area into which the text can be entered.

When added to the canvas, the Server Scriptlet step looks as follows:

From the palette of steps, it looks like:

The implementation tab of this Step looks as follows:

Be VERY careful here … adding quotes in the text adds quotes to the content. I have been bitten by this a number of times.

Modify Task

The Modify Task component allows us to dynamically alter a number of the attributes of the current task within a Human Service. When added to the canvas, the Modify Task element looks as follows:

From the palette, it shows as:

This element can change the characteristics of a Task under logic control.

When an attribute of a task is selected, the details of that attribute are shown in the right hand side. The attributes of a task available for modification are:

Due Date – The date by which the task should be completed.

Narrative – The description of the task.

Priority – The relative priority of the task.

Reassign – The ability to re-assign the task to someone else. The value for this property is a userid, however it does not appear that we can supply a variable value and hence the target userid appears to be hard-coded. This makes it questionable just how useful this capability actually is.

Status – The Status attribute of the task. The choices are:


Subject – The subject of the the task.

For client side human services, there does not appear to be an easy equivalent for this capability.

Postpone Task

The postpone element allows a task to suspend itself for later processing. What is being postponed here is the completion of the task. The state of the service is saved for later retrieval. When inserted into a Service Editor diagram, the element looks as follows:

From the palette area, it looks like:

When the Postpone is reached, the task is returned back to the in-box where it can be claimed again. If we want to hide the task for a period of time, we have to perform some additional work. One solution is to check at the conclusion of the Coach whether or not we suspended it and, if we did, pause the re-creation of the task for a period of time.

Within a client side Human Service, the equivalent capability is called "Postpone" and looks as follows:

See also:

Decision Gateway

The decision gateway is used to route the execution path of the service based on the evaluation of an expression. The following shows a Decision Gateway in the diagram.

From the palette, this component looks like:

The implementation settings for the component has the following:

There will be a line for each possible path out from the component. One of the lines will be the default path that will be followed if none of the other expressions evaluate to true.

The labels for each line are of the form:

End Event

The end event is used to mark the end of the service. On the diagram it looks as follows:

It has the same icon in the palette.

Note

A note can be added into the diagram that provides an aid to a subsequent reader when trying to understand the solution. Text is added in a yellow box that can be positioned in the diagram. An example of how this looks is shown following:

From the palette, the note has the following icon:

The properties of the note contains a text input area into which the text for the note can be entered:

Having a note in the diagram does not effect the operation of the solution its purpose is solely for readability.

Error End Event

When added to the canvas, the Error End Event looks as follows:

The purpose of this activity is to explicitly throw an error. This would be used when, during the processing of a service, it was detected that something problematic has occurred. For example, a request to purchase a product and the expiration of a credit card has passed or the product is not in stock.

Included in the Properties of this type of element is an Implementation section:

Error Intermediate Event

When added to the canvas, the Error Intermediate Event looks as follows:

Included in the Properties of this type of element is an Implementation section:

Invoke UCA

Within a Service, we may wish to invoke a UCA. Invoking a UCA can cause the creation of a new instance of a process. Remember that UCAs are usually associated with an external service or timer causing them to be invoked. Giving us the ability to initiate a UCA explicitly adds a lot more flexibility to solutions we may build. A primitive is supplied that allows us to explicitly invoke a named UCA.

When added to the canvas, the UCA caller primitive looks as follows:

It is added by dragging a palette entry that looks like:

Once added, its implementation properties look as follows:

The UCA caller primitives implementation names the UCA that is to be called. The Data Mapping section allows us to map the variables in scope in the process to the parameters expected by the UCA.

See also:

Catch Exception

If an activity in a service can fail then it is wise to try and handle that failure by taking some remedial action even if it is only alerting an administrator. A Catch Exception handler can be added to activities that can generate failures. To add the handler, drag it from the palette and drop it onto the activity.

Here is an example with a Catch Exception added:

In the palette area, the Catch Exception looks like:

The nature of the exception can be found in the XMLElement data contained in the variable tw.system.error.

Intermediate Tracking Event

A service can include an Intermediate Tracking Event step. When reached, this will externalize a row into the associated Tracking Group view in the Performance Data Warehouse database.

Stay On Page Event

From the palette, this entry looks as follows

Nested Service

The Nested Service step allows us to invoke another service from within the current service. By using this feature we can modularize our services into reusable pieces. We can build an aggregate service from a variety of other services.

When added to the canvas, the Nested Service step looks as follows:

From the palette of available steps, it looks like:

The implementation details of the Nested Service look like:

If the service being called has multiple end event elements, then each of these can contribute their own outgoing link. In the following, we have a simple service with two possible endings:

If we invoke this service in another service through a Nested Service call, we can then have links associated with each of the possible endings (in this case, an ending called Success and an ending called Failure).

The service to be called for a nested service can be explicitly selected with the "Select" button or, alternatively, a service dragged from the library of services and dropped on the service diagram will automatically add a bound Nested Service node.

Send Alert

When added to the canvas, the Send Alert step looks as follows:

From the palette of available steps, it looks like:

When called, this activity sends an Alert message to the named user or group. This message can be found in the Process Portal.

The implementation section of the step allows us to name the recipient, subject, message and priority.

The Send To field names the recipient which can be either of:

USER: <user name>

ROLE: <group name>

The Alert shows up as an entry in the Process Portal Collaboration section as an entry with a "service bell" beside it.

See also:

Web Service Integration

A Web Service integration component allows the service to invoke an external Web Service provider. When added to the canvas, a Web Service integration looks as follows:

It is added by dragging a palette entry that looks like:

The implementation property page for this service looks like:

In the WSDL URI: text field, the URL for a WSDL file should be entered. Clicking the Discover button will then cause IBPM PD to retrieve the WSDL pointed to by this URL and parse its content. Once the content has been parsed, IBPM PD will know the potential operations that can be invoked against that service. The Operations pull-down can then be used to select the desired operation.

Here is an example of having entered a WSDL URI, Discovered its operations and having selected an operation:

When a Web Service is called, it commonly expects input data to be provided. On return from the Web Service call, response data may be available. Data in IBPM is held in variables that are local to the IBPM Service and hence we have to map from IBPM Service variables to the input of the Web Service and map from returned Web Service data back to IBPM Service variables. This can be achieved on the Data Mapping tab of the panel.

See also:

Java Integration

Integration with Java is discussed in a separate section.

See:

Stay on Page Event

When added to a Human Service diagram, the node looks as follows:

From the palette, the corresponding icon is:

This activity can only be added to Human Services. Its purpose is that, when reached, the last shown Coach is returned to. Think of it like an implicit wire back to the last Coach shown.

No Comments
Back to top