WorkflowEditor Documentation

Overview

The WorkflowEditor component is a central component of the Vantage analytics and data platform, designed for creating and managing workflows visually using a visual graph-based interface. It allows users to drag and drop nodes and connect them, enabling flexible and intuitive workflow configurations. The editor provides an interactive experience, supporting functionalities like node selection, edge management, and viewport manipulation.

Purpose

The primary purpose of the WorkflowEditor is to serve as a visual interface where users can design complex data workflows by managing nodes (representing data operations or states) and edges (representing the connections between these operations). This capability is essential for analytics tasks, such as data transformation, analysis, and visualization.

How It Works

The WorkflowEditor uses a visual editor to render a canvas where users can interact with workflow elements. It is integrated with a context-based state management system to handle the following functionalities:

• Managing the current state of nodes and edges.
• Handling user actions like creating connections and modifying node settings.
• Storing and updating the main workflow data.

Data Expectations

The WorkflowEditor expects the following data structures to function correctly:

• Nodes: An array of node objects, each with an id, type, and additional properties (e.g., position, data).
• Edges: An array of edge objects connecting the nodes, usually containing source and target node identifiers.

This data is loaded and managed through the workflow state system.

Settings

The WorkflowEditor includes a range of settings that influence its behavior and appearance. Below is an exhaustive breakdown of each setting:

1. nodes

   • Input Type: Array
   • Description: Represents the nodes currently present in the workflow. Each node object should include properties like id, type, data, and position. Changing this affects the nodes displayed in the canvas.
   • Default Value: [] (an empty array).

2. edges

   • Input Type: Array
   • Description: Represents the connections between nodes in the workflow. Each edge object should typically include properties like id, source, and target. Adjusting this will change how nodes are interconnected visually.
   • Default Value: [] (an empty array).

3. onNodesChange

   • Input Type: Function
   • Description: Callback function fired when nodes are added, removed, or modified. This function is essential for handling changes in the node structure, allowing updates to the state store as needed.
   • Default Value: () => { } (empty function).

4. onEdgesChange

   • Input Type: Function
   • Description: Callback function triggered when edges are added, removed, or modified. Similar to onNodesChange, it updates the edge structure in the workflow.
   • Default Value: () => { } (empty function).

5. onConnect

   • Input Type: Function
   • Description: Callback that handles the creation of new edges between nodes when a user connects them. This function is critical for dynamically updating the workflow graph.
   • Default Value: () => { } (empty function).

6. onNodeClick

   • Input Type: Function
   • Description: Defines behavior when a node is clicked. The default implementation selects the clicked node, allowing for further actions such as configuring node settings.
   • Default Value: () => {} (empty function).

7. onPaneClick

   • Input Type: Function
   • Description: Triggered when the user clicks on the canvas outside any nodes. This action typically deselects any selected node, allowing users to reset their selection states.
   • Default Value: () => {} (empty function).

8. onSelectionChange

   • Input Type: Function
   • Description: Callback function called when the selection of nodes changes. This function allows for additional operations based on selected nodes, which can improve user interactions.
   • Default Value: () => {} (empty function).

9. onMove

   • Input Type: Function
   • Description: Invoked when the user pans or zooms the canvas area. It updates the viewport, thus maintaining the user's perspective on the workflow.
   • Default Value: () => {} (empty function).

10. proOptions

    • Input Type: Object
    • Description: Configuration options for the advanced editor features. The example shown disables attributions.
    • Default Value: {} (empty object).

11. nodeTypes

    • Input Type: Object
    • Description: Maps custom node types to their components (e.g., WorkflowNode). Adjusting this allows for different node representations or behaviors.
    • Default Value: {} (default may include only basic node types).

12. edgeTypes

    • Input Type: Object
    • Description: Similar to nodeTypes, it maps custom edge types. Changes here allow for different visual representations of edges.
    • Default Value: {} (default may include only a basic edge type).

13. selectionMode

    • Input Type: Enum
    • Description: Defines the mode of selection for nodes. Changing it can affect whether multiple nodes can be selected at once.
    • Default Value: SelectionMode.Partial (allows partial selections).

14. deleteKeyCode

    • Input Type: Array
    • Description: Specifies key codes that trigger the deletion of selected nodes when pressed. Customizing this changes user interactions.
    • Default Value: ["Backspace", "Delete"].

15. selectionKeyCode

    • Input Type: String
    • Description: Indicates which key enables selection mode when held. Changing this impacts how users interact with multiple nodes.
    • Default Value: "Shift".

Use Cases & Examples

Use Cases

1. Data Pipeline Creation: Users can design data pipelines by visually connecting nodes that represent different data processing steps, allowing for easier configuration and visualization of data flow.

2. Workflow Optimization: Analysts can modify existing workflows by adding, removing, or altering nodes, which helps refine analysis and reporting processes based on changing data requirements.

3. Collaborative Workflow Design: Teams can collaboratively build and adjust workflows in real-time, facilitating knowledge sharing and quicker iterative development of analytical processes.

Detailed Example

Use Case: Creating a Data Pipeline for ETL Process

Objective: To configure a workflow that extracts data from a source, transforms it, and loads it into a destination.

Sample Configuration:

{
  "nodes": [
    {
      "id": "1",
      "type": "extractNode",
      "data": { "source": "database" },
      "position": { "x": 50, "y": 50 }
    },
    {
      "id": "2",
      "type": "transformNode",
      "data": { "operation": "filter" },
      "position": { "x": 200, "y": 50 }
    },
    {
      "id": "3",
      "type": "loadNode",
      "data": { "destination": "dataWarehouse" },
      "position": { "x": 350, "y": 50 }
    }
  ],
  "edges": [
    {
      "id": "e1-2",
      "source": "1",
      "target": "2"
    },
    {
      "id": "e2-3",
      "source": "2",
      "target": "3"
    }
  ]
}

In this configuration:

• Three nodes (extractNode, transformNode, and loadNode) are positioned along the x-axis.
• Two edges connect these nodes, forming a simple ETL workflow.
• Users can interact with the rendered nodes and edges to visually modify the workflow as needed, facilitating immediate updates to the data pipeline design.

By utilizing the WorkflowEditor, analysts can deploy a functional and efficient ETL process with seamless adjustments based on evolving business requirements.