SAP SuccessFactors ATS → Beamery Integration

Data Flow, Designs & Diagrams

Data flow single direction SAP SuccessFactors ATS → Beamery

Within Beamery's SAP BTP instance, we create a CPI (Cloud Platform Integration) for each customer. This means that you will have a CPI instance that sits within the Beamery SAP BTP instance.

Beamery Connector Integration Flow:

• Queries the SuccessFactors APIs to “extract” three resources from your SAP SuccessFactors ATS account:

  • Vacancy (Job Requisition),

  • Candidate (Contacts) and,

  • Job Applications.

• Integration Flow then maps fields to the Beamery schema using SAP “Message Mapping” in the Integration Suite.

• The data is then pulled into the Horizon Pipeline.

• The Frontier APIs will then process the data and load into Beamery

Prerequisites:

What is required from the customer?

1) SuccessFactors details

• The URL of the customer's SuccessFactors instance
• The customer's API URL, eg. https://apisalesdemo2.successfactors.eu
• The Company ID of the customer's SuccessFactors instance, eg. SFCPART000242
• The username of an admin or API user which is used to access the customer's SuccessFactors instance -

• • The customer needs to provide us with the below mentioned permissions

  • If the customer provided us with an Admin or API user to their SAP-SF account, use that username

User roles are managed in the Admin Center of SuccessFactors - search for 'Manage Permissions Roles'

2) SuccessFactors access

• We need read access to the following APIs:

• • Job Requisition

  • Job Application

  • Candidate

  • https://api.sap.com/package/SuccessFactorsRecruiting/odata

3) Permissions

• During your onboarding and implementation phase, our Integration Consultants will work with you to ensure the integration is set up and configured correctly.
• We do require the following permissions set by your SuccessFactors user:

Manage Integration Tools
Allow Admin to Access OData API through Basic Authentication
Access to OData API Metadata Refresh and Export

Recruiting Permissions
OData API Application Export
OData API Candidate Export
OData API Job Requisition Export

Metadata Framework
Admin access to MDF OData API 

4) External job-posting URL

• The base external job-posting URL, eg. https://careersd2.successfactors.eu/sfcareer/jobreqcareer?company=SFCPART000242

  • You can find this in your SuccessFactors instance, by navigating to any Job Requisition with a Job posting attached.

• Initially, you will receive the URL in this format when copying: https://careersd2.successfactors.eu/sfcareer/jobreqcareer?jobId=13591&company=SFCPART000242

• You should input the URL in the following format in the field above: https://careersd2.successfactors.eu/sfcareer/jobreqcareer?company=SFCPART000242 - by deleting the jobId and & symbol.

Language Settings

• During the onboarding and implementation process, Beamery are able to configure your language settings within CPI.

• You are able to choose between en_GB and en_US.

• Once this has been configured, we are unable to change/amend.

• This is a global configuration - in that across the whole of your CPI, only one language configuration can be set. However the only area in CPI where this is used is to filter the correct vacancy stage.

Vacancy & Candidate Mapping

As you read through the following documentation, we detail the fields which we map from SuccessFactors to Beamery. We have also included the field type to assist you with identifying where that field sits when configuring in SuccessFactors.

The fields listed in the documentation are defined and documented in SuccessFactor's Public API. The API request will unfortunately fail if one of those fields is disabled (instead of returning an empty value). As long as the field exists in your Data Dictionary and is sap:visible, Beamery will be able to query successfully.

Data Sync Types

Please see the table below detailing the data synced between the SAP SuccessFactors ATS -> Beamery CRM via the single direction integration.

Data Type	SFSF → BM	BM → SFSF
Vacancies	check_circle	cancel
Candidates	check_circle	cancel
Applications	check_circle	cancel
Attachments	check_circle	cancel

We have two types of data sync:

TypeCadenceNotes

Historical

Once

Kicked off when the integration is initiated, dating back to an agreed start date stipulated by you.

Delta

Every 15 minutes

When any of the three entities we pull (Vacancies, Candidates & Applications, Resumes & Cover Letters) are created or any field that we sync (please see below for details on which fields we sync) is updated in SuccessFactors we will sync to Beamery. 

For Example: if we update a tag on a candidate, the candidate profile will be included in the next sync to Beamery.

We do not currently sync any 'delete' actions from SuccessFactors to Beamery.

Vacancies & Candidates - The flow of Data:

Feature	SFSF → BM	Notes
Create Vacancy	check_circle
Update Vacancy	check_circle
Confidential Vacancy	check_circle	There is no standard field for confidential vacancies, however it is possible for this to be supported via a custom mapping.
Create Candidate without Vacancy	check_circle
Create Candidate with Vacancy	check_circle
Update Candidate	check_circle
Confidential Candidate	N/A
Candidate Attachments (i.e Resumes)	check_circle
Merge Candidate	N/A	We are not syncing any SFSF merge logic currently.

Deduplication Logic:

When a candidate is synced from SuccessFactors →  Beamery, the candidate will be either created, updated or merged based on the following logic:

• IF the profile syncing across has a matching ATS ID to that of a profile already in Beamery, THEN the existing profile in Beamery will be UPDATED.

• IF the profile syncing across does not have a matching ATS ID to that of a profile already in Beamery, AND has an email address that does not match that of a profile already in Beamery, THEN the new profile will be CREATED.

• IF the profile syncing across does not have a matching ATS ID to that of a profile already in Beamery, AND has an email address that does match that of more than one profile already in Beamery, THEN the new profile will be CREATED.

• IF the profile syncing across does not have a matching ATS ID to that of a profile already in Beamery, AND has an email address that does match that of one profile already in Beamery, AND has an ATS ID, THEN the new profile will be CREATED.

• IF the profile syncing across does not have a matching ATS ID to that of a profile already in Beamery, AND has an email address that does match that of one profile already in Beamery, AND does not have an ATS ID, THEN the new profile will be MERGED.

In Beamery we keep two IDs per candidate - we have the Beamery specific ID and also the SuccessFactors ATS ID. So, if you have candidates in Beamery and then sync across an application from SuccessFactors, the candidates will only be merged if they share the same email address of one existing profile in Beamery, with the original candidate being enriched with the ATS ID. 

If they share the email address of multiple existing profiles in Beamery, then Beamery will follow suit and create an additional profile. This is to ensure that we are not merging some and not others. 

Deduplication Scenario Examples:

Scenario Examples

Scenario 1:

• Candidate Jane Doe is in Beamery with email address jane.doe@email.com and no ATS ID.

• Candidate Jane Jones applies to vacancy in SuccessFactors with email address jane.doe@email.com

• Upon sync, these two candidates will be merged.

• Within Beamery, the name of the SuccessFactors candidate will be presented 'Jane Jones' alongside the SuccessFactors ATS ID.

• All other contact fields are merged (i.e. phone number, education).

• If for example the Beamery candidate Jane Doe has phone number 111111111 but the SuccessFactors candidate Jane Jones has phone number 00000000, then the merged contact 'Jane Jones' in Beamery will have both phone numbers 111111111 & 00000000 .

• Any fields which are only present on the Beamery contact Jane Doe and are not pulled from SuccessFactors will be kept in Beamery (i.e. Skills, Language).

Scenario 2:

• Candidate Jane Doe is in Beamery with email address jane.doe@email.com

• Candidate Jane Jones applies to vacancy in SuccessFactors with email address jane.jones@email.com

• Upon sync, these two candidates will NOT be merged and thus Jane Jones will be created in Beamery.

Scenario 3:

• Candidate Jane Doe is in Beamery with email address jane.doe@email.com with ATS ID 1234

• Candidate Jane Jones applies to vacancy in SuccessFactors with email address jane.doe@email.com with ATS ID 6789

• Upon sync, these two candidates will NOT be merged and thus Jane Jones will be created in Beamery.

Scenario 4:

• Candidate Jane Doe is in Beamery with email address jane.doe@email.com with no ATS ID, has an application created in Beamery only.

• Another candidate Jane Jones with email address jane.doe@email.com and ATS ID 1234 applies to a vacancy in SuccessFactors

• Upon sync, these two candidates will be merged (as they have the same email address and the first candidate in Beamery does not have an ATS ID)

• Merged candidate Jane Jones will have two applications in Beamery, however there will only be one application in SuccessFactors - as only one application was created in SuccessFactors.

Scenario 5:

• Candidate Jane Doe is in Beamery with email address jane.doe@email.com

• Candidate Jane Jones applies to vacancy in SuccessFactors with email address jane.doe@email.com and ATS ID 1234

• Upon sync, these two candidates will be merged.

• A new candidate Jane Jones is created in SuccessFactors with email address jane.doe@email.com with ATS ID 0987.

• The first two will remain merged in Beamery, however the third candidate will be created in Beamery, as it will have a separate ATS ID to that of the two previously merged.

The merge action is not displayed in the timeline from Beamery candidate profile. We show the contact has been created by “Integration User”, like normal contacts, however the first ever creation shows the previous name i.e. Beamery only contact's name (please see screenshot below).

Contact Deletion, Archival or Anonymisation:

Please see the table below for expected behaviour when contacts are either deleted, anonymised or archived.

Data Mapping Details

Please see the table below detailing the key data points pulled in for each entity:

Vacancy Pull Mapping:

API documentation: SAP Business Accelerator Hub

Notes:

• The department_obj mapping can have different department values. Recruiters can create job requisitions in the SFSF UI using different departments, which are eventually stored within this object, linked to the job requisition and then only the name is pulled into Beamery.

• When syncing Job Requisitions from SuccessFactors to Beamery, we default the visibility field to Public.

• We currently do not natively support “Private” or “Confidential” vacancy types for the SuccessFactors integration with Beamery, and so we default all to “Public”. However if “Confidentiality” is required, we can look to configure a custom field on the vacancy to accommodate this.

• If a job requisition is set to “Private” in SuccessFactors, then that same Job Requisition will be set as “Public” in Beamery.

Vacancy Stages:

When we pull Vacancies in from SuccessFactors → Beamery, that Vacancy will inherit whichever Vacancy stages are set in Beamery in settings. Vacancy stages must be set in Beamery to mirror Requisition stages in SuccessFactors. We must have a 1 to 1 mapping for stages - so if there are 9 stages in SuccessFactors, then we must have 9 stages in Beamery.

This is important for correct synchronisation of which stage a candidate is in (an application). For implementation of the integration, we need a list of your Vacancy stages set in SuccessFactors, so that we can replicate them into Beamery. 

Vacancy Status:

Please see the table below detailing the mapping of Vacancy Status between SAP SuccessFactors ATS & Beamery:

SuccessFactors

Beamery

reqStatus_Hold

Hold

reqStatus_Open

Open

reqStatus_Filled

Closed

reqStatus_Vacancy_Cancelled

Cancelled

We are not mapping (and therefore not able to configure) any other vacancy status from SuccessFactors → Beamery as we do not have an equivalent status in Beamery.

In case that a status doesn't exist in Beamery (e.g: Assessments), the vacancy will sync but the status won't be updated and the last known status is preserved.

For example, if the vacancy is transitioned from Open → Assessments in SuccessFactors, in Beamery it will still be shown as Open until it is transitioned to a valid status.

Note: that within SuccessFactors there are 'Vacancy Status' and 'Application Status', however Beamery has 'Vacancy Status' and 'Vacancy Stages'. We are not able to configure Vacancy Status within Beamery, but we can configure Vacancy Stages (which are known as 'Application Status' in SuccessFactors.

Vacancy Type:

Please see the table below detailing the mapping of Vacancy Type between SAP SuccessFactors ATS & Beamery:

SuccessFactors

Beamery

employType_Full_time

Full Time

employType_Part_time

Part Time

employType_Fixed_contract

Contract

Candidate Pull Mapping:

API documents: SAP Business Accelerator Hub

Note: Education & Work Experience are top level “data field” background elements. Within these data fields, we have configured School, Degree, Major and start/end dates.

• When pulling the phone number, we are also pulling the country code. Whatever value is present under cellPhone for a candidate in SuccessFactors, it will be pulled into Beamery. As per SAP API documentation, there are only 2 fields in SuccessFactors related to phone number - cellPhone and homePhone. When a candidate is created in SuccessFactors using cellPhone, it is displayed as Phone for a candidate profile, and pulled into Beamery under Primary Phone. We are mapping this to Primary phone within Beamery.

• We are not currently syncing the source field(Source, Sourced By & Creation Source) during the one way integration. These Source fields are an attribute of the contact within Beamery - so when a candidate has been sourced via Beamery, the source will be attributed to the contact and not its application. When that candidate is eventually invited to apply, the application will sync and will not override the source field on the contact - it will maintain the original entry in Beamery of the field. If there is no Source field entry in Beamery, upon application sync from SuccessFactors → Beamery, the Sourced By field will be populated with “Integration user” as we are not currently mapping Sourced By as a field.

• Please note that within SuccessFactors, phone numbers can be added with or without a phone country code. So when an existing (in both SuccessFactors and Beamery) contact's phone number in SuccessFactors is updated with a country code, we will not merge on sync to Beamery - within Beamery we will have the original phone number AND an additional phone number, now with the addition of the updated phone country code.

  • For example: A contact exists in Beamery with phone number: 012345678 and later it is updated to have +44 added to 012345678, then within Beamery, we will present two telephone numbers for that contact - 012345678 AND +44012345678

• Within Beamery, we only detail or present one education record per organisationName.

  • So if a contact has multiple education records from the organisationName (i.e. two different degrees from the same School/University), then within Beamery we will only present one record.

Application Pull Mapping:

API Documentation: SAP Business Accelerator Hub

Error Management and Monitoring

We have two types of errors:

• Transient

  • These are errors which can be automatically recovered from on retry, for example: timeouts, rate limiting, out of order arrival of records.

• Non-Transient

  • These are errors that cannot be automatically recovered from, for example: data validation errors.

How does error management work?

For “Extraction” of data from SuccessFactors in CPI, we have a retry behaviour which:

• Query - for HTTP response codes 502, 503, 504, and 429.

• The system retries connection every 3 minutes for a maximum of 5 times.

For “Load” or ingestion of the data into Frontier from Horizon, we have:

• For Transient errors, a retry mechanism in place.

• For Non-Transient errors, a new sync will be scheduled for the failed entities.

Logging & Monitoring Management

We maintain different sub-accounts within the SAP BTP cockpit, which are linked to different and unique integration suite applications and are configured to a unique company in Beamery.

A company in Beamery is a unique instance and identified by using a company ID. All the data is stored and managed using the company ID.

To monitor the receiving and transformation of data from SuccessFactors, Beamery uses the SAP BTP Integration Suite and its built-in monitoring tooling. This generates a log every time the integration is triggered - executions which error out will have an error message attached to them to investigate further; whilst successful executions will display as “Completed”.

To monitor the loading and sending of data from our integration pipeline to Beamery, we will be using both Kibana and GCP (Google Cloud Platform) Dashboards. These will capture key health metrics including timeouts, out of memory errors, crashes, and latency rates per customer. We also have Slack alerting configured for any integration errors across shared Beamery components.

Additional notes to be mindful of:

• The single direction integration will not include any customizations or custom configuration.

  • This includes custom mapping,

  • Therefore we are not applying any filters or field mapping settings based on customer requirements.

• For single direction, Beamery will host the CPI connector for each customer within the Beamery BTP tenant.

  • As this sits within Beamery's BTP instance, Beamery will manage and support the on-going monitoring and logging of the customer's integration.

• When syncing data from SuccessFactors→ Beamery we only sync data that is either updated or created - not deleted.

  • So if you delete a candidate in SuccessFactors, we will not pull that action to Beamery, and therefore that candidate will remain in Beamery.

Attachments

For attachments to successfully sync from SF → BM, the contact (that the attachment belongs to) must have already successfully synced prior to the attachment sync attempt.

If the contact has not yet arrived into Beamery, the attachment sync will error and will re-try on the next sync strategy.

The attachment pull iFlow is set to sync every 15 minutes SF -> BM. (Please refer to the "Data Sync Strategies" section above for more info).

Info on the parameters of syncing attachments:

• Our integration will pull SuccessFactors -> Beamery candidate attachments (We have two separate flows from SF -> BM, one pulling resume, and one pulling cover letters. The field mappings remain the same as each other. Please see below).

• The maximum file size that SuccessFactors allows is 10MB (this may need to be configured within SuccessFactors). The largest file Beamery will be able to pull from SF and successfully store within BM will be 10MB.

• SuccessFactors can only support the following file types: .doc, .docx, .gif, .jpeg, .jpg, .pdf, .png, and .txt. Files not supported by SuccessFactors are: .html, .mp3, .mp4, .msg, .ppt, .pptx, .xls, and .xlxs.

• Any file that is supported by SuccessFactors is supported by Beamery.

• We can pull multiple CV/Resume and Cover Letters per contact, however only one of each type is displayed in SuccessFactors.

• We will list multiple attachments in Beamery - but if the file type and file name are the same as a previous attachment, Beamery will overwrite with the new attachment - even if the data within the document differs.

• If a document is updated in SuccessFactors, both versions will be kept in Beamery

Field Mapping: