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

Preface

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.

Introduction

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">
   <soap:Body>
      <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>
      </PostNewhireRecordResponse>
   </soap:Body>
</soap:Envelope>

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

     <!-- 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)" />		
        </xsl:with-param>
      </xsl:call-template>
     

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 –

<UserArea>
	<!-- Process to Start -->
	<xpresshr:CustomField name="Process" value="My_Onboarding_Process"/>
</UserArea>

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 –

<UserArea>
	<!-- 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"/>
</UserArea>

A custom Process with custom Elements would look like –

<UserArea>
	<!-- 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"/>
</UserArea>

Summary

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.