QMWISe

QMWISe stands for Questionmark Web Integration Services environment. It is a SOAP-based web services API that provides an alternative method of accessing the underlying data model of the qm:db:Delivery database.

QMWISe is available in all current versions of Questionmark software.

This part of the guide is in preparation and is not yet complete. For more general information on configuring QMWISe please refer to the older Perception 5.7 QMWISe API Guide

QMWISe is based on SOAP and defines a wide range of operations (also referred to as methods) covering the underlying data model.

String Parameters

simpleType string

Due to a limitation of the technology used in the original design of QMWISe all parameters of type string are marked as being nillable in the WSDL. This means that messages in which these values have been omitted will validate against the WSDL, however, it does not indicate that they are valid QMWISe messages.

QMWISe imposes additional rules over and above those expressed in the WSDL, in particular, where input parameters are of type string they may be required and omitting their values will result in a SOAP fault.

As a general rule of thumb, if a string parameter maps to a required field in the data model then it will be required. There are some exceptions, check the documentation for the method or type you are using for further restrictions.

Optional Parameters

For XML validation purposes it is important to realise that, if an element is present in a SOAP request then the content of the element must be a valid value for that element. In the vast majority of cases, optional elements are defined to be of type string so an empty element is interpreted as an empty string and in many cases is treated indistinguishably from an omitted element (which is interpreted as null).

In cases where the element type is something other than string you must either omit the element (interpreted as null or as the default value given in the WSDL, see Default Values) or provide a valid value. For example, the Participant.Use_Correspondence field is declared as follows:

<element minOccurs="0" maxOccurs="1" default="0"
    name="Use_Correspondence" type="int"/>

therefore, if you include this element in a request to create a participant it must contain a valid integer. In this case the integer is used as a flag and only the values 0 and 1 are permitted. You may omit the element completely which is equivalent to passing the value 0. A empty element will cause an error as the XML of the SOAP request will not be valid.

Assessment IDs

In QMWISe, Assessment IDs are represented using string. These strings should always be padded with leading 0s to create a string of exactly 16 characters. In the underlying data model assessment IDs are represented using two 32-bit integers (see MID and LID).

For example, suppose an assessment has the following ID in the database:

MID = 38074658
LID = 94065740

According to the rules for combining MID and LID this results in a 64-bit assessment ID of:

ID = MID * 100000000 + LID = 3807465894065740

In QMWISe you’ll pass this 64-bit integer as a 16-character string:

"3807465894065740"

Things are more complicated when the MID and LID have leading zeros, especially as some IDs follow the pattern MID = LID * 10 such as those in the following example:

MID = 320750
LID = 32075
ID = MID * 100000000 + LID = 32075000032075

In QMWISe you must pass this 64-bit integer as a 16-character string with 0-padding on the left:

"0032075000032075"

Warning

if you are also using the newer OData APIs note that they use a true 64-bit representation in the metadata but that, when serialised to JSON format, these values are represented as strings without the 0-padding on the left. The only safe ways to compare two assessment IDs are:

  1. convert both values to strings, left padding to 16 characters
  2. convert both values to 64-bit integers

Extension Types

QMWISe uses the XML schema technique of deriving types by extension. For example, the Result type is extended by the Result2 type. These extensions sometimes represent the development of the API from an earlier, smaller, set of return fields to a later revision returning more information (possibly reflecting changes to the underlying data model itself). For example:

<s:complexType name="Result2">
    <s:complexContent mixed="false">
        <s:extension base="tns:Result">
            <s:sequence>
                <s:element minOccurs="0" maxOccurs="1"
                    name="FirstName" type="s:string" />
                <s:element minOccurs="0" maxOccurs="1"
                    name="LastName" type="s:string" />
                <s:element minOccurs="0" maxOccurs="1"
                    name="PrimaryEmailAddress" type="s:string" />
                <s:element minOccurs="0" maxOccurs="1"
                    name="SubgroupPath" type="s:string" />
                <s:element minOccurs="0" maxOccurs="1"
                    name="CourseProperty" type="s:string" />
                <s:element minOccurs="1" maxOccurs="1"
                    name="ScoreBandIDProperty" type="s:int" />
            </s:sequence>
        </s:extension>
    </s:complexContent>
</s:complexType>

Although marked as returning type Result the method GetResult actually returns an element of type Result2 containing these additional fields.

Backwards compatibility remains an important goal of QMWISe but implementers using frameworks that take a snapshot of the WSDL (for example, to auto-generate code stubs in languages such as Java and C#) should be aware that additional, unexpected, elements may be returned in SOAP responses as a result of changes to the schema. This should not cause failures as this is precisely what the XML schema extension element was designed to achieve. That said, this type of change is kept to a minimum in QMWISe and the current pattern of development is to add new methods rather than extending the types returned by existing ones.

Default Values

In some cases the WSDL for QMWISe defines structures with default values, for example, see Schedule.Monitored:

<s:element minOccurs="0" maxOccurs="1" default="0" name="Monitored" type="s:int" />

A definition like this means that a missing Monitored element in a request or response should be inferred to mean “0”, the default value. Due to the nature of the technology used to implement QMWISe when serialising responses to XML elements with default values are typically omitted. This may be confusing at first, especially to tools that do not read and interpret the WSDL correctly.

Basic Types

QMWISe makes extensive use of the following basic types from XMLSchema.

simpleType boolean

Values “true”, “false”, “1” or “0”. See boolean.

simpleType double

See double.

simpleType short

See short.

simpleType int

See int.