Deploy SAP adapter

The SAP adapter is deployed automatically together with the installation of IQX AppBuilder. Updated versions of the SAP adapter may be deployed from time-to-time. The SAP adapter may also be independently deployed where a customer does not utilize AppBuilder. The SAP adapter may be deployed in a hub configuration with RFC connections to related systems, or directly on all SAP ABAP systems eg ECC, SRM, SolMan, CRM (legacy).

Configure SAP adapter

Configure the SAP adapter to integrate with OneList as follows:

Create a custom implementation class based on the IQX base class:
1. Use the Class Builder in SAP (t-code SE24) to open the class /IQX/CL_SAP_WL_ADPT.
2. From the menu bar, select Edit → Create Subclass.
3. Enter the name of the subclass in the Class field.
  - e.g. ZCL_OL_PO_ADAPTER
4. Enter a short description in the Description field.
  - e.g. Purchase Order adapter for OneList
5. Choose Save.
6. Enter the Package and choose Save again.
Redefine the following inherited methods (click on the method for the implementation example):
1. Redefine method – GET_OBJECT_DETAILS
2. Redefine method – GET_ATTCHMENT_CONTENT
3. Redefine method – EXECUTE_ACTION
Check, Save and Activate the implementation class.

Maintain the following OneList configuration tables via SM30.

*Table Name*	/IQX/OL_TASK_DEF
Description	Defines the association between the OneList Job and OneList task filter. The task filter can be either the SAP TS number or FAB form name.

*Field Name*	Description	Example
Job Type	The description of the type of task	PO_APPROVAL or FAB Form Name
O.L. Task ID	The SAP workflow task ID for the object you would like to retrieve the worklist items.	TS20000166
Project Name	Optional Project Name	FAB form name
Number	The number of workflow tasks that should be fetched per call	10

Table Name
/IQX/OL_JOB_DEF
Description
Defines the Background Job Parameters

There are 5 different background jobs that need to be configured, each as an individual row in the table. Each job type, based on the Subcomponent, is detailed be

SYNC_USER

*Field Name*	Description	Example
Job Type	The description of the type of task	SYNC_USER
Class	The class to use when executing this task	/IQX/CL_OL_SYNC_USERS
Subcomponent	The name of the method to be executed	SYNC_USER_REQUEST
Short Description	Short description of the job	Synchronize SAP users to OneList
Freq. In Mins	Job execution frequency in minutes	5

SYNC_ACTIONS

*Field Name*	Description	Example
Job Type	Must be the JobName you specified when configuring table /IQX/OL_TASK_DEF	PO_APPROVAL or FAB Form Name
Class	The name of the ABAP class you defined in step 1.	ZCL_OL_PO_ADAPTER or /IQX/CL_FAB_ADPT (if FAB task)
Subcomponent	The name of the method to be executed	SYNC_ACTIONS
Short Description	Short description of the job	Synchronize adapter task actions to OneList
Freq. In Mins	Job execution frequency in minutes	2

SYNC_ATTACHMENTS

*Field Name*	Description	Example
Job Type	Must be the JobName you specified when configuring table /IQX/OL_TASK_DEF	PO_APPROVAL or FAB Form Name
Class	The name of the ABAP class you defined in step 1.	ZCL_OL_PO_ADAPTER or /IQX/CL_FAB_ADPT (if FAB task)
Subcomponent	The name of the method to be executed	SYNC_ATTACHMENTS
Short Description	Short description of the job	Synchronize attachments to OneList
Freq. In Mins	Job execution frequency in minutes	2

SYNC_CHANGED_TASK

*Field Name*	Description	Example
Job Type	Must be the JobName you specified when configuring table /IQX/OL_TASK_DEF	PO_APPROVAL or FAB Form Name
Class	The name of the ABAP class you defined in step 1.	ZCL_OL_PO_ADAPTER or /IQX/CL_FAB_ADPT (if FAB task)
Subcomponent	The name of the method to be executed	SYNC_CHANGED_TASK
Short Description	Short description of the job	Synchronize the changed task list to OneList
Freq. In Mins	Job execution frequency in minutes	2

SYNC_DELTA_TASK_LIST

*Field Name*	Description	Example
Job Type	Must be the JobName you specified when configuring table /IQX/OL_TASK_DEF	PO_APPROVAL or FAB Form Name
Class	The name of the ABAP class you defined in step 1.	ZCL_OL_PO_ADAPTER or /IQX/CL_FAB_ADPT (if FAB task)
Subcomponent	The name of the method to be executed	SYNC_DELTA_TASK_LIST
Short Description	Short description of the job	Synchronize detailed task list to OneList (delta tasks)
Freq. In Mins	Job execution frequency in minutes	2

*Table Name*	/IQX/OL_ENDPOINT
Description	Configures the connection to the OneList server

*Field Name*	Description	Example
OneList U RL	Specify the OneList base URL	https://iqx.onelistapprovals.com
OneList Server App Path	Specify the path of the API endpoint	/onelistserver/api/DataSync
SSL Client Identity	The type of SSL client	ANONYM
API Key	The key used to authenticate with the OneList APIs.	Refer to "Retrieve API Key in OneList" below for detail.
Active	Whether this connection is active	Checked

5. Define a Scheduler background job via SM36 by following the steps below:

Enter the Job Name - ONELIST_SCHEDULER
Enter the Job Class - B
Press the Step button
Enter the User - e.g. OL_ADMIN (Note: This should be a service user account created for background jobs)
Enter the ABAP Program Name - /IQX/ONELIST_JOBS
Press the Save button
Press the Start conditions button
Press the Date/Time button and enter the scheduled start date and time
Press the Period Values button and choose Other period from the options
Enter 1 in the Minute(s) field

Press the Save button to complete the setup

Background jobs are usually created by the Basis resource and should be set up to use the existing service user account

Once the OneList Scheduler background job has been created, it will automatically schedule the OneList Adapter jobs defined in the /IQX/OL_JOB_DEF maintenance table (as per entries created in step 4 above).
A suggested schedule for background jobs:

Sub Component	Frequency
SYNC_ACTIONS	Every 2 minutes
SYNC_ATTACHMENTS	Every 2 minutes
SYNC_DELTA_TASK_LIST	Every 2 minutes
SYNC_CHANGED_TASK_LIST	Every 2 minutes
SYNC_USER	Every 5 minutes

Redefine method – GET_OBJECT_DETAILS

This method is executed in the implementation class whenever the SAP object details are requested from OneList.
In this method, you can define the ABAP logic to retrieve the required details from the SAP object that needs to be passed to OneList.

Method Parameters

Parameter Type	Parameter Name	Description	Data Type
Importing	IT_TASK_ID	OneList Task ID being actioned (SAP workflow work item ID)	TT_OL_TASK_ID
Exporting	ET_OBJ_DETAIL	Table of object details	/IQX/OL_TASK_DETAIL_TT
Exception	/IQX/CX_ONELIST_ADAPTER	Raised exception during adapter execution

Method Implementation

Custom ABAP logic can be implemented using the import parameters sent by OneList to retrieve the SAP object details that can be sent back to OneList using the export parameter.
The export parameter ET_OBJ_DETAIL is a table of type /IQX/OL_TASK_DETAIL_ST with the following structure:

Component	Type	Length	Description
TASK_TYPE	CHAR	50	The Job Type defined in the /IQX/OL_JOB_DEF table
ASSIGNEES	TABLE		Number of users processing one or more objects
TASK_ID	CHAR	50	The FAB Form Instance Id or SAP WorkItem ID
TITLE	STRING		Title
OBJECT_TYPE	CHAR	50	SAP business object type
OBJECT_ID	CHAR	100	SAP business object Id
REQUESTOR	STRING		Requestor Name
REQUESTED_DATE	DATS	8	Requested Date
DUE_DATE	DATS	8	Due Date
PRIORITY	CHAR	25	Priority
ORIGINAL_ASSIGNEE	CHAR	12	User Name of Original Assignee
STATUS	CHAR	25	Status
ACTIONS	TABLE		Enabled task actions
DOCUMENTS	TABLE		Links to attachments
JSON	STRING		Task detail in JSON format

An example of the ABAP code that can be implemented to retrieve Purchase Order details based on the work item number sent by OneList:
METHOD get_object_details.
CONSTANTS: lc_classname TYPE swr_obj_2-typeid VALUE 'BUS2012',
lc_catid TYPE swr_obj_2-catid VALUE 'BO'.
DATA: ld_return_code TYPE sy-subrc,
lw_leading_object_2 TYPE swr_obj_2,
lt_objects_2 TYPE STANDARD TABLE OF swr_obj_2,
ls_po_object TYPE /iqx/ol_task_detail_st,
ls_po_detail TYPE /iqx/ol_purchase_order_st,
ld_wi_number TYPE sww_wiid,
ld_po_number TYPE bapiekko-po_number,
ld_oid TYPE os_guid,
ld_objkey TYPE swotobjid-objkey,
ld_classname TYPE bapibds01-classname,
ld_classtype TYPE bapibds01-classtype,
ld_username TYPE username,
ls_address TYPE bapiaddr3,
lt_return TYPE STANDARD TABLE OF bapiret2.
"Work item number
ld_wi_number = it_task_id.
"Get object attached to WorkItem
CALL FUNCTION 'SAP_WAPI_GET_OBJECTS'
EXPORTING
workitem_id = ld_wi_number
IMPORTING
return_code = ld_return_code
leading_object_2 = lw_leading_object_2
TABLES
objects_2 = lt_objects_2.
IF lw_leading_object_2 IS INITIAL.
IF lines( lt_objects_2 ) > 0.
DELETE lt_objects_2 WHERE catid <> lc_catid.
READ TABLE lt_objects_2 INTO lw_leading_object_2 WITH KEY catid = lc_catid.
ENDIF.
ENDIF.
CHECK lw_leading_object_2 IS NOT INITIAL.
ld_po_number = lw_leading_object_2.
"Get PO detail
ls_po_detail = me->get_po_detail( id_po_number = ld_po_number ).
"Only carry on IF PO details having data.
CHECK ls_po_detail IS NOT INITIAL.
"Get task header
ls_po_object = me->get_task_header( id_wi_number = ld_wi_number ).
"Set object Id
ls_po_object-object_type = lw_leading_object_2-typeid.
ls_po_object-object_id = lw_leading_object_2-instid.
"Get requestor
IF ls_po_detail-created_by IS NOT INITIAL.
ld_username = ls_po_detail-created_by.
CALL FUNCTION 'BAPI_USER_GET_DETAIL'
EXPORTING
username = ld_username
IMPORTING
address = ls_address
TABLES
return = lt_return.
READ TABLE lt_return WITH KEY type = 'E' BINARY SEARCH TRANSPORTING NO FIELDS.
IF sy-subrc <> 0.
CONCATENATE ls_address-firstname ls_address-lastname INTO ls_po_object-requestor SEPARATED BY space.
ENDIF.
ENDIF.
"Serialize po detail to JSON string
ls_po_object-json = /iqx/cl_onelist_json_util=>data_to_json( ia_data = ls_po_detail ).
"Get PO action
ls_po_object-actions = me->get_po_action( ).
"Get PO document attachments
ld_objkey = ld_po_number.
ld_classname = lc_classname.
ld_classtype = lc_catid.
ls_po_object-documents = me->get_bds_documents( id_classname = ld_classname id_classtype = ld_classtype id_objkey = ld_objkey ).
"Return detail object
et_obj_detail = ls_po_object.
ENDMETHOD.
The object detail retrieved from SAP should be serialized into a JSON string which gets passed to OneList. It is important that the OneList configuration is set up to consume and de-serialize the JSON structure accordingly.

Redefine method – GET_ATTCHMENT_CONTENT

This method is executed in the implementation class to retrieve the attachment content from the SAP object and return it back to OneList, allowing the user to see a list of attachments and to preview their content.

Method Parameters

Type	Name	Description
Importing	ID_DOC_ID	IQX - OneList Document ID structure
Returning	RD_DOC_CONTENT	IQX - OneList Document content structure

/IQX/ONELIST_DOCUMENT_ST (used for ID_DOC_ID)

Component	Type	Length	Description
DOC_ID	CHAR	50	IQX - OneList Attachment ID
SOURCE	CHAR	3	IQX - OneList Document source

Structure /IQX/ONELIST_DOC_CONTENT_ST (used for RD_DOC_CONTENT)

Component	Type	Length	Description
DOC_ID	CHAR	50	IQX - OneList Attachment ID
CONTENT	STRING		Plain text for Binary in BASE64 format
ERROR_MESSAGE	STRING		Error message - if any

Method Implementation

Custom ABAP logic can be implemented to retrieve the attachment content for the SAP document.
The default method GET_BDS_DOCUMENT_CONTENT from the base class can be called in the implementation:
METHOD get_attchment_content.
rd_doc_content = me->get_bds_document_content( id_doc_id = id_doc_id ).
ENDMETHOD.

Redefine method – EXECUTE_ACTION

This method is executed in the implementation class whenever an action is triggered on a decision task by the user in OneList.
The actions are configured in OneList and can be used to represent approval decision made by the user for a specific task for example Approve, Reject, Return, etc.

Method Parameters

Type	Name	Description
Importing	ID_TASK_ID	OneList Task ID being actioned (SAP workflow work item ID)
Importing	ID_ACTION_BY	User Name that triggered the action
Importing	ID_ACTION_ID	OneList Action ID
Importing	ID_ACTION_COMMENT	Action comment entered by the user in OneList
Importing	ID_OBJECT_ID	The object ID of the workflow task (generally, the SAP document number being actioned)
Exception	FAILED_TO_ACTION	Raised exception when the action could not be executed

Method Implementation

Custom ABAP logic can be implemented using the import parameters sent by OneList to execute the desired action outcome in SAP.
As an example, the Release and Reject actions for a Purchase Order approval can be implemented as follow:
METHOD execute_action.
DATA: lo_api TYPE REF TO cl_gbapp_apv_po_api.
DATA: lt_approval_decision TYPE gbappt_po_approval_decision,
ls_approval_decision TYPE LINE OF gbappt_po_approval_decision,
ls_parameter TYPE LINE OF /iwbep/t_mgw_name_value_pair,
lt_parameter TYPE /iwbep/t_mgw_name_value_pair,
ls_action_result TYPE gbapps_action_result.
DATA: ld_po_number TYPE bapimmpara-po_number,
ld_rel_code TYPE bapimmpara-po_rel_cod.
ld_po_number = id_object_id.
ld_rel_code = me->get_po_rel_code( id_po_number = ld_po_number ).
lo_api = cl_gbapp_apv_po_api=>get_instance( ).
CHECK ld_rel_code IS NOT INITIAL.
CLEAR ls_approval_decision.
CLEAR lt_approval_decision.
ls_approval_decision-workitem_id = id_task_id.
CASE id_action_id.
WHEN 'RELEASE'.
ls_approval_decision-decision = '0001'.
ls_approval_decision-approval_text = id_action_comment.
WHEN 'REJECT'.
ls_approval_decision-decision = '0002'.
ls_approval_decision-rejection_text = id_action_comment.
ENDCASE.
APPEND ls_approval_decision TO lt_approval_decision.
TRY.
lo_api->set_decision( EXPORTING it_approval_decision = lt_approval_decision
IMPORTING es_action_result = ls_action_result ).
CATCH /iwbep/cx_mgw_busi_exception .
RAISE failed_to_action.
ENDTRY.
ENDMETHOD.

Configure AppBuilder for SAP Fiori (FAB) for OneList integration

To integrate FAB tasks into OneList, it is possible to configure the OneList layout directly in the FAB workbench.

Summary Task layout

In the workbench, right-click on the project structure and add a One-List Workflow Task to the project definition.
Add a Group under the OneList Workflow Task and give this an ID of TOP. The title of this group is the Task Title in OneList. This can be bound to the data model as illustrated below:

Figure 2 – OneList Task Title configured in FAB - showing ProjectName mapped from the data model
Below the Task title, insert Summary lines for additional information to display at the top level by mapping data model fields, or combinations of fields.

Additional Contextual Task Information

Additional Groups of information can be appended below the TOP (Summary task title) in a recursive manner. Each group has optional summary lines and detailed data elements.

Figure 3 - Summary Task layout line configured in FAB – showing CapexTypeCode from the data model
This data structure conforms to the OneList task layout format (sections) described further below.

IQX OneList Documentation

Deploy and configure SAP adapter

Deploy SAP adapter

Configure SAP adapter

Redefine method – GET_OBJECT_DETAILS

Method Parameters

Method Implementation

Redefine method – GET_ATTCHMENT_CONTENT

Method Parameters

Method Implementation

Redefine method – EXECUTE_ACTION

Method Parameters

Method Implementation

Configure AppBuilder for SAP Fiori (FAB) for OneList integration

Summary Task layout

Additional Contextual Task Information

*Table Name*	/IQX/OL_JOB_DEF
Description	Defines the Background Job Parameters