Journey into the Unified Inbox

Over the past 6 months I have been delving deep into the Unified inbox and its inner workings.

After doing an indepth analysis and comparison as shown here Workflow Inbox Feature Comparison Matrix of all the SAP standard options to use as a Workflow Inbox. It became apparent that the Unified Inbox would be the best option to go with. After asking the question on SCN Anyone using the Unified Inbox in a Production Environment yet? and not receiving an answer to that, it also became pretty clear that it is not widely adopted yet.

There is a really good blog Unified Inbox in Gateway SP09 written by Shyam Sunder Suthar showing what the latest version of the Unified Inbox is capable of, with screenshots demonstrating its functionality. However it doesn’t discuss much technical detail about how everything works behind the scenes and how to set it up, which I intend to cover in this blog.

Key strengths of the Unified Inbox

• Its much more than just another Workflow Inbox. Its a Task Inbox which allows you to view tasks not only from SAP Business Workflow, but also BPM and practically any other source you can think of or code, using the custom task provider concept. You are only limited by your imagination and external API’s available.
• It has excellent multi system support with the ability to do parallel calls to retrieve your tasks from multiple systems.
• It’s highly extensible given that it is a UI5 component which can be embedded in your own application and enhanced from there. Which I will talk about in more detail in my next blog. The gateway service can also be redefined and you have the ability to redefine task providers or completely create one from scratch.
• The power is in the API / Gateway service and you can use any number of custom or standard User Interfaces to utilise it. This is evident in the way that both the unified inbox and Fiori Approve Requests use this Gateway service and much of the same config.
• It has a modern HTML5 look and feel.
• It is not dependant on SAP Portal and can be run stand alone, in NWBC Client and NWBC for HTML as well as in Fiori Launchpad.
• Although not designed for mobile use, it is tablet friendly, meaning it can be used via a tablet although it is not optimised for that purpose.
• Works with Task Visualisation transaction SWFVISU similar to the UWL.
• Easy to brand using UI5 Theme Designer.

Unified Inbox  System Software requirements.

Although the Unified Inbox is available in older versions, I recommend being on the following minimum component versions as the older Support Packs are not as complete in functionality,

IW_PGW SP06  – Process Gateway Component – This component contains the main Gateway service /IWPGW/TASKPROCESSING and the UI5 Component and BSP application /IWPGW/TGW_UNIF_INBOX which is the UI layer of the Unified Inbox. This component is not installed by default so will need to be installed manually.

SAP_UI SP09 – SAP UI Component – This contains the UI5 library with UI5 version 1.22.2 (Current latest version at writing of this blog is 1.24.4 – It won’t hurt to have the latest as there are Inbox Control bug fixes which are mentioned in the release notes).

Netweaver Gateway SP09 on pre Netweaver 740 and Netweaver Gateway (SAP_GWFND) SP08 if you are on Netweaver 740 – these are the minimum required versions for IW_PGW SP06.

Internet Explorer 9 – Although it does work on Internet Explorer 8, it just looks and feels better on IE9 and up. Or Chrome and Firefox work great too.

Setup steps to start using the Unified Inbox

If you are planning to use SAP Business Workflow, make sure that it is configured already in you system in transaction SWU3.

If you are using BPM, you will need to go through other steps to setup the webservice to a BPM system. I won’t be covering these details in this blog.

You also need to have setup the destination RFC connections in SM59 for each of the systems you intend to use.

Step 1 – Setting up the System Aliases

Go to SAP Netweaver->Gateway->OData Channel->Configuration->Connection Settings->SAP Netweaver Gateway to SAP System->Manage System Aliases

In here, if you are already using Gateway and connecting to the systems, you will notice there will be entries in the table already, with the Software version field as DEFAULT. It does not work if you try and use these connections, you will get an error in the Gateway service. You will need to create additional entries for each system you intend to use and specify the correct software version. For SAP Business workflow that will be /IWPGW/BWF as shown below. For BPM it will be /IWPGW/BPM.

If you are using a Gateway Hub, you will put the destination systems as the external systems you want to access, for e.g. ECC or SRM. For an embedded deployment you will specify a local alias with RFC destination as NONE.

Step 2 – Adding the TASKPROCESSING Service in Service Maintenance

Go to transaction /IWFND/MAINT_SERVICE and click on the Add Service button.

Enter the filter criteria. Note that the Unified Inbox uses Version 2 of the service.

Click on the entry to add the service.

All you need to do is enter the package and press the green tick, the rest of the details are filled in for you.

You should see this successfully created message.

In the main screen of transaction /IWFND/MAINT_SERVICE you should now see the following entry:

Step 3 – Setting up Multiple System Aliases

In the bottom right in the System aliases section, click on Add System Alias button.

Since this is on a Gateway Hub system and the 2 systems I would like to connect to are ECC and SRM, I will remove the LOCAL_BWF and add 2 entries, one for ECC and the other for SRM, marking ECC as the default system. What this does is when the service is called without ;mo (Multi Origin) added to the service URL, only the default system will be called.

If you use the Call Browser button in the main screen of transaction /IWFND/MAINT_SERVICE it will open the service in a browser loading the meta data. By default there will not be the ;mo option in the service URL. If you add in TaskCollection as the Entity Set to query, notice the difference between the service call with and without the multi origin option.

Notice that an additional property is added automatically: <d:SAP__Origin>SAP_ECC_BWF</d:SAP__Origin>

This SAP__Origin property is used to determine which system the entity is in.

By default the Gateway system should be setup so that parallelization is used when more than 1 backend System Alias is called. This can be setup or changed in the config as below:

Another useful thing to setup when using multiple System Aliases is setting the TASKPROCESSING service as error tolerant. This means that if the call to 1 system fails, then the whole call does not fail, that system is just excluded from the results.

Step 4 – Activate and run the Unified Inbox

If it is not already activated, go into SICF and active the following service /sap/bc/bsp/iwpgw/tgw_unif_inbox and run it.

Or run it via the BSP Application in SE80.

And then you should see the following. Note there is nothing you need to setup to allow certain tasks to be viewed. You should see any items in your SAP Business Workplace (SBWP) in the Unified Inbox. If you are not seeing this, then you most likely need to look at transaction /IWFND/ERROR_LOG to see why. Authorisations is a likely cause.

Understanding the architecture behind the Unified Inbox

The Unified Inbox is actually made up of several layers and components. I thought the following diagram would best describe it.

The Gateway Service of the Unified Inbox

The core of Unified Inbox is actually the Gateway service (API): /IWPGW/TASKPROCESSING which provides an extremely powerful API for accessing Task Processing functionality including the following:

• Tasks Query
• Reading of Task Details – as plain text or as HTML
• Task Forwarding
• Reading Task Actions/Decisions
• Task Actioning / Actioning Decisions
• Comments handling
• Attachments handling
• Possible Agents
• Substitution handling
• and much more

And any other custom functionality can be added by redefining the /IWPGW/TASKPROCESSING service and/or redefining a task provider.

This service has 2 versions. Version 1 is the version being used by Fiori Approve Requests and Version 2 is being used by the Unified Inbox. Version 2 has much of the same functionality as Version 1 and more.

The Task Provider Layer

There are 2 standard Task Providers available:

1. BPM  – Business Process Management
2. BWF – Business Workflow

If you require additional functionality in one of the above, you can redefine the Task Facade Implementation Class and use your redefined class by changing it in the config. Alternatively you can create a completely custom Task Provider, I’d recommend reading How to create a custom data provider for Task Gateway to learn how to do that.

See below where to change or specify new Task Providers:

The UI Layer of Unified Inbox

The core of the Unified Inbox is actually made up of a really powerful complex control: the Inbox Control as you can see in the SAPUI5 SDK here: Inbox Control Demo or you can view the more advanced functionality available if you look at the Inbox API Reference here: Inbox API Reference.

This control is one of the few controls which is not available in OpenUI5 and only in the SAPUI5 SDK.

The next layer is the Unified Inbox UI5 Component which is inside the BSP application /IWPGW/TGW_UNIF_INBOX as illustrated in the top right of the architecture diagram above. This component instantiates the Inbox control and has the Unified Inbox View and Controller and binds the Gateway service /IWPGW/TASKPROCESSING to the Inbox, then sets up the Inbox control and configures it. Very little actually happens here besides instantiating the control and basic configuration of the control.

The next layer is still within the /IWPGW/TGW_UNIF_INBOX BSP Application and is the UI5 Application which instantiates the Unififed Inbox Component, places it in a Component Container and on the web page. This layer also adds the application header and handles the login and logoff aspects of the Unified Inbox. It also sets up user configurable settings, which are set up in a config table via SPRO. This allows the user to configure a few things such as:

• UI5 theme – default is sap_goldreflection, but personally I prefer sap_bluecrystal.
• Opening a task in an overlay frame or in a new tab. Default is for it to open in a new tab.
• Is the header visible or not. Default is for it to be visible.
• Is the user list enabled. Default is true.

See: Configuring the Unified Inbox – SAP NetWeaver Gateway – SAP Library

See below where to setup the Unified Inbox config parameters:

Please note that it is not mandatory to fill in this table. If you leave the table blank the application will just use the defaults as mentioned above.

See below by setting the theme in the table above to sap_bluecrystal it now shows the Unified Inbox using this theme.

The Configuration Layer of the /IWPGW/TASKPROCESSING Service

There is not much to configure on the UI layer more than mentioned above, such as theme and a few other options. However there are more configuration options which you can use for the backend TASKPROCESSING service. Things such as:

• Configuring custom actions / decisions. In the case of a workflow user decision these decisions are automatically determined and do not require any configuration, however if you would like to add manual actions on a normal activity task, you will need to configure the actions / decisions here and deal with the action handling using the BAdI /IWWRK/BADI_WF_BEFORE_UPD_IB which is mentioned in the next section.
• Maintain Task Names which is used by the filter in the Unified Inbox.

See below how to configure this:

The Enhancement Layer of the Unified Inbox / TASKPROCESSING service.

There are a number of BAdI’s available for:

• Handling custom actions or adding additional functionality to actions.
• Changing the task title.
• Changing the task description or setting HTML content for the description.
• Custom attributes.

These are the available BAdI’s:

• /IWWRK/BADI_WF_BEFORE_UPD_IB
  • BEFORE_UPDATE – Before Work Item handler update – This is used for custom actions behind the Decision Keys configured in the table above.

• /IWWRK/BADI_TGW_CUSTOM_ATTR
  • PROVIDE_ATTRIBUTE_DEFINITION – Read custom attributes definition – Define custom attributes metadata here.
  • PROVIDE_ATTRIBUTE_DATA – Read custom attributes value – Populate custom attribute data in here

• /IWPGW/BADI_TGW_TASK_DATA
  • MODIFY_TASK_TITLE – Modify Task Title – If you need to modify the task title from the work item task.
  • MODIFY_TASK_DESCRIPTION – Modify Task Description – Allows you to modify the plain text description or HTML description which is populated by default from the task description. One reason for using this could be to create an HTML table of items.

• /IWPGW/BADI_TGW_TASK_QUERY
  • MODIFY_ITEMS – Modify subject in task query – Mass modification of the task titles for a number of work items.

• /IWPGW/BADI_TGW_USER_DETAIL
  • READ_USER_DETAILS_BY_CONTEXT – Provide User Details
  • GET_USER_PICTURE_STREAM – Provide a user picture – Defines where the user picture comes from. This BAdI is necessary if you want pictures as there is no standard implementation for providing user pictures.

In future blogs I would like to demonstrate these enhancement options and also showcase what’s possible when enhancing the Unified Inbox. Stay tuned.

Update 12 Dec 2014: follow up blog Enhancing the Unified Inbox