knime web portal guide · finally, a data to report node (upper right, brown) is used to send data...

KNIME WebPortal Installation and quick start guide

Version 3.7

KNIME Web Portal – Installation and Quickstart Guide 1

© Copyright, 2012, KNIME.com AG, Zurich, Switzerland.

TABLE OF CONTENTS

Introduction ....................................................................................................................................................... 2

Installation ......................................................................................................................................................... 2

Prerequisites ................................................................................................................................................................... 2

Workflow Execution and Report Generation .................................................................................................... 2

Webportal Specific System Properties ................................................................................................................. 2

Web Portal deployment .............................................................................................................................................. 3

Installing a Sketcher ..................................................................................................................................................... 4

Authentication ................................................................................................................................................................ 4

Publishing Workflows and Report Workflows ...................................................................................... 4

WebPortal Browser ......................................................................................................................................... 5

Quick Form Nodes ............................................................................................................................................ 5

Example ............................................................................................................................................................................. 5

Example Flow ............................................................................................................................................................. 5

WebPortal page for the example flow .............................................................................................................. 6

QuickForm Nodes in KNIME Desktop .............................................................................................................. 6

Creating workflows for the KNIME Web portal ..................................................................................... 7

Available Quick Form Nodes .................................................................................................................................... 7

Configuration of Quick Form Nodes ................................................................................................................... 10

Creating a Workflow with Quick Form Nodes................................................................................................ 10

Create Temp Dir Node ......................................................................................................................................... 10

Java Edit Variable Node ...................................................................................................................................... 11

Java IF (Table) Node ............................................................................................................................................. 11

Quick Form Nodes in Metanodes .................................................................................................................... 11

Workflow Credentials .............................................................................................................................................. 12

WebPortal and Reports .............................................................................................................................. 12

The Web Portal Page .................................................................................................................................... 13

Main Page ...................................................................................................................................................................... 13

Details Pane .................................................................................................................................................................. 14

Direct Linking to Workflows in the WebPortal ............................................................................................. 15



K N I M E W E B P O R T A L

INTRODUCTION

KNIME WebPortal is an extension to KNIME Server. The WebPortal provides a web interface that lists all accessible workflows, allows to execute them and to investigate the results. The workflows input and output can be parameterized using “Quick Forms”. In addition report templates created with the KNIME Report Designer that are uploaded together with their associated workflow to the shared repository on the KNIME Server can be filled dynamically with data and downloaded in various formats.

INSTALLATION

PREREQUISITES

The WebPortal requires a KNIME Server installation. Please refer to the KNIME Server Installation and Quickstart Guide for more information on how to install a KNIME Server if needed.

The KNIME Webportal version 3.7 now supports the following browsers1:

Internet Explorer Version 8.0+

Firefox Version Version 3.5+

Google Chrome: Version 4.0+

Safari Version 4.0+

1. Please note that IE7 is no longer supported due to its lack of JSON support.

WORKFLOW EXECUTION AND REPORT GENERATION

To enable the workflow execution and report generation functionality in the WebPortal the KNIME Desktop installation used as the KNIME Server executor (to execute workflows on the server) must contain the KNIME Report Designer extensions and all other plug-ins required by any workflow executed through the WebPortal. Please refer again to the KNIME Server Guide for details on the installation of the KNIME executor on the server.

WEBPORTAL SPECIFIC SYSTEM PROPERTIES



The following optional system properties may be added to glassfish via the Glassfish Administration Page. To set the properties, navigate to: Application Settings > JVM Settings > JVM Options. Once added, glassfish will need to be restarted.

-Dcom.knime.server.sketcher_page=<URL of Sketcher Page>

Define the location of the main sketcher html-document. Helpful when the sketcher is deployed as static resources under a different context root. Note that the WebPortal and the sketcher need to be in the same domain. Otherwise cross-domain scripting would occur, which is considered a security threat in all browsers and is not allowed.

-Dcom.knime.server.sketcher_size=300x300

Define the size of the sketcher iframe 300x300 is the default value for the Marvin Sketcher.

-Dcom.knime.server.title_label=<Server Name>

Define an additional title label displayed to the right of the KNIME WebPortal logo.

-Dcom.knime.server.disable_report_preview=false

Boolean that lets you define if an HTML report preview is rendered and shown on the result page of appropriate workflow jobs.

-Dcom.knime.server.disable_warning_messages=false

Specify whether warning messages are displayed on the result page of workflow jobs. Note that errors are always shown.

WEB PORTAL DEPLOYMENT

The KNIME WebPortal uses a context root to construct a URL at which users will be able to access this tool via a web browser. Choose a context root that is compact and meaningful (such as “webportal”). This would result in a final url as below:

http://<server address>:<port>/<context root>/(<port> = 8080 by default)

The KNIME WebPortal comes as a web application that is packed into a war-file There are two ways to deploy it:

1. Web console: log in to Glassfish's admin page (http://<server_address>:4848 by default ). From the menu on the left, select “Applications” ” → “Web Applications”. Then click “Deploy…” and provide the location of the war-file. Change the option “Context Root” as described above

2. Use the command line tool asadmin: <glassfish-dir>/bin/asadmin deploy <path to webportal.war>

add --contextroot <context_root> to modify the context root as described above.

Regardless of deployment method, the URL for the WebPortal can be changed later in the file:

<glassfish-dir>/domains/<domain>/applications/j2ee-modules/<WebPortal>/WEB-INF/sun-web.xml



The web application must be reloaded in order to apply changes in sun-web.xml configuration file. This can be done by creating a file named .reload in the web application directory). When this file is created or modified the application server automatically reloads the application.

touch <glassfish-dir>/domains/<domain>/applications/j2ee-modules/<WebPortal>/.reload

INSTALLING A SKETCHER

The KNIME WebPortal can be used with an integrated molecular sketcher. While in theory any sketcher applet may be used, only support for Marvin has been included to date. The current version of the Marvin Sketcher provided by Chemaxon is available here.

Once the applet is downloaded, extract it to:

<glassfish-dir>/domains/<domain>/applications/j2ee-modules/<WebPortal>/VAADIN/sketcher/

Subsequently rename the file:

<glassfish-dir>/domains/<domain>/applications/j2ee-modules/<WebPortal>/VAADIN/sketcher/sketcher-marvin.html

To:

<glassfish-dir>/domains/<domain>/applications/j2ee-modules/<WebPortal>/VAADIN/sketcher/sketcher.html

Finally:

touch <glassfish-dir>/domains/<domain>/applications/j2ee-modules/<WebPortal>/.reload

AUTHENTICATION

The WebPortal uses the same user base and authentication mechanism as the KNIME Server, so users defined during the KNIME Server installation may also log in to the WebPortal using the same credentials. Additionally, access permissions granted in the KNIME Server apply to workflows and data files in the WebPortal. Note that only workflows which are readable and executable are displayed in the WebPortal for a user. Empty workflow groups, or groups with no permissible workflows are hidden.

Note: If using LDAP, you may need to update a glassfish library (appserv-rt.jar) if you are encountering a flood of LDAP authentication requests. The patched file can be downloaded from here and will need to replace the file of the same name at:

<glassfish-dir>/lib

PUBLISHING WORKFLOWS AND REPORT WORKFLOWS

Workflows and the associated report templates are published on the KNIME WebPortal by simply uploading the workflow from the local workspace to the server. This can be done by either with context menu in the KNIME Explorer view (copy/paste), or by dragging and dropping a workflow from a local workflow repository to a ServerSpace repository. Access permissions can be assigned to restrict the access to certain user groups.

Please refer to the KNIME Explorer Guide for more information.

https://www.chemaxon.com/download/marvin/for-web-developers/



WEBPORTAL BROWSER

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

http://<server address>:<port>/<context root>

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.

QUICK FORM NODES

The nodes in the node repository category “Quick Form” can be used to create flow variables and to assign them values. These values can then be used in the workflow to control the execution of nodes. There are different quick form nodes for different types of variables (e.g. Integer Input, String Input, Double Input, etc.).

Quick form nodes are especially useful when used in workflows designed for KNIME Server deployment via the WebPortal. When the WebPortal encounters a quickform 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. If the workflow contains Quick Form output nodes, the result is presented to the user in subsequent HTML pages either during or after execution of the workflow depending on the node’s position in the workflow.

EXAMPLE

Imagine we want to show a workflow in the WebPortal that allows the user to convert an XLS-file into a CSV-File (comma separated values text file). The flow is very simple: just connect an XLS Reader with a CSV-Writer.

For the WebPortal, we add nodes to enable the user to upload the XLS file and to download the result, and to write to a temporary location on the server. After the flow is created it is uploaded to the KNIME Server.

EXAMPLE FLOW



This example demonstrates a common sequence of nodes used to upload and download data using the KNIME Webportal. In addition to the “regular” nodes used for reading and analyzing the data (center, yellow) there are additional Quick Form nodes (left and lower right, green) that are provide the workflow with file import and export capabilities via a browser. Finally, a Data to Report node (upper right, brown) is used to send data to a predefined BIRT Report.

WEBPORTAL PAGE FOR THE EXAMPLE FLOW

After logging in to the KNIME WebPortal a user can select from available workflows. On the right pane of the page, the components corresponding to the Quick Form input nodes in the flow are shown. After selecting a file, the workflow can be executed on the server by clicking Run. After successful execution, the Quick Form output nodes are displayed providing the user with a download link of the converted result file:

QUICKFORM NODES IN KNIME DESKTOP



In addition to the main function of being able to use Quick Form nodes in the KNIME Webportal, you may also use them with the Quick Form execution wizard in the KNIME Desktop application. This feature allows you to execute a workflow while editing only the variables defined by the Quick Form nodes. This is useful when developing a workflow for the KNIME webportal or if a wokrflow is very complicated and finding the configuration dialogs of interest is time consuming.

CREATING WORKFLOWS FOR THE KNIME WEB PORTAL

AVAILABLE QUICK FORM NODES

Node Name Displayed component in the Web Portal User Input Output

Any user input is accepted String

Integer values Int

Floating point numbers Double

A date (as string) (or a selected date from the calendar form).

String

Choice of the available values. The available selection depends on the node's configuration.

String

<none>

Force a break in WebPortal execution. Needed when output QuickForms are used in metanodes.

none



Upload a file to the server using a temporary directory.

Path to the uploaded file

Boolean values Checked = 1

Unchecked = 0

Select columns from a KNIME Table

Empty data table with selected columns. Often used with Reference Column Filter.

Column name String

Multiple selections Column of selections

Values of a column Data Table



Value of a column String

Separate string inputs Data Table

Molecule String String

Download link:

result_file

The flow variable specified must contain an absolute file path.

String

value Displays the value of the specified variable as text.

String, Double, Int

KNIME Image

Any text String



CONFIGURATION OF QUICK FORM NODES

All Quick Form input nodes have very similar configuration dialogs. Below is as representative example the dialog of a String Input node, the second picture shows the corresponding display in the WebPortal web page:

CREATING A WORKFLOW WITH QUICK FORM NODES

Quick Form nodes in a workflow define points of interaction in a workflow when it is executed via the Webportal. This allows skilled analysts to expose powerful tools to users who may not have the training or time to run a full featured workflow from KNIME Desktop. This is usually done by injecting flow variables from the Quick Form node into another node’s settings to drive the configuration of that node on a per setting basis. Variables created by a QuickForm node are available at the node's variable output port (circular and red). To use the variable, connect the QuickForm variable port to the variable port of the target node whose settings you wish to override. If a target node doesn’t have a flow variable port you can make it visible with; “Show Flow Variable Ports” from its context menu. Alternatively, connect the output port to the upper left corner of the node (a convenient shortcut).

The overall process for developing a workflow looks like this:

1. Build a workflow and execute it with relevant test data.

2. Parameterize the workflow by adding QuickForm nodes as needed. Use the variables generated by these nodes to override the settings of your target nodes.

3. Make the workflow portable by removing any hardcoded paths.

4. Reset the workflow, save it, and upload it to the server and set appropriate permissions.

CREATE TEMP DIR NODE

The Create Temp Dir node creates a temporary directory when it is executed (in the Java Temp Dir, set in the KNIME properties). It can also be configured to create a new temporary file in this

The text displayed next to this input field.

The tooltip text seen on mouse over.

Input components are placed below each other in the WebPortal page - ordered by the specified weight.

The name of the variable that carries the value of this Quick Form node. It should be a unique and will automatically be assigned a type.

The default value assigned to the variable named above. Used both for workflow testing and as the default value in the WebPortal.



directory and store the full absolute path to that file in a flow variable. (In fact the file is not created but the generated file path in the new temp directory certainly doesn’t exist.)

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

With this node you can create temporary files (in unique temporary directories) and use them in writer nodes. If the variable that carries the name of the temporary file is then selected in a File Download node, the file written is made available for download in the WebPortal.

JAVA EDIT VARIABLE NODE

Another node that could be useful when flow variables are used is the Java Edit Variable node. It allows you to modify the value of an existing variable or to create a new variable and/or derive its value from another existing variable.

JAVA IF (TABLE) NODE

With the Java IF (Table) node you can selectively execute branches in the workflow, based on the value of a flow variable. Together with the String Radio Buttons node the Web Portal user could select different flow branches for execution.

QUICK FORM NODES IN METANODES

Temporary directory settings:

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

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

Create file paths:

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 directory and filename.

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

Add a new variable and file reference.



Quick Form nodes within a metanode are exposed automatically within the configuration of the metanode itself and can ne conveniently accessed through the Configure button in the metanode context menu.

WORKFLOW CREDENTIALS

If Workflow Credentials are used in a flow (e. g. for the database nodes), they are displayed above the Quick Form node input fields in the WebPortal page of the workflow:

Furthermore, if the workflow credentials identifier is entered as knime.system.default, then the username and password used to log in to the WebPortal will be propagated to the node’s credentials automatically.

WEBPORTAL AND REPORTS

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



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 DOC format.

THE WEB PORTAL PAGE

Flows that are uploaded to the KNIME Server are available through the WebPortal for execution. The Web Portal (default) entry page is: http://<server_address>:8080/webportal

MAIN PAGE

After logging in, the WebPortal main page is displayed showing the available workflows displayed in a structured list in the left frame of the page. Only workflows that are both readable and executable by the logged in user will be visible.

In the above example the user has only access to the flows in the workflow group “Demo User” and four workflows are available for execution in the WebPortal.



The items below a workflow (with a green or red indicator dot) are previously executed flows which are kept in memory (“workflow jobs”). They can be discarded individually with a right-click on the job, or with a right-click on the flow.

Jobs with a green indicator represent successfully executed flows. If they are selected, the result from the previous run is available.

Jobs with a red indicator represent flows previously executed but that have failed. If selected, the error message is displayed again.

If a job itself is red, this indicates that the workflow has been modified since the job was executed while if the Workflow has a red x across it, this means that the workflow which owns that job has been deleted.

DETAILS PANE

If a workflow is selected in the left section, its details page is shown in the section on the right. An example is illustrated below:

If Meta Information has been entered before the flow was uploaded, it is displayed beneath the workflow name. If the option “Mail notification on completion” option is selected, an email address must be entered. The server sends a notification email to this address as soon as the workflow execution finishes. After all information is entered, the flow execution can be initiated by clicking the “Start” button. A new job is then created.

If the job finishes the result can be inspected by selecting it in the left pane of the page: The example job shown below executed successfully (indicated by the green icon and the green line of text on the right).

Beneath these status lines the result files are available for download. The workflow contains Quick Form nodes that provide the path to two files. If the user clicks on one of the links the download of the corresponding file starts.

This example flow is generating a report. The preview is shown in the details pane. At the bottom of the pane the report can be previewed in a new window and is also available for download, either in PDF or XLS format, as PowerPoint presentation or as Word document.

If the user launches long-running jobs on the server through the WebPortal, the user can logout and come back any time later, re-connect and get the status of his jobs. The jobs can be canceled, or finished jobs can be inspected and the results can be downloaded.



The job (and all its results) can be discarded by clicking the “Discard” button. Its icon will disappear from the left Workflow Repository view and server resources will be freed. Jobs can also be discarded by right-clicking on their icon in the Workflow Repository (on the left). All jobs of a flow can be removed by right-clicking on the flow. Please note that jobs stay in the server’s main memory until they are discarded. If too many users keep too many jobs alive, the server will run out of memory.

DIRECT LINKING TO WORKFLOWS IN THE WEBPORTAL

As of KNIME Webportal 3.7 it is now possible to link directly to specific workflows in the WebPortal. RLs are generally set up like:

http://<Server_Address>:<port>/<ContextRoot>/#/<ItemPath>&<WorkflowParameters>

<ItemPath> = The path to a workflow, workflow group, or workflow job.

(A workflow job is referenced with its ID like: WorkflowGroup/Workflow?exec=job_id)

<WorkflowParameters> can appear in any order, but have to be after the <ItemPath>. Parameters are always appended with a leading '&'

Available Workflow Parameters

&single - Single mode: hides the workflow tree, so that only the selected item is visible.

&run - Auto run: If appended to workflow path, a new job is automatically executed.

&wv:<name>=<value> - Set variable: Sets the named workflow variable to the specified value.

&[email protected] – Enable email notification: enables email notification and sets the specified comma separated list of email addresses.

A complete URL might look like:

http://localhost:8080/webportal/#/demo/file%20to%20csv&wv:title=foo&[email protected]&run&single

knime web portal guide · finally, a data to report node (upper right, brown) is used to send data...

Documents