Monday, September 29, 2014

Integrate QuestBase With Your Own Systems

We have recently added a new feature, the API Callback URL, that allows you to call a web page or script as soon as someone takes a test, passing some information. For example, if you want to capture learners' data for your database/website, you can use this new feature.

Example Use Cases of Capture API
  • Inserting lead capture into your own database such as name, email etc. of quiz taker
  • Inserting names and information for people that take the test into SugarCRM, SalesForce, or any other CRM system
  • Triggering emails or any other process on your website when someone takes the test

How It Works

First of all, you need to create a script (in any web programming language) that will accept the data sent by the quiz through REQUEST method. We already provide basic samples in .NET C# and PHP. Whenever someone takes your quiz, your callback script will be called asynchronously, and it will accept the data. After accepting the data, you can write any custom code such as inserting into your database or CRM or triggering some business logic process.

This is a two part process, where first part is to to setup the callback script URL and the second step is done on your website where you will code this script file to accept the REQUEST data.

To enable the Callback URL, go to the Properties of your publication, Options tab, Set advanced options, Callback tab, and enable it. You can choose to pass information via POST (preferred) or GET methods. Enter the exact URL of your script on your website and confirm.

There are several variables which we support and pass them to REQUEST when someone takes your quiz. This is similar to REST or SOAP API's.

You would use the REQUEST array method to capture the response information. QuestBase will call your callback URL asynchronously and will post all of these variables to that particular script. Here are the supported variables:

accesscodethe access code entered by the user, if available
cf_labelthe value of this custom field (for example, cf_company if you have a custom field labelled company)
crt_numberthe URL of the awarded certificate(s). number is the numer of the awarded certificate, for example crt_1, crt_2, etc.
enddatethe date/time (UTC, yyyy-mm-ddThh:mm:ss) when the response was completed
firstnamethe first name of the user, if available
gr_labelthe value of this custom grade (for example, gr_passed if you have a custom grade labelled passed)
idthe id of the response. This can be also used to later display this response to the user (
ipthe ip address of the user, if available
ispreviewindicates if it's a preview (1) or a real response (0)
itemidthe custom id used in SSO login, if available
lastnamethe last name of the user, if available
maxscorethe maximum score available for the publication
minscorethe minimum score available for the publication
pinthe PIN of the publication (empty if it's a preview)
scorethe score (points) got by the user
scorepercentthe score (percent) got by the user
startdatethe date/time (UTC, yyyy-mm-ddThh:mm:ss) when the response was started
statusthe status of the response (2=completed, 3=passed, 4=not passed, 5=to be graded). Other values are reserved
titlethe title of the publication
usernamethe username of the user, if available

You can download a basic sample in .NET C# and PHP to get started.