Skip to Content

This blog explains how you can create or update an employee in Employee Central using OData APIs. To keep it simple, I will create an Employee with minimum possible fields.

The graphic below outlines the different Employee Central entities needed for employee creation, along with the corresponding minimal fields per entity, which are listed directly under the entity name.

Capture.PNG

The order in which you create the required minimum entities is critical. It should be in following order: User -> PerPerson -> EmpEmployment -> EmpJob -> PerPersonal as listed in graphic above.

The following table links the UI portlets with the respective OData entities.

UI name

OData Name

N/A

User

Biographical Information

PerPerson

Employment Details

EmpEmployment

Job Information

EmpJob

Personal Information

PerPersonal

For this example I am using Advanced Rest Client Application, which can be installed as a chrome extension/app. This application provides an easy way to call the OData API. Once you have installed this app, you have to perform following basic steps before executing any OData query:


1. In the top URL text box provide your OData url in the following format:

https://<SF URL>/odata/v2/upsert, you can find further information about your ODATA API endpoint here: About HCM Suite OData APIs – SAP Library.

2. For this example we will use the basic authorization, in order to use the basic authorization you have to use following format:

Authorization: Basic <Base 64 encoded (“user@company:password”)>, for example, please refer to the graphic below:

RestClient.PNG

In the next steps, I will provide the ODATA request for all the entities to create an employee. You can use these examples directly or extend it as per your requirement in order to create an employee in EC.To see the ODATA data dictionary for your company instance, please goto Admin Tools->OData API Data Dictionary.

1. User: After doing the above mentioned steps you can directly start with creation of user entity, by entering the following details in the payload section of Rest client

{

“__metadata”: {

“uri”: “User(‘mhoff’)”

},

“username”: “markushoff”,

    “status”: “Active”,

    “userId”: “mhoff”

  }}

If the user is successfully created you should get a response back with the status OK and editstaus as INSERTED or UPSERTED, this behaviour will remain same for all the entities.


2. PerPerson

Similarly to user creation you can create perPerson by entering the following minimum details:

{

“__metadata”: {

“uri”: “PerPerson(‘mhoff’)”

},

“personIdExternal”: “hoffmarkus”,

“userId”: “mhoff”

}}

3.EmpEmployment
The next step will be to create EmpEmployement, here you need to enter the start date, userID and PersonIDExternal

{“__metadata”: {

“uri”: “EmpEmployment(personIdExternal=’hoffmarkus’,userId=’mhoff’)”

},

“startDate”:”/Date(1388534400000)/”,

“personIdExternal”:”hoffmarkus”,

“userId”:”mhoff”

}}

Note: PerPerson will only appear in query after EmpEmployement is created

4. EmpJob: For creating EmpJob you will execute the following request, please note that fields below may change based on your own data-model configuration:

{“__metadata”: {

“uri”: “EmpJob”

},

“jobCode”:”ADMIN-1″,

“userId”:”mhoff”,

“startDate”:”/Date(1388534400000)/”,

“eventReason”:”HIRNEW”,

“company”:”ACE_USA”,

“businessUnit”:”ACE_CORP”,

“managerId”:”NO_MANAGER”

}

}


5. PerPersonal: For creating the PerPersonal one needs following information:

{ “__metadata”:{

“uri”:”PerPersonal(personIdExternal=’hoffmarkus’,startDate=datetime’2014-01-01T00:00:00′)”},

“personIdExternal”:”hoffmarkus”,

“gender”:”M”,

“firstName”:”Markus”,

“lastName”:”Hoff”

}

After successfuly calling the APIS for all the entities, you should be able to see the employee directly in the EC UI portlets.

In case if you need further information regarding ODATA, please refer to these resources:

ODATA Basics: http://www.odata.org/

HCM Suite APIS:  http://help.sap.com/hr_api

Looking forward to your questions and feedback in the comments section.

To report this post you need to login first.

27 Comments

You must be Logged on to comment or reply to a post.

  1. Brandon Toombs

    Great blog Naresh!  Full of useful information.  I used my favorite REST chrome extension (postman) and was able to follow your steps successfully.  Keep the blogs coming!

    (0) 
    1. Naresh Purohit Post author

      Hi Bradon,

      I am glad that you liked the blog and were able to use it directly. I just installed postman, looks like a cool extension :-),

      Best regards,

      Naresh

      (0) 
  2. Amit Tomar

    Great work Naresh – I was looking for something like this… will try it out and post my comments later.

    Is there any blog which has the consolidated list for pre-requisities before we can try the exercise in this blog.

    Cheers – Amit/-

    (0) 
    1. Naresh Purohit Post author

      Hi Amit,

      Glad that you liked the blog. As a pre-requisite you will need an EC Instance and an user with all the RBP permission to do a new hire and execute ODATA calls.

      Best regards,

      Naresh

      (0) 
  3. Alexa MacDonald

    Great information. When I added my user, I needed the following information for step 5 in my payload information:

    “namePrefix”

    and

    “initials”

    (0) 
  4. Bhargav Gogineni

    Great blog Naresh.

    We have employed similar workflow in one of my projects with few variations.

    In our case we have to use System AUTO generated NEXT userId. From release b1505 SAP released new API to fetch next UserId from system. In our case it was AUTO generated numeric value.

    Here are API details:

    ***********************

    https://api8.successfactors.com:443/odata/v2/generateNextPersonID

    It is Post method and below is sample response.

    Response back from request:

    {
    “d”:

    { “GenerateNextPersonIDResponse”: { “personID”:”80004203″ }

    }
    }

    Thanks,

    Bhargav

    (0) 
  5. Vishesh Agrawal

    Hi Naresh,

    I was trying to follow your steps but somehow it is not working.

    when i do a post to the SF i do not get any response back not even a faliure.

    Can you suggest.?

    Thanks ,

    Vishesh.

    (0) 
    1. Naresh Purohit Post author

      HI Vishesh,

      Did you check the ODATA  api audit log? Also what is the url you are using, please make sure that you use API server URL.

      Thanks,

      Naresh

      (0) 
    1. Naresh Purohit Post author

      HI Luke,

      Thanks a lot for mentioning this, yes, our guides are improving very well, will be great to have further feedback/comments on the documentation.

      Best regards,

      Naresh

      (0) 
  6. Jacques-Antoine Ollier

    Thank you for this very nice blog.

    Actually you are more precise than the official documentation that presents examples of POST request not even working.

    This is very precious info! 5 stars.

    Thank you for sharing.

    Best regards.

    Jacques-Antoine Ollier

    (0) 
  7. Carlos Dias

    Hello Naresh,

    thanks a lot for your blog. I’m looking for a way to delete Cost Centers. In the API Data Dictionary in EC says the operation is supported but I’m not able to find documentation explaining how to perform a delete.

    Do you have any documentation or guideline to do this?

    Thanks a lot!

    (0) 
    1. Naresh Purohit Post author

      Hi Syed,

       

      You can trigger rules for job info, personal info, compensation entities and termination. Workflow can be trigerred for job and termination. Workflow will not be trigerred for new hire use case.

      Please refer to imports guide for more details.

       

      Thanks,

      Naresh

      (0) 
      1. John Simonidis

        Naresh,

        We are making an API call from a FIORI service to create an EmpJob record changing the employees working hours, e.g. below:

        The record is being created correctly, however the workflow is not triggered. We have looked at the import guide and enabled RBP for import however the workflow is still not triggering. Are you able to provide any further guidance on how to enable triggering of workflow.

        When I create the record through the UI the record triggers as expected.

        Example:

        https://api10.successfactors.com/odata/v2/upsert?$format=json

        {“__metadata” : { “uri” : “EmpJob”},

        “startDate”: “/Date(1501545600000)/”,

        “userId”: “u008161”,

        “employmentType”:”2719″,

        “eventReason”:”CHGHOURS” ,

        “workscheduleCode” : “0003”,

        “workingDaysPerWeek”: “4”
        }

         

        Thanks,

         

        John

         

        (0) 
        1. Naresh Purohit Post author

          Hi John,

           

          If you have enabled rules and workflow in RBP(for imports), ideally it should trigger workflow. Please note that workflow is created only for incremental update and not created in case of new hire case.

          Thanks,

          Naresh

          (0) 
  8. Andreas Ebler

    Hi Naresh,

    thanks a lot for the blog.

    I tried it with our Successfactors Instance but always get this error:

    Request:

    https://xxx.successfactors.com/odata/v2/generateNextPersonID

     

    Response:

    <?xml version=”1.0″ encoding=”utf-8″?><error xmlns=”http://schemas.microsoft.com/ado/2007/08/dataservices/metadata”><code>MethodNotAllowedException</code><message lang=”en-US”>Method Not Allowed</message></error>

    Do we have to change something in the Successfactors configuration?

    Any ideas?

     

    Regards

    Andreas

     

     

     

     

    (0) 
  9. Florian Wilhelm

    Hello Naresh,

    thanks for your post. For me who did never before something with SF, this is quite helpful. I have one suggestion: Could you put the code snippets in code blocks? As is, I can’t just copy and paste the JSON snippets because there are typographic quotes instead of the required quote characters.

    This would also make the post easier to read.

    Best regards,

    Florian

    (0) 

Leave a Reply