Skip to Content
Author's profile photo Naresh Purohit

How to create an Employee using OData APIs

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.

Assigned Tags

      39 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Former Member
      Former Member

      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!

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog 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

      Author's profile photo Former Member
      Former Member

      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/-

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog 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

      Author's profile photo Former Member
      Former Member

      That's nice. I have done this with Boomi and this is good alternate way.

      Author's profile photo Klemens Schmid
      Klemens Schmid

      Can I also create all entities at once with one request?

      Author's profile photo Bhargav Gogineni
      Bhargav Gogineni

      As far I know we cannot do it.

      -Bhargav

      Author's profile photo Alexa MacDonald
      Alexa MacDonald

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

      "namePrefix"

      and

      "initials"

      Author's profile photo Bhargav Gogineni
      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

      Author's profile photo Gurpreet Walia
      Gurpreet Walia

      Great Blog Naresh!! Thanks for sharing

      Author's profile photo Vishesh Agrawal
      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.

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog 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

      Author's profile photo Vishesh Agrawal
      Vishesh Agrawal

      Hi Naresh,

      Thanks actually it was because was wrong URL. It started to work fine thanks.

      Thanks ,

      Vishesh.

      Author's profile photo Luke Marson
      Luke Marson

      Good blog. These examples were taken directly from the EC OData API handbook at http://help.sap.com/hr_ecintegration, where you can get more information

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog 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

      Author's profile photo Naga Swathi TJ
      Naga Swathi TJ

      very useful and nicely explained. Thanks Naresh for sharing this

      Author's profile photo Jacques-Antoine Ollier
      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

      Author's profile photo Former Member
      Former Member

      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!

      Author's profile photo Former Member
      Former Member

      Hi Naresh,

       Can we trigger business rule and workflow when we are creating employee via Odata API??

       

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog 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

      Author's profile photo John Simonidis
      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

       

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog 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

      Author's profile photo Andreas Ebler
      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

       

       

       

       

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog Post Author

      Are you  trying with post?

      Author's profile photo Former Member
      Former Member

      HI ,

      How to decode the dz Date Format.

      ”/Date(1388534400000)/”,

       

      Regards,

      Venkat

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog Post Author

      you can use any timestamp/epoch converter. for example: https://www.epochconverter.com/

      Author's profile photo Florian Wilhelm
      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

      Author's profile photo Jay Malla
      Jay Malla

      Hi Naresh,

      Excellent blog!

      Do you have any details on how to replace/delete information for employees?  Basically, I am able to create the employee in the system and also terminate them.  Now I need to change the start and end date.

      I am trying to replace the EmpEmployment information which has a start date - But I get the error "Start date cannot be greater than end date".  I am trying to change the employee start and end date to be later on - but I think the end date for the existing record does not like the new start date in the future that I am passing.

      I have created a question.  It would be great if you can take a look.

      SuccessFactors OData API purgeType=full not working. How to replace EmpEmployment/EmpJob entities

      Thanks,

      Jay

      Author's profile photo Pankaj Roushan
      Pankaj Roushan

      Hi Naresh,

      I am trying to post the request but always get below error. Have tried with different values but doesn't work. Can you please suggest what is wrong here?

      -------------------------------------------

      Request:

      { "__metadata": {
      "uri": "User(‘207798’)"
      },

      "username": "Test207798",
      "status": "Active",
      "userId": "207798"

      }


      Response

      {
      "d": [
      {
      "key": null,
      "status": "ERROR",
      "editStatus": "UPSERTED",
      "message": "bad valueString [‘207798’] as part of keyString [‘207798’]",
      "index": 0,
      "httpCode": 400,
      "inlineResults": null
      }
      ]
      }

       

      Thanks,

      Pankaj

      Author's profile photo Venkat Krishnah Togara
      Venkat Krishnah Togara

      Great Info

      Author's profile photo Godson Dabre
      Godson Dabre

      Hi Naresh,

       

      How can i fetch employee details like userId, name,phone,jobTitle and Photo(most important) via odata api in successfactors

       

      Regards,

      Godson

      Author's profile photo Regie Lucasan
      Regie Lucasan

      Hi Naresh,

       

      I followed the sequence of the entities, Everything gets upserted successfully.

      However, the data does not reflect in the Job Information Portlet.

      I tried to query the EmpJob, the Job data I upserted is present.

      Can you give me some clues on what caused this issue ?

       

      Thanks,

      Regie

      Author's profile photo Patricio Quintana
      Patricio Quintana

      Dear experts
      We are trying to put an employee as a draft from a third party system, could you share which API we need use for this odata or protocol?
      Many thanks in advance

      Author's profile photo Veronica Lorenzo
      Veronica Lorenzo

      Hello Patricio.

      Did you find the API?

       

      Author's profile photo Manuel da Silva Santos Gomes Ferreira
      Manuel da Silva Santos Gomes Ferreira

      Hi guys,

       

      Have you found any way to create an employee as a draft?

      Author's profile photo JONAS COSTA
      JONAS COSTA

      I have the same problem.

      Didi you solve this?

      Can you share your solution, please?

      Author's profile photo Manuel da Silva Santos Gomes Ferreira
      Manuel da Silva Santos Gomes Ferreira

      Hi guys,

       

      Have you found any way to create an employee as a draft?

      Author's profile photo JONAS COSTA
      JONAS COSTA

      Hi @Naresh,

       

      Thanks for this post.

      But, it's possible to use this same logic to integration a hire information of third part system to Employee Central on Manage Pending Hire window?

      Or integrate only user informations to Employee Central and complete the register of new hire with business informations on Employee Central Profile?

       

      Regards.

      Author's profile photo Naresh Purohit
      Naresh Purohit
      Blog Post Author

      Hi Jonas,

       

      I do not think we have API for manage pending hire. Please check the API guide for the list of all the APIs.

       

      Thanks,

      Naresh