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.
Prerequisites
In HackerRank for Work | In BrassRing |
|
|
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.
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
- Log in to HackerRank for Work as a Company Admin user.
- In the home page, click the arrow next to the user icon on the top right corner of the page, and select Settings.
- Click ATS Integration, and navigate to the BrassRing option.
- Click on configure.
- Click on Generate API Key to generate a token. This will launch a popup window where you can copy the API Token.
- This will show the key. If the key has already been generated, you can just copy it directly.
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 |
|
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.