Introduction to PIP

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

In Questionmark, the word assessment is used to describe a test, survey, quiz, exam, or other assessment.

The word participant is used to describe a student, employee, or other type of person who takes the assessment. The smallest unit of interaction with Questionmark is a participant taking an assessment. Assessments are delivered by a Questionmark program called session.php, as follows:

  1. The assessment is started by a call to session.php. The minimum information session.php needs is the identity of the assessment and the name of the participant. Other information including the name of a group can also be passed.
  2. The first action of the session.php program is to check that the attempt to call it is valid, for example that the assessment exists and that there is permission for this participant to do the assessment. If the call is not valid, session.php will return an Access Denied message.
  3. For a valid assessment, the first block of the assessment is then sent to the participant. A block consists of a single HTML document, containing one or more questions.
  4. The participant then submits answers to the first block. Depending on assessment settings, the participant may then be sent feedback to that block. And after viewing this, if the assessment has more than one block, additional blocks will be sent.
  5. An assessment ends when all blocks have been delivered (or it is also possible for jumps within a assessment to skip over blocks). At this point a final page is generated and sent to the participant. The contents of the final page can vary with the score the participant achieves. And the final page can contain a link to another assessment or to a URL. An assessment only finishes if this step is reached. If an assessment is abandoned by a participant, for example by closing down their browser before submitting answers, the assessment is unfinished.

In normal operation of Questionmark, participants access Questionmark by using either open.php or perception.php, which themselves call session.php at the first step above. PIP does two things:

  • It permits a valid, direct call to session.php to be made at the first step above. So another program can securely arrange for an assessment to be run. Alternatively, PIP can make calls to perception.php.
  • It gives a way of calling another program at the end of an assessment at the last step above. For example the calling program can be called to be told the results of the assessment. Or an independent program can be called at the end of an assessment, for example to print out a certificate or send an email if the participant is successful.

A PIP call is a URL call to a gateway file or another program with a CALL parameter specifying a PIP file. All PIP calls are made by HTTP, which is the protocol used on the internet and on intranets. The program calling or being called by Questionmark can be on the same computer as the one Questionmark is running on, or a different one. It's possible for example to use PIP to call Questionmark from a UNIX or other non-PC system.

PIP files are ASCII files that can be edited in any text editor. The following is an example PIP file that calls session.php passing an assessment ID of an assessment.

[Input]

NAME="PIP"

GROUP="Testing"

DETAILS="Perception Integration Protocol"

SESSION="4117626686784785"

[Settings]

UseNotify=no

Calls to perception.php

When calling perception.php, the PIP call must pass the participant name, if the name is not found an Access Denied message will be given. If the name matches that of a participant, a list of assessments scheduled for that participant will be generated. Each of these entries will consist of the same parameters passed in, plus an additional SESSION parameter matching the assessment. Any checksum will be recalculated to include this additional parameter, using whatever method and security is specified in the PIP file.

Starting an assessment from perception.php in this way is functionally equivalent to calling session.php with the assessment ID. Although perception.php does not invoke the callback mechanism, this is still done when session.php handles the resulting PIP call. 

Process diagram

The diagram below shows how PIP usually works. A third-party application calls PIP passing some information, and then PIP returns the results to the calling application.

Starting an assessment

There are a number of different ways of using PIP to start an assessment. The simplest method is just to put the information needed to start the assessment on the command line, but it's also possible to pass this information invisibly via HTTP, which is more work to set up, but is more secure. The options are described in the following table.

Method Description Advantages Disadvantages
Direct call from a program or HTML page (without checksum) Assessment and participant name are passed on command line.

Extremely easy to do.

All Questionmark information available to pass back at end of the assessment.

Offers very little security, not much different to directly calling open.php.

Participant could capture URL and use in another way or change participant name without difficulty.

Direct call from a program or HTML page (with checksum) Assessment and participant name are passed on command line, but a checksum with a secret key is used to make it difficult for these to be interfered with, or a call made from another source.

Easy to do.

All Questionmark information available to pass back at end of the assessment.

Only moderate security.

Command line parameters are visible although they can be protected by a checksum.

PIP callback Rather than passing information on the command line, PIP obtains its information via direct HTTP communication with the calling program.

Good security.

All Questionmark information available to pass back at end of the assessment.

Moderate development effort required.

AICC integration Calling parameters are exchanged via AICC HTTP protocol.

Good security.

You can use the same method to call other AICC compatible applications.

Moderate development effort required (perhaps slightly more than implementing PIP callback).

Limited Questionmark information available to pass back to calling program at end of the assessment.

For many users of Questionmark, it is best to use a direct call from a program or HTML page (with checksum) because it offers a good balance between security and ease of implementation. You pass the parameters on the command line, which is simple to program, but you use a checksum with a secret key, which makes it non-trivial for people to do the same call themselves. The security could be broken reasonably easily by someone who wants to, but will not usually be. For full security, you should use either PIP callback or AICC integration.

Security with PIP is enabled by adding a [Security] section to the PIP file being used. A PIP file without a [Security] section may compromise the security of assessments.

Calling a program at the end of an assessment

As well as using PIP to start an assessment, PIP also allows a call to a program at the end of an assessment. This call is performed by the server using HTTP. After the assessment's results are written to the repository, the server makes the call direct to the program. The participant does not see this call happen - it all happens in communication between the server and called program.

You can pass back lots of information at the end of the assessment, including the assessment score. You can also pass back the result index for the assessment's results in the repository. If the repository is accessible to the called program, this will allow it to get the full details of the assessment, including the answers to each question. If you are using the AICC support in PIP for integration purposes, then the information you can pass back is limited to the score achieved, a breakdown of topic scores and the time taken. You can do this whether or not PIP starts the assessment.