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:
convert both values to strings, left padding to 16 characters
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.
TLS and SoapUI¶
In accordance with the end of support for TLS 1.0 on Questionmark OnDemand you will need to follow the following instructions to use the popular SoapUI tool with QMWISe.
Open SOAP UI vmoptions, you can find this file under SoapUI installation folder:
C:\Program Files\SmartBear\SoapUI-5.3.0\bin\SoapUI-5.3.0.vmoptions
Add this line in vmoptions:
-Dsoapui.https.protocols=TLSv1.2
Close SOAP UI and try again accessing the QMWISe methods