KNIME WebPortal User Guide


Introduction

KNIME WebPortal is an extension to KNIME Server. It provides a web interface that lists all accessible workflows, enables their execution and investigation of results. The workflows' input and output can be parameterized and their visualizations customized, using Configuration and Widget nodes, Interactive Widget and View nodes. Using components containing these nodes it is then possible to create WebPortal pages.

In addition, report templates created with KNIME Report Designer that are uploaded together with their associated workflow to KNIME Server can be filled dynamically with data and downloaded in various formats.

The successful execution of the workflows can be alerted by email, and reports, if present, can be sent attached in various formats.

Creating workflows for KNIME WebPortal

A workflow execution on KNIME WebPortal consists of one or more pages or wizard steps, where a user gets guided through the process. Each page or step corresponds to the composite view of a component in the workflow. For a more comprehensive explanation about components, please refer to the KNIME Components Guide.

Composite views

You can create composite views in components, assembling different Widget nodes, Interactive Widget nodes and View nodes.

Once you have created them you can also style their layouts arranging them within the composite view and also adding some other elements to the layout. In this way you can decide how they will be visualized on the page once you run them in KNIME WebPortal.

Widget nodes

The nodes in the node repository categories Workflow AbstractionWidgets can be used to create composite views, where the user is able to adjust parameters which then can be used by the workflow to control the execution of nodes.

Widget nodes are especially useful when used in workflows designed for deployment to KNIME Server via KNIME WebPortal. When KNIME WebPortal encounters a Widget node in a workflow, it prompts the user to enter new values for its variables before proceeding with the workflow execution. The new values are injected into the workflow, and used to parameterize its execution.

You can create a component which encapsulates one or more Widget nodes. In this way you can create a composite view which will be a page on KNIME WebPortal.

Please refer to the Widget nodes section of the KNIME Components Guide, for a more comprehensive overview of the Widget nodes.

View and Interactive Widget nodes

The nodes in the node repository categories ViewsJavaScript can also be used to create composite views, which will then be visualized as a page on KNIME WebPortal.

Interactive Widget nodes can be encapsulated in components together with View nodes to build a page on KNIME WebPortal where views and interactive widgets are combined.

For an overview on how to build composite views please refer to the Components composite views section of the KNIME Components Guide.

Layouting composite views

You can customize the layout of composite views, deciding how the View and Widget nodes are visualized on the page.

Please note that with KNIME Server version 4.11 we introduced the legacy mode for execution of Widget nodes. Refer to the section Legacy Widget nodes to have more information about the legacy mode.

For an overview on how to layout composite views please refer to the Layout of composite views section of the KNIME Components Guide.

Stepping through pages

Each composite view of a component at the root level of the workflow represents one page in KNIME WebPortal.

Please notice that components that are not in the root level of the workflow, i.e. components wrapped inside a component, will not correspond to a page when the workflow is run in KNIME WebPortal.

For example, a series of three pages can be modeled with a sequence of three components, as the one shown in Figure 1.

02 sequence of nodes
Figure 1. A workflow made of three components

The composite view of each component will be a page in KNIME WebPortal, as shown in Figure 2.

02 sequence of views
Figure 2. Step-by-step execution on KNIME WebPortal of a workflow made of three pages

To dynamically show and hide pages during execution it is possible to disable a composite view of one component, activating of disactivating branches in the workflow, e.g. by means of IF or CASE blocks.

02 if workflow
Figure 3. A workflow using a IF block

It is also possible to insert components inside a loop to iterate over an item set or recursively refine a model, as shown in Figure 4.

02 loop workflow
Figure 4. A workflow using loop

Create temporary directories

If you want to write some data on KNIME WebPortal, which is later downloaded by means of, e.g. a web link, you can use Create Temp Dir node.

This node will create temporary files in unique temporary folders and expose the path to the temporary file as a flow variable. A Writer node can write a file to the temporary folder and a File Download node can make the written file available for download.

This is the configuration dialog of the Create Temp Dir node:

02 create temp dir dialog annotated

Create Temp Dir node settings:

  1. Prefix for the new folder. Unique names will be created automatically.

  2. Flow variable to be created containing the absolute path of the new folder

  3. If enabled, the newly created folder will be deleted when the node is reset (along with all contained files)

  4. Create temporary directory in the workflow folder

  5. Create file paths

  6. Add a new variable and file reference

  7. For each row in this table, a new workflow variable is created. The variable name is entered on the left and the file to be created on the right. The final variable will refer to the full path including folder and filename.

Publishing workflows

Workflows and, if present, any associated report templates are published on KNIME WebPortal by simply uploading the workflow from the local workspace to the corresponding KNIME Server mountpoint.

To do this you can:

  1. Copy/paste or drag and drop a workflow from a local workflow repository to a server repository

  2. Right-click the workflow and choose Deploy to Server…​ from the context menu.

In the window that opens, shown in Figure 5, you can choose the server repository. You also have the possibility to change the default option of the server in resetting the workflow before uploading. To do this check or uncheck the option Reset Workflow(s) before upload.

03 deploy to server
Figure 5. Destination window when deploying a workflow to KNIME Server

Access permissions can be assigned to restrict the access to certain user groups.

Please refer to the KNIME Explorer User Guide for more information.

WebPortal browser

You can use a standard web browser to connect to KNIME WebPortal. The address (URL) to get to the login page is:

https://<server-address>/knime/webportal/

The last part of the address may have been changed by your server administrator.

After providing the user’s login name and password, a listing of all available workflows is displayed. Only workflows the user can read and execute are shown.

KNIME WebPortal of the KNIME Server version < 4.11 is available and the login page is at the address (URL): https://<server-address>/knime/.

KNIME WebPortal page

Workflows that are uploaded to KNIME Server are available through KNIME WebPortal for execution.

Access to WebPortal using a standard web browser, as explained in the WebPortal browser section.

Main page

After logging in, KNIME WebPortal main page is displayed, showing the available spaces or workflows, as shown in Figure 6.

05 wp main page
Figure 6. KNIME WebPortal main page

You can modify the general look of KNIME WebPortal. Instructions on how to do this are given in the Theming section.

You can log out from KNIME WebPortal clicking the icon in the upper-right corner of KNIME WebPortal.

Clicking the folder of interest redirects you to a new page, as shown in Figure 7 where all the workflows available inside the space are shown in tiles, which display the name of the workflow and a preview of its description, if present. You can click the yellow "play" button in the upper-right corner of the corresponding tile to start executing a new job directly.

05 wp main page workflows
Figure 7. KNIME WebPortal page with workflows tiles

If previously executed jobs were kept in memory, dots and a number are also shown in the tile. A green dot indicates a successfully run job, a red dot a failed one, and an orange dot interrupted jobs requiring an action.

Workflow page

Clicking any other part of a workflow tile in the main page opens the workflow page, as shown in Figure 8.

05 workflow page
Figure 8. The workflow page

Here the title of the workflow is shown, and if meta information has been entered before the workflow was uploaded, a description is displayed beneath the workflow name.

You can choose to get notified by email after workflow has run. In this case you will be asked to insert the email and, if a report is part of the workflow, the format in which you want to receive the report.

Then click the "Run" button to execute the workflow. A series of web pages will open allowing you to interact with the workflow or to visualize results, according to the workflow components, as explained in the Stepping through pages section.

All the different actions are shown in Figure 9.

05 workflow execution
Figure 9. Web pages of a workflow executed on KNIME WebPortal

(1) Click "Cancel" button in the bottom-right corner to interrupt the execution at any time.

(2) Click "Next" button in the bottom-right corner to navigate to the next page.

(3) Click "←Back" button in the bottom-left corner to go to the previous page.
Click "Close" at the end of the execution and decide if you want to keep or delete the current result. When the workflow is executed entirely the message Finished successfully appears on the upper part of the page. This message will appear also in case nodes are executed after the last component. Please notice that the page showing the composite view of the last component of the workflow can not be re-executed. In case a report is available you can also download it in the last page, choosing between different formats. Please refer to KNIME WebPortal and reports section for more details about it.

In case you choose to not delete the executed job, the result will be made available in the workflow page, with different information like the workflow’s owner name, the start date and the final state, as shown in Figure 10. Also other jobs that are running and need interaction or jobs that failed are listed here.

05 workflow page jobs
Figure 10. The workflow page with different executed jobs

You can discard and delete any of the jobs from the workflow page at a later time by clicking the three dots on the line corresponding to the job execution and choosing Discard from the context menu that opens. Here you can also copy a direct link to the final results page of a specific job.

On the workflow page you can also click Copy link to…​ to obtain the address of either the link to the main page of the current workflow or to its execution page.

The link to the execution page of a workflow is considered the basic URL of the workflow, the starting point for the parametrization and Direct linking to workflows in KNIME WebPortal.

KNIME WebPortal page (version <4.11)

As explained in the WebPortal browser section the old WebPortal is still accessible and fully usable.

The functionality is slightly different from the new WebPortal available as of version 4.11 of KNIME Server.

For a complete guide for KNIME WebPortal on KNIME Server version < 4.10 please check the corresponding version of KNIME WebPortal User Guide.

KNIME WebPortal and reports

If a workflow with a report template is uploaded to KNIME Server and accessed through KNIME WebPortal, the report is generated and displayed after successful execution of the workflow, as shown in Figure 11:

06 webportal report
Figure 11. Report generated after workflow execution

A preview of the report is shown in the result page and the html preview can be opened in a new window. Download links are offered for pdf, xls, ppt and docx format.

For more information on how to build reports with the KNIME Report Designer, please refer to the KNIME Report Designer User Guide.

An example of a workflow with report is available on the KNIME Hub.

Direct linking to workflows in KNIME WebPortal

It is possible to link directly to specific workflows in KNIME WebPortal. Basic workflows URLs are generally set up like:

http://<server-address>/knime/webportal/<ItemPath>?exec&<WorkflowParameters>
  • <ItemPath> is the path to a workflow, workflow group, or workflow job. A workflow job is referenced with its ID like: <ItemPath>?exec=job_id

  • <WorkflowParameters> can appear in any order, but have to be after <ItemPath>?exec

  • ?exec redirects to the automatic execution of the workflow.

Additionally, you have the possibility to set up some parameters, listed in the next section. Parameters are always appended with a leading & to the basic URL. You can also obtain the workflow’s basic URL in KNIME WebPortal, as shown in Figure 12. Go to the chosen workflow page and, in the upper-right corner of the page, click Copy link to…​Run workflow.

Available URL parameters

&emails=sample@mail.com — Enable email notification: enables email notification and sets the specified comma separated list of email addresses.

&formats=<formats> — Set report formats: sets the report formats included as attachments in the notification email specified by a comma separated list. Available formats are: pdf (enabled by default), html, doc, docx, xls, xlsx, ppt, pptx, ps, odt, ods and odp. This list might have been changed by your server administrator to reduce the number of options available.

A complete URL might look like:

http://localhost:8080/knime/webportal/demo/file%20to%20csv?exec&emails=sample@mail.com&formats=.pdf,doc

Please note that some characters cannot be part of a URL (e.g the space). To encode the URL you can use any available online URL encoder tool.

Theming

The look of KNIME WebPortal can be modified in order, for example, to personalize it with corporate colors, logo, and other elements.

If you have access to a KNIME Server installation go to the server repository and navigate to config folder located inside the workflow_repository.

Here you will find an example folder webportalTheme which contains some theming files. You can modify these files or create your own theming folder.

To personalize the theming of your WebPortal open the file knime-server.config located in workflow_repository/config with any editor and add the name and, if necessary, the relative path, to your theming folder next to com.knime.server.webportal2.theme_folder:

com.knime.server.webportal2.theme_folder=<relative-path-to>/webportalTheme

We recommend using the browser Developer Tools to develop and test theming and then copy it into the theme.config to avoid frequent server restart.

theme.config file

Inside the theming folder you will find a theme.config file.

Here you can define:

  • A Title for your WebPortal

  • The relative path of a custom css file to style KNIME WebPortal

  • The relative path of an svg image for the logo on the top left corner in the WebPortal pages

  • The relative path of an svg image for the header bar.

css file

In the css file you can add explicit fonts and styling for KNIME WebPortal pages and for some of the Widget nodes.

In the example file the-company.css, that you will find located in the example theming folder webportalTheme.

Here, you can define different css elements.

In the file the-company.css, you will find some of these elements, listed below. You can either make your changes in this file, or create your own css file.

  • Fonts:

    @font-face {
      font-family: 'OpenSans Light';
      src: url(font/OpenSans/OpenSans-Light.ttf);
    }
  • Header background color and font:

    /* Header */
    --theme-header-background-color: #942e16;
    --theme-header-background-color: #FFFFFF;
    --theme-header-font-family: 'Roboto Slab'
  • Logo size:

    /* Logo */
    --theme-logo-width: 150px;
    --theme-logo-height: 50px;
  • Headlines font, color, and font weight:

    /* Headlines */
    --theme-headlines-font-family: 'Roboto Slab';
    --theme-headlines-color: black;
    --theme-headlines-font-weight: 300;
  • Text font and color:

    /* Text */
    --theme-text-normal-font-family: 'OpenSans Light';
    --theme-text-normal-color: #3E3A39;
    
    --theme-text-medium-font-family: 'OpenSans Bold';
    --theme-text-medium-color: #6E6E6E;
    
    --theme-text-bold-font-family: 'Roboto Slab Bold';
    --theme-text-bold-color: black;
  • Default, small, split, and function button color and radius:

    /* Default Button */
    --theme-button-background-color: #000000;
    --theme-button-background-color-hover: #942e16;
    --theme-button-background-color-focus: #942e16;
    --theme-button-foreground-color: white;
    --theme-button-foreground-color-hover: white;
    --theme-button-foreground-color-focus: white;
    --theme-button-border-radius: 0;
    --theme-button-border-color: transparent;
    --theme-button-border-color-hover: transparent;
    --theme-button-border-color-focus: transparent;
    
    /* Small Button */
    --theme-button-small-background-color: black;
    --theme-button-small-background-color-hover: #707070;
    --theme-button-small-background-color-focus: #707070;
    --theme-button-small-foreground-color: white;
    --theme-button-small-foreground-color-hover: white;
    --theme-button-small-foreground-color-focus: white;
    --theme-button-small-border-radius: 0;
    --theme-button-small-border-color: transparent;
    --theme-button-small-border-color-hover: transparent;
    --theme-button-small-border-color-focus: transparent;
    
    /* Split Button */
    --theme-button-split-background-color: #000000;
    --theme-button-split-background-color-hover: #440E07;
    --theme-button-split-background-color-focus: #440E07;
    --theme-button-split-foreground-color: white;
    --theme-button-split-foreground-color-hover: white;
    --theme-button-split-foreground-color-focus: white;
    --theme-button-split-border-radius: 0;
    --theme-button-split-border-color: transparent;
    --theme-button-split-border-color-hover: transparent;
    --theme-button-split-border-color-focus: transparent;
    --theme-button-split-divider-color: white;
    
    /* Function button */
    --theme-button-function-border-radius: 0;
    --theme-button-function-background-color: transparent;
    --theme-button-function-background-color-hover: #942e16;
    --theme-button-function-background-color-focus: #942e16;
    --theme-button-function-background-color-active: #942e16;
    --theme-button-function-foreground-color: #6E6E6E;
    --theme-button-function-foreground-color-hover: white;
    --theme-button-function-foreground-color-focus: white;
    --theme-button-function-foreground-color-active: white;
  • Widget nodes elements colors and style, including:

    • Dropdown

      /* Dropdown (global) */
      --theme-dropdown-background-color: transparent;
      --theme-dropdown-background-color-focus: #942e1666;
      --theme-dropdown-background-color-hover: #942e1666;
      --theme-dropdown-background-color-selected: #942e16;
      --theme-dropdown-foreground-color: #3E3A39;
      --theme-dropdown-foreground-color-focus: #3E3A39;
      --theme-dropdown-foreground-color-hover: #3E3A39;
      --theme-dropdown-foreground-color-selected: white;
    • Text links

      /* Text links */
      --theme-text-link-background-color: transparent;
      --theme-text-link-background-color-hover: #942e16;
      --theme-text-link-background-color-focus: #942e16;
      --theme-text-link-foreground-color: #942e16;
      --theme-text-link-foreground-color-hover: white;
      --theme-text-link-foreground-color-focus: white;
      --theme-text-link-text-decoration: none;
      --theme-text-link-text-decoration-hover: none;
      --theme-text-link-text-decoration-focus: none;
    • Tooltip

      /* Tooltip */
      --theme-tooltip-background-color: #942e16;
      --theme-tooltip-foreground-color: white;
    • Checkbox

      /* Checkbox */
      --theme-checkbox-border-color: #888888;
      --theme-checkbox-border-color-focus: #3E3A39;
      --theme-checkbox-border-color-hover: #888888;
      --theme-checkbox-border-color-selected: #942e16;
      --theme-checkbox-border-color-selected-focus: #942e16;
      --theme-checkbox-border-color-selected-hover: #888888;
      --theme-checkbox-background-color: white;
      --theme-checkbox-background-color-focus: white;
      --theme-checkbox-background-color-hover: #942e1666;
      --theme-checkbox-background-color-selected: #942e16;
      --theme-checkbox-background-color-selected-focus: white;
      --theme-checkbox-background-color-selected-hover: #942e1666;
      --theme-checkbox-foreground-color-selected: white;
      --theme-checkbox-foreground-color-selected-focus: #942e16;
      --theme-checkbox-foreground-color-selected-hover: #3E3A39;
    • Selection list

      /* Selection List */
      --theme-select-control-background-color: transparent;
      --theme-select-control-background-color-hover: #942e1666;
      --theme-select-control-background-color-focus: #707070;
      --theme-select-control-foreground-color: #6E6E6E;
      --theme-select-control-foreground-color-hover: #3E3A39;
      --theme-select-control-foreground-color-focus: white;
    • Radio buttons

      /* Radio buttons */
      --theme-radio-border-color: #888888;
      --theme-radio-border-color-hover: #888888;
      --theme-radio-border-color-selected: #00677F;
      --theme-radio-border-color-selected-hover: #888888;
      --theme-radio-background-color: white;
      --theme-radio-background-color-hover: #942e1666;
      --theme-radio-background-color-selected: #942e16;
      --theme-radio-background-color-selected-hover: #942e1666;
      --theme-radio-foreground-color-selected: white;
      --theme-radio-foreground-color-selected-hover: #3E3A39;
    • Slider

      /* Slider */
      --theme-slider-border-radius: 0;
      --theme-slider-border-color: #888888;
      --theme-slider-border-color-hover: #888888;
      --theme-slider-border-color-focus: #707070;
      --theme-slider-foreground-color: white;
      --theme-slider-foreground-color-hover: #942e16;
      --theme-slider-foreground-color-focus: #993c2766;
      --theme-slider-bar-radius: 3.5px;
      --theme-slider-background-color: #942e16;
      }

Accessibility support

KNIME WebPortal provides full support of screen reader software as well as complete keyboard-only access.

Any screen reader that follows ARIA guidelines can be used for the work in KNIME WebPortal. The recommended screen reader software includes JAWS (v.16), NVDA (v.2016.3) and ChromeVox (v.53.0.2784.1).

KNIME WebPortal can be completely controlled by using the keyboard only, implementing the ARIA best practices on keyboard navigation:

  • Tab (Shift + Tab) key moves the focus to the next (previous) element

  • Enter key performs the default action on focused element

To operate with UI components of KNIME WebPortal standard shortcuts can be used. For more details see the ARIA specification page.

Legacy mode for components

Legacy Widget nodes

From KNIME Server version 4.11 we changed the Widget nodes to an updated version. The backwards compatibility is in any case assured for the Widget nodes, so that you can continue to use the Widget nodes in KNIME WebPortal version 4.11 with the same behavior and user interface they had in KNIME WebPortal version <4.11.

KNIME WebPortal of the KNIME Server version < 4.11 is available and the login page is at the address (URL): https://<server-address>/knime/.

In fact, the Widget nodes contained in workflows created with KNIME Analytics Platform version 4.1 will be displayed by default in the legacy mode. However, it is possible to change this option re-opening the workflows in KNIME Analytics Platform version 4.2 and deselecting the Use legacy mode in the Visual Layout tab of the Node Usage and Layout window.

Also when creating the workflows with KNIME Analytics Platform version 4.2 allows to use legacy mode for the whole component encapsulating the Widget nodes or for each node individually.

Please see the Components Guide for documentation about how to activate/deactivate the legacy flag when building workflows for KNIME WebPortal.

Quickform nodes

If a workflow contains Quickform nodes it will still be executed in the same manner, as in previous versions of KNIME Server.

However, we discourage the use of Quickform nodes in favour of Widget nodes.

Note that legacy Quickform nodes will have to be separately installed on the server executor and any client designing or executing legacy workflows. The plugin is found under KNIME & ExtensionsKNIME Quick Forms (legacy) in the "Install KNIME Extensions" dialog.

Migration FAQ

In this section we want to highlight what has been changed in KNIME WebPortal version 4.11.

Differences to KNIME WebPortal version <4.11

New URL

  • The URL to access KNIME WebPortal version 4.11 is changed so the path to specific workflows will change accordingly.

  • Additionally, the use of URL parameters has changed.

    • The parameter &run is now substituted by the parameter ?exec. ?exec always needs to be the first URL parameter to be followed by the other available ones.

    • For security reasons, it is not possible to provide username and password anymore together with the workflow URL.

Theming

The theming of the login page to KNIME WebPortal works the same way as for previous versions of KNIME WebPortal. For more information on how to apply your own style to KNIME WebPortal, please refer to the Theming section.

Generic JavaScript Views

With KNIME WebPortal version 4.11 it is not possible to escape the IFrame of Generic JavaScript Views to change the CSS of the WebPortal itself. The Generic JavaScript Views which were configured to escape the IFrame will not work anymore. We also do not encourage escaping IFrames in KNIME WebPortal as CSS classes of the WebPortal may change in future versions of KNIME WebPortal.

CSS styling

  • Styling widgets from KNIME Analytics Platform version <4.2 with the former css-classes is not supported anymore. However, the CSS styling of Widgets is still possible, but not documented. We recommend the use of theming to style your KNIME WebPortal and Widget elements. Widget styling that was created with KNIME Server version <4.11 and KNIME Analytics Platform version <4.2 can still be used and we assure backwards compatibility with the use of legacy mode.

  • Some CSS layout options of the page builder, i.e. the use of Bootstrap library elements, are not supported anymore. Please refer to the Layouting of composite views section of the KNIME Components Guide for the available elements.

Other migration changes

  • Indication about the version of a workflow in a job with respect to the version of the workflow actually present on KNIME WebPortal is not given anymore. Additionally, jobs that are not started through WebPortal are not displayed in the KNIME WebPortal. Please notice that, however, jobs that are started in KNIME WebPortal version 4.11 are displayed in KNIME WebPortal version 4.11 and vice versa.

Known limitations

  • Credential Widget (Legacy)
    The Credential Widget has the option to use the Server-login Information as credentials. This is available for KNIME WebPortal version <4.11 but it is not yet supported in KNIME WebPortal version 4.11.

  • The setting of configuration variables via URL parameters is not yet available on KNIME WebPortal version 4.11.

  • Single page mode is not yet available in KNIME WebPortal version 4.11.

  • While KNIME WebPortal version 4.11 is compliant with ARIA guidelines it is not possible yet to use shortcuts for the navigation through the workflow repositories.