Getting started with QMWISe
What you will need:
- An installation of Questionmark Perception
- A license for QMWISe for third-party applications
- Access to the QMWISe test harness
Step 1: Configure QMWISe security in Enterprise Manager
Before you can experiment with QMWISe you need to change the default security configuration of your Perception installation to allow QMWISe to be called from your new application.
Log in to Enterprise Manager and create a special administrator for use with QMWISe. This administrator is the identity that will be used for all transactions through the QMWISe interface. For example, if you were going to use QMWISe to integrate with your Student Record System (SRS) you might define an administrator called "SRSAdmin". Give this user "Set Configuration" permission. If you are just testing on a private system the default "Manager" account works just fine.
Now go to the Server Settings screen in Enterprise Manager, turn on "Security Require" and turn off "Trust Require", make a note of the Trusted Key because you will need this in the next step. Save the settings!
Step 2: Calculate the administrator checksum
Open the test harness and use the "Security Settings..." dialogue to enter the user name of your QMWISe user, the password of that user and the TrustedKey you noted in the previous step. Click OK.
Now enter the URL for your QMWISe installation into the top box on the Test Harness window and click "Show Methods". If you've got the URL right then you should see a list of methods appear in the left-hand pane of the window. Select "GetAbout" and wait for the input pane to be updated with details of the input parameters.
At this point you should see the ClientID populated with the name of the user you entered into the dialogue and the checksum box filled with a long hex string. This string is important, you will need it in all of your calls to QMWISe, it is unique to this administrator and represents the password used to access QMWISe. You must keep it private!
Step 3: Set the QMWISe security configuration
If you are using Perception 5 or later then you can skip this step.
Perception 4 stores QMWISe configuration in two places, an "ini" file that is updated by Enterprise Manager and a "web.config" file that is managed by QMWISe itself. To make the changes we made in Enterprise Manager active in QMWISe we need to tell QMWISe to update its web.config with the new settings stored by Enterprise Manager in the ini file. This is done by calling QMWISe itself!
In the TestHarness, select the SetConfiguration method from the method pane. QMWISe doesn't know about our new security settings so we'll have to use the old security settings to tell it to update the configuration.
By default, QMWISe comes configured with TrustRequire turned on so check the "Add Trust Header" box, remember, we have to use the old settings at this point. If you forget, you'll get an exception when invoking methods: "Trust Header Required but missing". Which tells you exactly what you are doing wrong. You can't write applications that use "TrustRequire" yourself, this is a special mode of access used by the Test Harness and other components provided by Questionmark themselves.
The security information is all in the headers, there are no other input parameters to the SetConfiguration method. Notice that by default the encoding parameter is set to 'des'. If you leave like this the responses will just appear as a long string of hex digits, change it to 'none' for now and then invoke the method with button provided. Wait for the QMWISe response to be displayed, the output is actually the outgoing security settings.
After the call to SetConfiguration, your new settings from Enterprise Manager should be active. So now uncheck the "Add Trust Header" box and check the "Add Security Header" box instead. It doesn't hurt to call SetConfiguration again - if it worked you'll see the unencrypted output in the response pane.
Problems? There are circumstances in which the configuration is not copied correctly between the two files. It is much easier to fix these in the Test Harness from your own code! If the test harness continues to complain about the absence of the Trust Header, log in to the Perception server itself and repeat the process above, checking that the ini file and web.config file are actually being updated. Force the configuration to change by toggling the TrustRequire setting back and forth and/or by changing the default TrustedKey.
Once you have got QMWISe working with the Security Headers you are ready to start calling QMWISe from your own code.