These common Internet methods make it easy to integrate Brillium data with most any website or web application using HTTP POST (via Form) or GET (via QueryString)
Introduction
Most customers integrating with Brillium do so using common web technologies such as ASP.NET, Java Server Pages (JSP), PHP, or secure CGI scripts.
The following diagram summarizes a typical integration flow. Integration can and may be more complex (involving encryption and/or multiple applications), so this serves as only a reference model. In the diagram, the word Customer indicates the client or third party software being integrated with the Brillium service. The word Brillium indicates a screen or process within the Brillium application.
Configuring Brillium for HTTP Integration
Brillium Settings [Required]
In order to properly establish communication between Brillium and your Website, application, or database, you MUST configure the following settings for each assessment. These settings are found on the Integration tab in Assessment Builder maintained within the Brillium Assessment "Advanced Options" page. They may be set during the original creation of the assessment, or they may be changed any time thereafter.
Mandatory settings:
- Integration Method – This field defaults to "None", which indicates no data will be transmitted to Brillium from an external site or application when a respondent comes to enter an assessment. Change this to "POST (via Form)" if your application will send login information to Brillium within an HTML form that is posted to the Brillium assessment engine. Change this to "GET (via QueryString)" if your application will send login information to Brillium within the link clicked by the respondent (i.e. on the QueryString).
- Postback Method – This field defaults to "None", which indicates no data will be sent from Brillium to your Website, application, or database result script when the respondent reaches the summary page of their assessment. Change this to "Blind Post" if you would like Brillium to send result summary information to your integration script without returning anything from the script. Change this to "Post and Return" if you would like Brillium to send result summary information to your integration script and also display returned data or messages to the respondent at the bottom of their result summary page. This returned data may be a custom message or custom scoring report you would like to display to the respondent depending on their results.
- Postback URL – Enter the Web address (fully-qualified URL) the summary results will be sent to when the respondent reaches the summary page of their assessment (i.e. when they have completed their assessment and a score has been issued). The respondent will not see the communication between Brillium and the script specified.
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.
Note
Tip
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.
| Field ID | Description | Size | Required |
| AID | Assessment Identifier | Text (25) | Yes |
| APASS | Assessment Password | Text (25) | Yes |
| FNAME | Respondents First Name | Text (50) | Yes* |
| LNAME | Respondents Last Name | Text (50) | Yes* |
| Respondents Email Address | Text (255) | Yes* | |
| CUST1 | Custom Field 1 (FIELD1) | Text (255) | No* |
| CUST2 | Custom Field 2 (FIELD2) | Text (255) | No* |
| CUST3 | Custom Field 3 (FIELD3) | Text (255) | No* |
| CUST4 | Custom Field 4 (FIELD4) | Text (255) | No* |
| CUST5 | Custom Field 5 (FIELD5) | Text (255) | No* |
| CUST6 | Custom Field 6 (FIELD6) | Text (255) | No* |
| CUST7 | Custom Field 7 (FIELD7) | Text (255) | No* |
| CUST8 | Custom Field 8 (FIELD8) | Text (255) | No* |
| CUST9 | Custom Field 9 (FIELD9) | Text (255) | No* |
| CUST10 | Custom Field 10 (FIELD10) | Text (255) | No* |
| CUST11 - CUST20 | Custom Fields 11 through 20 are also denoted as FIELD11 through FIELD20 as above. | Text (255) | No* |
| LOGINHASH | Combination of the optional Link Password and the Respondents Primary Key | Text (32) | No |
Note
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.
| Field ID | Description | Size | Required |
| ORGNAME | Respondent’s organization or company name. | Text (100) | Optional |
| POSITION | Respondent’s position or title. | Text (100) | Optional |
| DEPT | Respondent’s department or group. | Text (100) | Optional |
| ADDR1 | Respondent’s mailing address row one. | Text (100) | Optional |
| ADDR2 | Respondent’s mailing address row two. | Text (100) | Optional |
| ADDR3 | Respondent’s mailing address row three. | Text (100) | Optional |
| CITY | Respondent’s mailing address city. | Text (100) | Optional |
| STATE | Respondent’s mailing address state or province. | Text (100) | Optional |
| POSTALCODE | Respondent’s mailing address postal or zip code | Text (50) | Optional |
| COUNTRY | Respondent’s mailing address country. | Text (100) | Optional |
| PHONE | Respondent’s phone number. | Text (50) | Optional |
| FAX | Respondent’s fax number. | Text (50) | Optional |
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
Sending Data via GET QueryString Parameters
When sending data via QueryString parameters, append each data field parameter shown above after the "a=L2" within the link. For example:
https://mycompany.onlinetests.app/assess.aspx?a=L2&aid=ASSESMENTID&key=ASSESSMENTKEY&FNAME=Joe&LNAME=Baxter&EMAIL=joe@email.com&CUST1=Boston&CUST2=Jamaica Plains
Breaking down the example above, the following information is passed into Brillium:
https://mycompany.onlinetests.app/assess.aspx | This is the main body of the link. In this example, "mycompany" is the Brillium subdomain for your Brillium account. |
?a=L2 | This tells Brillium this assessment is integrated via HTTP method |
&aid | The Brillium Assessment ID |
&key | The Brillium assessment Key (or Password) |
&FNAME | The First Name - Respondent Field |
&LNAME | The Last Name - Respondent Field |
| The Email Address - Respondent Field | |
&CUST1 | The CUSTOM1 - Respondent Field (FIELD1) In this example, it is a open input field that asks for a City |
&CUST2 | The CUSTOM2 - Respondent Field (FIELD2) IN this example, it is a open input field that asks for a neighborhood |
Note
Brillium Personal/Basic, Professional, Brillium for Thinkific, and Enterprise: Substitute the term "mycompany" within the link with the name of your Brillium sub-domain. Your Brillium instance sub-domain is the first part of the domain name after "https://"
Brillium Server Edition Customers: The link will be the URL of your Brillium web server installation with "assess.aspx?a=L2" appended to the end.
Ensure that the "?a=L2" is included at the end of the link. This tells Brillium that the Respondent Information will be provided in the URL and the Respondent will go directly into the assessment, bypassing the login screen.
Tip
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.
By specifying a Link Password on the Assessment Builder Integration tab, Brillium will expect the Assessment ID, Password, and user login credentials to be included within the assessment URL. The Link Password is a 32-character hexadecimal string of characters (MD5 hash) is composed of the combined assessment password and Respondent Primary Identifier (email address by default). Assessment links that do not include a properly "MD5 hashed" password will fail to authenticate with the Assessment and result in an error.
Creating the 32-character MD5 hash password value
- 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
Below is an example of an MD-5 hash password using the Respondent’s Primary Key (in the example it is an email address) combined (i.e. concatenated) with the Link Password
Pre-Hash: LOGINHASH Value:
Link Password: PASSWORD<br>Primary Key: jdoe@email.com<br>Combined Link Password and PrimaryKey: PASSWORDjdoe@email.com<br>Resulting MD5 Hash: 724ff5ae73a6fdb2f94bdcb34ec9d73c
Receiving Respondents Assessment Results from Brillium
Handling Return Data
The following contains the information that can be transmitted from Brillium when the Logout button is selected from the Feedback screen at the end of the assessment. This information is transmitted to the Postback URL defined on the Feedback tab of Assessment Builder. The data is transmitted via the HTTP POST or HTTP GET method in accordance with the Postback Method selected on the Feedback tab of Assessment Builder.
When creating a web page to receive the data coming from Brillium, you will need to reference the name in the Field ID column. The description column information is not transmitted, and the size column indicates the maximum number of bytes that will be transmitted for each field.
Note
Field ID | Description | Size |
AID | Assessment Identifier | Text (25) |
RID | Respondent’s unique identifier assigned by the Brillium software. | Integer |
FNAME | Respondent’s First Name | Text (50) |
LNAME | Respondent’s Last Name | Text (50) |
EMAIL | Respondent’s Email Address | Text (255) |
CUST1 | Custom Field 1 | Text (255) |
CUST2 | Custom Field 2 | Text (255) |
CUST3 | Custom Field 3 | Text (255) |
CUST4 | Custom Field 4 | Text (255) |
CUST5 | Custom Field 5 | Text (255) |
CUST6 | Custom Field 6 | Text (255) |
CUST7 | Custom Field 7 | Text (255) |
CUST8 | Custom Field 8 | Text (255) |
CUST9 | Custom Field 9 | Text (255) |
CUST10 | Custom Field 10 | Text (255) |
GRADE | Respondent’s Grade/Score | Integer |
STARTDATE | Respondent’s Start Date/Time | Date |
FINISHDATE | Respondent’s Finish Date/Time | Date |
TIMESTAKEN | Number of times respondent has completed this particular assessment. | Integer |
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.
Example HTML File - Sending Data to Brillium via HTTP POST
<html><br><head><br><title>MyCompany Link To Assessment</title><br></head><br><body><br><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"<br>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"> <br><input type=RESET name="RESET" value="Reset"><br></form><br></body><br></html>
Receiving Data from Brillium
The following example web page code demonstrates how to receive the data from Brillium after a respondent has completed an assessment. This data can then be populated into most any database.
This example is written in Microsoft ASP Classic Visual Basic for ease of readability, but can be written using any modern web scripting language. This code has been simplified and does not contain any error or bounds checking, as would be typically found in a production environment.
Example Visual Basic Code
<%@ Language=VBScript %><br><%<br><br> Option Explicit<br><br> Dim strAssessID, intRespID, strName, strEmail, strCust(11)<br> Dim intGrade, datStart, datFinish, intTimesTaken, intX<br><br> strAssessID = Request.QueryString("AID")<br> intRespID = CInt(Request.QueryString("RID"))<br> strName = Request.QueryString("LNAME") & ", " & _<br> Request.QueryString("FNAME") Integration Guide Page 11<br> strEmail = Request.QueryString("EMAIL")<br> For intX = 1 To 10<br> strCust(intX) = Request.QueryString("CUST" & CStr(intX))<br> Next<br> intGrade = CInt(Request.QueryString("GRADE"))<br> datStart = CDate(Request.QueryString("STARTDATE"))<br> datFinish = CDate(Request.QueryString("FINISHDATE"))<br> intTimesTaken = CInt(Request.QueryString("TIMESTAKEN"))<br><br> 'Now that you have the fields passed from Brillium stored <br> ' in the variables above, you can use some script to store <br> ' the data in a database or use within an application.<br>%><br><html><body><br><br><!-- Your content here, if any. --><br><br></body></html>