API Documentation: Workflow invocation

[innovate-invent]

The documentation is incomplete/ambiguous for invoking a workflow.

Can someone clarify:

POST /api/workflows/{encoded_workflow_id}/invocations

vs.

POST /api/workflows with workflow_id

There is also the issue that the documentation only describes the 'legacy' method of workflow invocation. There is an undocumented 'inputs' parameter being referenced in the code.

@jmchilton the git blame says you would be best to answer this

[mvdbeek]

The second one is a general purpose endpoint that does all "create-y" things, like import from archive, create from history, import from toolshed repo and run depending on the keywords. This is the one used by the UI for running workflows.

The first one is newer but takes the same arguments and runs through the same code to build the workflow config, but queues workflows differently (doesn't wait for some things to happen ...) and doesn't return any outputs, just the invocation(s). So for external API usage use /invocations.

The docs are a little more extensive on bioblend:
https://bioblend.readthedocs.io/en/latest/api_docs/galaxy/all.html#bioblend.galaxy.workflows.WorkflowClient.invoke_workflow

[innovate-invent]

Thanks! What is the format of the inputs record for simple input params?

…

On Sat, Aug 3, 2019, 1:48 AM Marius van den Beek, ***@***.***> wrote: The second one is a general purpose endpoint that does all "create-y" things, like import from archive, create from history, import from toolshed repo and run depending on the keywords. This is the one used by the UI for running workflows. The first one is newer but takes the same arguments and runs through the same code to build the workflow config, but queues workflows differently (doesn't wait for some things to happen ...) and doesn't return any outputs, just the invocation(s). So for external API usage use /invocations. The docs are a little more extensive on bioblend: https://bioblend.readthedocs.io/en/latest/api_docs/galaxy/all.html#bioblend.galaxy.workflows.WorkflowClient.invoke_workflow — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#7593?email_source=notifications&email_token=AANP25EG32E7U7MOEQUTR53QCVA43A5CNFSM4HA5ZKEKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD3PKGYA#issuecomment-517907296>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AANP25GRRHCG76IHHLWPOVDQCVA43ANCNFSM4HA5ZKEA> .

[mvdbeek]

Same as for dataset inputs, they're all regular input parameters.
You can see the required values with a GET to /api/workflows/<workflow_id>,
which should return something like:

In [4]: gi.workflows.show_workflow('06ec17aefa2d49dd')
Out[4]:
{'model_class': 'StoredWorkflow',
 'id': '06ec17aefa2d49dd',
 'name': 'Select first n lines',
 'published': False,
 'deleted': False,
 'tags': [],
 'latest_workflow_uuid': 'd494800b-a4ae-4a2c-aa3c-89c4c2f474d7',
 'url': '/api/workflows/06ec17aefa2d49dd',
 'owner': 'mvdbeek',
 'inputs': {'0': {'label': 'My input',
   'value': '',
   'uuid': 'ac600c9c-04f0-4e2d-9bd7-636de8a7ae56'},
  '1': {'label': 'Select the number of lines',
   'value': '',
   'uuid': '6904ef57-f6b9-46ce-bdab-e66d744e0329'}},
 'annotation': None,
 'steps': {'0': {'id': 0,
   'type': 'data_input',
   'tool_id': None,
   'tool_version': None,
   'annotation': None,
   'tool_inputs': {},
   'input_steps': {}},
  '1': {'id': 1,
   'type': 'parameter_input',
   'tool_id': None,
   'tool_version': None,
   'annotation': 'Very important',
   'tool_inputs': {'__page__': None,
    '__rerun_remap_job_id__': None,
    'optional': 'false',
    'parameter_type': 'integer'},
   'input_steps': {}},
  '2': {'id': 2,
   'type': 'tool',
   'tool_id': 'toolshed.g2.bx.psu.edu/repos/bgruening/text_processing/tp_head_tool/1.1.0',
   'tool_version': '1.1.0',
   'annotation': None,
   'tool_inputs': {'__page__': None,
    '__rerun_remap_job_id__': None,
    'complement': '',
    'count': {'__class__': 'ConnectedValue'},
    'infile': {'__class__': 'ConnectedValue'}},
   'input_steps': {'count': {'source_step': 1, 'step_output': 'output'},
    'infile': {'source_step': 0, 'step_output': 'output'}}}},
 'version': 5}

So in this case in can run the workflow (if you use the uuid) in bioblend with

inputs = {'ac600c9c-04f0-4e2d-9bd7-636de8a7ae56': {'id': 'e2f19943bfe7b314', 'src': 'hda'}, '6904ef57-f6b9-46ce-bdab-e66d744e0329': 2}
gi.workflows.invoke_workflow('<workflow_id>', inputs=inputs)

That'd be the same as POSTing to /api/workflows/<workflow_id>/invocations with {'inputs': inputs, 'key': <api_key>}.

You can also specify the inputs by name, though that's not exposed in bioblend.
In that case the payload would be

{'inputs': '{"My input": {"id": "e2f19943bfe7b314", "src": "hda"}, "Select the '
           'number of lines": 2}',
 'inputs_by': 'name',
 'key': '<your_api_key>'}

and you can POST that like

In [77]: import requests

In [78]: r = requests.post('http://localhost:8080/api/workflows/06ec17aefa2d49dd/invocat
    ...: ions', payload)

In [79]: r.json()
Out[79]: {'model_class': 'WorkflowInvocation', 'id': 'f6509e58756240f2', 'update_time': '2019-08-04T11:29:05.334846', 'workflow_id': 'aebaa141e7243ebf', 'history_id': '32d48e3506ae8cf7', 'uuid': '11094652-b6ab-11e9-8aa4-c4b301d1ef93', 'state': 'new'}

If you want to specify the params by name make sure the inputs really have specified labels.

[innovate-invent]

Thanks!
If a workflow has a single dataset input but receives a collection: "My input": {"id": "e2f19943bfe7b314", "src": "hdca"}, does it automatically map over the entire workflow?

[innovate-invent]

@martenson can you please reopen this issue, it is unresolved.

[martenson]

@innovate-invent I believe I addressed your concern in #8541. The rest of the issue seems like a support discussion so I'd like to have it elsewhere. Either gitter or https://help.galaxyproject.org work.

[innovate-invent]

The issue is that the domain of the parameters for this api endpoint isn't clear. #8541 doesn't address this.

[martenson]

@innovate-invent please create a new issue with sample workflow, invocation, expected results, and received results to help us debug it

[innovate-invent]

I think you misunderstand, there is no bug. I am requesting documentation of the workflow invocation endpoint, its parameters, and their domains.

[martenson]

@innovate-invent I invite you to read the code and/or test the execution and then update the documentation if you deem it beneficial. But I think we cannot have an open issue for every tiny bit of documentation missing.

[innovate-invent]

That is a contradiction to what I was told repeatedly by the Galaxy team.
Please see the conversation here #8349