How to write a documentation for a KNIME workflow?

Dear community,

I set up a couple of workflows and managed to convince both our business and IT department to have a look at KNIME. Our IT security department asked me to prepare a brief summary, how to document a workflow. So, is there a possibility to extract a list of all nodes out of KNIME giving the name, ID, type, description, in- and output connectors and flow variable connections? I’d like to use this as a starting point to describe the workflow at hand.

Ideally, I’d expect something in that style:

ID: 1234 Type: Join Input from: Node ID 1233 and 1232 Output to: Node 1235 Join mode: INNER JOIN Join field: FK_CustomerID = ID

Any ideas?

Kind regards,

Patrick

Various options…

  • Right click on a blank but of workflow canvas and select Workflow annotation, gives you a text box you can resize, change colour etc
  • Edit the node label on an individual node by double-clicking the label (e.g. ‘Node 3’ underneath the nude)
  • Collapse a group of nodes into a metanode. You can give it a descriptive name, edit its label, and also right-click and select Edit metadata
  • Right click on the workflow name in the workspace browser and select Edit metadata

The workflow metadata will be shown in the several if you have a server when you select the workflow.

Steve

Sorry, to answer your question, you need to look at the workflow.knime xml file at the root level and the settings.xml file for each node

Workflow.knime gives you the nodes and their connections, settings.xml the individual node settings

Steve

Hey @Steve,

thanks for your suggestions - they’re not hitting the nail. I’m looking for something beyond pure developer notes within the code.

I’m looking for a file like documentation (WORD / PDF) that can be stored in a DMS or DocSafe. One scenario could be, that a time-triggered KNIME workflows terminates abnormally and the operators can have a look into the DMS telling them what the workflow is about and if they can fix it them self or have to address the developers.

So, KNIME creates a stub with all information inside available to KNIME (ideally as a WORD document or a text file) and the developer has to add the “brain information”. So, any change to extract that from a KNIME workflow?

Kind regards,

Patrick

Try a knime workflow which uses an xml reader to read the workflow.knime file for the workflow to document. Xpath will get you any annotations and metadata, and the nodes and their connections, and relative paths to each node’a settings.xml. You can then read and posse those four specific settings you are interested in,and use the BIRT to put it into a word or pdf document.
That’s the best i can think of unfortunately
Steve

2 Likes

Hey @s.roughley,

thanks for your idea. I’ll follow down this road and keep you posted.

Kind regards,

Patrick.

Good luck! Be interested to know how you get on! Thinking about it, all the parts from the first answer wind up in the workflow.knime file, so you might be able to combine the two answers

Steve

This would be a good feature to suggest to the Knime developers - a metadata report

1 Like

Hey @s.roughley,
hey @morebento,

after some 6hrs of work (including teaching myself XPath), I achieved a solution. I build a workflow reading a “workflow.knime” file and extracting the nodes and connections. I attached the workflow and some screen shots below. I would be more than happy if some people share their ideas on that with me.

Aimed for achievements:

  • Read any given “workflow.knime” file
  • Extract nodes and connections
  • Write a DOCX stub file
    ** One page per node
    ** Node ID and Node type as header
    ** Connections (Destination / Source)
    ** Name of target or source node
    ** placeholder for descriptive text (to be added by workflow owner)

Please note some caveats:

  • Since I’m not that good in XML processing at all, I applied some changes on the “workflow.knime” file such as
    ** Replacing the first config-tag by an empty workflow-tag
    ** Renaming the file to “workflow.knime.xml” (so the file opens automatically in my web browser)
  • I tried to dive into the report facility of KNIME but failed. Hence, workflow below writes the results in to a MS ACCESS DB where I defined a report. I’d be more than thankful if someone could turn this into a genuine KNIME report.

Select the “workflow.knime” file

Define the target ACCESS DB - I’d be more than thankful if someone could turn this into a genuine KNIME report

Result from sorter node. The sorter nodes functions is only to provide human-readable feedback

Layout of ACCESS target table
KnieWorkflow0004

KNIME workfloe
Workflow Documentation.knwf (57.8 KB)

4 Likes

Hi Patrick -

Could you provide an example workflow.knime file that you modified? Specifically, I’m referring to what you described as “replacing the first config-tag by an empty workflow-tag”. Without that, the workflow is producing weird results.

(I’m not a pro with XPath by any means, and I’m trying to reproduce what you did in the hopes of generating a KNIME report.)

Thanks!

Hey @ScottF,

here you are! The picture shows the diff-analysis and the ZIP contains the files.

workflow.knime.zip (6.0 KB)

Perfect, thanks! Let me see what I can come up with.

HI @Patrick1974 -

Here’s my initial stab at it. This report uses the Groups feature in BIRT (grouped by RowID) to produce a short table for each node, and inserts a page break after each. I used blank labels to add white space, and put a “Description:” label in the footer, so that when it gets exported the user has a place to make notes in the DOCX file.

I’m sure this could be polished even more, I was just trying to make something quickly that approximates your “aimed for achievements” above.

Workflow_Documentation_SF.knwf (63.5 KB)

1 Like

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.