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: