aBPM Step by Step – Part 2
In the first part of this series I described the basics of user interface modelling and interacting with aBPM. This time I’ll show how to integrate aBPM with SAP BPM workflows. This includes:
- how to model a BPM process that works with aBPM
- how to define aBPM as BPM tasks for human activities
- how to start a BPM process out of aBPM’s callback interface
- how to access aBPM managed form data in BPM process context
- how to interact between BPM and aBPM outside of user activities
aBPM does not require different BPM modelling, only a few elements are affected. One is the process start that needs to use an aBPM pre-defined data-type. So let’s have a look on the service-interface:
This is a typical (asynchronous) service interface for a BPM process, the only difference is the usage of the pre-defined ABPMDataType for input parameters. These parameters are filled by the aBPM callback if the process is started from a start user interface like as request form.
This service interface is used by an event trigger and the event trigger as assigned to the start event.
Typically we define a data object (in the example below it’s called “ABPM”) of the same ABPMDataType in the process context and map all parameters to this data object:
The mostly used attribute of “ABPM” is the “ABPMProcessId”. It’s a mandatory input for aBPM user interface integration as well as for interaction between BPM and aBPM.
Starting BPM processes from aBPM
After defining the BPM process in a way aBPM expects we can now add the necessary code in the aBPM callback. There are 2 places: The startBPMProcessAutomatically method provides the necessary information about the process (that are the vendor, the development component name and the process name itself):
The start is typical triggered by a button and then executed in the handleUIEvent method that we already know from the previous part. Starting a process looks like this:
The Java-code does the following steps:
- If the eventName equals the generated constant START_PROCESS then it’s checked if there are any validation errors in the form. The validation will be done automatically by the framework.
- If there are no validation errors the startProcess method is called. This method is defined in the base callback class in order to ease development. This method will save the process, retrieve the definition of the workflow from startBPMProcessAutomatically and start the BPM process via the Java API. If exceptions occur they will be returned as result.
- In the example we’ll return a SimpleOption object. These allow e.g. returning messages to the user. In this case we’ll return either a success or error message within a message box.
Use aBPM for human activities
We are now able to show the user the initial user interface and start the process. The next task is to show the user interface for human activities. As aBPM uses UI5 for user interfaces (Web Dynpro Java is also supported, but its focus is support to support existing processes) we need to create tasks with UI type “Custom Technologies”. The URL as well as the input and output data-type are fixed:
It would be possible to define one aBPM-UI5 Task for all human activities but we recommend to create separate for each human activity because you might to add custom attributes etc. Also the inboxes offer filtering by type that would be useless if only one task-type is used.
After creating the task it can be used to describe a human activity. In order to allow aBPM to know which aBPM process should be shown as well as which attributes should be shown we must set multiple input data attributes via data mapping:
In this case we set:
- ABPMProcessID – Identifies the process and allows aBPM to find the form data in the database tables.
- ConfigID – Contains the value of the button configuration to be used. This allows us to determine which set of buttons should be shown.
- ProcessState – The state determines if an attribute is visible, editable and mandatory. In order to understand this we need to have a look at the Excel definition sheet from the last part:
For each attribute we defined a visibleOnCreate, editableOnCreate and requiredOnCreate property. The value of the property contains the states for which the attribute is visible, editable and required. In our example “Firstname” is visible for the states “START”, “ACC”, “MGR”, editable for “START” and “ACC” and required for “START”. So if we define “MGR” as state for our human activity this field would be visible but read-only and not mandatory!
The states can be defined without any restriction by the developer (best to have some guidelines in place) and can contain placeholder like “*” to define generic states (e.g. “START*” if you have multiple start-states).
- TaskSubject – This defines the subject of the task in a way that it can be translated and also used by the email function.
- HtmlEmailTemplateName – As an additional service, aBPM offers template based HTML emails. I’ll describe this service in a later part of the series but for now: This field contains the name of a template that is used to send HTML notification emails (replacing the default notification email services).
After all this, if the user opens the task he can see the following screen when opening the task:
Access aBPM data in BPM process context
As you have seen in previous section the BPM process contains some basic aBPM data, e.g. the aBPM process Id. What if you need more of the data aBPM stores, e.g. a certain amount to determine if the process needs an additional approval? For this, aBPM provides 2 ways of accessing the data:
- aBPM creates a XSD schema in the BPM DC that you can use as a data definition. Together with an EJB function you are able to bring data from aBPM into the BPM context. The XSD schema is generated with information retrieved from the Excel. There you find a column called “includeInXSD”. For each attribute that is marked in this column an entry in the XSD schema is created. The next screen shows the definition of the function:
After defining the function and a data object of the generated XSD data type, you can map the data with the function fillContext(ABPM/ABPMProcessId).
- The second way of accessing aBPM data is to use the predefined functions that aBPM provides. These allow the direct access of one attribute directly by it’s name:
Interaction between aBPM and BPM outside user activities
The last topic I’ll cover in this blog is the interaction between aBPM and BPM beside human activities.
If you need to set aBPM status or interact with aBPM from BPM you can use a predefined web-service that provides multiple methods to call aBPM from outside. With this it’s possible to:
- Set the state of the process, e.g. to set the process state to finish if the BPM process ends.
- Trigger an action from the BPM process. The call is handled by a callback method so that it provides an extremely flexible way of interaction.
- Handle search parameters to save and update parameters that are used for the cockpit search. I’ll handle the cockpit and it’s customization in a later part of this blog.
Beside this there some more options that you can trigger also from outside a human activity.