Upload Attachments in SuccessFactors Using OData API and Integration Suite: A Step-by-Step Guide

[HammadSharif1]

Introduction

SAP SuccessFactors is a comprehensive Human Experience Management (HXM) software that offers a variety of operations to manage the HR processes efficiently. One of the critical parts of HR Management is dealing with the required attachments, this includes resumes, offer letters, confirmation letters, payslips, appraisal letters, tax certificates, etc. In this blog, I will walk you through the step-by-step process of uploading the attachments in the success factors system using OData API.

Pre-Requisites:

Below are the required prerequisites for this process,

1. Get access to your organization's Success Factors Instance.

2. Get the required Success Factors credentials for your organization instance along with the required roles for the OData API, if there is any existing OData API Integration user available, will do the job for you.

Reference Link: Permission Settings | SAP Help Portal

3. Identify the API URL, based on your success factors system data center, refer to the below SAP Note in this regard,

SAP Note Reference Link: https://me.sap.com/notes/0002215682.

4. Identify the entity in which attachments need to take place.

This blog contains two parts, first is how to upload the attachment in the success factors system, second is how to achieve it via Integration Suite.

Part A: Procedure of Uploading the Attachment in the Success Factors System
Below are the Steps for uploading the attachment in the Success Factors system,

Step 1:
Understand the Success Factors Attachment Entity as it serves as the main repository for all the attachments. You need to UPSERT the record in this entity first.

• 1.1 Create an Attachment Object in the Attachment Entity. It should include all the necessary fields for the request to be complete, below is the sample request payload for reference,

Request Payload:

{

    "__metadata": {

        "uri": "Attachment"

    },

    "fileName": "Resume.pdf",

    "module": "RECRUITING",

    "userId": "XXXXXXXX",

    "viewable": true,

    "fileContent": "XJD+VGnuc......DRHujHew4FX"

}​

 

• 1.2 Make a POST(or UPSERT if using Success Factors Adapter) operation to the Attachment entity's endpoint (e.g., `https://<sf-api-server>/odata/v2/Attachment`) with the payload you constructed in the previous step. This will create or update the attachment in the Success Factors Attachment Entity. For your reference, below is the response after a successful attempt, Response Payload:
  

  {
  
      "d": [
  
          {
  
              "key": "Attachment/attachmentId=ZZZ",
  
              "status": "OK",
  
              "editStatus": "UPSERTED",
  
              "message": "Upserted successfully",
  
              "index": 0,
  
              "httpCode": 200,
  
              "inlineResults": null
  
          }
  
      ]
  
  }​

  
  

 

Step 2: Upload Attachment to the Desired Entity

Once the attachment gets successfully upserted into the Attachment Entity, only then you can link it to the relevant entity as the attachment navigation property in an MDF entity doesn't allow you to inline edit attachments. To link an attachment to an MDF entity, you first create the attachment object with the Attachment entity and then link this object to the MDF entity.

• 2.1 Retrieve Attachment ID

Once the upserting gets successful to the Attachment Entity, you receive a new attachment ID in response, store this ID as it will be used in the next step.

• 2.2 Link Attachment to the Target Entity

Create a new entry or update an existing entry for the required MDF entity with the newly created attachment in the last step, below is the request payload for your reference,
Request Payload:

{

    "__metadata": {

        "uri": "cust_TestMDFObject"

    },

    "externalCode": "test entry 01",

    "effectiveStartDate": "/Date(1565222400000)/",

    "externalName": "Test MDF Entry 01",

    "cust_attachmentNav": {

        "__metadata": {

            "uri": "Attachment(ZZZL)"

        }

    }

}

 

Note: The same attachment ID is not allowed to be added to multiple objects, in case needed, upload it again create a new attachment ID and then Add.

 

Part B: Procedure of Uploading the Attachment in the Success Factors System via Cloud Integration of Integration Suite

Step 1: Doing it Practically via Integration Suite

Design Integration Flow as Below

Below are the steps to achieve the above-shown Integration scenario,

• 1.1 Receive the Incoming payload and Map it accordingly to the Attachment Entity


• 1.2 Request Payload would be as shown below,


• 1.3 From the Attachment Entity Successful Upsert, you will get the below response,


• 1.4 Now from the received response, the value of key is "Attachment/attachmentId=331236", and we need to split it from attachment ID value which is 331236. As it's coming with the concatenated entity and the field name which needs to be removed in order to link to our required portlet, for this split functionality is required. For splitting there are multiple ways to do it, I leave it to you.

• 1.5 In the final stage, we need to map our request with the Custom Entity Required Property as shown below,


• 1.6 The final success response, after sending the request to success factors main entity would be like as shown below,
  I have kept the specific entity name and response key intentionally private as this can vary depending on the specific scenario. For your reference, the structure of the key is shown below,
  
  ```key = entityName/externalCode=xxxxxxxx```This format will enable you in case any further processing is required.

 

 

Conclusion

In SAP Success Factors, uploading attachments via OData API seems too intricate but once you grasp the process, it becomes a valuable tool for managing HR-related documents. As per the above steps, it would be easy to analyze the whole process and design according to your needs efficiently in an organized manner.

Remember that SuccessFactors APIs may vary based on your specific requirement, so before starting any integration, put the majority of the time into making an effective and precise design. With the right knowledge and resources, the overall employee experience can be enhanced.