The QMWISe data model and web service definition
The Questionmark Perception allows the passing of data via HTTP by using command line parameters. This has limitations, particularly in:
- Passing structured data is cumbersome. When there are lists of elements, a separate instance of the same parameter is required for every item on the list.
- No data can be passed back. All parameters are for sending data only, any output that is generated must be obtained from elsewhere in the system.
Suppose that a list of names and passwords need to be processed. By using an XML representation, the list can be put in a format like the one below:
|
<students> <student> <name>Student 1</name> <password>Password 1</password> </student> <student> <name>Student 2</name> <password>Password 2</password> </student> <student> <name>Student 3</name> <password>Password 3</password> </student> … </students> |
This XML list can be placed in an envelope with a standard header, where the header can be used independently of the data. For example:
|
<envelope> <header> <identifier>Administrator</identifier> <code>Checksum</code> </header> <body> <UpdatePassword> <students> <student> <name>Student 1</name> <password>Password 1</password> </student> <student> <name>Student 2</name> <password>Password 2</password> </student> <student> <name>Student 3</name> <password>Password 3</password> </student> … </students> </UpdatePassword> </body> </envelope> |
The envelope, headers and other elements can be formatted in a standard way by using SOAP, which gives the benefits of an existing standard and a clearly defined protocol. You can find out more about SOAP at:
QMWISe provides a set of web service methods whose request and response message formats are precisely defined in a web service definition.
Using web service methods is a case of issuing the web service method with the required input parameters and dealing with the output parameters as necessary.
An example of a web service method construction would be:
|
WEB SERVICE METHOD ( INPUT PARAMETER 1, INPUT PARAMETER 2, INPUT PARAMETER 3, INPUT PARAMETER 4, etc. ) |
An example created in Visual Basic is provided below. This method uses input from a form which collects the data ASSESSMENT_ID, PARTICIPANT_NAME, PARTICIPANT_DETAIL, GROUP_NAME and uses the web service method GetAccessAssessment to return a URL into the memory allocation strReturned. The data stored in the memory can then be manipulated and used as required in an application.
|
strReturned = soapclient.GetAccessAssessment ( ASSESSMENT_ID, PARTICIPANT_NAME, PARTICIPANT_DETAIL, GROUP_NAME ) |
How this would be translated into a programming language depends on the language of your choice. For further examples of using web service methods, please refer to the Examples section.
Input parameters for a web service method are mandatory unless they are denoted as being optional by being italicised. Please refer to individual web service methods for further details.
The QMWISe web service is precisely defined using a Web Service Description Language (WSDL) document. This is itself an XML format document, for more information about its syntax see:
Within the WSDL document, the following appears for the definition of the web service method named CreateParticipant:
|
<s:element name="CreateParticipant"> <s:complexType> <s:sequence> <s:element minOccurs="1" maxOccurs="1" name="Participant" nillable="true" type="s0:participant" /> </s:sequence> </s:complexType> </s:element> |
This defines the request message format for a web service method named CreateParticipant that requires the Participant input data (this is defined elsewhere in the WSDL document). One set of Participant data must be sent in the request message, but only several items in this set are mandatory.
The corresponding response message for the web service method named CreateParticipant is defined as follows:
|
<s:element name="CreateParticipantResponse"> <s:complexType> <s:sequence> <s:element minOccurs="0" maxOccurs="1" name="Participant_ID" type="s:string" /> </s:sequence> </s:complexType> </s:element> |
This requires exactly one Participant_ID is to be included in the response.