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.

[Muji]

You are a great asset to the SAP integration community helping with your blogs, supporting teams internally and developers from partners and customers.

I always got support/answers from you when I needed it. Happy to work with you buddy.

[zebashah]

This was a much needed Blog !! Thank you Hammad .

[szas79]

Very nice effort Hammad... keep up the great work!!

[Jose_Aguirre]

Do you know if this api can locate file into a particular repository (like SAP Content server or Content Server Service from BTP ?

I don't want to save files into my SSFF system, I prefer those filesin another SAP repository. thanks in advance.

[dbtutor]

Hi,

I have written a blogpost that contains end to end details and automation of token via postman platform. If you are interested visit there ,

Postman to call SuccessFactors API using OAuth aut... - SAP Community

[PTecnico]

Hi.

I have issue for link the attachments to the MDF Entity

No permission to access the attached file XXXX. Attachment in field XXXX does not belong to the user XXXX" error

I am checking the note: https://me.sap.com/notes/0003353598/e

However the issue continue.

This is the resulted of the upsert for the entity Attachment

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/...">
    <entry>
        <content type="application/xml">
            <m:properties>
                <d:key>Attachment/attachmentId=13418</d:key>
                <d:status>OK</d:status>
                <d:editStatus>UPSERTED</d:editStatus>
                <d:message>Upserted successfully</d:message>
                <d:index m:type="Edm.Int32">0</d:index>
                <d:httpCode m:type="Edm.Int32">200</d:httpCode>
                <d:inlineResults m:type="Bag(SFOData.UpsertResult)"></d:inlineResults>
            </m:properties>
        </content>
    </entry>
</feed>

And this the resulted of try of link the attachment with the MDF.

{
    "__metadata": {
        "uri": "cust_MY_MDF"
    },
    "externalCode": "18116060",
     "externalName": "1035677899",
    "cust_Attachment_18Nav": {
        "__metadata": {
            "uri": "Attachment(attachmentId=13418)"
        }
    }
}

[rosaarroyo]

Hi! 

If my MDF have 3-4 attachment fields and I want to upload by API in single call the 3-4 attachments field, I can follow the same process? or is not supported and I have to make a single call for each attachment?