Accessing the XMCDA web services

Currently there exist 4 ways to access the XMCDA web services:

• standard SOAP requests, detailed below;
• Decision Deck’s diviz software;
• Decision Deck’s d2 software;
• Decision Deck’s d3 internet application.

The standard SOAP requests allow you (among other things) to integrate the call of the web services into your own application.

The diviz software allows you to build execution workflows of XMCDA web services via a GUI.

The d2 software contains the Rubis MCDA method which makes use of an XMCDA web service to generate the results.

Finally, the d3 internet application can be used to conveniently access the XMCDA web services from a web browser.

SOAP requests

All web-services are available through the standard SOAP protocol.

The URLs under which they are published take the following form:

http://webservices.decision-deck.org/soap/<service_name>.py

except for 4 services:

• IRIS,
• IRIS-testInconsistency,
• inconsistencyResolution,
• and weightsFromCondorcetAndPreferences

that are available under the following url:

http://ernst-schroeder.uni.lu/cgi-bin/<service_name>.py

Note

The URLs are subject to change (especially the second template, which will eventually be changed into the first one). If you use these services, we recommend to check this page on a regular basis.

The <service_name> of each web-service can be found in its documentation, along with the description of its input and output parameters; this documentation can be found here.

Example: using a python script

An python script accessing those web-services is available here.

You’ll need python ZSI to make it work.

Suppose we want to call the service named rankAlternativesValues,

Its documentation (here) states that two inputs are mandatory:

• alternatives: the set of alternatives
• overallValues: the overall numeric value for each alternative.

We have examples of such inputs, you’ll get them here:

• alternatives.xml
• overallValues.xml

Now, the command-line to submit a new job to service rankAlternativesValues with those two files is the following:

python ./genericXMCDAService.py           \
    -n rankAlternativesValues-RXMCDA -s   \
    alternatives:./alternatives.xml       \
    overallValues:./overallValues.xml

The job is submitted, and after having submitted successfully you get a ticket number that you’ll use to retrieve the results.

Say we got ticket orPiIXdej7SVgOLf, let’s ask for our results:

python ./genericXMCDAService.py         \
    -n rankAlternativesValues-RXMCDA    \
    --request-solution orPiIXdej7SVgOLf

If everything goes fine, the results are dumped into the current directory and the script prints out their names on the standard output: you’ve just received two files, messages.xml and alternativesRank.xml. Again, the documentation tells us that this is what we expect: the first one contains informational messages, while the second is the result itself: the ranking of the alternatives supplied as input.

Of course, this example does not take long to execute: the dataset is small and the program has a simple task to perform, so by the time you typed or copy-pasted the above command lines, the job is finished and you get the results. However, if you combine real-life data with complex algorithm this can result in jobs requests which require minutes, hours, or even days to complete. This is why every XMCDA web-service was designed this way: decoupling the task submission from the request for results makes it possible to execute long-running jobs without fearing that, for example, the HTTP connection drops as some point.

What happens if you request a solution but the service has not finished computing it yet? Then the script will appear to hang a little and then returns, without printing anything (except if you ask it to be more verbose by adding the option -v). The default is 60 seconds, it can be changed with option -t. When returning without a solution, the script’s exit status is 2.

Last, the submission of a job and the request for the results can be done together:

python ./genericXMCDAService.py     \
    -n rankAlternativesValues-RXMCDA  \
    --submit-and-wait-solution        \
    alternatives:./alternatives.xml   \
    overallValues:./overallValues.xml

If this script fails to retrieve the result within the defined period, again it exits with an exit status equal to 2. The results can naturally be retrieved later, using the ticket number that was given.

Last but not least: as stated above, some services are available under a different URL than the default one. In this case, you use the option --url, as in:

python ./genericXMCDAService.py \
    --url http://ernst-schroeder.uni.lu/cgi-bin/IRIS-CppXMCDA.py
    ...

Integration into a shell script:

This script should be simple to integrate into a shell script.

• When submitting a new task, only one thing is printed on the standard input: the ticket number. In bash, you get it simply like in: ticketNumber=$(python ./genericXMCDAService.py -s ...).
• When requesting results, only the names of the returned files are printed on the standard output, one per line.
• the exit status is 0 if everything goes fine, 2 if the timeout was reached when waiting for solutions.

Option --help gives all the details.