runWorkflow Documentation

Purpose

The runWorkflow logic is designed to execute workflows identified by their ID, utilizing result caching for efficiency. It aims to optimize performance by avoiding redundant executions of workflows that have already produced results. Furthermore, it accommodates various operational modes (like preview and force execution) and manages dependencies using a determinate caching strategy.

Settings

This section provides an exhaustive overview of all settings used within the runWorkflow function, detailing their purposes, types, impacts on behavior, and default values.

1. workflowId

• Input Type: Numeric (integer as string)
• Description: This is a required parameter indicating the unique identifier of the workflow to be executed. If not provided, the function will log a warning and return a default value.
• Default Value: None (must be supplied).

2. skipCache

• Input Type: Boolean
• Description: When set to true, this option instructs the function to bypass any cached results and re-execute the workflow regardless of existing cache data. This can be particularly useful for ensuring that the most up-to-date information is retrieved or when expecting changes in data that affect the workflow outcome.
• Default Value: false.

3. previewMode

• Input Type: Boolean
• Description: Activating this option limits the output data to a maximum of 10 rows, primarily for testing purposes. This avoids long execution times and demonstrates what the workflow would produce with limited data. The results generated in this mode will not be cached due to their truncated nature, as they could skew future performance evaluations.
• Default Value: false.

4. outputNodeId

• Input Type: Numeric (integer as string) or null
• Description: It allows users to specify a particular terminator node whose results they want to retrieve. This becomes essential when workflows have multiple terminator nodes. If a specific node ID is set, only the output from that node will be returned. If not provided, the default behavior will return outputs from all terminator nodes.
• Default Value: null.

5. forceSync

• Input Type: Boolean
• Description: When true, this option forces the execution of the workflow in sync mode, disregarding any optimizations or asynchronous operations that could otherwise speed up the execution. This is typically used in scenarios requiring strict integrity and sequence of operations.
• Default Value: false.

How It Works

The runWorkflow function begins by fetching parameters from the provided config or context objects. It validates the workflowId, ensuring it’s a numeric type and checking for null or undefined values. It generates a deterministic caching key based on whether a cache skip is requested and checks Redis for existing results.

If valid cached results exist, the function checks if the relevant data is still valid. If invalid, the function re-executes the workflow. Post-checks, the function queries the database to retrieve the workflow's details, including nodes and edges necessary for execution.

The function passes the relevant data to the executeWorkflow helper function, which handles the actual processing. After execution, if not in preview mode, results are cached for future requests.

Data Expectations

The runWorkflow function expects the following data:

• A valid workflowId which corresponds to an existing workflow in the database.
• Optional configurations that guide execution behavior (skipCache, previewMode, outputNodeId, forceSync).
• Redis must be correctly configured and available to store and retrieve results.

AI Integrations

While there are no explicit AI integrations within the runWorkflow function itself, it is endowed with capabilities to utilize machine-learning models or AI engines through the workflows it executes. By manipulating workflow nodes that might call AI services, users could drive intelligent data transformations, insights, or predictions.

Billing Impacts

Executing the runWorkflow function and leveraging its features may incur costs based on the number of executions, the amount of data processed, and storage of results in Redis. Utilizing caching can minimize costs associated with redundant workflows; however, disabling cache (skipCache set to true) or heavy workloads may lead to increased expenses due to resource usage.

Use Cases & Examples

Use Case 1: Data Processing Automation

A company automates its reporting workflow to generate weekly summary reports. It schedules a workflow to execute every week, leveraging runWorkflow to produce the latest report based on current sales data.

Use Case 2: Real-time Preview

A data analyst reviews the output of a new experimental workflow without affecting the production cache. By using runWorkflow in previewMode, the analyst can see instant results from the trial execution, adjusting parameters before full-scale deployment.

Example Configuration

For the above use case of a real-time preview, the analyst might configure runWorkflow as follows:

const workflowConfig = {
    workflowId: '123',               // ID of the specific workflow to execute
    skipCache: false,                // Utilize caching
    previewMode: true,               // Enable preview mode to limit output
    outputNodeId: null,              // Retrieve results from all terminators
    forceSync: false                  // Default asynchronous behavior
};

const result = await runWorkflow(workflowConfig);
console.log('Workflow result preview:', result);

This example would generate a preview output of the workflow identified by ID 123, providing insight into its performance without committing changes to the cache.