How do you “Onboard” a NEWHIRE with SuccessFactors Onboarding?
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!
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.
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.
<!-- 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.
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.
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>
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>
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.
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.
Nice blog and you're welcome 🙂
Thanks Arijit for such nice document !!
Well articulated 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.
Much appreciate if you can give me an advice.
Hi Former Member
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).
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...)
Hi Former Member
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 🙂
Nice Blog Arijit.. It really help me to prepare XSLT mapping easily to onboarding candidate in SF ONB system
I've a question - Is there any sample XSLT mapping for GlobalOnboarding and Cross boarding.. Whenever I process record it always goes into US onboarding (Onboarding) bucket.. I don't know, how to hire candidate in global & cross boarding..
Below are the XSLT mapping which I trying to onboard candidate in GlobalOnboarding
Really appreciate your time.
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.
Hi Former Member
I am sorry I haven't dabbled with the Offboarding API.
So did you fix you problem with the update of HRData with postnewhirerecord ?
I am still receiving the error about missing First Name and Last Name. I tried my own messages with <FirstName> <LastName> tags. Also with <GivenName><FamilyName> tags and also your xml with all of those tags 😉
Any clues ?
I am using HCI and the prepackaged integration between SAP and ONB gives me the same error.. no matter what I put inside.
I used the SOAP API services instead HCI so that I'm not sure it can help you.
I fixed it by checking correctly the setting from Successfators side. The standard configuration follows by RDS document should be ok.
You could find more information by this link: https://help.sap.com/viewer/9c2f8380e6d14dd1adb43bfeebfcb2a1/3.0%20SP06/en-US/eb175d55f8fd1941e10000000a423f68.html
Hope it's helpful for you.
Is there a way to update a newhire record via API ?
Is postnewhirerecord a valid option ?
You can use PostNewHireRecord service to post a new hire.
Just follow the xml sample and remember the GivenName and FamilyName is required.
By using SoapUI, it helped me to find the correct request payload.
Yes you may use the API PostNewhireRecord to update a new hire record. Use the mandatory and key fields to ensure the right record is updated.
PostNewhireRecord works in a confusing way. Especially with that GivenName and FamilyName.
We managed to get some results with AddHRDataRecord method – this works well when you have just a single or few fields you need to change in ONB
Thanks for the wonderful blog.
In our case, we have added custom fields as part of XSLT file and uploaded into Super admin.
Now the question is, how the Integration consultant can make use of these custom fields on Integration side?
Hi Naresh Dasika
You will need to extend the CDATA with the custom attributes; and then use the new WSDL in your middleware.
Its good to see the blog about custom field add to the existing SOAP payload. I have a requirement to integrate between a external recruiting system Greenhouse to SuccessFactor-Onboarding. I am new to SuccessFactor and right now we don't have any technical expert.
By using the below SOAP API call able to frame the payload and push record to Onboarding.
Its awesome, where need to worry about what objects in which order I need to create record at SF. Earlier tried with SF Connector from Boomi, able to query, but Not able to create record using connector.
Error follows as below:
Looks we need Super admin account to change those property settings. Right now don't have time, client doesn't have support license with implementation partner. If my details has to be added as Super admin, then i should be a Onboarding certified person.
So only possible is SOAP call.
Challenge is, we have two dashboard as Onboarding which is default from SF, I guess International Onboarding is customized process. Snapshot FYR.
gone through too many docs, KB still not able to identify right material or even through self exploration, not able to reach to the goal.
Do anyone have idea on how to populate data to Onboarding and International Onboarding.
Actual process is Onboarding will have only US candidates, where as International Onboarding will have Non US candidate. Which key plays major role to deviate the date to two different tabs/ process.
Tried with different options by having different values for location, office location, adding process under USERAREA element.
If anyone have idea who have already faced and have solution guide me or share proper KB/blog links. If anyone have queries than what I have explained above, please let me know.
Have you resolved this issue? I'm facing an issue where I can't create new hire record.
Is there any way to view the logs from Onboarding WebServices?
I was trying to create a new hire record (no luck yet) and keeps returning 400: Bad Request even though I followed the docs exactly.
I'm not sure if this has something to do in SuperAdmin but if that is the case I have to at least show them something which proves it. API logs would be really helpful.
Here is my sample request:
I am facing same issue, were you able to resolve this?
What are the enpoints to Add a new user directly to ONB1.0 using an API POST to Odata?
Is it possible to configure customized new employee step for each country?
I mean, when the candidate choose the country, then he/she sees only country-specific fields for address info?