Introduction

stefan_henke · ‎06-21-2013

Introduction

In the recent past, I was asked several times how to cancel a process instance via the public API of SAP NetWeaver BPM. My answer was very short and simple: you can´t. Fortunately, I asked for the use case because I wanted to understand why people are asking for support via the public API though it can be done via the SAP NetWeaver Administrator (NWA). The answer I got was always very similar: It should be possible for process participants or the process initiator to reject their request even if it has not yet been completely processed from a business perspective. And for this, access to the NWA naturally should not be opened to end users.

As this is a common pattern, which is interesting for many scenarios, I want to share some ideas about it with the whole community. The following list summarizes a couple of example scenarios:

Employee wants to cancel one of his leave requests, which has not yet been approved or declined by his manager
In a Master Data Management scenario, an employee wants to reject a request for article creation, which he created accidently

Background – What exactly is the challenge?

The requirement is actually fairly simply and straight forward. However, it is not only about the question if NWA should be accessible for end users or not. There is a bit more behind this to completely understand the requirement. It is important to consequently distinguish between two types of users: business user and technical administrator.

SAP NetWeaver BPM offers the possibility to cancel a process instance via the NWA. This is an administrative action that can be used to move a process instance into a final state. Typically, it will be performed if the process instance encountered some technical issue, which cannot be resolved (e.g. context mapping issue). From this you can see that it is really meant for exceptional cases. The state of process instance will be 'Canceled', but not 'Completed'. Though 'Canceled' is a valid final state from a technical perspective (resources occupied by the process instance in the process engine will be cleaned up), but it should not be treated as a valid final state from a business point of view. Canceling a process instance will simply interrupt the process flow and terminate it. There is no guarantee that the data managed by the process flow is still in a consistent state.

So, for a proper handling of the above scenarios, it is not a good practice to use the cancel action. All these examples have in common that this operation is performed by a business user. So, as general rule, you can check if your scenario requires to offer such a rejection or cancelation possibility to technical or business users. For business users, you should consider implementing the pattern offered in this blog.

Note: The scenario I´m using throughout the description assumes that there is a business key that uniquely identifies the process instance. This uniqueness is required at multiple locations as you will see later on. It doesn´t matter if the business key is a simple string identifier or a more complex one consisting of multiple attributes as long as you can express it as an XML schema definition and map it into the BPM process model.

The technical ID could also be used; however it is local to the process and is only available after the process has been started. A business key on the other hand is typically already available also in other contexts outside of BPM. This will not work with the process instance ID as it is randomly created on process start.

Solution

As described above, there is the need for a better design of the process model to reach the goal. The basic idea of the proposed pattern is to support termination of the process flow using an Intermediate Message Event (IME). The following process model visualizes this idea.

At process start, the business key is passed as parameter so that it can be stored within the process context. As first step in the process flow, there is a split, which separates the actual business flow from the option to reject the request again. The latter is realized using the mentioned IME. Having this in a parallel flow of the process, it is possible to send messages to the IME at any point in time the process instance is running. Once a message has been consumed by the IME, the flow runs into a termination event which not only stops this branch, but every other branch in the flow as well. In this example, the branch I referred to as actual business flow only contains a simple Human Activity to keep things simple. In a real life scenario this would be the branch you add your process logic to. This might include other activity types like Automated Activities, but also more complex things like Referenced or Embedded Sub-Processes. The termination event will be propagated down to such Sub-Processes so that they also get stopped.

There is one important thing missing to make the pattern work. In order to only reject a single process instance when sending a message to the IME, it needs to be configured with a proper correlation condition. Here comes again the business key into game. The message interface of the IME needs to include the business key of the instance to reject. We simply correlate messages to process instance where the business key in the message matches the one stored in the process context when we trigger the process instance.

Having this in place, it is possible to send a web service message to the IME with the valid business key (for details, see section Consumption).

Variants

The described pattern might not be completely sufficient for all use cases. Let´s assume the request for which the process instance has been created includes some persisted data or any other kind of state. This data could be stored outside the process context so that it will not be cleaned up when terminating the process instance. There needs to be a way of synchronization of these two systems. In the example of a leave request, this could be the leave request as such, which includes among others the start date, end date and a type of the request (determining if it is about a new request, a change request, etc.). If we allow the requestor to reject his request, this data will need to be cleaned up or at least marked in a way that it has been rejected.

Therefore, the flow is extended by adding an additional (automated) activity once the intermediate message event has been consumed by the process instance. With this, an application can execute any kind of activities to react on the rejection. Of course, such compensation operations could be more complex than just executing a single activity. Having this possibility is a big advantage over the original proposal, but of course not always required.

Consumption

As described before, using this pattern a process instance can be completed by sending a web service message to the IME “Trigger Completion”. This web service message has to be structured according to the interface of the IME. In this simple example, it mainly consists of the business key referencing the process instance that should be completed. The following XML snippet outlines the message structure for a business key with value 11:

<?xml version="1.0" encoding="utf-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<SOAP-ENV:Body>

<yq1:SimpleBusinessKey

xmlns:yq1="http://www.example.org/InterfaceWithSimpleBusinessKey/">

</yq1:SimpleBusinessKey>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The sending party can be easily incorporated into a business user´s UI next to the option to trigger new process instances. The concrete steps to do this depend on the UI technology you are using. In case of Web Dynpro, you can easily import the endpoint configured for the IME as a web service model. Using standard Web Dynpro capabilities, the web service operation can be invoked passing the business key. If you are using SAP UI5, you can leverage standard JavaScript Ajax functionality to trigger a web service invocation on the endpoint. It should also work in a very similar manner for other UI technologies as it is about standard web service consumption.

By default, message reception is rejected for users. In order to be able to send a message to an IME, the sending user has to have the UME action “SAP_BPM_TRIGGER_EVENT” assigned.

Timer-Based Cancellation

There are other use cases which follow a very similar pattern. However, the step to cancel the process instance is not done by a user. It is more that the process instance should be terminated if it has not been completed from a business point of view within a certain point of time. This can be done by replacing the IME with an Intermediate Timer Event in the described process model. With this type of event, you can configure an amount of time. This can be either a static value or again mapped from outside into the process context.

Conclusion

In this blog, it has been discussed why the “cancel process” operation in SAP NetWeaver BPM is not suited to cancel a process from a business perspective. Rather a new process pattern has been described that allows business users to complete a process instance aside the regular process flow.

What you should know about cancelling a process instance ....

Introduction

Background – What exactly is the challenge?

Solution

Variants

Consumption

Timer-Based Cancellation

Conclusion

Further Reading

Get Your SAP HANA Idea Incubator Badge Today!

SCN Mission - SAP HANA Quiz Challenge is now retired

Share your #HANAStory and Win