Implementing a custom provider for Task Gateway

The Task Consumption Model in Gateway is a harmonized task representation defined by SAP and exposed by SAP NetWeaver Gateway as a restful OData service.

To enable third-party task engines to provision their tasks within this harmonized inbox (Unified Inbox), SAP NetWeaver Gateway provides an extensibility mechanism for adding additional task providers.

Figure 1 : Task Gateway architecture

The Unified Inbox application can be used together with Task Gateway to view tasks. In this post I will explain how to use Unified Inbox with a custom provider for Task Gateway.

To create a new Task Gateway provider, the following steps must be performed .

Note: As a prerequisite, the component IW_PGW (SP03 or higher) must be installed in the SAP NetWeaver Gateway system in order to implement Task Gateway custom provider.

Step 1: Create a new provider (software version)

Step 2: Implement data retrieval code for the new provider

Step 3: Configure the new provider

Step 4: Consume the Task Gateway service with the new provider

Step 1: Create a new provider (software version)

In the view "Create a new provider" in view /IWFND/V_COCCOL open the view in transaction SM30 and click ‘Maintain’. Add a new entry with type Software Version for “Instance Manager”. The new software version is just a string to enable unique identification of the new provider.

Step 2: Implement data retrieval code for the new provider

The Task Gateway framework extracts data for all configured providers via the task façade (implementations of abstract class /IWPGW/CL_TGW_TASK_FACADE_ABS).

Create a provider class that inherits from abstract class /IWPGW/CL_TGW_TASK_FACADE_ABS.

(Note: the class has to be final or it will not be instantiated.)

Depending on the support package version of the IW_PGW component, you have to redefine particular methods. If no actual functionality could be provided for a method, an empty implementation needs to be created. Without the creation of an empty implementation, the provider class cannot be activated.

Three different types of methods exist: Query, Read, Action

Query - extract a multiple entries of data item from your data source

• /IWPGW/IF_TGW_TASK_FACADE~QUERY_TASKS
  • Exporting parameter:

                         ET_TASKS (Type /IWPGW/IF_TGW_TYPES=>TT_TASKS)

• You need to fill the et_tasks table type with the list of tasks from the data provider.
• /IWPGW/IF_TGW_TASK_FACADE~QUERY_TASK_ATTACHMENTS - extract all attachments and map to AttachmentCollection structure
• /IWPGW/IF_TGW_TASK_FACADE~QUERY_TASK_COMMENTS - extract all comments and map to CommentsCollection
• /IWPGW/IF_TGW_TASK_FACADE~QUERY_TASK_POSSIBLE_AGENTS - extract all agents of the organization that can get the task and map into PossibleAgentsCollection
• /IWPGW/IF_TGW_TASK_FACADE~QUERY_TASK_POTENTIAL_OWNERS - extract a list of approvers assigned to the task and map these to PotentialOwnersCollection
• /IWPGW/IF_TGW_TASK_FACADE~QUERY_TASK_PROCESS_LOGS – logging list for the task
• /IWPGW/IF_TGW_TASK_FACADE~QUERY_SCENARIO_TASK_COUNT – extract number of tasks/scenarios per TaskID
• /IWPGW/IF_TGW_TASK_FACADE~QUERY_TASK_DEFINITIONS – extract source data task definition

Interfaces to the abstract class have been added for for additional features in higher SPs providing methods like

• /IWPGW/IF_TGW_TASK_FACADE_V2~QUERY_CUSTOM_ATTR_DEFINITIONS – get custom attributes definition list
• /IWPGW/IF_TGW_TASK_FACADE_V2~QUERY_CUSTOM_ATTRIBUTES – get custom attributes data list

Read - extracts a single item by distinct key (instance id or instance id and additional data)

• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK
  • Parameters: IV_INSTANCE_ID, ES_TASK
  • Instance ID can be a unique identifier of a task.
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_ATTACHMENT – extract specific attachment metadata
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_ATTACHMENT_STREAM – extract specific attachment data
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_COMMENT – extract specific comment data
• IWPGW/IF_TGW_TASK_FACADE~READ_TASK_DEFINITION –  extract specific task id definition
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_DESCRIPTION – extract specific task description
• /IWPGW/IF_TGW_TASK_FACADE~READ_SUBSTITUTE_PERSONAL – extract specific substitute data
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_POSSIBLE_AGENT – extract specific data for user in the same organization as the approver
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_POTENTIAL_OWNER – extract specific data on approver
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_PROCESS_LOG – extract specific log details
• /IWPGW/IF_TGW_TASK_FACADE~READ_TASK_UI_EXECUTION – create a URL to SAPUI for approval of task
• /IWPGW/IF_TGW_USER_DET_FACADE~READ_USER_DETAILS_BY_CONTEXT – extract user details for specified user

Interfaces to the abstract class have been added for additional features in higher SPs providing methods like

• /IWPGW/IF_TGW_TASK_FACADE_V2~READ_CUSTOM_ATTR_DEFINITION – get a specific custom attribute definition
• /IWPGW/IF_TGW_TASK_FACADE_V2~READ_CUSTOM_ATTRIBUTE – get a specific custom attribute data
• /IWPGW/IF_TGW_TASK_FACADE_V2~READ_TASK_STREAM – get task icon stream data

Action – change/update/create a task related feature (Examples: Approve Task, Change Priority)

• /IWPGW/IF_TGW_TASK_FACADE~CLAIM_TASK
  • Parameters: IV_INSTANCE_ID, IV_COMMENTS, ES_TAS
  • With the instance ID and the action code (use the interface /IWPGW/IF_TGW_SRV_CONSTANT) you can handle the claim action, which is triggered by clicking ‘Claim’ in the Unified Inbox)
• /IWPGW/IF_TGW_TASK_FACADE~RELEASE_TASK
  • Similar to the claim action.
• /IWPGW/IF_TGW_TASK_FACADE~APPLY_DECISION_ON_TASK – apply decision to task, for example, approve
• /IWPGW/IF_TGW_TASK_FACADE~APPLY_PRIORITY_ON_TASK – change task priority
• /IWPGW/IF_TGW_TASK_FACADE~FORWARD_TASK – forward task to another user
• /IWPGW/IF_TGW_TASK_FACADE~CREATE_SUBSTITUTE_PERSONAL – create a substitute that can take action on the task
• /IWPGW/IF_TGW_TASK_FACADE~UPDATE_SUBSTITUTE_PERSONAL – update status of substitute(activate / deactivate)
• /IWPGW/IF_TGW_TASK_FACADE~DELETE_SUBSTITUTE_PERSONAL – remove substitution
• /IWPGW/IF_TGW_TASK_FACADE~GET_TASK_DECISION_OPTIONS – get available decisions for task
• /IWPGW/IF_TGW_TASK_FACADE~CREATE_TASK_ATTACHMENT – create an attachment on the BO of the task
• /IWPGW/IF_TGW_TASK_FACADE~DELETE_TASK_ATTACHMENT – remove attachments from the Task BO

Note :

1. To map the status and priority fields, use the table /iwpgw/i_tgw_flm
2. You might want to pay attention to method /IWPGW/IF_TGW_TASK_FACADE~GET_RETURN_TAB, as this method is been called from the Task Gateway framework to retrieve potential messages been created within a provider implementation. So you need to fill either underlying message table or redefine method /IWPGW/IF_TGW_TASK_FACADE~GET_RETURN_TAB.

RFC / Web service

If your data does not reside on the same system as Task Gateway, you can use either RFCs or Web services to manipulate the data. RFCs or Web services can be called directly within each method or alternatively you can use a backend operational proxy.

Additional information

Unified Inbox features are dependent on the support package version of the IW_PGW component. Some features such as forward, comment, substitute are only available as of the higher support packages.

Recommendation: use the latest available version of SAP NetWeaver Gateway 2.0 (latest support package).

In case you started implementation of provider class until SAP NetWeaver Gateway 2.0 SP08, please consider SAP Note 2015793.

Before proceeding with the implementation, you are recommended to familiarize yourself with the Task Consumption Model and the features offered by the Unified Inbox.

Helpful links:

Task Gateway service:

http://help.sap.com/saphelp_gateway20sp08/helpdata/en/dc/272f5b5a3b401481a71a954f92a413/content.htm

Unified Inbox: http://help.sap.com/saphelp_gateway20sp08/helpdata/en/12/8ca5519b12df0de10000000a441470/content.htm

To use SAP Business Workflow

Task Gateway provides a default connector.

List of backend operational proxies (RFCs are called via BOPs) created:

'/IWPGW/WF_TGW_QUERY_TASKS',
'/IWPGW/WF_TGW_TASK_DET_QUE',
'/IWPGW/WF_TGW_TASK_DET_REA',
'/IWPGW/CL_TGW_TASK_DEF_BOP',
'/IWPGW/WF_TGW_TASK_ACTION',
'/IWPGW/WF_TGW_TASK_ACTIONS',
'/IWPGW/WF_TGW_TASK_DEC_OPT',
'/IWPGW/WF_TGW_ATT_STRM_CRE',
'/IWPGW/WF_TGW_ATT_STRM_DEL',
'/IWPGW/WF_TGW_SUBS_GET',
'/IWPGW/WF_TGW_SUBS_UPD',
'/IWPGW/WF_TGW_SUBS_DEL',
'/IWPGW/WF_TGW_USER_GETLIST',
'/IWPGW/WF_TGW_USER_GET_DET',
'/IWPGW/WF_TGW_QUERY_OUTBOX',
'/IWPGW/WF_TGW_SCN_COUNT',
'/IWPGW/WF_TGW_USER_DETAILS',
'/IWPGW/WF_TGW_EXPAND',

Depending on the system alias maintained, the call is routed to the correct system.

Sample scenario

View tasks that come from a newly created data source in a remote system.

• Create a new table in your provider system

In SE11, create a new table with these fields.

• Create RFC function modules to read and update the data from the table.

In SE37. create a new function module which takes ‘Work Item Identifier’ as an optional input parameter and returns the complete table/a row.

(If you prefer to work with Web services as opposed to RFCs, you can create a new consumer proxy and use the proxy class to generate BOP.)

• Create the backend operational proxy at the consumer side

Fill in all the details and generate

• Implement data retrieval code for the new provider

Create a new class in transaction SE24

Sample coding for query tasks:

*** call the rfc/webservice using the bop
lo_bop_query_tasks = create_rfc_bop( lc_bop_id ).
lo_bop_query_tasks_do = lo_bop_query_tasks->get_data_object( ).

*** pass the parameters as per the method (read/query/action)

ls_bop_request-iv_user = sy-uname.
lo_bop_query_tasks_do->set_request_generic( iv_request = ls_bop_request ).
lo_bop_query_tasks->execute( lo_bop_query_tasks_do ).

*** map the response

map_task_query( EXPORTING is_bop_response = ls_bop_response
IMPORTING et_tasks = lt_tasks ).

For any other methods, change the BOP name as required and also change the parameters as appropriate.

*** handle filters

loop at mt_filter_select_options into ls_filters.
case ls_filters-property.
when 'Status'.
lt_range_status = ls_filters-select_options.
when 'Priority'.
lt_range_priority = ls_filters-select_options.
when 'TaskDefinitionID'.
lt_range_tasktype = ls_filters-select_options.
endcase.
endloop.

loop at lt_tasks into ls_tasks where task_def_id in lt_range_tasktype
and status in lt_range_status
and priority in lt_range_priority.
insert ls_tasks into table et_tasks.
endloop.

Create a new method to create BOPs..

METHOD CREATE_RFC_BOP.
rr_bop = /iwbep/cl_mgw_bop_factory=>create_rfc(
iv_system_alias = mv_system_alias
iv_bop_id = iv_bop_name
iv_rfc_dest = mv_rfc_destination ).
ENDMETHOD.

METHOD create_ws_bop.
DATA: lv_logical_port TYPE prx_logical_port_name.
lv_logical_port = mv_prov_system.
TRY.
rr_bop = /iwbep/cl_mgw_bop_factory=>create_ws(
iv_system_alias = mv_system_alias
iv_bop_id = iv_bop_name
iv_logical_port = lv_logical_port
iv_use_logical_port = abap_true
).
CATCH /iwbep/cx_mgw_bop.
ENDTRY.
ENDMETHOD.

METHOD /iwpgw/if_tgw_task_facade~set_system_alias_info.
CALL METHOD super->/iwpgw/if_tgw_task_facade~set_system_alias_info
EXPORTING
iv_system_alias = iv_system_alias
iv_rfc_destination = iv_rfc_destination
iv_prov_system = iv_prov_system.
ENDMETHOD.

Step 3: Configure the new provider

• Configure the new provider
  • http://help.sap.com/saphelp_gateway20sp08/helpdata/en/29/801ec804854ee58c805f50b80480cf/content.htm

Some of the steps mentioned in "Configuring the Task Gateway Service" (linked above) are explained in the following steps:

• Map the provider to the provider class

For the provider you might want to follow SAP naming conventions.

• Configure the service

• Create a new RFC destination (this only applies if you are using an RFC connection to access the data provider.)
• Manage system alias
• Activate the service

• Assign data provider to data modelthods like

Step 4: Consume the Task Gateway service with the new provider

Consume the Task Gateway service with the new provider.

If you do not have a UI, you can use the Unified Inbox. Alternatively, you can view the results by navigating to the Gateway Client or any other rest clients/browsers.