PI REST Adapter – SFSF LMS Integration (OData V4)
We had a requirement to bring in SFSF LMS “Learning Approvals” into SAP HCM and to be able to approve or reject these items from SAP. Although SFSF LMS exposes various entities as OData V4 APIs, when trying to integrate with SAP HCM there were a few questions on the approach:
- Which PI adapter to use – SFSF, OData or REST ?
- How to convert JSON to XML (for processing in PI) and vice versa ?
- How to generate the required XSDs for LMS APIs (for use in mapping)?
A quick search on both PI/PO and Successfactors communities reveals that there has been a lot of work already done covering integration scenarios for SF Bizx, EC and SF LMS (standard SAP delivered content or earlier version of LMS APIs). There is very little information that we could find on how to integrate the latest SFSF OData V4 LMS APIs using SAP PI.
We realised that the best way to answer these questions was to start a POC.
I started off with the NW PI Connectivity add-on 1.0 “SFSF Adapter” and “OData Adapter”. While this is a good starting point, soon I found that there are limitations on how these adapters can be used to consume SFSF LMS APIs. There are many discussions on the SFSF LMS forums on the issues faced in consuming LMS OData V4 using PI/PO.
After going through various “PI REST Adapter” blogs, SAP documentation and looking at the generic nature of the adapter, I decided to give the REST Adapter a try.
The second question, how do we convert the JSON to XML and vice versa? Again there are some wonderful blogs stating how this can be done by using:
- Standard REST Adapter JSON converter or
- Custom module developed by Eng Swee Yeoh
Finally, Creating XSD for the SFSF LMS APIs to carry out the required mapping in PI. The plan was to use Eclipse (Mars) “Modelling operations” to generate the XSDs but again looking at the options available, this was not possible for SFSF LMS APIs.
Eg: When using Successfactors adapter with REST or OdataV4 protocols the “Modelling operation” option is not available and with OData V2 protocol “Modelling operation” does not allow authentication using the SFSF LMS “Client Secret”.
This required a bit more investigation to come up with a set of repeatable steps to generate XSD and which could be potentially applied on other scenarios. The guide will cover the steps I used during this POC.
To implement the end-to-end process described above, we will need to create 3 flows:
- First to get the user OAuth token,
- Second use the OAuth token to retrieve the “Learning Approval” items for the user and
- Finally use these items to approve or reject in SFSF LMS from SAP.
This guide will focus on how the second flow is implemented to retrieve “Learning Approval” items from SFSF LMS. Other flows are implemented in similar way but are not covered in this document.
LMS API Used: GET /learning/odatav4/public/user/user-service/v1/learningapprovals
PI Version used for this POC was 7.31 SP 12 (Single stack)
How to generate XSD for SFSF LMS Entities?
Step 1: Using SOAP UI or any other REST client, get the request or response JSON from SFSF LMS
Step 2: Use an online tool to convert JSON to XML. Click here to find out the tool I used.
Step 3: In the generated xml file:
- After the tag, create a and end the file with . An XML file cannot have multiple root nodes.
- Remove any special symbols (eg: @).
- The resultant XML will look like the following
Step 6: Upload and validate the XSD in ESR as External Definition (ED_LearningApproval) for Response.
HINT: Use “root” Message for SI, MM and OM.
Step 7: Repeat the above steps to create the external definition for handling “Requests”. In this flow, we only require an empty XSD to pass the OAuth Token. See ESR steps for more details.
Step 1: Create new Data Type and Message Type for both Request and Response as required in the Sender system (SAP HCM).
Request : DT_LearningApprovalRequest, MT_LearningApprovalRequest.
Response : DT_LearningApprovalResponse, MT_LearningApprovalResponse.
Step 2: Create the Outbound and Inbound Service Interfaces (Synchronous)
NOTE: The request External Message is a Dummy XSD with message name “root”. Not to confuse with the Response External message name which also has a message name “root”? – Should have named it differently !
Step 3: Complete the Message Mapping for both request and response.
Request: MT_LearningApprovalRequest to External Definition (empty)
NOTE: In this particular scenario we are going to use the Request mapping to take the OAuth Token to the REST Adapter HTTP Header (Generated in the first flow).
OR Dynamic Configuration could be used to pass Adapter specific values. Choice is yours.
Response: ED_LearningApproval to MT_LearningApprovalResponse
Step 4: Complete “Operation Mapping” connecting both Source and Target Operations
Moving on to Integration Builder, we will first configure the channels and use standard REST Adapter JSON to XML conversion.
This will be a normal SOAP adapter to the SAP HCM box.
Following shows the REST Adapter configurations.
The “oauth_token” is taken from mapping following XPath and then passed through the HTTP Headers.
There are two options to handle the payload conversion, One could choose between the “Standard REST Adapter” JSON to XML conversion as shown here
OR use the custom module (Custom_AF_Modules/FormatConversionBean) for JSON2XML conversion.
Both options work fine.
Leave the module configuration as default for the standard JSON to XML conversion.
Running the Scenario:
To run the interface, a test ABAP program was created which gets the “User ID” in selection screen and triggers two interface calls into SF LMS.
The initial call is to get the OAuth token and then the second call to retrieve any pending “Approval items” from SF LMS by passing the received OAuth token.
By clicking the “Tap ID” the user will be given option to “Approve” or “Deny” and respective APIs are called(which is the third flow).
The final implementation will be looking at creating SAP Workitems and pushing it to a custom mobile approval app, which is currently used at our site.
Following shows the request/response log and also shows the JSON to XML conversion of payload using the standard REST Adapter:
Payload: Before conversion
Payload: After conversion
I hope the above approach or parts of it will be useful as a guide to integrate SFSF LMS APIs (OData V4) using SAP PI REST Adapter.
SAP NetWeaver Process Integration, connectivity add-on 1.0 SP01
Learning OData API Reference
PI REST Adapter – Blog Overview
OData Adapter and SFSF Adapter (extensions) for SAP Process Integration
Successfactor (LMS) Integration with HCM system Using SAP PI
REST Adapter in PI/PO: Enhanced XML/JSON Conversion
JSONTransformBean Part 1: Converting JSON content to XML
Eclipse Modelling Operations
XML Schema Definition Tool (Xsd.exe)