Copyright © 1998-2014 Questionmark Computing Ltd. All rights reserved. Questionmark and Perception are either registered trademarks or trademarks of Questionmark Computing Ltd in the United States of America and the United Kingdom and other countries. Microsoft, Windows 2000, Windows 2003, Windows XP Windows Vista, Windows 7 and Windows Server 2008 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Adobe, Adobe Flash and Adobe Captivate are registered trademarks of Adobe. Other product and company names mentioned herein might be trademarks of their respective owners. VERSION 1.8

Table of Contents Welcome ............................................................................................................................7 Introduction to PIP ...........................................................................................................9 Calls to perception.php .........................................................................................................10 Process diagram ...................................................................................................................10 Starting an assessment .........................................................................................................10 Calling a program at the end of an assessment ......................................................................11 Configuring Perception to use PIP ..................................................................................13 Calling session.php ...............................................................................................................13 Using callback ......................................................................................................................14 Calling a program at the end of an assessment ......................................................................14 Assessment monitoring .........................................................................................................15 Branching to another assessment when using PIP ..................................................................15 Disabling PIP ........................................................................................................................15 PIP Logging ..........................................................................................................................16 Working with PIP files ....................................................................................................17 PIP file server variables .........................................................................................................17 [Callback] settings ................................................................................................................18 [Input] settings ....................................................................................................................18 Input parameter mapping ..................................................................................................19 Other inputs ......................................................................................................................19 [Output] settings ..................................................................................................................20 Server variables that can be used as output parameters ......................................................21 Demographic data .............................................................................................................21 Output parameter mapping ................................................................................................22 [Security] settings ................................................................................................................22 Calculating the checksum...................................................................................................24 HMAC-SHA256 ............................................................................................................24 MD5...........................................................................................................................25 Verifying the checksum in PIP NOTIFY calls .....................................................................25 [Settings] settings ................................................................................................................25 Control settings .................................................................................................................25 Topic scoring settings ........................................................................................................26 Home button settings ........................................................................................................27 Questionmark Secure settings ............................................................................................28 AICC support in PIP ........................................................................................................31 Using HACP ..........................................................................................................................31 How PIP works with HACP .................................................................................................31 Topic information ..............................................................................................................32 AICC core data ..................................................................................................................33 AICC status data ...............................................................................................................34 PIP file entries for AICC.........................................................................................................34 Example PIP files ............................................................................................................37

perception.pip ......................................................................................................................37 qs.pip ..................................................................................................................................38 Collecting demographic data .................................................................................................38 Creating an HTML page .....................................................................................................39 Creating a PIP file .............................................................................................................40 Using the HTML page ........................................................................................................41 Creating a report ...............................................................................................................41 Appendix .........................................................................................................................43 Troubleshooting ...................................................................................................................43 Finding more information ......................................................................................................43 Enterprise Manager ...........................................................................................................43 Enterprise Reporter ...........................................................................................................44 QMWISe ...........................................................................................................................44 Contacting Questionmark ......................................................................................................44

Welcome Perception Integration Protocol (PIP) is a secure, programming-level interface to Questionmark. This guide describes how to use PIP and is divided into: 

Introduction to PIP



Configuring Perception to use PIP



Working with PIP files



AICC support in PIP



Example PIP files



Appendix 

Finding more information



Troubleshooting



Contacting Questionmark

7

Introduction to PIP 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 Perception Server 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"

9

[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 in the repository, 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. An example PIP call might look like the one below: http://www.xyzcompany.com/q/perception.php?CALL=mypip.pip&name=Steven

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.

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.

Only moderate security.

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

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

Good security.

Moderate development effort required.

10

Extremely easy to do. All Perception information available to pass back at end of the assessment.

All Perception

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.

Method

Description information via direct HTTP communication with the calling program.

AICC integration Calling parameters are exchanged via AICC HTTP protocol.

Advantages

Disadvantages

information available to pass back at end of the assessment. Good security.

Moderate development effort required (perhaps You can use the same method to call slightly more than implementing PIP other AICC callback). compatible applications. Limited Perception 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.

11

Configuring Perception to use PIP To configure Perception to use PIP, you must first create a PIP file. PIP files are ASCII files with the extension .pip, and are similar in format to Windows INI files. You can edit PIP files in any text editor. If you have Office XP or later installed on the operating systems, double-clicking a PIP file will result in Windows presenting you with a warning message. This is because Microsoft Office uses files that also have a .PIP extension. If you are sure that the file you are trying to edit is a PIP file and not an Office file then it is safe to edit the file in a text editor. PIP files for each repository are stored on the Perception Server in the following default folder. C:\Perception5\Repositories\shared\\pip ...where is the name of your shared repository. Once you have created your PIP file, you can use PIP to: 

Call session.php directly



Use callback

 

Call a program at the end of an assessment Use the AICC support of PIP

 Branch to another assessment at the end of an assessment These tasks are described in the following sections.

Calling session.php The most common approach is to make a direct call to session.php, adding the parameter: CALL= Where pip file is a PIP file name (this can be blank). You can put the .pip extension in or not as you choose. If you leave the PIP file name blank, then the default PIP file is used. For example, these might be possible calls: http://www.questionmark.com/perception5/session.php?CALL=mypipfile.pip http://www.questionmark.com/perception5/session.php?CALL=mypipfile You then add further parameters on the command line, for example the Assessment ID and Participant Name. Thus the call will look similar to: http://www.questionmark.com/perception5/session.php? CALL=mypipfile&SESSION=1234567890123456&NAME=MyName This call will use the PIP file mypipfile.pip, and will pass in the Assessment ID and Participant Name into the call. If a PIP call includes an EXPIRES parameter and this parameter specifies a time earlier than the time when an PIP call to session.php is made, then session.php will not run the defined assessment. The EXPIRES parameter should be in the format: DD:MM:YYYY:HH:MM An example call using the EXPIRY parameter would be: http://www.questionmark.com/perception5/session.php? CALL=mypipfile&SESSION=1234567890123456&NAME=MyName&EXPIRY=31:10:2010:13:00 If this call is made after 13:00 on the 31st of October 2010 an Access Denied error message will display, because the possible time period for this call to occur has expired.

13

Using callback A variant of calling session.php directly is to use callback to obtain the parameters instead of passing them on the command line. The URL of a program to call is either passed on the command line or stored in the PIP file. This program is then called by session.php to obtain the Assessment ID and Participant Name, and is usually also called later to pass information back on the results of the assessment. This communication happens directly between the server and the called program by HTTP, and so is not usually vulnerable to interception by the participant.

Calling a program at the end of an assessment It's also possible to use a PIP file to call a program at the end of an assessment without calling the session from PIP. To do this: 1.

Use Assessment Editor within Authoring Manager to edit the assessment outcome from which you want the call to happen. If you want it to happen for all assessment outcomes, then you need to make the change to each assessment outcome.

2.

Edit the branching settings for the assessment outcome to Branch to another program or URL. Set the URL to be: CALL= Where is the name of your PIP file.

3.

You can add other parameters in the URL, including the name of the program to call. For example: CALL=mypipfile&NOTIFY=http://www.questionmark.com/enterprise/pip_log.asp This will use mypipfile.pip and make it call the pip_log.asp program. Because such a call happens from within Perception, passwords and checksums are not needed to validate internal PIP calls made this way, whatever the settings in the PIP file. The assessment outcome PIP file is only used if the assessment is not already using a PIP file. If the assessment is started with a PIP file, then any reference to a PIP file in the assessment outcome is ignored.

14

Assessment monitoring Assessment monitoring means that a Perception administrator needs to login prior to a participant starting an assessment. This would be done by an administrator who is proctoring or invigilating the assessment and would be used to allow the administrator to confirm the identity of the participant before they start the assessment. Monitoring can be invoked when starting an assessment using PIP by passing a parameter called MONITOR with a value of 1. This can be passed on the command line URL with other parameters, or in the PIP file, or from a callback. If no MONITOR parameter is passed at the beginning of a PIP assessment the assessment may still require monitoring if this has been set as required when the assessment was created. If an assessment was started from PIP and group information was passed, then the group name will be checked to see if it corresponds with a group in the repository. If it does then the monitor will be required to either an authoring owner of that group and to have permission to monitor schedules in that group or be an administrative user with monitoring permission for all groups. If the PIP group does not corresponds to an existing group (that is, the group was passed for reporting purposes only) then any user with monitoring permission will be able to monitor the assessment.

Branching to another assessment when using PIP It is possible to branch to another assessment when using PIP. If you plan on doing so, there are a few things to keep in mind: 

Only the results of the first assessment are passed back to the Learning Management System. The consequent assessment results are only stored in Questionmark.



The PIP branching applies to both SCORM 1.2/2004 and AICC



If you use the USEHOME=1 setting, only the Home button on the final assessment will have this functionality, and the previous assessment will show a Next Assessment button at the end



If you are using a Javascript based API to communicate with your LMS (SCORM), the result data is passed back to the LMS when the window is closed (via the Close button or the if the browser window is closed) For more information regarding branching to another assessment, please refer to: How can I branch an assessment to go to another assessment or repeat itself?

Disabling PIP If you do not want PIP to be available in Perception, you can disable it by making a change to Perception's configuration. To do this: 1.

Login to Enterprise Manager as an administrator who has rights to access the Server Settings screen

2.

On the Server Settings screen, check Disable PIP

3.

Click the link to Save and Exit

4. Confirm that you want to make the changes by clicking OK in the pop-up box PIP will now be disabled and any attempt to launch an assessment with a call to session.php using PIP will be responded to with an Access Denied message and an entry in the Perception log file will show: PIP request denied. PIP is disabled.

15

PIP Logging To enable logging for PIP you will need to apply the setting in the Server Setting page in Enterprise Manager. To enable PIP logging place a check in the following setting and click Save and Exit: PIP log files If this is set, and logging isn't disabled, then a pip.log file will be created in your logs directory giving detailed information about PIP calls. This log file is very useful in troubleshooting, and we strongly recommend you make this setting while developing your PIP application. You can turn it off once your application is proven.

16

Working with PIP files PIP files settings are divided into the following sections: 

See "[Callback] settings" on page 18



See "[Input] settings" on page 18



See "[Output] settings" on page 20



See "[Security] settings" on page 22

 See "[Settings] settings" on page 25 The settings in each section are described in this chapter. (For information on PIP files that use AICC, please refer to AICC support in PIP.) PIP files use the same syntax as Windows .ini files, and are divided into sections. Each section contains entries in the following format. [Section name] Name=Value ; this is a comment Where [Section name] is the name of the PIP file section.

PIP file server variables For assessments started with PIP, all entries in the PIP file are available to question, assessment and template authors as PIP file server variables. All entries in the PIP file can be referenced using server variables of the format: %PIP.section.entry% ...where entry is the PIP file entry's name in the section of the PIP file in which the entry can be found , and section is [Input], [Output], [Settings] or [Security] according the section if the PIP file in which the entry can be found. For example, a PIP file may have the following entries. [Input] NAME=User_Name GROUP=User_Group In this case, the values passed in to the PIP call for the settings User_Name and User_Group can be accessed by using the server variables %PIP.INPUT.NAME% and %PIP.INPUT.GROUP% in question, assessment and template content. In addition you can use the following server variable: %PIP.PARAMETERS.parameter_name% ...where parameter_name is the is the name of any parameter that has been passed into PIP, set by PIP, returned to PIP by a callback function or mapped by PIP from another variable.

17

[Callback] settings This section defines what information is to be sent to the notify URL when callback is used. The notify URL (specified in the [Settings] section) will receive this information and can respond by returning any extra parameters as name value pairs. For example: SESSION=123456789012345&NAME=User&GROUP=testing These extra parameters will be used in addition to those passed on the command line or contained in the [Input] section. CHECKSUM A checksum may also be used in the [Callback] section and the [Output] section to validate the data being passed from PIP to the notify URL (specified in the [Settings] section) by setting an entry to have the value %CHECKSUM%. The checksum is calculated using the values of all entries and is always added to the end of the data, for example: [Output] 

User_Name="User"



Checksum=%CHECKSUM%

 User_Group="Group" This will send the output: USER_NAME=User&USER_GROUP=Group&CHECKSUM=940 If the security KEY is set, this will be added to the end of the data values and included in the checksum.

[Input] settings The parameters passed into session.php are defined by the contents of the [Input] section of the PIP file and the contents of the command line used to call session.php. The SESSION parameter must be defined on the command line or in the [Input] section for calls to session.php. This is because session.php can only run if it can identify which assessment to run. And you should usually define one or both of the NAME or GROUP parameters to identify the participant. If the SESSION parameter is not included in a call to perception.php, the assessment list for the specified participant will be shown. You can provide values for any of the ten special fields in the repository by either providing values for the parameters S1 to S10 in the PIP file, or by passing values for these settings on the command line. (An example of collecting demographic data is given in this document.) You can also pass a NOTIFY parameter (in the [Settings] section) and ACCESS and PASSWORD parameters (in the [Security] section) and other external parameters which are simply passed into session.php and passed out the other end. The [Input] section can also define any mappings you may require between the parameters passed to session.php in the PIP call and the standard Perception parameter names. This can be useful if you are calling session.php from a third party product that is configured to pass values with different parameter name to the ones that Perception is expecting. When you define a mapping in the [Input] section the Perception parameter name is on the left, the name of the parameter passed in by the third party product is on the right. So, for example, the following entry in the [Input] section of the PIP file: SESSION=Lesson_ID

18

will configure session.php to take the value of the parameter Lesson_ID passed to it on the command line and assign it to the Perception parameter SESSION. Therefore, calling: session.php?CALL=mypipfile&Lesson_ID=1234567890123456 ... will be the same as calling: session.php?CALL=mypipfile&SESSION=1234567890123456 Parameters may also be assigned values enclosed in quotes. Enclosing a value in quotes in the [Input] section of the PIP file indicates that you are not defining a mapping but actually providing a static value to be assigned to the parameter. So, for example, the entry: SESSION="1234567890123456" ...will give the parameter SESSION the value 1234567890123456. Therefore, calling: session.php?CALL=mypipfile ...will be the same as calling: session.php?CALL=mypipfile&SESSION=1234567890123456 If you use characters other than letters or numbers inside command line parameters to session.php, these must be URL encoded. All parameters passed on the command line to session.php must be URL encoded if they contain any special characters. For example if you pass NAME on the command line and the name includes a space, you should use %20 as the representation of the space character.

Input parameter mapping PIP will map input parameters so that you can give a parameter of one name the value of an input parameter of another name. For example: SESSION=TEST_ID This means that the value of TEST_ID passed in will be given to SESSION which is then available from then on.

Other inputs Setting

Description

Possible values

SESSION You must define the SESSION and NAME parameters on the command line or in the [Input] section. This NAME is because session.php can only run if it can identify which assessment to run and which participant is to run it.

GROUP

Defines the group

S1 to S10

Demographic data to pass to Perception

NOTIFY

The URL that PIP needs to notify

session.php?CALL=mypipfile &group=maths &SESSION=1234567890123456

19

Setting HOME

Description

Possible values

You can control what happens when a participant clicks the Home button at the end of an assessment that is launched from PIP. This means that if a Learning Management System (LMS) calls Perception, the Home button can be used to return from Perception to the LMS when the participant completes the assessment.

Possible values: 

A standard URL



A file location file:///C:/Program Files/resources/Parameters.html



Javascript Close function javascript:self.close();

DETAILS Participant details to be recorded in A_Result.Participant_Details

DETAILS=some details you want to record

FNAME

Participant first name to be recorded in A_Result.First_Name

FNAME=Steve

LNAME

Participant last name to be recorded in A_Result.Last_Name

LNAME=Blogs

PEMAIL

Participant email address to be recorded in A_Result.Primary_Email

[email protected]

[Output] settings This section defines what parameters you wish to be passed to the URL which is to be notified at assessment end. The name of the parameter to be passed is on the left and the value to be given to the parameter is on the right. The parameter value can be: 

The name of any of the original parameters passed to session.php



Any Perception parameters that have been mapped to in the [Input] section



Any quoted text, in which case the parameter will be given the value of the text, without the quotes



Any of the server variables that can be used as output parameters

 Any of the demographic data values Here are some examples of possible settings. Setting

Description

LESSON_SCORE=%SESSION.PERCENT%

Will output the parameter LESSON_SCORE as the score for the assessment as a percentage

LESSON_TAG="123"

Will output the parameter LESSON_TAG as 123

If session.php is called with the parameter LESSON_ID=1234

The setting LESSON_ID=LESSON_ID will pass on the parameter as LESSON_ID=1234. This means that session.php will pass through external parameters (see output parameter mapping)

20

Server variables that can be used as output parameters Server variables can be used as output parameters. For example, the following table provides a list of useful server variables you may want to use as output parameters. Server variable

Description

%SESSION.DATE%

The current date

%SESSION.GROUP%

The current group name, or blank if not set

%SESSION.ID%

The numeric ID of the assessment.

%SESSION.MAX%

The maximum score in points for the assessment.

%SESSION.PERCENT %

The percentage score

%SESSION.RESULT%

The index of the record created for this session in the A_Result table of the repository database; this is particularly useful as it allows a program to get all the details for the assessment including all answers by the participant by reading the repository database

%SESSION.SCORE%

The score in points for the assessment.

%SESSION.SCOREBA ND%

The title of the end block or assessment outcome reached at the end of the assessment

%SESSION.TIME%

The current time

%SESSION.TIMEELAP SED%

The number of seconds since the start of the assessment (only if a time limit is set). This is not 100% accurate within PIP, but is roughly correct

%SESSION.TITLE%

The name of the assessment in the repository

%SESSION.URL%

The full URL of session.php

%SESSION.USER%

The current participant name, or blank if not set

%SESSION.USERDET AILS%

The current participant details, or blank if not set

Demographic data You can include demographic data (special fields) in the PIP output by using the variables %SPECIAL.n% (where n has a value between 1 and 10), for example: DemographicData1=%SPECIAL.1% An assessment might generate this output parameter if the above setting is used: ?DemographicData1=Mid%20Year%20Assessment

21

Output parameter mapping PIP will map output parameters so that of the parameters that have been passed in or mapped can then be assigned to any parameter to be passed out. For example: EXAM=SESSION means that at the end of the assessment PIP will set EXAM to whatever the value of SESSION is and send it to the URL is defined in the notify URL (specified in the [Settings] section). If this mapping is also made in the [Input] section: SESSION=TEST_ID Then the call: session.php?pip=mypip&TEST_ID=9266402345738501 ...means that at the end of the assessment PIP will send: EXAM=9266402345738501 ...to the notify URL. To pass through a parameter you just need to declare it in the [Output] section, as in the example above. If the parameter isn't used internally, you can leave out the input parameter mapping and just echo the parameter in the [Output] section, for example: TEST_ID=TEST_ID So if we use this setting and no input setting and call: session.php?pip=mypip&TEST_ID=9266402345738501 ...at the end of the assessment, PIP will send TEST_ID=hello to the notify URL.

[Security] settings This section lets you define the security used when calling session.php via PIP. The security is needed to make sure that the calling program is legitimately able to call the assessment. If you don't use these settings, then a user could call session.php directly themselves and bypass your security. PIP security uses a special checksum that is added to an assessment URL. This checksum value combines the values of the PIP parameters and a hidden key using a hash algorithm. The algorithm is a complex arithmetic calculation that encrypts the values, preventing access to the hidden key and, therefore, preventing the creation of unauthorized URLs. This hidden key is set in the PIP file and must be known by the program that is making the call. If the checksum is not calculated correctly, session.php will not run. You can also configure PIP so it can only be called from certain domains and/or IP addresses. If you configure it like this, you can further restrict the authorized devices that can launch assessments via PIP. You define this security by setting the following parameters in the PIP file: Setting

Description

HOSTS

This setting restricts PIP calls to defined domains and/or IP addresses. If a request fails to match against any defined domains and/or IP addresses, an Access Denied message will be

22

Possible values Examples of the setup of Hosts within the PIP file follows: [Security] Hosts = 123.234.56.*

Setting

Description displayed. If no Hosts item is specified, no check will be done. This setting can be given one or more of the following values: 

An IP address with a wild card for the least significant byte. (eg 123.234.56.*)



A host name with a wild card for the domain host name (eg *.xyzcompany.com)



An IP Address



A host domain name (eg main.xyzcompany.com)

Possible values Hosts = *.xyzcompany.com Hosts = main.xyzcompany.com 123.234.56.123 *.questionmark.com



A combination of any of the above items delimited by spaces If more than one item is specified, each item will be checked in the order given until a match is found or the end of the list is reached. The result of each check will be logged. It's recommended you set this value, as it makes it much harder for someone to use a "rogue" program to access assessments by pretending to be an approved program. LEVEL

The checksum means that the program calling session.php must perform some arithmetic on the parameters to work out a checksum. A hidden key is used which is set in the PIP file and must be known by the calling program. If the checksum is not calculated correctly, session.php will not run.

For Perception 5.7+ and OnDemand, the recommended setting is: LEVEL=hmacsha256 With this level of security, the checksum is calculated using the HMAC-SHA256 hashing algorithm. See the Calculating the checksum section below for information about how to calculate the checksum. For Perception 5.4 and earlier versions, the recommended setting is: LEVEL=md5 With this level of security, the checksum is calculated using the MD5 hashing algorithm. See the Calculating the checksum section below for information about how to calculate the checksum. The following settings mean that no checksum will be used: LEVEL=0 LEVEL=none No setting in the PIP file for LEVEL ...when any of the above three settings that indicate no checksum will be used,

23

Setting

Description

Possible values assessments that are configured to "Run from Integration" can be launched from any program. For backwards compatibility, the following setting may be used: LEVEL=2 With this level of security, the checksum should be calculated using the MD5 hashing algorithm. For Perception 5.7+ and OnDemand, a checksum calculated using HMAC-SHA256 is also accepted with this security level.

KEY

This is an optional text string that can be added to the data used for the security checksum. If this entry is present and is not blank, then the text must be added to any text used to calculate the checksum. It only applies when LEVEL is set to hmacsha256, md5, or 2 for backwards compatibility. If this value is set to %SERVER.KEY%, the value of the key will be taken from the Server Key setting on the Server Settings page in Enterprise Manager.

Calculating the checksum When the security level is set to one of the values that requires use of a checksum, access will only be permitted to the assessment if the call is accompanied by an ACCESS parameter (or any parameter mapped to ACCESS in the [Input] section). The ACCESS parameter must contain a hexadecimal string representing the output (or 'digest') output by the hash algorithm.

HMAC-SHA256 For example, if your PIP file is called secure_test.pip and has LEVEL=hmacsha256 and KEY=sgvtyw7, then an example PIP call might look like the following: http://www.xyzcompany.com/perception5/session.php?CALL=secure_test.pip& user_name=Steven&Lesson_id=4117626686784785&checksum=fa9df8748475c64712fb813f63588 09fbde2839091d4ad7c3fb8bf6981bf2b03 The HMAC-SHA256 algorithm requires two [Input] parameters, a key and a string of characters representing the message. In the above example: Key sgvtyw7 (taken from the Key setting in the PIP file referenced by CALL) Messagesecure_test.pipSteven4117626686784785 Notice how the parameter values are added to the message in the same order as they appear in the URL and that parameter names are ignored. When parameter values contain characters that are escaped in the URL, the escape sequences must be removed before calculating the checksum. For example, a parameter like GROUP=R%26D would contribute the characters R&D to the message string. Extra care is needed with the plus sign character (+) which, unless encoded itself, represents a space in the URL. Because of this, GROUP=Sales+and+Support in a URL would contribute the string Sales and Support to the message (including the space characters).

24

MD5 For example, if your PIP file is called md5pip_test.pip and has LEVEL=md5 and KEY=sgvtyw7, then an example PIP call might look like the following: http://www.xyzcompany.com/perception5/session.php?CALL=md5pip_test.pip&user_name=Steve n&Lesson_id=4117626686784785& checksum=931472062af794fdf7c73c62632d911d Unlike HMAC-SHA256, the MD5 algorithm only requires a message parameter. This is calculated in the same way as the HMAC-SHA256 message but with the PIP Key value appeneded: Messagemd5pip_test.pipSteven4117626686784785sgvtyw7

Verifying the checksum in PIP NOTIFY calls The checksum may also be used in the [Callback] section and the [Output] section to validate the data being passed from PIP to the notify URL (specified in the [Settings] section) by setting an entry to have the value %CHECKSUM%. In this case, the receiving program will need to validate the checksum. The method of verifying the checksum is the same as that of calculating the checksum (described above). The resulting checksum must match the corresponding value of the parameter mapped to %CHECKSUM%. If it doesn't match, then the URL is likely to have been generated by an unauthorized program and the receiving program must not act on the request.

[Settings] settings This section defines any configuration settings to be used by the PIP file. The following settings are possible: 

Control



Topic scoring



Home button



Questionmark Secure

Control settings Control settings are described in the following table. Setting NOTIFY

Description This specifies a URL of a program to be called (notified) at end of the assessment and/ or when session.php needs to perform a callback. If a URL is passed on the command line, the URL specified here will not be used.

Possible values URL

If no NOTIFY parameter is passed on the command line and this entry is omitted or blank in the PIP file, then no program is called at the end of the assessment. If a NOTIFY parameter is used, then this URL is called at the end of the assessment and/or when session.php needs to perform a callback. The call to the URL is configured by the parameters in the rest of the [Settings] section. The actual parameter values that are passed to the URL when it is called are defined in the [Output] section when the call is

25

Setting

Description

Possible values

made at the end of the assessment or in the [Callback] section when the call is made at the start of the assessment as a callback. METHOD

This specifies the HTTP method to be used when calling the notification URL. This may be either GET or POST.

GET or POST

If this is not set, the default value of POST will be used. You are recommended not to change this unless you are an expert user. HEADER

This specifies the HTTP header to be used when calling the notification URL. If this is not set, the default value of: Content-Type: application/x-www-form-urlencoded will be used. You are recommended not to change this unless you are an expert user.

OUTPUTFORMAT This specifies the format used to pass the parameters and values when calling the notification URL. The first %s is replaced by the parameter name and the second %s is replaced by the parameter value. If this is not set, the default value of %s=%s& will be used. You are recommended not to change this unless you are an expert user.

%s=%s&

CALLBACK

Yes/1

If this is set to yes or 1, PIP will call the notify URL when the initial PIP call is made, passing the information as defined in the [Callback] section and adding any information received to the parameters used to start the assessment.

No/0

This provides a secure mechanism for starting assessments; the calling program can simply send an ID on the command line, PIP will then call the notify URL to receive extra information such as the ID of the assessment to be run and the participant's name. USENOTIFY

USEHOME

CLOSEHOME

DISABLE COOKIES

If this is set to no or 0, the notify URL is prevented from being called when the assessment is finished. This may be used in conjunction with the callback protocol when PIP is only used to start an assessment and the results of the assessment are not required.

No/0

If this is set to 1 or Yes the Home button will display at the end of an assessment. If USEHOME is used in conjunction with CLOSEHOME the assessment window will close when a participant clicks the Home button. For more information see the Home button settings section below.

Yes/1

If this is set to 1 or Yes the Home button will close the assessment at the end of an assessment. The CLOSEHOME setting can only be used if USEHOME is set to 1 or yes. For more information see the Home button settings section below.

Yes/1

If set to 0 no cookie information is sent in the callback and notify HTTP calls.

0/1

Topic scoring settings You can include topic scoring information in the PIP.

26

Yes/1

No/0

No/0

Setting

Description

Possible value

TOPICSCORES

You can include topic scoring information in the PIP output with the Yes/1 settings TopicScores and TopicPercent. The TopicScores and TopicPercent No/0 TOPICPERCENT need to be defined if they are enabled. If the setting: TopicScores=yes is made, a series of parameters of the form shown below will be included in the output. Parameter

Description

TOPICS

The number of topics in the assessment

TOPIC_n

The topic description of topic number n, unless the topic description is blank in which case the topic name is used

SCORE_n

The actual score for topic number n

MAXSCORE_n The maximum possible score for topic number n If the setting: TopicPercent=yes is made, a series of parameters of the form shown below will be included in the output . Parameter

Description

TOPICS

The number of topics in the assessment

TOPIC_n

The topic description of topic number n, unless the topic description is blank in which case the topic name is used

PERCENT_n The percentage score for topic number n If both TopicScores and TopicPercent are set to yes, these parameters are consolidated as follows. 

TOPICS



TOPIC_n



SCORE_n



MAXSCORE_n

 PERCENT_n For example, if both TopicScores and TopicPercent are set to yes, an assessment that contains three topics might generate these output parameters: ?TOPICS=3&TOPIC_1=Math1&SCORE_1=5&MAXSCORE_1=10&PERCENT_1=50 &TOPIC_2=Math2&SCORE_2=10&MAXSCORE_2=10&PERCENT_2=100 &TOPIC_3=Math3&SCORE_3=7&MAXSCORE_3=10&PERCENT_3=70

Home button settings You can control what happens when a participant clicks the Home button at the end of an assessment that is launched from PIP. This means that if a Learning Management System (LMS) calls Perception, the Home button can be used to return from Perception to the LMS when the participant completes the assessment. This is done with the Home button settings described below. Setting HOME

Description Specifies what the HOME button does at the end of an assessment. This setting can be a URL:

27

Setting

Description HOME=http://www.questionmark.com/resources/Parameters.html It can be a file reference: HOME=file:///C:/Perception5/resources/Parameters.html Or it can be a Javascript command (However, this will only work if the assessment window was opened via javascript to begin with.): HOME=javascript:self.close(); This setting can also be made with the session.php command line parameter home, for example: session.php?call=perception.pip&home=http://www.questionmark.com/results.html If this command line parameter is used, it takes precedence over the HOME setting in the PIP file. If the HOME setting is used in the PIP file, or the command line parameter is used, when a participant clicks the HOME they are directed to a URL that is composed of the specified home URL plus all data as defined in the [Output] section, for example: http://www.questionmark.com/results.html/?assessment_id=4749119486591492 &details=Perception%20Integration%20Protocol

USEHOME

Used to enable or disable the URL for the HOME button even if it is set in the PIP file or passed as a command line parameter. If UseHome is set to no or 0 (or the setting UseHome is not present in the PIP file), a participant will not be directed to the home URL when they click the HOME button. Using the HOME and NOTIFY settings together the HOME setting is used independently of the NOTIFY setting, which means that: These settings can be used together and with different URLs. Notification takes place before the final page is displayed a participant will be directed to the home URL when they click the HOME button.

CLOSEHOM E

If USEHOME is enabled the CLOSEHOME setting can be used to close the assessment window when the Home button is clicked. The NOTIFY parameter can be used independently of this setting as well. If enabled, along with USEHOME and NOTIFY, the defined URLs for these settings are processed before the command to close the window.

Questionmark Secure settings If you are calling a Perception assessment via PIP you can require Questionmark Secure to be used by participants taking the assessment with the setting: Require QS=yes If you make the settings: UseHome=yes CloseHome=yes

28

...this makes the Home button on the final page of the assessment close Questionmark Secure.

29

AICC support in PIP The Aviation Industry CBT Committee (AICC) have defined a standard mechanism whereby a Learning Management System (LMS), also known as a Computer-Managed Instruction application (CMI), can launch an Assignable Unit (AU), an element of instruction or testing to be carried out by another application, and receive notification when the AU has finished, along with performance data detailing score, time taken, etc. The AICC have defined a web-based version of this protocol, the HTTP AICC CMI Protocol (HACP), allowing communication between the LMS and AU to take place using HTTP, so that the system can function on the Internet, with the student using a web browser. For more details about the AICC, please refer to: http://aicc.org/joomla/dev/

Using HACP 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 Perception 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:///perception5/session.php?CALL=aicc_file ...where is the domain name for your Perception Server. This is used to make the call that launches the Perception 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 Perception will receive the data in the form: CALL=aicc.pip&AICC_SID=1&AICC_URL=http://cmiserver.com/cmi.cgi 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 Perception Assessment ID, PIP file password etc., must also be defined so that it can be sent to Perception. These are often referred to as vendor parameters, and will be sent to Perception when it requests the start-up information. Perception then makes a call to the LMS URL it received using the AICC GetParam call. 31

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: command=GetParam&version=2.0&session_id=2 ...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 Perception 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: [Settings] UseAICCTopics=yes If set to yes, then at the end of the assessment, when Perception 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 J_ID.x

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

Example 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 Perception: 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

J_Status.x

32

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

Perception will always set this parameter to completed:

Identifier

Purpose

Example



pass

J_Status.1 = completed



completed

J_Status.2 = completed



fail



incomplete



not attempted



browsed

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: [Objectives_Status] 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. Perception sets this to end lesson_status

If the LMS passed a parameter Mastery_Score to Perception, and if this had a value greater than 0, then Perception 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 See "AICC status data" on page 34 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 Perception 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:

33

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, Perception 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: command=ExitAU&version=2.0&session_id=2 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 Perception from an LMS via AICC, there can be a situation with some LMSs where you do not want Perception 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: [Settings] AICCStatusPass=Good AICCStatusFail=Bad AICCStatusOther= None Some LMSs calling Perception via AICC use the lesson_status parameter returned from Perception. The usual value for this is that if a mastery score was not set, Perception returns completed. If a mastery score was set by the LMS when calling Perception, then if the score exceeds the mastery score, Perception returns passed, and otherwise Perception 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.

PIP file entries for AICC A PIP file that uses AICC can contain the following sections:

34



[Input]



[Settings]



[AICC Get]



[AICC Put]

 [AICC Exit] These sections are described in the table below. Section [Input]

Description The NOTIFY parameter should be mapped to the AICC_URL parameter, or whatever other parameter is used by the LMS to send its URL.

[Settings] This section must contain the entry AICC=yes (or AICC=1) to tell PIP that the AICC protocol is being used. If this is omitted, or set to 0 or no, then the normal PIP methods will be used and no support for the AICC protocol will be provided. If it is wished to suppress the final ExitAU message then the settings section should contain the entry UseAICCExit=no (or UseAICCExit=0). [AICC Get]

This should be set to pass the GetParam command along with the AICC session id, or the input parameter it was mapped to. The version of the AICC protocol being used may also be included, for example: command="GetParam" version="2.0" session_id=SESSION_ID

[AICC Put]

This should be set to pass the PutParam command along with the AICC session id, or the input parameter it was mapped, for example: command="PutParam" version="2.0" session_id=SESSION_ID

[AICC Exit]

This should be set to pass the ExitAU command along with the AICC session id, or the input parameter it was mapped to, for example: command="ExitAU" version="2.0" session_id=SESSION_ID

The [Output] section is not used when the AICC protocol is being used and may be omitted.

35

Example PIP files When you install Perception, some example PIP files are also installed. By default, they can be found in the following directory: C:\Program Files\Questionmark\server\pip\examples ...if you installed Perception in its default location. If you have installed Perception elsewhere, this path will look slightly different. In Perception 5.7, qmwise.pip and sps.pip are the only PIP files installed in Resource Manager by default. If you want to create a Content Package to launch an assessment from an LMS through AICC, SCORM 1.2 or SCORM 2004, you will now need to download and upload the relevant PIP file via Resource Manager (Authoring | Resource Manager | PIP). AICC and SCORM assessments launched without the appropriate PIP files will fail. You can download these PIP files, as well as perception.pip and qs.pip, below (right-click and save as): 

aicc.php



aicc_qs.pip



scorm.pip



perception.pip



qs.pip

In Perception 5.4, the following example PIP files are installed by default: Example PIP file

Description

perception.pip

Starts a Perception assessment with PIP. Please refer to See "perception.pip" on page 37 for more information on this example file.

aicc.pip

Enables you to use PIP for AICC interoperability.

scorm.pip

Passes topic percentages in the PIP output to the notify URL.

qmwise.pip

Certain QMWISe methods, for example GetAccessAssessmentNotify, require a PIP file as an input parameter. The file qmwise.pip can be used for this purpose. For more information on QMWISe, please refer to the Questionmark QMWISe API Guide.

qs.pip

Starts a Perception assessment in Questionmark Secure. Please refer to See "qs.pip" on page 38 for more information on this example file.

aicc_qs.pip

Using AICC and Questionmark Secure. Does the same thing as aicc.pip except that it starts an assessment in Questionmark Secure.

Please refer to See "Collecting demographic data" on page 38 for an example PIP file that demonstrates how to use PIP to collect demographic data.

perception.pip The PIP file perception.pip is the simplest possible PIP file that allows you to try using PIP with minimum work. It calls session.php passing an Assessment ID of an assessment.

37

In the PIP file: [Input] NAME="PIP" GROUP="Testing" DETAILS="Perception Integration Protocol" SESSION="4117626686784785" [Settings] UseNotify=no Set the SESSION parameter to the Assessment ID of an assessment in the repository. You should be able to make a call from your browser to: http:///perception5/session.php?CALL=perception.pip ...where is the domain name for your Perception server. This will run the assessment the Assessment ID defined in the PIP file. No program is called at the end of the assessment.

qs.pip The PIP file qs.pip allows you to start a Perception assessment in Questionmark Secure and close Questionmark Secure when the participant clicks the Home button at the end of the assessment. In the PIP file: [Input] NAME=NAME GROUP="Testing" DETAILS="Questionmark Secure" SESSION="1482104035460703" [Settings] UseNotify=no Require QS=yes UseHome=yes Home=%PIP_CLOSE_QS% Set the SESSION parameter to the Assessment ID of an assessment in the repository. You should be able to make a call from your browser to: http:///perception5/session.php?CALL=qs.pip&NAME= ...where is the domain name for your Perception, and is the name of the participant taking the Perception assessment. The assessment will then start in Questionmark Secure.

Collecting demographic data Authors can utilize PIP to pass demographic information from a calling program to Perception, and have this information stored in special fields within the answer database.

38

There are ten special fields in the repository called Special_1 to Special_10 and each field can hold up to 50 characters of text. These fields can be displayed in Enterprise Reporter and can be used to filter the contents of reports. PIP includes ten input parameters that correspond to the ten special fields in the answer database. These are S1 to S10 and each of these input parameters can also hold up to 50 characters of text. This section contains instructions on how to pass demographic information to Perception using PIP and use it in reports. To do so you will need to: 1.

Create an HTML page that will collect the demographic information and run an assessment

2.

Create a PIP file that is called from the HTML page above

3.

Use the HTML page to collect the demographic information and take the assessment

4. Create a report that displays the demographic information Each of these steps is described below. Please note that in the example used below, the fields specified in the PIP file correspond to the fields created in the HTML file, for instance the PIP file contains: S1=Organization ...and the HTML file contains: You can change the names of these fields, as long as the HTML file and the PIP file contain the same name. Only 3 special fields are used to store demographic information in the example, but you can store up to a maximum of 10.

Creating an HTML page To create an HTML page that will collect the demographic information: 1.

Using an HTML or ASCII editor, such as Notepad, enter the following HTML code. Demographic PIP example
Your name:


39

Organization name:
Organization type:
Educational Corporate Non-profit Org Can we contact you with more details?
Yes
No Note: Change http://www.questionmark.com/perception5/session.php to match the URL to your own Perception Server installation. 2.

Save the HTML document as demographics.html.

3.

In Authoring Manager, create a global resource folder called demographics in the repository.

4.

Add the file demographics.html to the demographics global resource folder as a global resource.

Creating a PIP file Once you have created the demographics.html file, you will need to create the PIP file that is called from the HTML page. To do so: 1.

Create a new document in your HTML or ASCII editor, and enter the following information. ; demographics.pip [INPUT] SESSION="4117626686784785" S1=Organization S2=Industry S3=Contact Note: Change the value of SESSION="4117626686784785" to an Assessment ID that exists in the repository. By placing the Assessment ID in the PIP file you make your PIP use more secure. Using this approach the PIP file can be used with the specified assessment only.

40

2.

Save this document as demographics.pip in the following directory of your Perception Server installation: C:\Program Files\Questionmark\Perception5\server\pip

Using the HTML page To collect the demographic information and take the assessment: 1.

In your browser, enter the URL below of the form: http:////demographics/demographics.html ...where is the domain name for your Perception server, and is the webshare name of the resources directory in the repository (you can find this with Shared Repository Manager).

2.

Complete the demographic information, and click the Submit details and start survey button.

3.

Complete the assessment that now starts

Creating a report To create a report that displays the demographic information: 1.

Open Enterprise Manager.

2.

Go to Report Manager and create a new Coaching Report.

3.

Select Special fields 1, 2 and 3 and assign these fields some useful labels in the Alternative label column. 41

42

4.

Configure the rest of the report according to the other information that you wish to be included.

5.

Once you have named this report, click Save and View to run the report.

6.

When the Coaching Report main page appears, select the report definition you just created and the assessment you called from the HTML file.

7.

Click Search.

8.

Click the name of the participant whose results you wish to view.

9.

You should now see the demographic information shown in the report.

Appendix The Appendix contains technical information on: 

Finding more information



Troubleshooting



Contacting Questionmark

Troubleshooting Here are some things to look at if you are using PIP and you can't get it to work: 

Check you have correctly defined the PIP directory on the Server Settings page of Enterprise Manager, and that the PIP file you are calling is there. Check if necessary that permissions are correct for this directory.



If the PIP file contains a password, as many of the example ones do, check you quote it on the session.php command line.



Make sure you include an assessment reference in the call. The ID of an assessment that exists in the repository must be passed to session.php or it will not run.



Turn PIP Logging on, and look at the pip.log file, and also at the perception.log and perception.err files. PIP calls, notifications and problems will all be logged here.



Check the keys Show data and Show debug in Server Settings screen of Enterprise Manager. This will show you some debugging information in the HTML page that is sent to the clients browser when they try and run the assessment.



If you are having a problem calling a program at the end of an assessment, remember this only happens when the assessment is over, that is when the participant sees the assessment outcome.



If calling a program at the end of an assessment is failing, try using one of our test programs to log data rather than your program and see what is being sent. Timeout problems, for example if the call cannot be made, will be written in the log file, but not until the server timeout period has expired.



If clicking the Home button at the end of an assessment displays an error, please make sure your PIP file has USEHOME and CLOSEHOME both set to 1 or yes.

Finding more information This section contains a list of useful resources on the following subjects: 

Enterprise Manager



Enterprise Reporter



QMWISe

Enterprise Manager For more information on Enterprise Manager, please refer to the Enterprise Manager Guide. This guide is available to members of Questionmark Communities and is located on the Perception Product Support site:

43

www.questionmark.com/perception/help/v5/product_guides/ Additionally, comprehensive guidance on how Perception administrators can use Enterprise Manager can be found in the Help that accompanies the product.

Enterprise Reporter For more information on Enterprise Reporter, please refer to the Enterprise Reporter Guide. This guide is available to members of Questionmark Communities and is located on the Perception Product Support site: www.questionmark.com/perception/help/v5/product_guides/

QMWISe For more information on QMWISe, please refer to the Questionmark QMWISe API Guide. This guide is available to members of Questionmark Communities and is located on the Perception Product Support site: www.questionmark.com/perception/help/v5/product_guides/

Contacting Questionmark If you have a technical problem with Perception that you cannot resolve, please contact Questionmark Technical Support. Contact details are provided in the table below. Area

Technical Support phone

Technical Support Email

US

800-597-3950

[email protected]

UK

+44 (0)800 731 5895

[email protected]

Europe

+32 (0)2 398 02 05

[email protected]

Rest of World

+44 (0)800 731 5895

[email protected]

If you have a licensing query, please email the Questionmark Customer Service team. Please refer to the full list of Questionmark Sales Offices for the contact details of your nearest office.

44