Using HACP

Applies to the following products: 
Questionmark OnDemand
Questionmark Perception
Questionmark OnPremise
Applies to the following Perception versions: 
Perception 5.7
Perception 5.4
Perception 5.2
Perception 5.1

The core of HACP consists of 5 steps:

  1. The student access the CMI and selects, or is assigned, an AU to take. The LMS calls the URL of the AU complete with start-up parameters, that is a unique assessment ID for this interaction and a URL which the AU can use to communicate with the LMS.
  2. The AU calls the URL of the LMS, passing the unique assessment ID and requests details of the AU to run. The LMS returns these details to the AU.
  3. The AU then presents the course or test to the user, who interacts with the AU until the course or test is finished.
  4. When the AU is finished it sends performance data to the LMS, for instance the status of the test, the score achieved, the time take etc.
  5. The AU then sends an additional message to the LMS indicating that it is finished.

The Questionmark AICC interface adds onto PIP to make the connection.

How PIP works with HACP

When an HACP course or test is defined in a LMS, the URL of session.php is given, with the PIP call appended as a query string, for example:

http://<domain name>/perception5/session.php?CALL=aicc_file

...where <domain name> is the domain name for your Questionmark area. This is used to make the call that launches the Questionmark assessment, as in the first step of the HACP core.

PIP will then be started using the settings in the defined file and will receive 2 additional parameters:

  • AICC_SID - The unique ID to identify this HACP session
  • AICC_URL - The URL of the LMS to be used for subsequent HACP communications

Questionmark will receive the data in the form:


The [Input] section of the PIP file may be used to map differently named parameters to these names if necessary. Any additional information required, for example the Questionmark assessment ID, PIP file password etc., must also be defined so that it can be sent to Questionmark. These are often referred to as vendor parameters, and will be sent to Questionmark when it requests the start-up information. Questionmark then makes a call to the LMS URL it received using the AICC GetParam call.

The call is made using the POST method, with a header of:

Content-Type: application/x-www-form-urlencoded

...and the data as defined in the [AICC Get] section of the PIP file, for example:


...the LMS will then return the additional vendor parameters and these will be mapped to the input parameters as in an ordinary PIP call.

On completion of the Questionmark assessment, PIP will again call the LMS URL, this time using the data as defined in the [AICC Put] section.

Topic information

In addition to the data defined in the [AICC Put] section, information about the names of, and scores for the topics, from which questions that the participant saw were drawn, can also be sent back to the LMS URL. This functionality needs to be explicitly turned on by a setting in the PIP file used to configure the PIP session.

The setting UseAICCTopics must be placed in the [Settings] section of the PIP file. The value for this setting can be yes or no. To enable this functionality the setting should have a value of yes as in the example below:



If set to yes, then at the end of the assessment, when Questionmark passes information back to the calling program, it will include three name/value pairs for each topic from which questions were drawn in the assessment. The three name/values that are passed back for each topic are shown below (The x will be replaced with a number starting at 1 and incrementing by one for each topic.):

Identifier Purpose Example
J_ID.x This is an identifier for the topic and will have a value of the topic name.

If an assessment included questions from two topics (Topic_A and Topic_B), then these J_ID.x name value pairs will be passed out by Questionmark:

J_ID.1 = Topic_A

J_ID.2 = Topic_B

J_Score.x This will have assigned to it the value of the score for the topic identified by the value of J_ID.x.

If the values below were returned:

J_Score.1 = 5,10,0

J_Score.2 = 10,20,0

This would indicate that the participant had achieved:

For Topic_A A score of 5 out of a maximum possible of 10 and a minimum of 0

For Topic_B A score of 10 out of a maximum possible of 20 and a minimum of 0


This is a completion status for the topic. Valid AICC values for this parameter are:

  • pass
  • completed
  • fail
  • incomplete
  • not attempted
  • browsed

Questionmark will always set this parameter to completed:

J_Status.1 = completed

J_Status.2 = completed

These groups of three name/value pairs will be returned in a section called [Objectives_Status]. Thus, using the values in the examples above, the complete response for the AICC topic scoring section of the response would look like this:


J_ID.1 = Topic_A

J_Score.1 = 5,10,0

J_Status.1 = completed

J_ID.2 = Topic_B

J_Score.2 = 10,20,0

J_Status.2 = completed

AICC core data

In addition to sending the data defined in the [AICC Put] section and optionally the topic information, the following AICC core data will also be sent to the LMS URL:

Core data Description
lesson_location The stage reached in the lesson or test. Questionmark sets this to end.

If the LMS passed a parameter Mastery_Score to Questionmark, and if this had a value greater than 0, then Questionmark will compare the percentage score achieved with the mastery score. This will be set to:

  • passed - If the score is greater than or equal to the mastery score
  • failed - If the score is less than the mastery score
  • completed - If no mastery score parameter was received, or if it was 0

For more information about defining your own AICC lesson_status, please refer to the Using HACP below.

score This will be set to the percentage score achieved for the assessment.
time This will be set to the time between the start and finish of the assessment, in the format 'hours:minutes:seconds'.

This core data is appended to the data defined in the [AICC Put] section of the PIP file as the value of the aicc_data parameter, preceded by the keyword [Core] and with each of the elements separated by a carriage return (0D0A in hex). The data is URL encoded (for example, carriage returns are converted to %0D%0A). For example if a LMS called a Questionmark assessment and specified a mastery score of 50, and the student achieved a score of 51%, and took 1 minute 30 seconds to complete the assessment, then the following data will be sent:

command=PutParam&version=2.0&session_id=2&aicc_data=[Core]%0D lesson_location=end%0Dlesson_status=passed%0Dscore=51%0D time=00:01:30

Finally, Questionmark will send an ExitAU message to the LMS, to signify that the AU has finished, sending the data as defined in the [AICC Exit] section of the PIP file, for example:


If the LMS itself controls the finish of the AU, then the final ExitAU message may be suppressed by an entry in the [Settings] section of the PIP file.

When calling Questionmark from an LMS via AICC, there can be a situation with some LMSs where you do not want Questionmark to return the score parameter to the LMS. If you need this, you can make a new setting in the PIP file [Settings] section of UseAICCScore. If you set UseAICCScore=no, then the score parameter is not sent when returning results to an LMS. Its default value is yes if not present.

AICC status data

Status data Description
AICCStatusPass The default lesson status passed by AICC is "passed".
AICCStatusFail The default lesson status passed by AICC is "failed".
AICCStatusOther The default lesson status passed by AICC is "completed".

Each of the default statuses can be modified in a PIP file be setting the preferred values in the [Settings] section. For example:




AICCStatusOther= None

Some LMSs calling Questionmark via AICC use the lesson_status parameter returned from Questionmark. The usual value for this is that if a mastery score was not set, Questionmark returns completed. If a mastery score was set by the LMS when calling Questionmark, then if the score exceeds the mastery score, Questionmark returns passed, and otherwise Questionmark returns failed. You can now make settings in the PIP file to change the values passed. These all go in the [Settings] section of a PIP file (as shown above):

  • The value AICCStatusPass defines the text to be used for the lesson_status parameter if score >= mastery score, defaults to passed if not present.
  • The value AICCStatusFail defines the text to be used for the lesson_status parameter if score < mastery score, default to failed if not present.
  • The value AICCStatusOther defines the text to be used for the lesson_status parameter if no mastery score was set, defaults to completed if not present.

If no mastery score was defined a status of "completed" is passed.