Ranking Applications / Job Submissions On-Demand (PREVIEW)

Important

This feature is currently still under development. These instructions are preliminary and may change in the final version. If you are interested in becoming a beta tester when we are ready, please contact your Bullhorn account manager.

The recommended best practice is to view and act upon Textkernel match ranking scores in the Textkernel package's UI components, either Textkernel Portal, or the Best-Match widgets. These elements are built to give up-to-date scores on-demand as needed. The scores change very frequently as Jobs and Candidate records change, so it does not make sense to try to maintain up-to-date score data outside of the Textkernel index in Salesforce, especially when the score data is only used infreqently. Because of this, best practice is to always calculate/refresh the scores on-demand at the time they are needed.

However, for some workflows, recruiters may want to access score data inside the Salesforce ATS. One scenario is when interactive recruiters want to view and rank applications / job submissions inside Salesforce where they can immediately trigger custom component workflows.

Most ATSes have Candidate-Job junction object that keep track of a suitability of a Candidate for a particular Job. These objects may be called Application or Job Submission, or something similar. When these records exist, the integration offers a way to add a Quick Action button to the Job and/or Candidate record layout to calculate / re-calculate the scores on-demand, so that the recruiter can see which of the existing Applications / Job Submissions is the best match, either from the Job or Candidate perspective.

Info

In Textkernel's ranking engine there is no single match/ranking quality score. There is a score that calculates the fitness of a Candidate against a given Job profile, and there is a different score that calculates the fitness of a given Job against a Candidate profile. For any given pair of Job and Candidate, those 2 scores are different. When using the scores for ranking, it is critical to compare similar score types (ie, only compare Candidate-to-Job scores for a given Job to each other).

Textkernel score scaling

Raw Textkernel ranking scores are a value between 0 and 1. In order to make the scores more user-friendly, this feature scales to score up to a range between 0 and 100.

Recruiter User Interface

Depending on the Salesforce ATS features and configuration, the recruiter will see the scores differently. Below are some screenshots showing 2 possible examples.

Bullhorn-4-Force

This shows a potential Bullhorn-4-Force configuration, including an embedded custom view of the Application and showing when the scores were last recalculated.

The recruiter's user experience when viewing a Job would look something like this:

The recruiter's user experience when viewing a Contact/Candidate would look something like this:

General demo user interface

This shows a general demo UI presenting the score information, but without showing when the scores were last updated

The recruiter's user experience when viewing a Job could look something like this:

The recruiter's user experience when viewing a Contact/Candidate would look something like this:

Technical architecture

To support re-ranking, the managed package includes a lightning web component (LWC) called updateMatchScores. The LWC can be configured as a Quick Action button to recalculate the match/ranking scores and store them to the Candidate-Job junction object. The component can also write a date-time value to show the recruiter when the scores were last re-calculated, and it can be configured to calculate the scores according to a specific global user context. The LWC component is configured via custom metadata type settings, that are discussed in the next section.

Info

In order to use this feature, you already have a working Textkernel Search and Match indexation setup configured. Your Candidate-Job junction object should be visible on the Job and Vacancy record page as a custom component or related list.

Configure match score retrieval

The LWC needs to access the Textkernel index in the background, so this is the first thing to configure.

Go to Salesforce Setup --> Textkernel App --> Search and Match Setup --> Match Component Settings

1. Under Search endpoint, enter the value that Textkernel support provided for your environment.

2. Under Job search environment enter the values that Textkernel support provided for your environment.

3. Under Candidate search environment enter the values that Textkernel support provided for your environment.

4. Be sure to Save all these changes.

Now the LWC can retrieve match scores from Textkernel.

Make changes to data-model

Match score data model

Match scores can be stored differently in the ATS. We recommend that you us the Textkernel Match Scores object that is included in the Textkernel managed package to store the two ranking scores, rather than storing the scores directly on the Candidate-Job junction object. The scores change frequently, and by using a linked score object, it means that match score changes will not activate other Triggers on the Candidate-Job junction object. It also means it is much less likely you will accidentally trigger indexation updates to the Textkernel index when the scores change.

Important

The match score fields should NEVER be mapped to Textkernel’s search index. The index already calculates the match score, so this just wastes Salesforce compute resources. Also, in some scenarios, it could create an infinite update loop.

To use the Textkernel Match Scores object, you need to link your ATS data model’s junction object to the Textkernel Match Scores object from the package. You can simply create a Lookup relationship from your Candidate-Job junction object to the match scores object. If you do that you have a data model looking like this:

Score Last-Updated fields

Since the scores are only updated on-demand, it is helpful to show the recruiter when they were last re-calculated. The LWC supports this. You simply add a custom Date-Time field onto both your Job and Candidate objects, and add it to the relevant Job and Candidate page layouts.

Configuring the LWC for on-demand score recalculation

The LWC is flexible to fit different ATS data models. To configure the LWC using custom metadata types, follow this procedure:

1. Go to Setup->Custom Metadata Types
2. Find "Textkernel Re-Ranking Service Settings"
3. Click "Manage Records"
4. Click "New"
5. Select the custom metadata type settings to configure the LWC component according to your data model

Info

You should only ever have 1 "Textkernel Re-Ranking Service Settings" custom metadata type record in your org.

This is the screen to configure the custom metadata type:

Here are the available settings:

1. Candidate Scores Last Updated Field - (Optional) The field API name on the target Candidate record to save the “last updated” timestamp whenever match scores are updated for that target Candidate. If not specified, no field is updated.

2. Job Scores Last Updated Field - (Optional) The field API name on the target Job record to save the “last updated” timestamp whenever match scores are updated for that target Job. If not specified, no field is updated.

3. Candidate Junction Relationship - (Required) The relationship API name from the target Candidate record to the junction object defining what shortlisted Job to score/re-score. This should be a fully qualified relationship name, including the “__r” suffix.

4. Job Junction Relationship - (Required) The relationship API name from the target Job record to the junction object defining what shortlisted Candidate to score/re-score. This should be a fully qualified relationship name, including the “__r” suffix.

5. Shortlisted Job ID Field - (Required) The field API name on the junction object containing the JobID that will be added to the scoring/rescoring shortlist for the target Candidate.

6. Shortlisted Candidate ID Field - (Required) The field API name on the junction object containing the CandidateID that will be added to the scoring/rescoring shortlist for the target Job.

7. Candidate Score Field Path - (Required) The field API name or field API path on the junction object where the Job’s score calculated from the target Candidate will be stored.

8. Job Score Field Path - (Required) The field API name or field API path on the junction object where the Candidate’s score calculated from the target Job will be stored.

9. Candidate User ID - (Optional) The ID of the Salesforce user for whom the re-ranking API request is made for target Candidates. If unspecified, default to the contextual user’s ID. Typically you should use a standard integration user with global visibility of all Candidates and Vacancies.

10. Job User ID - (Optional) The ID of the Salesforce user for whom the re-ranking API request is made for target Jobs. If unspecified, default to the contextual user’s ID. Typically you should use a standard integration user with global visibility of all Candidates and Vacancies.

Example configuration for Bullhorn-4-Force

The below table shows examples of how the LWC could be configured in a Bullhorn-4-Force ATS, after making necessary configuration changes.

CMT field	Value	BH4Force Config needed?	Comments
Label:	BH4Force Re-ranking		Standard SFDC field, customer picks a name
Textkernel Re-Ranking Service Settings Name:	BH4Force_re_ranking		Standard SFDC field, customer picks a name
Candidate Junction Relationship	TR1__Application1__r	No	Application is a child of Contact it has a Lookup relationship to Contact; standard BH4SF relationship
Candidate Score Field Path	Textkernel_Match_Scores__c.Textkernel1__Candidate_To_Job_Score__c	Yes	Here Textkernel_Match_Scores__c is a lookup relationship from Application_V2 to Textkernel Match Scores. This was added outside managed packages.
Job Junction Relationship	TR1__Application1__r	No	Application_V2 is a child of Job it has a Master-Detail relationship to Job, where Job is the Master. Standard BH4SF relationship
Job Score Field Path	Textkernel_Match_Scores__c.Textkernel1__Job_To_Candidate_Score__c	Yes	Here Textkernel_Match_Scores__c is a lookup relationship from Application_V2 to Textkernel Match Scores. This was added outside of managed packages.
Shortlisted Candidate ID Field	TR1__Applicant__c	No	This is standard field on Application_V2
Shortlisted Job ID Field	TR1__Job__c	No	This is standard field on Application_V2
Job Scores Last Updated Field	Job_Scores_Last_Updated__c	Yes	Added on Job object, outside of Managed package
Candidate Scores Last Updated Field	Candidate_Scores_Last_Updated__c	Yes	Added on Contact object, outside of Managed package
Candidate User ID		No	Org-dependent, provide the SFDC UserID
Job User ID		No	Org-dependent, provide the SFDC UserID

Add a Quick Action button to the Candidate and Job to recalculate scores

You need to add the LWC component to your Candidate and Job page layout so that recruiters can refresh match scores and rerank the junction object records when needed.

Go to SFDC Setup → Object Manager → Candidate/Job → Buttons, Links and Actions → New Action

Select the following settings:

• Action Type: Lightning Web Component
• Lightning Component: select the appropriate LC or LWC for the desired use case (eg updateMatchScores)
• Label: pick an appropriate label for the action button
• Name: pick an appropriate API name for the action

Now you need to place the buttons on the Candidate and Job layouts

1. Go to Candidate/Job object → Page Layouts section → select your Layout
2. From Mobile & Lightning Actions drag the new quick action and drop it to Salesforce Mobile and Lightning Experience Actions section where you want to display it
3. Save the layout.

Now recruiters are able to see ranking scores on the Candidate-Job junction records and trigger re-ranking.