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: 

FUNCTION z_s_osp_wf_purchaseorder_ch_ob. *”———————————————————————- *”*”Local Interface: *”  IMPORTING *”     VALUE(IT_WORKITEM_DETAIL) TYPE  SOSP_TT_WF_RUNTIME_INFO OPTIONAL *”  EXPORTING *”     VALUE(EV_ERROR_FLAG) TYPE  S_OSP_DT_FLAG *”     VALUE(ET_WORKITEM_DETAIL) TYPE  SOSP_TT_WF_RUNTIME_INFO *”     VALUE(ET_RETURN) TYPE  BAPIRETTAB *”———————————————————————-  * Values taken from LS_OSP_WF_PATTERN_DEFLT_CHTOP+LS_OSP_WF_PATTERN_RUNTIMETOP   CONSTANTS:         gc_approver        TYPE s_osp_dt_role_type    VALUE ‘APPROVER’,         gc_bound_gpwobj    TYPE s_osp_dt_obj_sub_type VALUE ‘BND’,         gc_task            TYPE s_osp_dt_obj_type     VALUE ‘TASK’.    DATA: lt_objects         TYPE swrtobject,         ls_objects         TYPE swr_object,         ls_swotobjid       TYPE swotobjid.    DATA: ls_add_data_xprops TYPE sosp_s_xprop,         ls_workitem_detail TYPE sosp_s_wf_runtime_info,         ls_client_gpw_info TYPE sosp_s_client_gpw_info.    DATA: lt_add_data_xprops TYPE sosp_tt_xprop,         lt_client_gpw_info TYPE sosp_tt_client_gpw_info.    DATA: lv_purchaseorder   TYPE ebeln,         ls_header          TYPE bapiekkol,         lt_items           TYPE bapiekpo_tp,         ls_item            TYPE bapiekpo,         lv_prefix(10)      TYPE c,         lv_numc3           TYPE numc3,         lv_totalvalue      TYPE nwertbapi.   * Pre-populate Export table   et_workitem_detail = it_workitem_detail.  * Pick the “APPROVER” item   LOOP AT et_workitem_detail INTO ls_workitem_detail     WHERE wi_task_role_type EQ gc_approver.  *   Get table of BOR-Objects from the Workitem     CALL FUNCTION ‘SAP_WAPI_GET_OBJECTS’       EXPORTING         workitem_id = ls_workitem_detail-parent_wi_id       TABLES         OBJECTS     = lt_objects.      LOOP AT lt_objects INTO ls_objects.       ls_swotobjid = ls_objects-object_id.  *     Process the Purchase Order Object       CHECK ls_swotobjid-objtype EQ ‘BUS2012’.        lv_purchaseorder = ls_swotobjid-objkey.  *     Use standard BAPI to read header+items       CALL FUNCTION ‘BAPI_PO_GETDETAIL’         EXPORTING           purchaseorder = lv_purchaseorder           items         = ‘X’         IMPORTING           po_header     = ls_header         TABLES           po_items      = lt_items.   *     Fill xprops with PO-header attributes       ls_add_data_xprops-name = ‘HD_PO_NUMBER’.       ls_add_data_xprops-value = ls_header-po_number.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_DOC_TYPE’.       ls_add_data_xprops-value = ls_header-doc_type.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_CREATED_ON’.       ls_add_data_xprops-value = ls_header-created_on.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_CREATED_BY’.       ls_add_data_xprops-value = ls_header-created_by.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_VENDOR’.       ls_add_data_xprops-value = ls_header-vendor.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_VEND_NAME’.       ls_add_data_xprops-value = ls_header-vend_name.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_PURCH_ORG’.       ls_add_data_xprops-value = ls_header-purch_org.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_PUR_GROUP’.       ls_add_data_xprops-value = ls_header-pur_group.       APPEND ls_add_data_xprops TO lt_add_data_xprops.        ls_add_data_xprops-name = ‘HD_CURRENCY’.       ls_add_data_xprops-value = ls_header-currency.       APPEND ls_add_data_xprops TO lt_add_data_xprops.  *     Fill xprops with PO-item attributes * *     FYI: xprops attributes have to be unique. So in case you want to download *          a table to Lotus Notes, you have to have unique field names for each *          attribute across all lines. That’s the reason why I derive the *          resulting field name from the loop index.       CLEAR lv_totalvalue.       LOOP AT lt_items INTO ls_item. *       Special case: Our client Form can only render up to 10 items. So we *       send max 11 to indicate it         CHECK sy-tabix LE 11.         lv_numc3 = sy-tabix.         CONCATENATE ‘IT’ lv_numc3 ‘_’ INTO lv_prefix.          CONCATENATE lv_prefix ‘PO_ITEM’ INTO ls_add_data_xprops-name.         ls_add_data_xprops-value = ls_item-po_item.         APPEND ls_add_data_xprops TO lt_add_data_xprops.          CONCATENATE lv_prefix ‘MATERIAL’ INTO ls_add_data_xprops-name.         ls_add_data_xprops-value = ls_item-material.         APPEND ls_add_data_xprops TO lt_add_data_xprops.          CONCATENATE lv_prefix ‘SHORT_TEXT’ INTO ls_add_data_xprops-name.         ls_add_data_xprops-value = ls_item-short_text.         APPEND ls_add_data_xprops TO lt_add_data_xprops.          CONCATENATE lv_prefix ‘QUANTITY’ INTO ls_add_data_xprops-name.         ls_add_data_xprops-value = ls_item-quantity.         APPEND ls_add_data_xprops TO lt_add_data_xprops.          CONCATENATE lv_prefix ‘UNIT’ INTO ls_add_data_xprops-name.         ls_add_data_xprops-value = ls_item-unit.         APPEND ls_add_data_xprops TO lt_add_data_xprops.          CONCATENATE lv_prefix ‘NET_PRICE’ INTO ls_add_data_xprops-name.         ls_add_data_xprops-value = ls_item-net_price.         APPEND ls_add_data_xprops TO lt_add_data_xprops.          CONCATENATE lv_prefix ‘NET_VALUE’ INTO ls_add_data_xprops-name.         ls_add_data_xprops-value = ls_item-net_value.         APPEND ls_add_data_xprops TO lt_add_data_xprops.  *       Total is self-calculated, as the header structure does not provide it         lv_totalvalue = lv_totalvalue + ls_item-net_value.       ENDLOOP.        ls_add_data_xprops-name = ‘HD_TOTALVALUE’.       ls_add_data_xprops-value = lv_totalvalue.       APPEND ls_add_data_xprops TO lt_add_data_xprops.   *     Put xprops into Export-table       lt_client_gpw_info = ls_workitem_detail-client_gpw_info.  *     The Groupware client entry with “APPROVER”,”BND”,”TASK” needs to receive *     the xprops       LOOP AT lt_client_gpw_info               INTO   ls_client_gpw_info               WHERE  recp_role_id        = gc_approver     AND                      gpw_object_sub_type = gc_bound_gpwobj AND                      gpw_object_type     = gc_task.          ls_client_gpw_info-task_details-xprop_list = lt_add_data_xprops.         MODIFY lt_client_gpw_info FROM ls_client_gpw_info.       ENDLOOP.        ls_workitem_detail-client_gpw_info = lt_client_gpw_info.        MODIFY et_workitem_detail FROM ls_workitem_detail.        EXIT.     ENDLOOP.   “lt_objects    ENDLOOP.     “et_workitem_detail  ENDFUNCTION.

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:

That’s it.