API Method: workflow create

POST /:user_id/workflow/:workflow_id

Creates and enacts (i.e. runs) the supplied sequence of REST API commands in the specified user account. Returns the string "ok" with a 201 Created HTTP status code. The method returns immediately but the workflow may take a long while to execute (possibly minutes or hours). Workflows are automatically destroyed once completed. Creating a workflow with the same workflow_id as an existing workflow (in the same user account) will halt and replace the existing workflow if not already completed.

Note that this is a minimalist workflow language and enactment system; it is no replacement for a full scientific workflow system and is only provided as a convenience for simple use cases: in particular to enable Web 2.0 applications to easily initiate long-running tasks (e.g. harvesting web pages) and multistep tasks (e.g. import documents and then profile them once the importing has finished) without having to use other systems.

URL:

http://subsift.ilrt.bris.ac.uk/user_id/workflow/workflow_id.format

Formats (about return formats):

csv, json, rdf, terms, xml, yaml

HTTP Methods (about HTTP methods):

POST

Requires Authentication (about authentication):

true

Parameters:

  • workflow_id. Required. The ID of the workflow to create in the specificed user account.
  • commands. Required. A list of SubSift REST API commands in csv format, where each row specifies the flow, method, url and (optionally) parameters of a single API command. The flow determines the behaviour in response to the HTPP status code and is one of:
    • + where a success HTTP status code is required to continue to the next command;
    • - where a failure HTTP status code is required to continue to the next command;
    • ? where the HTTP status code is ignored and enactment continues to the next command regardless;
    • * where this command is repeated until a failure HTTP status code is returned and then enactment continues to the next command. This may only be used for HTTP read-only methods (i.e. get and head) and should be used with caution to avoid infinite workflows.
    The method is one of: get, delete, head, post, put. The parameters are none or more key=value pairs with each pair delimited by commas. To specify a parameter value with line breaks or commas in, enclose the entire parameter pair (not just the value) in quotes - i.e. "key=value", not key="value". Otherwise, quotes are optional. Use normal csv double quotes to include a single quote in the value (e.g. "name=Mike ""Mobile"" Jones" defines a pair with key name and value Mike "Mobile" Jones).
    • Example: http://subsift.ilrt.bris.ac.uk/kdd09/workflow/myflow.xml
      commands=
      ?, delete, documents/pc
      +, post, documents/pc, description=Programme Committee, mode=private
      +, post, documents/pc/import/pc
      *, head, documents/pc/import/pc
      ?, delete, profiles/pc
      +, post, profiles/pc/from/pc, "ngrams=1,2", limit=3
      ?, delete, profiles/abstracts
      +, post, profiles/abstracts/from/abstracts, "ngrams=1,2", limit=3
      ?, delete, matches/pc_abstracts
      +, post, matches/pc_abstracts/profiles/pc/with/abstracts

      The above example deletes and creates/recreates a documents folder called "pc" into which it imports the bookmarks from bookmarks folder "pc". It then profiles the "pc" documents folder. A similar sequence then follows for the "abstracts". Finally, a match is performed between the "pc" and "abstracts" profile folders to create the "pc_abstracts" matches folder. Each command will wait for the previous command to complete - including waiting for all the bookmarks imported into the "pc" folder to be harvested by the web robot (which may take minutes or hours). Note that it is not necessary to specify the implicit "http://subsift.ilrt.bris.ac.uk/kdd09/" prefix for each url. Likewise, the authorisation token is not required for each command.

Usage Examples:

cURL (about cURL):

cURL is not particularly convenient for submitting multi-line data because the arguments have to be uri encoded so that, for example new lines become %0A and special uri characters like + become %2B or " become %22.

curl -X POST -H "Token:mytoken" -d "commands=
?,delete,bookmarks/pc%0A
%2B,post,%20bookmarks/pc,description=PC%20homepages,mode=private,%22items_list=%0A
Peter%20Flach,http://www.cs.bris.ac.uk/~flach%0A
Simon%20Price,http://www.cs.bris.ac.uk/~price%22%0A
?,delete,documents/pc%0A%2B,post,documents/pc,description=PC,mode=private%0A
%2B,post,documents/pc/import/pc%0A
*,head,documents/pc/import/pc%0A
%2B,post,profiles/pc/recalculate"
http://subsift.ilrt.bris.ac.uk/kdd09/workflow/myflow.xml

For the sake of clarity, the submitted commands in the above example are the uri encoded version of the following unencoded text:

?,delete,bookmarks/pc
+,post, bookmarks/pc,description=PC homepages,mode=private,"items_list=
Peter Flach,http://www.cs.bris.ac.uk/~flach
Simon Price,http://www.cs.bris.ac.uk/~price"
?,delete,documents/pc
+,post,documents/pc,description=PC,mode=private
+,post,documents/pc/import/pc
*,head,documents/pc/import/pc
+,post,profiles/pc/recalculate

Response (about return values):

XML example:

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <value>ok</value>
</result>