Preface

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

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

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.

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 –

<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 Harsha Vernekar – for their continued help and support, without which neither an interface to Onboarding nor this blog would have been possible.

To report this post you need to login first.

10 Comments

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

  1. Kaustubh Datta

    Great blog Arijit! I’m sure this will be useful to a number of customers who decide to continue to use their existing Recruitment solutions but integrate that with Onboarding.

    (1) 
  2. Hieu Tran Nguyen Trong

    Hi Arijit,

    I have a problem with the error code 203 and 202 even I passed the value of fields GivenName and FamilyName.

    Below is the sample test by SOAP UI.

    Request:

    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:hrd="http://ATS.online-onboarding.com/Client/HRDataServiceEx">
       <soap:Header>
          <hrd:CorrelationHeader>
             <!--Optional:-->
             <hrd:CorrelationId>?</hrd:CorrelationId>
             <!--Optional:-->
             <hrd:SourceEndpoint>?</hrd:SourceEndpoint>
          </hrd:CorrelationHeader>
       </soap:Header>
       <soap:Body>
          <hrd:PostNewhireRecord>
             <!--Optional:-->
             <hrd:Ticket>2cb64074-228c-4774-b480-dba00733adc9</hrd:Ticket>
             <!--Optional:-->
              <hrd:Data>
        <![CDATA[
        <NewhireRecord>
          <DictionarySerializer>
            <ns0:Dictionary xmlns:ns0="http://www.kmanage.com/xml/serialization">
              <item>
                <key>EmployeeId</key>
                <value>10000013</value>
              </item>
              <item>
                <key>FirstName</key>
                <value>ABC</value>
              </item>
              <item>
                <key>GivenName</key>
                <value>ABC</value>
              </item>
              <item>
                <key>PreferredGivenName</key>
                <value>ABC</value>
              </item>
              <item>
                <key>LastName</key>
                <value>XYZ</value>
              </item>
              <item>
                <key>FamilyName</key>
                <value>XYZ</value>
              </item>
              <item>
                <key>ExternalId</key>
                <value>10000013</value>
              </item>
            </ns0:Dictionary>
          </DictionarySerializer>
        </NewhireRecord>]]>
      </hrd:Data>
          </hrd:PostNewhireRecord>
       </soap:Body>
    </soap:Envelope>

    Response:

    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/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>

    Much appreciate if you can give me an advice.

    Thanks,

    Hieu

    (0) 
    1. Arijit Das Post author

      Hi Hieu

      The Request payload does not look right to me. Pls get the sample request from XpressHR or the Onboarding and Offboarding API guide. You may refer to the below sample XML (this works). 

      <hrd:Data><![CDATA[<?xml version="1.0"?><!-- Sample HR-XML newhire feed file for XpressHR -->
      									 <!-- Copyright (c) 2023 SAP AG or an SAP affiliate company. All rights reserved. -->
      <NewHire xmlns="http://ns.hr-xml.org/2007-04-15" xmlns:xpresshr="http://online-onboarding.com/Schemas/XpressHR-hrxml.xsd" xmlns:dc="http://purl.org/dc/elements/1.1/">
         <TypeOfHire>
      	  <StandardValue>NewHire</StandardValue>
      	  <!-- value of this element must be NewHire -->
         </TypeOfHire>
      
         <EmployeeInfo>
      	  <PersonName>
      		 <GivenName>GivenName</GivenName><!-- FirstName -->
      		 <FamilyName>FamilyName</FamilyName><!-- LastName -->
      	  </PersonName>
         </EmployeeInfo>
      
      </NewHire>
      ]]></hrd:Data>
      

      Regards

      Arijit

      (0) 
  3. Hieu Tran Nguyen Trong

    Thank Arijit for your reply,

    The result of my Payload request because of we’re using the SAP XI SFIHCM03 package which the XSLT mapping as below.

    Do you have any XSLT file for this mapping? I’m trying to build the correct one but It’s so difficult because the accepting Payload should match 100% (Case sensitive element, namespace…)

    Thanks,

    Hieu

     

    (0) 
    1. Arijit Das Post author

      Hi Hieu

      I see your issue.

      One suggestion – are you able to use a Java UDF (instead of XSLT mapping) to map the mandatory elements GivenName and FamilyName – and see what the result is?

      Or perhaps you could try to concatenate multiple elements into your CDATA segment – again I suggest that you start with just the bare minimum – GivenName and FamilyName – and build from there.

      Unfortunately we aren’t using SAP PI on this project so can’t offer you any ideas.

      Let us know how you go 🙂 

      Cheers

      Arijit

       

      (0) 
  4. Hieu Tran Nguyen Trong

    Hi Arijit,

    I actually can use the Java UDF to fix this issue as your recommendation for Onboarding.

    But I still got the problem with OffBoarding service.

    Currently, the PI also uses the XSLT mapping but On/Offboarding API doesn’t show the request Payload of PostOffboardUserRecord API.I really don’t know how to apply this API to trigger OffBoarding record.

    Btw, I’m also so confused when the RDS using XSLT mapping when integrating with On/OffBoarding SF but it didn’t work. Do I need to configure any step at SFSF site because it’s just the XML data as I thought.

    Thanks,

    Hieu

    (0) 

Leave a Reply