Nestworkfloweditor

NEST Workflow Editor #

This page contains the following content:

The NESTWorkflow Editor visualizes a NESTWorkflow, facilitates its modification, and offers the subsequent export of the modified workflow graph to an XML file. The graphical representation of a NESTWorkflow can be exported in the SVG or PDF file format. Additionally, an editor for modifying DataObjects attached to NESTGraphItems as semantic descriptions is provided.

⚠️ The editor creates a copy of the NESTWorkflowObject provided as a parameter during instantiation and applies the modifications made by the user to this copy. To transfer the modifications to the original NESTWorkflowObject, the Save action from the File menu or toolbar has to be used

Starting the editor #

To open the editor, an instance of the class NESTWorkflowEditor needs to be created with the desired NESTWorkflowObject as a parameter.

To create a new workflow graph with the editor, you must first create a corresponding object. An ID must also be set for this object, as this is not possible later in the interface and the export would fail as a result. The following code can be used for this:

NESTWorkflowObject nestWorkflow = ModelFactory.getDefaultModel().createObject(NESTWorkflowClass.CLASS_NAME);
nestWorkflow.setId("nestWorkflowSampleId");
new NESTWorkflowEditor(nestWorkflow);

Alternatively, the constructor of the workflow editor can be called on an already existing NEST workflow.

GUI Overview #

gui-overview

Inserting Nodes #

New nodes can be inserted into a NESTWorkflow by drag and drop of the desired node from the palette into the canvas area. Another way to insert new nodes is by copy and paste of an existing node. This can be achieved by clicking the copy and paste buttons in the toolbar or by using the standard keyboard shortcuts CTRL-C and CTRL-V while a node is selected. Drag and drop with the left mouse button while holding CTRL also copies a node. The copy of the node gets an own ID and a copy of the semantic description of the original node.

Inserting Edges #

Nodes can be connected with an edge by drag and drop from the source node to the target node with the right mouse button. The editor only allows edge creation between compatible node types and automatically creates edges of the correct type.

Sequence nodes can be dropped upon control flow edges resulting in a “split” of the respective edge and the insertion of the new node into the control flow at that position: The post of the existing edge is set to the new node and a new edge is created linking from the new node to the post of the original edge. The new edge receives a copy of the semantic descriptor of the original edge. Edge splitting works for either existing task nodes (note that any existing controlflow edges connected to that task node will be deleted) or new sequence nodes from the palette.

Editor Controls #

An explanation for each setting/section of the editor controls panel in the left sidebar follows.

Node Visibility #

Here can be chosen which types of nodes should be shown in the canvas area.

Layout Configuration #

Changing any of these parameters will cause a re-layout of the workflow graph with the updated parameters.

  • Orthogonal dataflow edge routing: Routes dataflow edges orthogonally around nodes and keeps the edges from overlapping. Disabling this option causes dataflow edges to be drawn in a straight line without bends from their source to their target nodes which may cause them to intersect with nodes on their way or to be drawn nearly overlapping with other edges.
    • Edge to edge spacing: Spacing in PX between parallel sections of dataflow edges. This is an ideal value that may not always be respected due to restricted space circumstances.
    • Edge to node spacing: Distance in PX for dataflow edges to keep from other nodes.
  • Place data nodes vertically close to their task nodes: Disabling this option places all data nodes in a single dedicated layer below the controlflow nodes.
    • Additionally place above task nodes: Available to additionally use a layer above the task nodes to place data nodes in. The data nodes are distributed in two layers above and below each sequence while minimizing dataflow edge crossings. Note: This setting currently uses a computationally expensive implementation, so be advised to disable this setting if the layouting is too slow.
  • Vertical spacing for nodes: How much vertical space (in PX) should be left between nodes.
  • Horizontal spacing for sequence nodes: How much horizontal space (in PX) should be left between sequence nodes (task nodes / controlflow nodes). Values lower than Controlflow edge label margin are ignored.
  • Controlflow edge label margin: Defines how much space is left in sum in front and behind controlflow edge labels before a sequence node placement occurs. This setting is applied even when the controlflow edge label is empty.
  • Re-layout on edge insertion: Defines whether the layout should be applied whenever a connection between nodes is created.

Cell Labels #

Here the visibility of edge labels can be toggled and whether to prepend the NESTGraphItem ID to the labels.

Misc #

Toggle tooltips for hovering nodes and edges. The NESTGraphItems ID and type in addition to a tabular representation of the semantic descriptor is shown.

tooltip_example

By triggering Refresh NESTWorkflow, the graphical representation of the underlying NESTWorkflow is re-drawn to account for external changes made to the NESTWorkflowObject.

In this section, you can also invoke the NESTWorkflowValidator. It offers several validity checks for the NESTWorkflow and shows a list of detailed error messages when a check fails.

Pressing the Reset NESTWorkflow button resets the state of the currently displayed NESTWorkflow to the state it had on the last save or when no save took place to the state it had on editor instantiation.

Editing Semantic Descriptors #

The semantic description of nodes and edges can be edited by double clicking the node or edge, which causes a SemanticDescriptorEditor window to show:

data_object_editor_example

The dropdown at the top enables you to change the semantic descriptor class. Changing the class causes a new object of the corresponding class to be instantiated and set as the semantic descriptor. To set the semantic descriptor to null, select null from the dropdown (first entry). Clicking Reset changes reverts the semantic descriptor to the state it had when the SemanticDescriptorEditor was opened.

Ordered collections (ListObject) are supported, drag and drop the index label of an element of the collection onto another index label of an element of the collection to move the dragged element in front of the element it was dropped on.

Clicking the x button next to the name of an attribute sets this attribute to null. Attributes with null values can be filled by clicking the + button. A new object of the class defined in the model is created and then can be modified. When multiple classes are possible as the attribute value, a popup with a searchable dropdown menu is presented from which the desired class can be selected.

Configuring Labels #

Attribute names of semantic descriptors to be used as labels for nodes and edges can be set in the composition.xml file for the cake.utils.objectpooleditor.LabelProviderFactory factory. The editor uses cake.utils.nestworkfloweditor.NESTWorkflowEditorLabelProvider for label generation, so parameters controlling the label values have to be set for that class. Parameters can be defined to specify which attribute values of an aggregate of a specific class present in the semantic descriptor of a NESTWorkflowItemObject should be incorporated into the label. Multiple attributes for labels are supported by separating them by a comma in the parameter value.

Example:

<Factory name="label_provider" class="cake.utils.objectpooleditor.LabelProviderFactory">
    <Implementation class="cake.utils.nestworkfloweditor.NESTWorkflowEditorLabelProvider">
        <Parameter name="multiAttributeLabelDelimiter" value="newline"/>
        <Parameter name="displayAttributeName" value="false"/>

        <Parameter name="WorkflowSemantic" value="**full**"/>
        <Parameter name="TaskSemantic" value="name"/>
        <Parameter name="DataSemantic" value="name,amount"/>
        <Parameter name="AmountType" value="value,unit"/>
    </Implementation>
</Factory>

This causes the editor to look for the attributes name and amount whenever it encounters an aggregate of type DataSemantic and use their values for the generation of labels. Analogously, the attributes named value and unit will be incorporated into the label when an aggregate of the type AmountType or sub types derived from it are present in the semantic descriptor. It is possible to output the complete semantic descriptor in tabular form (including attribute names) by providing the special keyword **full** as the parameter value (see WorkflowSemantic).

How multiple attribute values are separated in the label can be controlled via the multiAttributeLabelDelimiter parameter. newline is a special keyword that inserts a new line (\n) after each attribute, regular chars or char sequences like " " or " - " are also possible. The displayAttributeName can be set to true to prefix attribute values with their names.

For a more dynamic and fine-grained label configuration during runtime the Set as label option in the SemanticDescriptorEditor can be used: Double click a node or edge to open the SemanticDescriptorEditor. Now choose an arbitrary attribute, right click its name label and select Set as label from the popup menu. This causes the selected attribute value to be used as the label for every graph item with the same semantic descriptor class it was chosen from.

Furthermore, it is possible to fully display the semantic description of selected elements in a tabular form. Right click the selection, choose Label from the popup menu, and then choose whether to show null attributes or not. To revert, select Normal in the aforementioned menu.

Export/Import Capabilities #

Saving the changes made to the workflow graph is possible via the Save and Export as actions in the toolbar or the File menu.

The Save action transfers the modifications made to the workflow graph to the NESTWorkflowObject which was given during the instantiation of the editor.

Export as offers to serialize the workflow graph to the chosen XML file or to export the visualization of the graph to an SVG document.

Customization applied to the layout of the workflow graph or the style of graph elements can be persisted to a file and later reloaded and re-applied via the File -> Export / Import graph layout and style options.

Displaying semantic descriptors in separate nodes #

It is possible to display the semantic descriptor of a node in a helper node connected to its corresponding NESTNode via an undirected edge. These nodes are “virtual”: they have no representation in the underlying NESTWorkflow data structure and only exist to aid the visualization of semantic descriptors for the SVG export. To create such nodes, select an arbitrary amount of nodes, right click them and choose Add semantic descriptor node from the popup menu.

For each selected NESTNode, a helper node containing the semantic descriptor is created and placed on top of its corresponding NESTNode. These helper nodes now can be moved arbitrarily to arrange them in a desired way. To help with positioning, a snap-enabled grid can be drawn in the background by clicking View->Grid->Show Grid and View->Grid->Line. The text content of the helper nodes can be freely modified in the text editor opening on double clicking the node.