Textkernel Match Automation (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 Textkernel account manager.

Important

Customers using this feature require a configured search and match environment.

Salesforce offers rich automation features via Flow and custom APEX. To extend these capabilities, the Textkernel integration offers a simplified interface to request matches from the Textkernel platform. Textkernel has extensive SOAP APIs for querying the index, but this simplified interface enables customers to rapidly build out match automation for a wide rande of use cases.

The simplified interface is a request queue, implemented as the Textkernel Match Request object. Two Flows are needed to use the feature. An initial "Requestor" Flow creates a new Textkernel Match Request record. Asynchronously, the managed package integration consumes that request, retrieves the results, and stores them back on the requesting object. A second "Consumer" Flow listens for changes on the Textkernel Match Request records, and it processes the results when they are ready.

This provides a flexible mechanism to leverage Salesforce automation features.

Configuring Match Request Automation

The match request queue will 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.

Textkernel Match Request object

The Textkernel Match Request queue object (TMR) enables matching or ranking of Candidates and Jobs through the Textkernel engine. It allows users to request match results, set constraints (such as maximum matches), and manage the lifecycle of the request (Pending, Ready, Processing, Completed, or Failed). Fields are designed to capture request details, including the type of matching, user context, shortlisted and excluded candidates or jobs, and error handling. Results are provided in a structured format, typically processed and updated by the system.

Info

You should implement a deletion policy when using this feature. The TMR records are useful to help with debugging, but there is no need to retain them forever, and they consume data storage.

Textkernel match scores

You do not necessarily need to use the scores returned by this feature. Scores change all the time as Candidates and Jobs are updated with new information, so if you store them in Salesforce they will quickly become outdated. However, the scores could be useful for a quick assessment by the Flow or APEX consuming the match request result.

Info

Raw Textkernel match/ranking scores from the search APIs are a number between 0 and 1. In order to make the scores more user-friendly, this feature scales scores up to a range between 0 and 100.

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

Fields

Type

• Description: Indicates the type of matching requested:
  • Match Candidates to Job: for ranking applicants against jobs.
  • Match Jobs to Candidate: for ranking jobs for a given candidate.
• Required: Yes

Target

• Description: Holds the ID of the record representing a Job or Candidate, depending on the type of request.
• Required: Yes
• Validations: Must match the appropriate object type (Job or Candidate) as per the request type.

Maximum Matches

• Description: Specifies the maximum number of matches to return.
• Required: No, but must be specified when the Shortlist is empty and is disallowed if the Shortlist is populated.
• Validation: Must be within the range of 1–200.

Shortlist

• Description: A comma-separated list of IDs (up to 1000) representing candidates or jobs to be ranked in the request.
• Required: No
• Validation: All IDs must correspond to the correct object type (Candidate for Match Candidates to Job or Job for Match Jobs to Candidate.

Exclusion List

• Description: A comma-separated list of IDs (up to 1000) representing candidates or jobs to be excluded from ranking.
• Required: No
• Validation: Similar to the Shortlist, all IDs must match the appropriate object type.

User

• Description: The user associated with the request. Match results are filtered based on the visibility of the user in Textkernel.
• Required: Yes

Timestamp

• Description: The date and time when the request was created or updated to a Ready status. Automatically set by the system.
• Required: No

Status

• Description: Represents the current status of the request:
  • Pending: Request is created but not yet ready.
  • Ready: Request is ready to be processed.
  • Processing: Request is being processed.
  • Completed: Request has finished successfully.
  • Failed: Request encountered an error.
• Required: Yes
• Validation: Status transitions are restricted (e.g. cannot directly change from Pending to anything but Ready).

Processing Error

• Description: Describes any error encountered during processing if the request fails.
• Required: Yes, when the status is Failed.

Ranked Results

• Description: Contains a JSON array with ranking results, including the match ID and match quality score. An invocable class is provided in the package so that Flows or Apex can consume the response easily.
• Required: Should only be set by the processor.

Using the match results

The managed package includes a global invocable Apex method to help consume the returned matches. The method is called Ranked Results from JSON, and it post-processes the JSON string returned by the Textkernel Match Request consumer. The method converts the JSON into a ranked list of RankedMatchResult instances and makes it readily available for use in a Flow or Apex code. Each of the RankedMatchResult instances contains an ID and score.

Signature

• Name: Ranked Results from JSON
• API Name: RankedResultsFromJSONInvocable
• Description: Converts ranked result details from a JSON string into a Flow-accessible Apex Type instance

Inputs

• Params (Array of Parameters): The input is a set of parameters that contains the ranked match results in JSON format that were returned from the Textkernel Match Request queue
• Variable Name: Ranked Results as JSON
• API Name: RankedResultsFromJSONInvocable.Params
• Type: String

Outputs

• Results (Array of Results): The output is an array of instances of the RankedMatchResult class, which are used to represent the individual ranked results.
• Variable Name: Ranked Results
• API Name: RankedResultsFromJSONInvocable.Results
• Type: List of RankedMatchResult

Supporting Classes

• Class Name: RankedMatchResult
• API Name: RankedMatchResult
• Aura Enabled Properties:
  • Property id
    • Type: String
    • Description: Salesforce ID of the Candidate or Job that was matched/ranked against the target
  • Property score
    • Type: Double
    • Description: Ranking score of the Candidate or Job that was matched/ranked against the target

Example Workflow: automatically create Applications when a Job is posted

Here is the process of a common automation example that can be implemented with this feature:

1. A new Job is created in the ATS and its status is set to "Posted"
2. A requestor Flow is a record-triggered Flow that runs when the Job record status changes to "Launched". It creates a new Textkernel Match Request record to retrieve the top 10 matches for this Job automatically. It requests the processing by setting the Status field to "Ready"
3. The integration infrastructure submits the match request to the Textkernel index and retrieves the match results, setting the Status field on the Textkernel Match Request to "Completed"
4. A second consumer Flow is a record-triggered Flow that runs whenever the status on a Textkernel Match Request record has been set to "Completed". This Flow uses an invocable class called Ranked Results from JSON provide by the managed package to unpack the "Ranked Results" JSON data structure, loops over the ranked match results, and creates an Application linking the matched Candidates to the Job. There is a "Source" field on the Application which is set to "Automatic Match on Job Creation"
5. At some later point in time, the recruiter logs in to review the Job and sees these automatic matches already in their ATS. Or, other Flow automation sees the creation of these Applications, and may directly email the Candidates to see whether they are interested in the role.

The details are discussed later, but here is what it looks like to manually create a Textkernel Match Request (although this would be created via automation):

Here is what an example response would look like when the Textkernel Match Request has been completed successfully, showing the JSON response:

Here is an example of a Flow that would use the invocable method to transform the JSON response, and loop over the result to complete the workflow. In this case, it creates a list object with the results.