Productionize

URLs in the KNIME WebPortal

August 12, 2014 — by Christian Albrecht

If you are using the KNIME Server with the KNIME WebPortal in your organization you can easily share published workflows with your colleagues by using the URL parameters of the WebPortal. Not only is this a great way of linking directly to a specific workflow, but it also gives you the possibility to embed the WebPortal somewhere else in your corporate environment.

This powerful feature was introduced with KNIME Server 3.7 and some enhancements were added with version 3.8.

Navigation

To understand how the URLs work, let's look at a quick example:
http://<Server_Address>:<port>/<ContextRoot>
is the scheme of the general browser access to your WebPortal. For example this might look like:
http://localhost:8080/webportal

 

To now link to a workflow append the pound sign and the absolute path to the desired item:
http://localhost:8080/webportal/#/myWork/workflow
If you type this URL into your browser the WebPortal will automatically redirect you to the specified workflow and the start page with workflow description, variables, etc. will be shown. In case you were not logged in beforehand, you will see the login page and after successful authentication be redirected to the workflow as well.

Workflow jobs are identified by a unique id. To link directly to a job you can append this id by setting the exec parameter:
http://localhost:8080/webportal/#/myWork/workflow?exec=jobID
When you want to share a workflow URL with your colleague, there is in most cases no need to construct it manually. Simply navigate the workflow tree on the left hand side and select the desired workflow or job. The URL will automatically be updated in the location bar of your browser and always reflect the selected workflow or job.

For portability the URLs can also be created by using relative paths. By a path that starts with ../ the parent item of the currently selected workflow or workflow group will be selected. This is very helpful if you for example want to construct a drill-down analysis and providing the user with different workflows, that can then be linked from one master workflow. You can also use these links in your workflow by using the TextArea Output node with HTML format selected or include them into BIRT reports.

Parameterization

The URLs provide even more powerful possibilities when used with additional parameters. The parameters can appear in any order after the path and are always appended with an ampersand sign in front of the parameter name.

&single
Appending this parameter will hide the workflow tree on the left hand side. The use of this option is particularly helpful when a certain workflow is supposed to be embedded in a different application or website.

&run
If the auto-run parameter is appended to a URL linking to a workflow, a new job is automatically created and started. Using this option on a workflow with wizard execution enabled results in the first input page being shown. If there are no eligible Quickform nodes inside the workflow, the result page is shown directly after successful execution.

&wv:<name>=<value>
Use this option to assign a value to a globally defined workflow variable. This is helpful when the start page of a workflow is supposed to be skipped (&run parameter) and the workflow needs to be parametrized to successfully execute.

 

&cr:<name>=<user>:<password>
Similar to workflow variables you can also assign workflow credentials in the URL. Note that the credentials and user name cannot contain the “=” and “:” symbols and that the password is transmitted in plain text.

&emails=sample@domain.com
The KNIME Server can send out email notifications after a workflow job has finished. These contain the status of the workflow and may contain generated report files. To enable this feature use the &emails parameter. Specify the list of recipients as a comma separated list of email addresses, as the value of the parameter.

&formats=<formats>
If a workflow generates a report and the email notification feature is enabled, you can additionally specify the output formats of that report. Simply append a comma separated list of the desired formates. Available formats are: pdf (enabled by default), html, doc, xls, ppt, ps, odt, ods and odp.

&root=path/to/root
To further restrict the visible part of the workflow tree, you can use the &root parameter. Provide the path to the item, that is supposed to be the root element of the tree.

You can mix and match all these parameters as you need. A complete URL might look like
http://localhost:8080/webportal/#/demo/file%20to%20csv&wv:title=foo&ema…
at the end. This URL navigates to the specified workflow, sets a workflow variable, enables email notification, hides the workflow tree and starts a new job.

Further reading