Accessing the XMCDA web services

Example: using a python script

A python (python 3) script accessing those web-services is available here: ddws_soap_client.py.
You also need to install the simplesoap library to make it work.

In this example, we want to call the service named ‘rankAlternativesValues-RXMCDA’. Its documentation 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: rankAlternativesValues-RXMCDA/tests/in1

Say we go for ‘tests/in1/’, there are two files:

• alternatives.xml
• overallValues.xml

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

python3 ./ddws_soap_client.py -n rankAlternativesValues-RXMCDA \
        --submit-problem alternatives:./alternatives.xml   \
                         overallValues:./overallValues.xml

The job is submitted, and after having submitted it successfully, a ticket number is returned which we use to retrieve the results.
Suppose we received the ticket ‘orPiIXdej7SVgOLf’, let’s ask for our results:

python3 ./ddws_soap_client.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: we have just received two files, ‘alternativesRank.xml’ and ‘messages.xml’. Again, the documentation tells us that this is what we expect: the latter contains informational messages, while the former 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 we 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 having to keep a program running, or fearing that 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 we 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; as expected, the return status is 0 when results are available and have been successfully retrieved.

Last, the submission of a job and the request for the results can be done with one single command:

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

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

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 ./ddws_soap_client.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.

Options -h or --help gives all the details.