Launching workflows from external sources¶
If your analysis workflows are hosted on external sources such as source code repositories (GitHub, GitLab), digital repositories (CERN Open Data, Zenodo), or other locations on the web (generic URL), it is possible to launch your workflows directly from the REANA web interface. This technique is an alternative way of executing workflows using a command-line client.
For example, to launch a RooFit demo workflow from GitHub on REANA instance at CERN, you can click on the badge below:
After clicking on the above Launch-on-REANA@CERN badge, you will be redirected to the
and presented with an intermediate launcher page where you can check desired parameters and click on the "Launch" button to execute this workflow.
The launcher functionality is available on
/launch URL and looks like:
url, pointing to the external source where the analysis is hosted;
name(optional), providing the desired workflow run name (default=workflow);
specification(optional), pointing to the REANA specification file (default=reana.yaml);
parameters(optional), providing encoded list of parameter values for the workflow execution (default=none).
For example, the above badge for RooFit demo workflow is using this URL:
The arguments are explained in detail below. Please note that argument values should be properly encoded in order to comply with RFC 2396 URI standard.
url is a required argument that points to the external source where your workflow is hosted.
Below you can find supported external sources.
You can point to publicly available GitHub or GitLab repositories to launch a workflow. Below are examples of supported URL formats:
https://github.com/reanahub/reana-demo-root6-roofit/tree/my-branch(to launch a particular branch)
https://github.com/reanahub/reana-demo-root6-roofit/tree/v1.0(to launch a particular tag)
https://github.com/reanahub/reana-demo-root6-roofit/tree/3441d3b2d417c7f39f091a1d7f0df38bdaca82e8(to launch a particular commit hash)
You can also provide a generic URL to any hosting service, for example:
https://example.org/reana.yaml(to launch a workflow from its specification)
https://zenodo.org/record/5752285/files/circular-health-data-processing-master.zip(to launch a workflow from a zip tarball)
The launch page accepts an optional
name argument that will determine the desired name of the launched workflow.
If the argument is missing, REANA will generate a name based on the URL of the external source, repository or branch name.
If your workflow uses a different REANA specification file than the default
you can specify the path to the desired specification file using the
specification optional argument:
You can optionally send extra parameters for the workflow execution that would override the ones specified in your REANA specification file.
For example, the RooFit demo example uses
events parameter to determine how many events to generate.
If you would like to override the default value of 20000 to, say, 30000, you can pass in a JSON format:
Note that the value should be properly encoded, which gives:
Final URL looks like this:
You may want to generate a custom "Launch-on-REANA" badge and include it in your source code repository so the analysis would be runnable with a single click.
The standard set of badges look as follows:
You can include one of the above badges into your Markdown documentation pages using the following syntax:
[![Launch on REANA badge](https://www.reana.io/static/img/badges/launch-on-reana.svg)](https://reana.cern.ch/launch?url=https%3A%2F%2Fgithub.com%2Freanahub%2Freana-demo-root6-roofit)
This example points to the RooFit analysis demo. You should replace the
url to point to your own analysis sources.
You can include one of the above badges into your HTML documentation pages using the following syntax:
<a href="https://reana.cern.ch/launch?url=https%3A%2F%2Fgithub.com%2Freanahub%2Freana-demo-root6-roofit"><img src="https://www.reana.io/static/img/badges/launch-on-reana.svg" alt="Launch on REANA badge"></a>