Get Even More Visitors To Your Blog, Upgrade To A Business Listing >>

How do you “Onboard” a NEWHIRE with SuccessFactors Onboarding?


So your organisation has decided to implement (or continue using) a COTS Recruitment solution (like Page Up or Taleo to give an example) to attract talent instead of implementing SuccessFactors Recruitment Management (RCM). Now a key challenge is to integrate it with SuccessFactors Onboarding (henceforth referred to as Onboarding) so that the Candidate’s required details can be onboarded into the organisation, and then sent to SuccessFactors Employee Central (EC) so that an Employee record can be created.


The Onboarding module is an addition to the SuccessFactors suite by means of acquisition. Like with many technology acquisitions although Onboarding and the greater SuccessFactors suite integrate well with one another functionally, however, given that the two products are built on completely different technology platforms with varied underlying architectures, it has left telltale differences in the integration framework, the UI and other functionality (such as import/export data, security etc.).

The lack of documentation poses another challenge when implementing Onboarding. Although having said the quality and richness has improved in leaps and bounds every quarter. For e.g. from there being no in built Data Dictionary in the system (like in EC for OData and SFAPI), and no guide on what the API signatures / schemas look like, to having an Onboarding and Offboarding API guide with API sample schemas feels like a quantum leap!

The APIs

There are several differences in the APIs used in Onboarding to those in EC. However, the key difference is that the constituting Elements are represented in a CDATA. CDATA is a collection of well pretty much anything – elements, pictures, bytes, words etc. The rules that apply to XML validation don’t apply to CDATA. Thus you can have elements here without a value (which may violate XML rules in your middleware where an element without a value is not permitted).

In this blog we will explore some of the features of the core API – PostNewhireRecord.

PostNewhireRecord API

Mandatory Parameters

It is important to note that the minimum elements that are required in a “skeleton schema” to successfully create an Onboarding record are the Candidate’s First Name and Last Name.

Although the payload has dedicated elements for First Name – – and Last Name – – the “actual” mandatory elements used by Onboarding are –

– note the embedded comments

– note the embedded comments 

You will get the below error message if either of these elements are missing from the payload (in the below example both and have been omitted) –

00000000-0000-0000-0000-000000000000203First Name is missing202Last Name is missing]]>

The best thing about the PostNewhireRecord API is that it is extremely elastic i.e. you can add any number of fields to it to suit your requirements.

Custom Elements need to be defined in Super Admin (similar to Provisioning for SuccessFactors) and then added to Custom Panels in XpressHR (this is the front end like BizX is for SuccessFactors Employee Central) and finally represented in the API.

Lets start with Super Admin first.

Super Admin

Once your business has narrowed in on a list of Custom Fields they want to see in Onboarding and your Functional Consultant has added these to the Panels the scene is all set for the Integration Consultant to enable them for use via the PostNewhireRecord API.
First of all the custom fields need to be added to an XSLT file in Super Admin. This file defines the data elements of the PostNewhireRecord API.
To add the custom fields to the XSLT file we you have to download it, then update it with the fields, and import it back into Super Admin again. To download the XSLT file click on the Account name under ONBPREM Accounts >> Import/Export Settings >> HRXML.ImportNewHire then select Export file and click on Submit. 
Open the XSLT file HRXML.ImportNewHire.XSLT in Notepad++ (or any other suitable XML editor). Add custom elements in the /hrxml/NewHire/UserArea/CustomField section using the below as an example –

Once you have added all the custom fields click on Import File >> Choose File >> Submit.

Note: with each version that you import you will see the Modification history getting built up.You can revert to an earlier version of the XSLT by clicking on Restore for a given version.
Now that we have seen how custom fields are updated in the XSLT in Super Admin, we shall look at the changes required in the API payload.


First of all the custom fields need to be added to the custom Panels of a custom Process. This is typically done by a Functional Consultant, who then provides the list of the custom fields to the Integration Consultant.

Custom Process

Why would a client want a custom defined Onboarding process?

A key reason could be because the standard Onboarding process is US centric (they represent USA specific taxation I-9 elements, veteran related information etc.) and is non-modifiable (like most standard SAP defined functionality). There are 2 ways to define a custom process –

  • One is to copy the standard wizard (aka Steps that constitute a Process) and modify the underlying panels.
  • The other (and easier) approach (imho) is to define your custom Process and Steps from the ground-up. You can import standard Panels into your custom Process (for e.g. country compliant Panels – like TFN, Superannuation for Australia).

The below XML snippet shows how a custom Process is represented by a name (Process) and value (My_Onboarding_Process) pair in the PostNewhireRecord payload –

Custom Elements

All the custom elements are represented by name and value pairs in the section  as illustrated in the XML snippet below –

A custom Process with custom Elements would look like –


As you have seen even though the schema may look daunting at the start, once you break it down into it’s constituting elements it becomes easier to manage.

A word of thanks to our Onboarding friends at SAP – Kumaran Purushothaman and Harsha Vernekar – for their continued help and support, without which neither an interface to Onboarding nor this blog would have been possible.

This post first appeared on Web Service Testing A Blackjack GUI And API, please read the originial post: here

Share the post

How do you “Onboard” a NEWHIRE with SuccessFactors Onboarding?


Subscribe to Web Service Testing A Blackjack Gui And Api

Get updates delivered right to your inbox!

Thank you for your subscription