$Date: 2009-03-06 20:02:13 +0100 (Fri, 06 Mar 2009) $
$Rev: 289 $
Currently, IWWE&M has 6 frontends, used by AJAX GUIs:
First of all, all these frontends have lots of parameters, and some of them may contain international characters, like Spanish ñ or French and Catalonian ç. So, all these frontends expect that must of their parameters are encoded in UTF-8, no more, no less. The only exceptions are PARAM_ prefixed parameters passed as files, whose encoding can be driven by their corresponding ENCODING_ prefixed parameters
All these frontends use the concept of Ids: workflow Ids, example Ids, enaction Ids, snapshot Ids and confirmation Ids. All the unqualified Ids have the format of an UUID, but there are some differences when the IDs are fully qualified:
The workflowmanager frontend is responsible of all the workflow repository management tasks,
like workflow uploading and validation, workflow repository description, and workflow deletion.
Each time a workflow is uploaded, workflowmanager tries resolving all its dependencies before
validating it using INBWorkflowParserWrapper.
The workflowmanager frontend receives a set of optional input parameters, described below.
Then, it answers the list of available workflows and an optional message about the success of the
operation described by the optional input parameters, in XML. This XML content follows XML Schema
defined at IWWEM-messages.xsd, which is described
at IWWEM-messages.xsd.html.
Call parameters
When this frontend is called with no input parameter, it answers the detailed status of the workflow repository (see live example). Additional
parameters are used for the workflow repository maintenance:
- id (optional):
When this parameter is set with an identifier (workflow Id, qualified enaction Id, qualified snapshot Id), workflowmanager frontend change its default behavior, listing only this information instead of the default one (whole workflow repository listing). When this parameter is set with special keyword enaction:, workflowmanager frontend change its default behavior, listing whole enaction repository information as workflows. Last, when this parameter is set to a partially qualified snapshot Id, in the form of snapshot:{wUUID}, workflowmanager frontend change its default behavior, listing whole snapshot information associated to workflow {wUUID} as workflows.
- eraseId (optional, multiple):
When this parameter is set with an identifier (workflow Ids, qualified example Ids, qualified enaction Ids, qualified snapshot Ids), workflowmanager frontend disposes all the resources associated to the element labeled with that identifier before returning the workflow repository status. This parameter can be set many times, doing all the erasing operations at once.
- autoUUID (optional):
When this parameter is set, workflowmanager frontend uses it as automatable authentication token. This token has some different meanings, because it can be the one from a trusted user so it adds workflows, or from a trusted owner of something which is going to be erased.
- workflowRef (optional): This parameter was designed to upload new workflows by reference, usually from other repositories. This parameter must be either a valid internal or external workflow Id, a valid qualified enaction Id or a valid qualified snapshot Id associated to the corresponding resource in the workflow repository. If you want to upload a workflow by content, then workflow parameter must be used.
- workflow and workflowDep (optional, multiple):
These parameters were designed to upload new workflows to the workflow repository. So, the best enviroment to use them is in a POST transfer, in multipar/form-data style, optionally transferring them as files. workflow parameters represent the workflows to be added, in Taverna SCUFL format. As any of the uploaded workflows can have locally referenced dependencies, workflowDep parameters can be used to upload those local dependencies along with the workflows to upload. This step is not needed when there is no external dependency (i.e. the dependencies are already embedded in the workflows), or the dependencies are referenced with HTTP, HTTPS or FTP urls. The workflow addition operation is not effective until it is confirmed (see IWWEMconfirm and responsibleMail parameter).
- freezeWorkflowDeps (optional):
If this parameter is set, then any workflow dependency on external workflows which is found is substituted by the content of the reference workflow.
- responsibleMail and responsibleName(optional):
Parameter responsibleMail must be set with a valid e-mail address when optional workflow parameter is set, because it is the e-mail address of the responsible person of the workflow (different from the workflow author).
Parameter responsibleName can be set to the name of the responsible person of the workflow to be inserted.
- licenseURI and licenseName(optional):
Parameter licenseURI should be set with a valid URI pointing to a license document when optional workflow parameter is set, because it is the URI of the document where the distribution and manipulation rights of the workflow are described.
Parameter licenseName can be set to a common abbreviated name used to tell about the license model.
- dataIsland (optional, either 1 or 2):
When this parameter is set to 1 or 2, the workflow repository report is returned embedded in an XML data island.
This parameter was created because AJAX GUIs running on some browsers (like Konqueror or old Internet Explorer versions) cannot
parse pure XML loaded in embedded FRAMEs or IFRAMEs due browser limitations. When the parameter is 1, the content is wrapped
by an xml tag (for Internet Explorer), and when parameter is 2, the content is wrapped by a div tag
(for Konqueror).
- altViewerURI (optional): When a workflow is added,this parameter allows customizing the enaction viewer URI to use when an enaction is run. The URI can optionally contain the particle @JOBID@, so IWWE& core knows where to put the job id when it has to build a GUI enaction URI.
The enactionlauncher frontend module is used to start an enaction process over a given input workflow or a previously stored one. As any program based on Taverna core uses lots of resources for any enaction process, enactionlauncher must restrict the number of concurrent enaction instances, queuing further queries until an enaction slot is available for each one.
In any case, enactionlauncher builds up the input parameters for INBWorkflowLauncherWrapper, and
it also manages the creation and usage of example inputs. Also, enactionlauncher must create both the
job identifier returned and the infrastructure needed by enactionstatus
module and INBWorkflowLauncherWrapper backend program. This job identifier is returned in XML format, which follows
the XML Schema defined at IWWEM-messages.xsd and described
at IWWEM-messages.xsd.html.
Call parameters
- dataIsland (optional, either 1 or 2):
When this parameter is set to 1 or 2, the enaction launcher report is returned embedded in an XML data island.
This parameter was created because AJAX GUIs running on some browsers (like Konqueror or old Internet Explorer versions) cannot
parse pure XML loaded in embedded FRAMEs or IFRAMEs due browser limitations. When the parameter is 1, the content is wrapped
by an xml tag (for Internet Explorer), and when parameter is 2, the content is wrapped by a div tag
(for Konqueror).
- workflowRef or its alias id (required): This parameter must be either a valid internal or external workflow Id, a valid qualified enaction Id or a valid qualified snapshot Id associated to the corresponding resource in the workflow repository. If this parameter is not used, then workflow parameter must be used.
- reusePrevInput (optional): When id parameter is either a qualified enaction Id or a qualified snapshot Id, this parameter is set and no other input has been sent, the input from previous enaction or snapshot is reused. Otherwise, it is ignored.
- workflow and workflowDep (optional, multiple):
These parameters were designed to upload new workflows to the workflow repository. So, the best enviroment to use them is in a POST transfer, in multipar/form-data style, optionally transferring them as files. workflow parameters represent the workflows to be added, in Taverna SCUFL format. As any of the uploaded workflows can have locally referenced dependencies, workflowDep parameters can be used to upload those local dependencies along with the workflows to upload. This step is not needed when there is no external dependency (i.e. the dependencies are already embedded in the workflows), or the dependencies are referenced with HTTP, HTTPS or FTP urls.
- BACLAVA_FILE (optional, multiple): This parameter is used to set input values for the enaction process as a whole. This parameter can be used in two different ways: when this parameter has been passed as a value, then its content is interpreted as the identifier (either qualified or unqualified) of an input example associated to the workflow identified by the id parameter; when this parameter has been passed using a POST transfer in multipart/form-data style and it has been marked as a file, then its value is interpreted as the raw content of a Baclava-formatted file.
- PARAM_ prefixed parameters (optional, multiple): These parameters are used to set values for the inputs of the workflow to be enacted. The text after the PARAM_ prefix sets the name of the input to be assigned. As BACLAVA_FILE parameter, these parameters can be used in two different ways: when any of these parameters has been passed as a value, then its content is interpreted as the raw value; when this parameter has been passed using a POST transfer in multipart/form-data style and it has been marked as a file, then the content of this transferred file is interpreted as the raw content assigned to the parameter.
- ENCODING_ prefixed parameters (optional, multiple): These parameters are used to tell the encodings of the values for the inputs of the workflow to be enacted, and they must be legal ones. They way to tell that an input is binary is using the illegal encoding "binary". The text after the ENCODING_ prefix sets the name of the input to be assigned to. If there is no prefixed PARAM_ parameter corresponding to an encoding one, then it is discarded. If there is no prefixed ENCODING_ parameter corresponding to a parameter one, then it is assumed that its encoding is UTF-8.
- MIME_ prefixed parameters (optional, multiple): These parameters are used to tell the MIME types of the values for the inputs of the workflow to be enacted, and they should be legal ones. The text after the MIME_ prefix sets the name of the input to be assigned to. If there is no prefixed PARAM_ parameter corresponding to a MIME type one, then it is discarded. Other supplementary way to send a MIME type is through the Content-Type header associated to a file transfer in multipart/form-data style.
- exampleName and exampleDesc (optional): These parameters are used to save and describe the input to this workflow enaction as an input example associated to the original workflow. These parameters do not work with inline workflow definitions. exampleName has no restrictions in its value, and at the moment it should be encoded in UTF-8. exampleDesc is the description of the input example which is being created, and it can be HTML content (also encoded in UTF-8). The example addition operation is not effective until it is confirmed (see IWWEMconfirm and responsibleMail parameter). Current behavior is that when an example is saved, no workflow enaction is issued (and so onlySaveAsExample is deprecated).
- responsibleMail and responsibleName(optional):
Parameter responsibleMail must be set with a valid e-mail address when optional exampleName parameter is set, because it is the e-mail address of the responsible person of the example (different from the workflow author and workflow responsible).
An e-mail is sent to the responsible person when enaction is just starting and when enaction has just finished. Parameter responsibleName can be set to the name of the responsible person of the example to be inserted.
- autoUUID (optional):
When this parameter is set, enactionlauncher frontend uses it as automatable authentication token. This token has some different meanings, because it can be the one from a trusted user so it adds examples.
- onlySaveAsExample (optional, deprecated): When exampleName is set, id parameter is a workflow Id, a qualified enaction Id or a qualified snapshot Id, and this parameter is set, only save parameters stage is done and no enaction process is issued.
- altViewerURI (optional): When a job is launched, an e-mail with the URL to the enaction viewer is sent. This parameter allows customizing that enaction viewer URI just for this run. The URI can optionally contain the particle @JOBID@, so IWWE& core knows where to put the job id when it has to build a GUI enaction URI.
The frontend module enactionstatus reports the status of an in-course or finished enaction.
It reports the available inputs and outputs for the whole enaction process and any of its steps, and it also
reports the same information for any of the iterations of any workflow step. Additional information, like if
an step has started, is iterating, has finished or has failed is also provided. All this information is described
in an XML format which follows the XML Schema defined at
IWWEM-messages.xsd and described
at IWWEM-messages.xsd.html.
This frontend module is also responsible of new enaction snapshots creation, the kill of in-course jobs and the disposal of
enactions and enaction snapshots.
Call parameters
- jobId (required):
enactionstatus frontend needs either an enaction job identifier (either qualified or unqualified) or a qualified snapshot identifier.
- dispose (optional, either 0 or 1):
If this parameter is set to 0, the enaction process is killed (if it is still running).
If this parameter is set to 1, the server resources used by the job or snapshot identified
with the jobId parameter are reclaimed and freed.
- snapshotName and snapshotDesc (optional):
These parameters are used to take, name and describe an snapshot. An snapshot of an snapshot cannot
be taken. snapshotName has no restrictions in its value, and at the moment it should be encoded in UTF-8.
snapshotDesc is the description of the snapshot, and it can be HTML content (also encoded in UTF-8). The snapshot addition operation is not effective until it is confirmed (see IWWEMconfirm and responsibleMail parameter).
- responsibleMail and responsibleName(optional):
Parameter responsibleMail must be set with a valid e-mail address when optional snapshotName parameter is set, because it is the e-mail address of the responsible person of the snapshot (different from the enaction responsible).
Parameter responsibleName can be set to the name of the responsible person of the snapshot to be inserted.
- autoUUID (optional):
When this parameter is set, enactionstatus frontend uses it as automatable authentication token. This token has some different meanings, because it can be the one from a trusted user so it adds snapshots, or from a trusted owner of something which is going to be disposed.
This frontend module was created to overcome some of the limitations of current browsers. Enaction process launched with enactionlauncher save both inputs and ouputs of the whole process, intermediate steps and iterations in Baclava XML format. AJAX GUI Enaction Viewer allows the end user to browse this information, but some data viewers it uses are only able to handle information coming from an URL. IWWEMproxy is responsible of decoding, extracting and streaming this information under demand. Data bundles can be accessed in listing or raw modes when bundle64 and IOPath parameters are unset. Data bundles listing shows the backbone of the data bundle (i.e. its tree structure), meanwhile raw mode access gives full access to the raw storage format (Baclava).
Call parameters
- jobId (required):
IWWEMproxy frontend needs either a qualified or unqualified enaction job identifier, a qualified snapshot identifier or a qualified example identifier in order to work and know where to find the information to decode, extract and stream.
- asMime (required):
The value of this parameter sets the MIME type used to label the streamed information, so HTTP clients (web browsers, GUIs) are able to select a viewer or a program to use based on it. It is ignored when bundle64 and IOPath are unset.
- charset (optional):
The value of this parameter sets the charset of the streamed information, so HTTP clients (web browsers, GUIs) are able to see it properly. It is ignored when bundle64 and IOPath are unset.
- withName (optional):
The value of this parameter sets the suggested name for the streamed content when it is going to be saved by a web browser. If this parameter is set to the empty string, the suggested name is derived from the input parameters.
- bundle64 (optional):
When this parameter is set, then the information to decode, extract and stream comes from its value.
If bundle64 is not set, then information needed to fetch and decode is given by next parameters:
- step (optional):
The name of the workflow step which took this input or generated this output. This only make sense for enaction job identifiers and snapshot identifiers, when the information from a concrete step is being fetched.
- iteration (optional):
If we have set the workflow step and the workflow step iterated, the iteration number. Otherwise, the whole step is taken into account.
- IOMode (optional, either I, O or B):
This parameter only makes sense with enaction job and snapshot identifiers. If this parameter is set to I, then IOPath is referring to an input. If this parameter is set to O, then IOPath is referring to an output. Parameter can only be set to B when IWWEMproxy is used either in listing or raw modes.
- raw (optional):
When requested information is in list mode, this parameter switches to its raw representation.
- IOPath (required):
The virtual path to reach the value to return. These paths are similar to:
- gene_input: An input (or output) with the name gene_input and a single value
- Genes/17/0: An input (or output) with the name Genes and a set of values. We are getting value 0 from subset 17 from Genes. The number of nested subsets depend on the data structure
- PDB_Enriched(structure)/#EnrichedPDB[0]: An input (or output) with the name PDB_Enriched(structure) and a single value, which has an interesting result identified and extracted by EnrichedPDB pattern. The value which is returned is the result 0 obtained when EnrichedPDB pattern is applied to PDB_Enriched(structure).
Characters '#' (virtual step), '/' (step separator) and '&' have special meanings. If any step in the IOPath contains any of these characters,
you must substitute occurrences of '#' with '#' or '#', '/' with '/' or '/', and '&' with '&'.
Patterns used in IOPath parameter are stored in the IWWE&M server in an XML document, which follows the XML Schema IWWEM-patterns.xsd (documentation). Currently defined global patterns are available at EVpatterns.xml
IWWE&M: IWWEMconfirm frontend documentation and call parameters
This frontend module is used as an operations confirmation proxy. All erasing operations requested using workflowmanager (workflows, examples, snapshots and enactions),
and the addition operations from workflowmanager (workflows), enactionlauncher (examples) and enactionstatus (snapshots) must be confirmed by the end user before being effective. So, these frontends use responsibleMail parameter to send e-mails to the responsible people of the object to be added/removed, which contain an URL to this frontend. When the URL is visited, the operation is just made effective.
Call parameter
- code (required): The confirmation Id, or code, which confirms the operation.
- reject (optional): If it is set, the actions of the operation are rejected.
IWWE&M: IWWEMfs frontend documentation and call parameters
This frontend module was created to give path-like access to almost all the information stored and provided by IWWE&M server.
So, it provides almost all the information you can fetch using workflowmanager
(available workflows and enactions), enactionstatus (enaction and snapshot status)
and IWWEMproxy (access to workflow examples content, and inputs and results from enactions
and snapshots), including single files like workflow graphs or raw workflow definitions.
Call parameters
This module reuses parameters asMime, charset and withName
from IWWEMproxy, and reuses the semantics of the content of IOPath
from IWWEMproxy when an input or an output is being fetched.
- digested (optional):
When requested Input/Output information is in raw mode, this parameter switches to its digested (listing) representation.
As this module works in a seamless way with virtual paths, next ones are relative sample URIs with valid paths:
- IWWEMfs/workflows (detailed list of available workflows)
- IWWEMfs/workflows/a04fe33d-4496-415b-a6ef-8b92559160f0/workflow.svg (SVG graph representation of a concrete workflow)
- IWWEMfs/workflows/a04fe33d-4496-415b-a6ef-8b92559160f0/workflow.xml (Taverna representation of a concrete workflow)
- IWWEMfs/workflows/a04fe33d-4496-415b-a6ef-8b92559160f0/examples/fc4756c6-c7fa-4237-9fb3-4ab03895d075.xml (An example in Baclava format)
- IWWEMfs/enactions (detailed list of available enactions, as workflows)
- IWWEMfs/enactions/87f3c937-a822-41fa-9749-93efd6f9eeb7 (detailed status of an enaction)
- IWWEMfs/enactions/87f3c937-a822-41fa-9749-93efd6f9eeb7/Outputs.xml (outputs in Baclava format)
- IWWEMfs/enactions/87f3c937-a822-41fa-9749-93efd6f9eeb7/Results/getSymbolInteractions/Inputs.xml/Object(search)
(value of one of the inputs to getSymbolInteractions enaction step)
- IWWEMfs/enactions/87f3c937-a822-41fa-9749-93efd6f9eeb7/Results/extractSymbols/Iterations/0000/Outputs.xml?digested=1
(listing of available outputs from iteration 0000 from enaction step extractSymbols)
"INB IWWE&M frontends call parameters" by José María Fernández González is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License.
Based on a work stored at IWWE&M Trac Server.