Enterprise Resource Planning Blogs by Members
Gain new perspectives and knowledge about enterprise resource planning in blog posts from community members. Share your own comments and ERP insights today!
Showing results for 
Search instead for 
Did you mean: 
Product and Topic Expert
Product and Topic Expert

So your organisation has decided to implement (or continue using) a COTS Recruitment solution 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 is 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, there are telltale differences in the integration framework, the UI and other functionality (such as import/export of 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 (fields) are represented in a CDATA segment.

CDATA is a collection of - well pretty much anything - elements, pictures, bytes, words etc. The stricter 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 a mandatory element with a null value may 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 - <FirstName> - and Last Name - <LastName> - the “actual” mandatory elements used by Onboarding are –

<GivenName> - note the embedded comments <!– FirstName –>

<FamilyName> - note the embedded comments <!– LastName –>

You will get the below error message if either of these elements are missing from the payload (in the below example both <GivenName> and <FamilyName> have been omitted) –
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PostNewhireRecordResponse xmlns="http://ATS.online-onboarding.com/Client/HRDataServiceEx">
<PostNewhireRecordResult><![CDATA[<PostNewhireRecordResult><NewhireId>00000000-0000-0000-0000-000000000000</NewhireId><Errors><Error><ErrorCode>203</ErrorCode><ErrorDescription>First Name is missing</ErrorDescription></Error><Error><ErrorCode>202</ErrorCode><ErrorDescription>Last Name is missing</ErrorDescription></Error></Errors></PostNewhireRecordResult>]]></PostNewhireRecordResult>

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 elements 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 elements to the XSLT file we you have to download it, then update it with the elements, 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 –

     <!-- preferred_name -->	  
<xsl:call-template name="item">
<xsl:with-param name="key">preferred_name</xsl:with-param>
<xsl:with-param name="value">
<xsl:value-of select="normalize-space(/hrxml:NewHire/hrxml:UserArea/hrxml:CustomField/hrxml:preferred_name)" />

Once you have added all the custom elees 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.


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 –
<!-- Process to Start -->
<xpresshr:CustomField name="Process" value="My_Onboarding_Process"/>

Custom Elements

First of all the custom elements 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.

All the custom elements are represented by name and value pairs in the section <UserArea> as illustrated in the XML snippet below –
<!-- Custom Fields -->
<xpresshr:CustomField name="preferred_name" value="David Test"/>
<xpresshr:CustomField name="address1" value="some free text"/>
<xpresshr:CustomField name="address2" value="some more free text"/>
<xpresshr:CustomField name="cellular" value="1234567890"/>
<xpresshr:CustomField name="okToRehire" value="Yes"/>

A custom Process with custom Elements would look like –
<!-- Process to Start -->
<xpresshr:CustomField name="Process" value="My_Onboarding_Process"/>

<!-- Custom Fields -->
<xpresshr:CustomField name="preferred_name" value="David Test"/>
<xpresshr:CustomField name="address1" value="some free text"/>
<xpresshr:CustomField name="address2" value="some more free text"/>
<xpresshr:CustomField name="cellular" value="1234567890"/>
<xpresshr:CustomField name="okToRehire" value="Yes"/>


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 Former Member - for their continued help and support, without which neither an interface to Onboarding nor this blog would have been possible.
Labels in this area