IBM Kenexa BrassRing - HackerRank Tests Integration

Last updated: December 27, 2024

Overview

The below diagram describes the workflow of the BrassRing and HackerRank integration for recruiters. Recruiters will move a candidate into a custom HackerRank Test status. Upon entering this status, BrassRing will dispatch a payload to HackerRank via the candidate Export API. HackerRank will then send a test invitation to the candidate. After the candidate has completed the test and HackerRank has graded the test, HackerRank will send the results back to BrassRing via the Form Import API. 

image2.png

Prerequisites

In HackerRank for Work

In BrassRing

  • You must own an Enterprise plan with a Recruiter license.

  • You must have an activated Recruiter type user account with Company Admin permissions. This user account must belong to any team.

  • Recommended: HackerRank for Work Sandbox account for integration testing.

  • You must be a BrassRing customer with access to Candidate Export and Form Import APIs. Contact your IBM representative if you are not sure if you have access to these APIs.

  • You must either: be a Workbench Administrator and configure the integration yourself or work with IBM professional services.

  • Recommended: BrassRing Sandbox environment for integration testing. 

Integration Steps

The integration involves a 3-step process:

  • Configure the List of HackerRank Tests in BrassRing

  • Configure the Candidate Export 

  • Configure the Form Import 

Configure the List of HackerRank Tests in BrassRing

The lists of tests need to be set up on the BrassRing side as options in a HACKERRANK_TEST_ID field. 

integ_brassring.png

When building out and testing the integration for the first time, you can get the Name and Test ID from the HackerRank Test page and the page URL, respectively. In the example below, the Test ID is 454785 and the Test Name is “HackerRank Full-stack Developer Hiring Test.”

When the integration is ready, your HackerRank Solutions Engineer can do a one time bulk export of all Test Names and Test IDs to be entered into BrassRing.

Any time new tests are created in HackerRank that need to be used in BrassRing, you will need to add them in manually. 

Configure the Candidate Export 

Obtain the BrassRing API key from HackerRank for Work

  1. Log in to HackerRank for Work with the Company Admin user account.  

  2. On the home page, click the drop-down next to the user icon in the top right corner.

  3. Click Settings.

    settings.png

  4. On the left pane, click Integrations. The Integrations page is displayed. Scroll down and click Configure on the BrassRing option. You can also search the Integration from the Search bar.

    integ_brassring1.png

  5. Click Generate API Token to generate the API token.

    integ_brassring_api.png

    A unique API Key is displayed.

    integ_brassring_api_token.png

  6. Copy this key. You will need to add this key to the BrassRing account to establish the integration.

Note: Ensure to store the API key safely. Once the popup is closed, you cannot retrieve the key again.

URL and Authentication Setup

In BrassRing, create a new Candidate Export payload. It should be sent to the following URL:

https://ats.hackerrank.com/brassring/v2/invite

The username for this export should be set to the BrassRing API key generated within HackerRank. (The password field is not used by HackerRank and can be set to any value if it is a mandatory field.) 

Note - The API key might be longer than the username and password fields allow. If this is the case, you will need to make a request to your IBM integration representative to have it configured by IBM.   

Setup Candidate Export XML Payload

This is the format for the Candidate Export XML that is understood by HackerRank out of the box. You will need to configure Workbench to create a matching XML:

<?xml version="1.0" encoding="UTF-8"?>
<Envelope version="01.00">
  <Sender>
    <Id></Id>
    <Credential></Credential>
  </Sender>
  <Recipient>
    <Id></Id>
  </Recipient>
  <TransactInfo transactType="data">
    <TransactId></TransactId>
    <TimeStamp></TimeStamp>
  </TransactInfo>
  <Packet>
    <PacketInfo packetType="data">
      <PacketId>1</PacketId>
      <Action>SET</Action>
      <Manifest>HACKERRANK_CANDIDATE</Manifest>
    </PacketInfo>
    <Payload><![CDATA[<?xml version="1.0"?>
<HACKERRANK_CANDIDATE>
        <CANDIDATEID></CANDIDATEID>
        <REQUISITIONNUMBER></REQUISITIONNUMBER>
        <BRREQNUMBER></BRREQNUMBER>
        <JOBCODE></JOBCODE>
        <STATUS></STATUS>
 <EMAIL></EMAIL>
 <FIRSTNAME></FIRSTNAME>
 <LASTNAME></LASTNAME>
 <HR_ACCOMMODATION></HR_ACCOMMODATION>
</HACKERRANK_CANDIDATE>
]]></Payload>
  </Packet>
  <Packet>
    <PacketInfo packetType="data">
      <PacketId>2</PacketId>
      <Action>SET</Action>
      <Manifest>HACKERRANK_CANDIDATE_REQEXPORT</Manifest>
    </PacketInfo>
    <Payload><![CDATA[<HACKERRANK_CANDIDATE_REQEXPORT language="en">
        <REQFORM id="111"></REQFORM>
 <RECRUITEREMAIL></RECRUITEREMAIL>
 <HACKERRANKTESTID></HACKERRANKTESTID>
</HACKERRANK_CANDIDATE_REQEXPORT>
]]></Payload>
  </Packet>
</Envelope>

Mandatory System Fields

Field Name

Format

Note

CANDIDATEID

Integer

This is the unique identifier of the candidate in the BrassRing system

REQUISITIONNUMBER

Varchar

(Optional) This is the Client Req number also referred as the Optional Req Number. The value will be blank if client does not use it

BRREQNUMBER

Varchar

This is the unique identifier of the Job in BrassRing. It is always a value that ends with “BR”, for example 100 BR, 3423BR, etc.

JOBCODE

Varchar

(Optional) This is the standard job code associated with the Job

STATUS

Varchar

(Optional) This is the HR Status value that triggered the integration

Custom Candidate Fields  

Field Name

Format

Note

EMAIL

Varchar

This is the candidate email address. HackerRank will send the invitation email. 

FIRSTNAME

Varchar

Candidate First Name. 

LASTNAME

Varchar

Candidate Last Name. 

HR_ACCOMMODATION

Varchar

(Optional) This field represents a time accomodation that is candidate specific. The field expects a value in percent. The percent time will be added to the test to create a candidate specific test time. For example, if the test is 1 hour, you can send in 50 to make the test 1 hour and 30 minutes.  

Custom Requisition Fields  

Field Name

Format

Note

RECRUITEREMAIL

Varchar

This is the email address of the user in BrassRing who is taking the action. This is important so that the report from HackerRank is sent to the right recruiter. Additionally, this ensures correct auditing in HackerRank. 

HACKERRANKTESTID

Varchar

This is the Test ID of the test that should be sent to the candidate. For example, the Test ID for the following test URL is 454785: https://www.hackerrank.com/work/tests/454785/questions

Send Candidate Export XML Payload Preview to HackerRank 

Once the Workbench configuration is complete, generate the sample XML and send to HackerRank for validation.

Configure the Form Import 

Setup Candidate Export XML Payload

This is the format for the Form Import XML that is sent from HackerRank out of the box. You will need to configure Workbench to create a matching XML:

<?xml version="1.0" encoding="UTF-8"?>
<Envelope version="01.00">
  <Sender>
    <Id>HRXMLEMPLID</Id>
    <Credential></Credential>
  </Sender>
  <Recipient>
    <Id />
  </Recipient>
  <TransactInfo transactType="data">
    <TransactId></TransactId>
    <TimeStamp>M</TimeStamp>
  </TransactInfo>
  <Packet>
    <PacketInfo packetType="data">
      <PacketId>1</PacketId>
      <Action>SET</Action>
      <Manifest>HACKERRANK_FORM_IMPORT</Manifest>
    </PacketInfo>
    <Payload><![CDATA[<?xml version="1.0"?>
<form formTypeId="(generated by BR)" formName="HackerRank Results" formId="" action="UpdateIndividual" resumeKey="" FirstName="" LastName="" email="" homePhone="" language="EN" autoreq="" optionalreq="">
<FormInput name="(generated by BR)" title="Assessment Name"></FormInput>
<FormInput name="(generated by BR)" title="First Name"></FormInput>
<FormInput name="(generated by BR)" title="Last Name"></FormInput>
<FormInput name="(generated by BR)" title="Percentage"></FormInput>
<FormInput name="(generated by BR)" title="Requisition ID"></FormInput>
<FormInput name="(generated by BR)" title="Date of Assessment"></FormInput>
<FormInput name="(generated by BR)" title="Link to Assessment Summary Page"></FormInput>
<FormInput name="(generated by BR)" title="Overall Score"></FormInput>
<FormInput name="(generated by BR)" title="Assessment Code/ID"></FormInput>
<FormInput name="(generated by BR)" title="Candidate Status"></FormInput>
</form>]]></Payload>
  </Packet>
</Envelope>

Custom Form Fields  

This is the status of the candidate’s results. It matches the status that is shown in HackerRank.  

Field Name 

Note

Assessment Name

This is the candidate email address. HackerRank will send the invitation email. 

First Name

Candidate First Name. 

Last Name

Candidate Last Name. 

Percentage

This is the percentage score for the candidate

Requisition ID

This is the Requisition number. It will match the BRREQNUMBER from the Candidate Export. 

Date of Assessment

This is the date of the assessment

Link to Assessment Summary

This is a link back to the test results in HackerRank

Overall Score

This is the score, in points. 

Assessment Code/ID

This is the test that was taken. 

Candidate Status

Send Form Import XML Payload Preview to HackerRank

The following fields are generated by BrassRing and will be environment-specific: 

  • formTypeID field

  • formName field

  • Each FormInput name field

Once the XML payload is created, you must send a preview XML to HackerRank so the correct identifiers can be send from HackerRank for Work.