Brillium Integration via HTTP POST and GET

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.

Brillium HTTP Integration Diagram

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.

Integration Tab Settings

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 a shareable web address.

NOTE:  The Logout button label can be changed to another label and may not be "Logout".

 

TIP: For more information regarding this optional authentication method, see Authenticating Respondents with MD5 Hash Passwords.

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*

EMAIL

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:

* Indicates default values of the required status for each field. First name, last name, email address, and all ten custom fields can be set to “Required” or “Not Required” via the Edit Custom Fields form within Brillium.

 

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
&EMAIL
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, Professional, Brillium for Thinkific, and Enterprise: Substitute the term "mycompany" within the link with the name of your Brillium sub-domain. Your Brillium isntance 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: It is recommend that your method parameter be POST, unless you have a specific reason for using the GET method. Passing login information using a QueryString by using the GET method is slightly less secure than using the POST method.

Authenticating Respondents with Link Passwords (MD5 Hash Password)

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. 

Integration Tab Settings

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
Primary Key: jdoe@email.com
Combined Link Password and PrimaryKey: PASSWORDjdoe@email.com
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:  The description column information listed below is not transmitted. The size column indicates the maximum number of bytes that will be transmitted for each field.

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>
<head>
<title>MyCompany Link To Assessment</title>
</head>
<body>
<b>MyCompany Link To Assessment via Form</b><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>
Email Address: <input type="TEXT" name="EMAIL"
value="jdoe@email.com"><br>
Company: <input type="TEXT" name="CUST1" value="Doe Corporation"><br>
Address 1: <input type="TEXT" name="CUST2" value="1 Main Street"><br>
Address 2: <input type="TEXT" name="CUST3" value="Suite 500"><br>
City: <input type="TEXT" name="CUST4" value="Anytown"><br>
State: <input type="TEXT" name="CUST5" value="MA"><br>
Zip Code: <input type="TEXT" name="CUST6" value="01010"><br>
Country: <input type="TEXT" name="CUST7" value="USA"><br><br>
<input type=SUBMIT name="SUBMIT" value="Login">&nbsp;
<input type=RESET name="RESET" value="Reset">
</form>
</body>
</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 %>
<%

Option Explicit

Dim strAssessID, intRespID, strName, strEmail, strCust(11)
Dim intGrade, datStart, datFinish, intTimesTaken, intX

strAssessID = Request.QueryString("AID")
intRespID = CInt(Request.QueryString("RID"))
strName = Request.QueryString("LNAME") & ", " & _
Request.QueryString("FNAME") Integration Guide Page 11
strEmail = Request.QueryString("EMAIL")
For intX = 1 To 10
strCust(intX) = Request.QueryString("CUST" & CStr(intX))
Next
intGrade = CInt(Request.QueryString("GRADE"))
datStart = CDate(Request.QueryString("STARTDATE"))
datFinish = CDate(Request.QueryString("FINISHDATE"))
intTimesTaken = CInt(Request.QueryString("TIMESTAKEN"))

'Now that you have the fields passed from Brillium stored
' in the variables above, you can use some script to store
' the data in a database or use within an application.
%>
<html><body>

<!-- Your content here, if any. -->

</body></html>

LEARN MORE: The following links may provide helpful information to learn more about using HTTP GET and POST methods to send and receive data.