HCM Processes and Forms: Mobilize Your Processes with UI5 and SAP Gateway Part II: The Gateway Side

[ckuczera]

How to use Processes and Forms in Mobile Architecture Part II of III

This blog will explain how Processes and Forms can fit into the mobile world of SAP Fiori / UI5 and SAP Gateway.

The blog is split up to three different documents:

1. Part I: Basic Technology Blog with hints how to use the technololgy and power of SAP Gateway and Pro...
2. Part II: Best Practice Gateway Blog showing how to use the Data and Definition of a P&F Process in U...
3. Part III: Build up the APP Consuming Processes and make use of the powerfull Extension-Concept of SA...

After the prototyping phase we started developing the SAP Gateway service. The aim was to combine all results of the prototype into a compact SAP Gateway Service and to refactor the work of the prototype as well.

The Processes and Forms Request Gateway Service

This blog describes how we set up the SAP Gateway service triggering the P&F framework from an OData call. To achieve that we focused on the main functionalities:

1. Listing / Search for Processes
2. Addressing Processes
3. Read, Create, Delete Process Details and Display History
4. Read and Change Process Data
5. Read Process Value Help
6. Field Control per Step
7. Perform Employee Selection

Let's go...

1. Listing / Search for Processes

Listing the processes is quite simple. The easiest solution is to select all entries from table "T5ASRPROCESSES" and to return them as a list of entities to the SAP Gateway. Using sql statements automatically allows to use filtering on the table because of the SAP Gateway functionality of the technical context function  "io_tech_request_context->get_osql_where_clause( )" which returns the full where clause that can be passed to the sql statement directly.

The second option is to use the "cl_pobj_process_object" and method "if_pobj_process_object~query_using_sel_options" to start the search for processes. This is the way we decided to go. This class is used in the FPM based process search component as well. At least we decided to use this class. Starting search is simple and requires select options parameters to be passed to the search. Exactly these select options are generated automatically when starting a filtered search in the user interface. The select options can be read using the technical context "io_tech_request_context->get_filter( )->get_filter_select_options( )." which returns a table of select options (it_filters):

As shown in the screenshot, the parameter "ls_level_in" is passed as a search parameter input to the process object query method. The returned structure level_search_output contains the list of the processes including the required values:

We have developed a helper class to convert the table structure from the P&F framework to a standard ABAP structure and are using this helper function in several steps of the SAP Gateway data provider class.

The structure ls_process contains additional information read by "cl_hrasr00_fpm_utilities=>get_process_start_config( )" (e.g. process description) and "cl_hrasr00_process_utilities=>get_pd_object_name" (the "object" (employee) name).

2. Addressing Processes

Addressing processes and reading process data can be implemented in different options, depending on the available information in the user interface. The options to access the process information can be:

• using the Process ID
• using the Process Name
• using the GUID of the process
• using the GUID of the current step
• using the Workitem ID of the assigned workflow

Again, we have implemented a helper function getting an ID and trying to read the process in reversed order of the listed options (WI ID, Step ID ...). Furthermore it is required to add several information when read read the process data using e.g. the process GUID. In this case, the helper class automatically searches for the last step GUID:

and tries to retrieve the assigned Workitem ID:

Furthermore we are checking if the Workitem ID is assigned to the current user in a separate step.

It is required to read all this information to initialize the process data correctly. For example when reading the step history, the data must be initialized using the step GUID to read the requested information per step. Another example is the operation when reading the data using the Workitem ID assigned to the current user. Only in that case it is allowed to read and save the data in draft mode.

From the UI perspective there should be no difference when calling the process using the different options. Therefore we added an additional structure to the request and all data entitites containing the id, action and a comment field:

This "decoupling" of the SAP Gateway ID and the real IDs for processes, steps and workitems allows to address the process entity in several ways:

• RequestSummarySet('YHCM_PA_0329_REQUEST_FP2') or RequestSummarySet('0002') by process name or id to retrieve initial data
• RequestSummarySet('005056A515621EE692B5D522923B6737') by process or step GUID
• RequestSummarySet('409300') by Workitem ID

Furthermore we have decoupled the entity for list generation from the "real" entity for data access to have a better control on the refresh and navigation operation of the master form. But more details can be found in the following chapters.

3. Read, Create, Delete Process Details and Display History

Reading the process itself is quite simple. As already mentioned in the previous chapter, we are reading the process information based on the given information, adding additional information from the workitem or the tables "T5ASRPROCESSES", "T5ASRSCENARIOS" and "T5ASRSTEPS". I am quite sure that there is a better way than accessing the process information directly from the database tables, but until now we didn't investigate that point any closer.

Creating a process is a little bit more interesting. In fact, the SAP Gateway service is stateless, which means that the data is received per http request and ends after a successful action (list, get, create or update entity) without any session or stateful information like we are used to have in the WebDynPro world. Creating a process means storing the data temporary in a customer / cluster table or persisting the data directly in the real P&F Framework. We have chosen the second option and saving the process in draft mode directly after the create action:

The base information like process name, initiator role and object key (to be honest it should be object type as well) are passed by the user interface to the create function. The information is read using the data provider class. After that some additional information is added, an unique GUID is generated and the process is started passing the action for save as draft. As shown in the screenshot, we are looping and waiting a second until the process is really created and can be read using the helper class method get_process because we were facing issues when creating the process and directly trying to access the data.

Deleting a process in the P&F Framework is possible as far as the data is not written into the "database" or infotypes of an employee. The call for deletion is simple using our P&F utility class, because we just need to execute a different event and pass it to the P&F Framework:

As we are able to create, update and delete processes, we need to access further information of a process in different points of the user interface. Further information can be requested using the associations and navigation properties, as you can see in the following screenshot, we enabled the navigation for:

• Actions - available buttons like save draft, withdraw, delete and so on
• FieldControl - to control step dependent field settings
• ObjectSelection - selection types for employees based on the process and initiator role
• History - to display the history of the process

The following screen shows the navigation operation to the history data of a request:

This type of data navigation is the main part of our data access logic and was already described in Part I. We will describe the data access in the following chapter in detail.

4. Read and Change Process Data

As already described in Part I we have decided to generate the data entities based on the P&F framework data definition on the fly.

Step 1 was to create the entity and the appropriate entity set using the data definition of the P&F Framework. Therefore we have redefined the "define" method of the generated "_MPC_EXT" class and added some code:

First, we are reading the allowed processes based on a customer table assigning the process number to a process name in P&F which is 0002 and "YHCM_PA_0329_REQUEST_FP2" in our "Sideline Job Request" demo.

Looping through the list of processes reads the field definition based on P&F (line 14) and automatically generates the entity and entity set (line 16). Most of the coding is taken from the SEGW generated MPC classes and a little bit of testing.

The second (line 11) and fourth step (line 17) is to define the the data annotations for value help requests, but more on this topic see chapter 7.

Finally the associations and navigation options are created (line 21). As a result we can find additional navigation options in the metadata file and of course in the request object that were generated automatically without the manual definition in the SAP Gateway Builder SEGW:

Each entity was created using the process information of the P&F framework. Furthermore, we have added some default fields, like the ID, action and comment we already saw in the definition of the request entity. Next next screenshot shows the navigation options connected to the request entity:

Finally we can see how the data is requested in the SAP Gateway call:

Of course we had to redefine the method "/IWBEP/IF_MGW_APPL_SRV_RUNTIME~GET_ENTITY" and in addition the methods for create and update in order to handle the data and read the information from the P&F Framework.

5. Read Process Value Help

During the development of the prototype we analyzed the capalities to execute value help requests in a generic way. The most interesting functionality here, was the capability of smart fields to read value help configurations based on annotation information generated by the SAP Gateway Service.

As you can see in the screenshot 1 of chapter 4 we are generating the annotations (line 11 and 17) for value help definitions automatically. In fact we need to load the vocabulary of the annotation first. These vocabularies are "com.sap.vocabularies.Common.v1" and "Org.OData.Core.V1". After that, it is possible to add the required annotation information for fields having a value help. Again, the coding can be found in the generated "*_MPC" class created by the SAP Gateway Service Builder SEGW.

As a result, all fields having value help information will be annotated with "com.sap.vocabularies.Common.v1.ValueList" automatically as shown in the following screenshot:

This annotation will search for value help information in the entity "ValueHelp(Process='0002',Field='I0329_TTKEY')/DropDown" which triggers a request to the entity VHValueHelp by navigating from VHDefinition (ValueHelp) using association DropDown.

As shown in the above screenshot the result structure of the value help entity is similar to the elements of an object list item. We have choosen this data structure to enable a generic value help to read more than one key, value pair and deliver that information to the user interface.

Of course the passed parameter for "process" can be a process id or name, process or step GUID or a Workitem DI. The values of the value help are read using the data processor initialize_form method or alternatively using the function modules "F4IF_GET_SHLP_DESCR" and "F4IF_SELECT_VALUES" which works fine for search help type (SH):

Compared with the value help of P&F the "raw" value help returns more values than the calculated value help of the frequency field. The calculated value help for field "I0329_FRQTX" returns only six values and the raw value help 45, therefore we prefer to use the P&F Framework generated value help:

Well: Value help is done so far. More details how this option behaves in the user interface can be found in Part III.

6. Field Control per Step

The P&F framework is able to control fields per request step. For example all fields should be disabled in the approval step by the line manager and only some fields should be editable in the step by personal administrator who is correcting details of the request and saving the request into the infotypes.

We have solved this using an association from request to the field control entity. In combination with the different kinds of process initialization by process id or name, process or step GUID or a Workitem ID, the data processor always returns the correct field control elements in table "ET_FIELD_UI_ATTRIBUTES". This table contains information about mandatory, readonly and visible flags which was used to transfer directly to the user interface:

This information is used in the user interface to set the properties of each field based on the requested field control.

7. Perform Employee Selection

The last point was to calculate the employees that can be chosen to start a process. This option is not relevant for the employee himself who is going to start a process for e.g. address change. More interesting is the start of a process by his manager or even a personal administrator.

When creating a process, the user interface is passing the request mode, which is "HRASRA" for Personal Admin, "HRASRB" for Manager or "HRASRD" for Employee. Based on this request mode type the user interface should allow a selection of employees. We were thinking about the best option to realize this requirement and selected the very flexible and configurable framework "Object and Data Provider" OADP, that is used quite often in the ESS and MSS components of SAP.

The association "RequestSet('ID')/ObjectSelectionSet" returns all available object selection views available for the process and request type that is stored as a property in the process. In our example process, which is triggered by the manager, the request returns "MSS_LTV_EE_DIR" and "MSS_LTV_EE_ALL". These are the views for direct reports (employees) and all reports of a line manager.

Passing this to the request "ObjectSelectionSet('MSS_LTV_EE_DIR')/ObjectSearchSet" is executing the search for employees based on the object view. The function module used in the background is "HRWPC_RFC_OADP_GET_OBJECTS" passing the object selection it returns a list of employees:

This table is used in the user interface to display selectable employees for a process and the request mode.

Summary

In this blog we focused on the SAP Gateway Service and the set up of the entities used to retrieve, update or delete processes in the P&F Framework. I hope we could point out some challenges and describe describe our solution to several issues in detail. Of course there is always a way to solve something in a different way, but this is how we proceed in the prototype.

The most interesting point from my side was the dynamic generation of entities, associations and annotations at run-time. But this is the way SAP is doing the job when using the SAP Gateway Service Builder SEGW as well, so choosing this way was quite logical for me.

Combining the power of annotations with the capabilities of the smart field control in the user interface moves the logic of building and controlling the behaviour of the user interface to the SAP Gateway, which is reducing the effort in the user interface dramatically.

Creating annotations in the SAP Gateway Service Builder SEGW is a little bit "strange" and you really need to get used to that, but generating them automatically is, based on the code templates from SAP, really simple.

Now let's see how this will be put together in the user interface where we where our main focus lay on its re-usability and flexibility of the user interface.

Let's go to Part III