How to enrich your Alloy Workflow with backend attributes
In the previous blog How to set up an easy Material Master creation Workflow for Duet or Alloy we’ve already sent new parameters to the Notes client by creating new Workflow Container Elements, and by mapping the Business Object attributes to these Container Elements. Advantage of this approach was that it does not require any coding to be done. It’s just modelling.
The disadvantage is that we need to touch the workflow definition itself (creating + mapping new Container Elements). This is not nice, especially if the customer runs some standard SAP Workflow.
Another option – and that’s what this blog is about – is to leave the workflow definition as it is, and to leverage the Alloy Custom Handler API (outbound processing) to add additional attributes to the workitem.
In this blog we will use the example of an easy Purchase Order approval workflow to send down additional header and item attributes to the Notes Client. Assumption and starting point is that we have an existing workflow that is being triggered by the BOR object BUS2012 (Purchase Order). Another assumption is that this workflow (or to be more precise the workflow definition) references and maps this BOR type to one of its Container Elements:
In the blog “How to expose a Decision Workflow to Alloy” I’ve already explained what you need to do in the Workflow Pattern Customizing in order to define a new “Workflow Application” for Alloy. In the sub-node Workflow we have specified the default Workflow Application Handler module S_OSP_WF_PAT_DEFAULT_CH_IB for the inbound processing, and S_OSP_WF_PAT_DEFAULT_CH_OB for the outbound processing of a specific Alloy workflow application. We will use the same setup in the current example as well, but this time with an additional outbound z-function module that takes care about the additional attributes.
When you define your own custom outbound handler you need to ensure that it has the same interface as the default handler S_OSP_WF_PAT_DEFAULT_CH_OB. So it’s probably the easiest to copy the default handler into your own function group (make sure to wipe out the copied coding, as we just need the interface). In our case I’ve copied the default handler to my z-module: Z_S_OSP_WF_PURCHASEORDER_CH_OB.
As per the call sequence you need to ensure that all custom outbound handlers are called prior to the default outbound handler S_OSP_WF_PAT_DEFAULT_CH_OB. This is necessary because the default handler finally sends the item out to the Alloy Add-on, and thus further data changes would not affect the item that is on its way to the Notes client. The call sequence can be influenced by using the Counter field in the customizing:
As per the use-case, we want to send down Purchase Order approval workitems enriched with some header data (e.g. PO-number, Document Type, Vendor, etc.), as well as item information (Item-number, Material number and text, Quantity, Price, etc.). On the Notes client we will use a custom form to display the purchase order in a proper way to the approver.
So at first we have to ensure that our custom handler on the backend side adds the necessary information into the so-called xprops. Xprops is the way of how we can put additional attributes into the item, which will show up as regular document attributes on the Notes client. Technically xprops is a field-value pair table, in which you put a unique field name into the NAME property, and the value you want to send into the VALUE property of the xprops structure (DDic reference is SOSP_S_XPROP). As mentioned the field names have to be unique. If you use the same field name more than once, only the last entry will be considered.
In our simple use-case we first query the workitem for all BOR objects that are referenced. We assume (and check) that we only get a reference to a BUS2012 type back, along with the primary key (PO-number). With that key we call the standard API BAPI_PO_GETDETAIL to fetch the header and the item information. Based on that we can fill the xprops-table with all attributes we want to send.
The sample coding of the custom handler (z-module) can be found here:
On the Notes / Domino side we need to use the Domino Designer to create our own Form (or Sub-Form) to display the purchase order attributes in the right way. In the current example I’ve simply created a sub-form PurchaseOrderTestWorkflow.ApproverTask that is being called by the modified default form (ERPApprovalWorkflow). Another option is to copy the default form (ERPApprovalWorkflow) into your own form, and to adapt it the way you want. In both cases you need to ensure that you enter your form name into the definition of the workflow application on the Domino server.
As I’m not a Notes developer, I’ve just used a very simple way of displaying the purchase order attributes from the workitem. Especially the list of items is not a dynamic list, but rather a kind of hard coded list that can show up to 10 items, and suppresses empty lines if not needed:
So now we just need to issue a new workitem on the backend by creating a new Purchase Order, and as soon as the replication has happened the item will appear on the Notes client: