Integration using HTTP POST and GET

Optional Assessment Builder Settings:

• Assessment Logout Options → Button Label– Enter the caption that should appear on the Logout button at the end of the assessment. This is the button that will trigger the Link After Assessment URL and bring the respondent back to your Website or application.
• Assessment Logout Options → Link After Assessment  – This is the web URL (fully-qualified URL) the respondent browser will go to when the Logout button is selected at the end of the assessment. (See note below)
• Integration → Link Password – This is the password that will help to form an additional authentication layer (referred to as an MD5 hash) when a Respondent selects a link to the assessment using HTTP integration. The purpose of this is to help to ensure that the link is clicked from the website intended, specific to each respondent that selects the link, and prevent it from being an easily shareable web address.

Sending Respondents Login Information to Brillium

Field Descriptions and Recommendations

The following table contains information that may be transmitted to Brillium's login screen to facilitate the assessment login process. Note the fields size limitations for each field. Brillium will enforce these size limitations and data will be truncated if it is beyond the imposed limitation.

It is also important to note that a subset of the data below may be transmitted to Brillium. The Respondent will be prompted for any required information that is not submitted.

Contact Information

If you using the Contact Information Respondent Fields and would like to include Brillium this information when using HTTP integration, the following table identifies the field ID's.

Link Example

The following is an example link to a Brillium assessment using HTTP integration. This link is normally used in an HTML <form> tag as the action parameter.

	https://mycompany.onlinetests.app/assess.aspx?a=L2
	

Securing Integration

To aid in the prevention of assessments taken under multiple or fictitious respondent identities, Brillium's assessment Link Password feature helps to add another layer of protection towards securing access to assessment content. 

• The MD5 hash is created by concatenating the Link Password (as entered on the Integration tab in Assessment Builder) with the Respondent's Primary Key (identified in the Respondent Fields). Ensure the no spaces exist between the concatenated Link Password and Respondent Primary key. By default the Primary Key is the Respondent email address, but any Brillium Custom field may be designated as the Primary Key.
• Process the concatenated value with an MD5 hash algorithm to generate a 32- character hexadecimal string. The string is not case-sensitive.
• The assessment link will include this string as a field named "LOGINHASH".

It is important to test login to Brillium assessments thoroughly when implementing the MD5 hash login feature. You must ensure the hash is generated properly for all potential primary key values and entry hash password combinations. If the passed "LOGINHASH" field does not match the hash generated by Brillium, the respondent will not be allowed into the assessment.

Example of a Properly Formatted MD-5 Login Hash

Link Password: PASSWORD
Primary Key: jdoe@email.com
Combined Link Password and PrimaryKey: PASSWORDjdoe@email.com
Resulting MD5 Hash: 724ff5ae73a6fdb2f94bdcb34ec9d73c
    

An Example of Sending Data to Brillium via HTTP

The following example code demonstrates one method to link to the Brillium login page via a simple HTML form via POST method. The Respondent Fields in this example are visible to the respondent, but may be set to HIDDEN so the respondent only sees a button or link to the assessment.

<b>MyCompany Link To Assessment via Form</b>
<br><br>

<form name="ASSESSLOGIN" method="POST" action="https://mycompany.brillium.com/assess.aspx?a=L2">
    Assessment ID: <input type="text" name="AID" value="TEST123"><br>
    Password: <input type="text" name="APASS" value="PASSWORD"><br>
    First Name: <input type="text" name="FNAME" value="John"><br>
    Last Name: <input type="text" name="LNAME" value="Doe"><br><br>

    Email Address: <input type="text" name="EMAIL" value="jdoe@email.com"><br><br>
    Company: <input type="text" name="CUST1" value="Doe Corporation"><br><br>
    Address 1: <input type="text" name="CUST2" value="1 Main Street"><br><br>
    Address 2: <input type="text" name="CUST3" value="Suite 500"><br><br>
    City: <input type="text" name="CUST4" value="Anytown"><br><br>
    State: <input type="text" name="CUST5" value="MA"><br><br>
    Zip Code: <input type="text" name="CUST6" value="01010"><br><br>
    Country: <input type="text" name="CUST7" value="USA"><br><br><br>

    <input type="submit" name="SUBMIT" value="Login">&nbsp;
    <input type="reset" name="RESET" value="Reset">
</form>

// Example using Express-style request typing
import { Request } from "express";

function processRequest(req: Request) {
    // Query parameters (always strings | undefined)
    const strAssessID: string | undefined = req.query.AID as string;

    const intRespID: number = Number(req.query.RID);

    const strName: string = `${req.query.LNAME}, ${req.query.FNAME}`;
    const strEmail: string | undefined = req.query.EMAIL as string;

    // Array for custom fields (index 1–10 to match VBScript behavior)
    const strCust: (string | undefined)[] = new Array(11);

    for (let intX = 1; intX <= 10; intX++) {
        strCust[intX] = req.query[`CUST${intX}`] as string;
    }

    const intGrade: number = Number(req.query.GRADE);

    const datStart: Date = new Date(req.query.STARTDATE as string);
    const datFinish: Date = new Date(req.query.FINISHDATE as string);

    const intTimesTaken: number = Number(req.query.TIMESTAKEN);

    // At this point, the variables contain the values passed from Brillium
    // You can now persist them or process them as needed.

    return {
        strAssessID,
        intRespID,
        strName,
        strEmail,
        strCust,
        intGrade,
        datStart,
        datFinish,
        intTimesTaken
    };
}