.. _chap-webservices:

************************
Example: Web Services
************************

A *web  service* grants you programmatic  access to an  online data source
via a straightforward  API.  In this chapter, you will learn  how to invoke web
services from within |vistrails| workflows. We will build a simple workflow that
invokes a web service and generates an HTML table with the results. Our current
example is  intentionally simple; for  more in-depth examples, please  refer to
the |vistrails| website.

**Where we're going in this chapter:**  The European Bioinformatics Institute maintains ChEBI, [#]_ a database of  over 15,000 chemical
compounds.   Each  entity   is  referenced  by  a  unique   ID  number,  called
its *chebiID*. To see  an example of the kind of queries  we will build in
this example, go to http://www.ebi.ac.uk/chebi/webServices.do and scroll
down   until   you   find   the   web   form   labeled   "getCompleteEntity."
(Figure :ref:`fig-webservices_webform1`).   If  you  type  15357 into  the  text
field,  it  will  return a  long  string  of  data  in  XML format  about  this
chemical.   We  learn,   among  other   things,  that   this   chemical's  name
is *acetylenedicarboxylate(-2)*.

To try another  query, scroll down to the  area labeled "getOntologyChildren"
and type 15357 into the text  field. This returns an XML representation of this
chemical's  ontology  children.    In  this  case,  the  result   is  a  single
chemical,    *acetylenedicarboxylate(-1)*,   whose   chebiID    is   30782
(Figure :ref:`fig-webservices_webform2`).

.. _fig-webservices_webform:

.. _fig-webservices_webform1:

.. figure:: figures/example_webservices/webservices_webform.png
   :width: 3.2in
   :align: center

   \(a\) Web browser interface for the ChEBI database 

.. _fig-webservices_webform2:

.. figure:: figures/example_webservices/webservices_webform_result.png
   :width: 3.2in
   :align: center

   \(b\) Results from a "getOntologyChildren" query

In  this example,  we will  build a  workflow that  accesses a  web  service to
perform the second of these two  queries. Because we're using a web service, we
don't  need  a  browser  ---   we  will  perform  this  query  programmatically
within |vistrails|.

Enabling the SUDSWebServices Package
====================================

In  order to  use  web services  in |vistrails|,  you  need to  ensure that  the ``SUDSWebServices`` package  is enabled in the ``Preferences``
dialog. (Please  refer to  Chapter :ref:`chap-packages` for more  information on enabling packages.)

Adding Web Service Packages
===========================

Within the ``Module Packages`` tab of the ``Preferences`` dialog, click the ``Configure`` button to open the configuration dialog for this package (``SUDSWebServices``).  Select the ``wsdlList`` and click on the ``Value`` field.  This is where you will enter the URL(s) of the web service(s) you wish to access.  If there is more than one URL, place a semicolon (;) between each URL, but *not* after the final URL. In other words, the URLs must be semicolon-delimited, but not semicolon-terminated.

For our example, we need the following URL:

``http://www.ebi.ac.uk/webservices/chebi/2.0/webservice?wsdl``

After closing the dialog, you need to reload the ``SUDSWebServices`` package in order to load the changes. Then, close the ``Preferences`` dialog.  A new package will be created for each URL provided.

Alternatively, you may add a web service package by clicking the secondary mouse button on the "SUDS Web Services" package in the module palette and entering the corresponding URL.  You may remove a web service by clicking the secondary mouse button on the corresponding package in the module palette and selecting ``Remove this Web Service``.

.. _fig-webservices_preferences:

.. figure:: figures/example_webservices/modules_list.png
   :align: center
   :height: 3in

   The available modules in the ``webServices`` module are shown in the ``Modules`` panel.


Creating a new vistrail
=======================

After  configuring the  ``SUDSWebServices``  package properly,  there
will  be a  ``SUDSWebServices`` entry  in  your ``Modules``
panel.
The  ``SUDSWebServices``  package will  generate  a  module for  each
published method in a web service.

.. %Figure TODO. 

Start with  a new empty workflow  in the ``Pipeline``  view, and drag
the following modules to the canvas.

.. index::
   pair: modules; adding

* ``String`` (under "Basic Modules")
* ``getOntologyChildren`` (under "Methods" for the current web service)
* ``getOntologyChildrenResponse`` (under "Types" for the current web service)
* ``OntologyDataItemList`` (under "Types" for the current web service)
* ``PythonSource`` (under "Basic Modules")
* ``RichTextCell`` (under "Spreadsheet")

As discussed in  Chapter :ref:`chap-creating`, ``PythonSource`` has no
input  and  output  ports  by  default;  we  need  to  create  some.  Open  the
configuration dialog  for ``PythonSource``  by selecting this  module in
the  pipeline  canvas   and  typing  'Ctrl-E'.  Add  a   new  input  port
named  "ontologyDataItemList" of  type ``List``,  and  a new
output port named "outfile"  of type ``File``. (Please refer
to Chapter :ref:`chap-creating` for more information about configuring and using
the ``PythonSource`` module.)

We will now add  some Python code to this module. This  code generates a simple
HTML table based on the information retrieved from the web service query.  Type
or  paste  the  following   source  code  into  the  ``PythonSource``
configuration dialog:

.. code-block:: python

   dataitemlist = self.get_input("ontologyDataItemList")
   output1 = self.interpreter.filePool.create_file()
   f1 = open(str(output1.name), "w")
   text = "<HTML><TITLE>Chebi WebService</TITLE><BODY BGCOLOR=#FFFFFF>"
   f1.write(text)
   text = "<H2>getOntologyChildren Query</H2><BR>"
   f1.write(text)
   text = "<CENTER><table border = 1><tr><TH>ChebiId</TH> <TH>ChebiName</TH>"
   text += "<TH>Comments</TH> <TH>Type</TH> <TH>Status</TH>"
   text += "<TH>CyclicRelationship</TH></tr>"
   f1.write(text)
   for element in dataitemlist:
       if not hasattr(element,'Comments') or str(element.Comments) == '[]':
           comment = ""
       else:
           comment = str(element.Comments)
       line = "<tr><td>" + str(element.chebiId) + "</td><td>" + str(element.chebiName)
       line += "</td><td>" + comment + "</td><td>" + str(element.type) + "</td><td>"
       line += str(element.status) + "</td><td>" + str(element.cyclicRelationship)
       line += "</td></tr>"
       f1.write(line)        
   text = "</table></CENTER></BODY></HTML>"
   f1.write(text)
   self.set_output("outfile",output1)
   f1.close()

Close the dialog.  One of the ports we need to use is an optional port.  Select the ``OntologyDataItemList`` module and select the ``Outputs`` tab from the ``Module Information`` panel.  Click in the left column next to ``ListElement`` so the eye icon appears.  Now connect the modules together as shown in Figure :ref:`fig-chebi_pipeline_screenshot`.

.. _fig-chebi_pipeline_screenshot:

.. figure:: figures/example_webservices/only_modules.png
   :align: center
   :width: 2.5in

   Our example pipeline

Our workflow is now complete except for one crucial element: the starting point.  We need to pass a chebiID string to the workflow in order to look up information about a chemical.  We do this by assigning a chebiID string to the ``String`` module at the top of the pipeline.  Highlight the ``String`` module in the canvas, then in the ``Module Information`` panel on the right, make sure the ``Inputs`` tab is selected and click on ``value`` and type ``CHEBI:15357`` into the ``String`` input box that comes up.

Executing the workflow
======================

.. index::
   pair: spreadsheet; RichTextCell

The workflow  is now ready  to be visualized.  Click  the ``Execute``
button  to   send  the  current   pipeline  with  the  current   parameters  to
a ``RichTextCell`` within the |vistrails|
Spreadsheet.           Your           result          should           resemble
Figure :ref:`fig-webservices_spreadsheet`.       As      you       can      see,
the "ontology children" query  returns the same information as before,
but without  the use  of a  web browser. In  addition, we  used a  small Python
program (via the ``PythonSource`` module)  to transform the raw XML into
a readable HTML table.

.. _fig-webservices_spreadsheet:

.. figure:: figures/example_webservices/ws_spreadsheet.png
   :align: center
   :height: 2.5in

   The HTML table generated by our workflow

.. rubric:: Footnotes
.. [#] ChEBI  is an acronym for Chemical Entities of Biological Interest.
