State Machine

A placeholder node for state machine

Overview

This node implements a state machine executor that integrates with a PostgreSQL database to persist and manage the current state of multiple instances. It fetches state machine code from a specified URL, caches it locally, and executes transitions based on incoming events. The node is useful for workflows requiring complex state management, such as order processing systems, user session tracking, or any scenario where an entity's state evolves over time in response to events.

Typical use cases include:

  • Managing workflow states in business processes.
  • Tracking device or user states in IoT or web applications.
  • Implementing custom finite state machines without embedding logic directly in the workflow.

Properties

Name Meaning
State Machine URL URL endpoint to fetch the JavaScript code defining the state machine behavior.
State Machine Diagram Name The name identifier of the state machine diagram; used to name database tables and cache files.
Cache Folder Local folder path where fetched state machine code files are cached for reuse.

Output

The node outputs JSON data for each input item with the following structure:

  • event: The event string that triggered the state transition.
  • instance: The unique identifier of the state machine instance.
  • previousState: The state before processing the event (or null if none).
  • state: The resulting state after processing the event (or null if an error occurred).
  • error (optional): Error message if the state transition failed due to invalid event/state or other issues.

No binary data output is produced by this node.

Dependencies

  • PostgreSQL Database: Used to store and retrieve the current state of each state machine instance. Requires connection credentials (host, port, user, password, database).
  • External HTTP Endpoint: The node fetches the state machine JavaScript code from a user-provided URL.
  • Local File System Access: For caching the downloaded state machine code in the specified folder.
  • Node.js Modules: Uses standard modules like fs/promises for file operations, path for file paths, and pg for PostgreSQL client.

Troubleshooting

  • Invalid Property Types: The node throws errors if required properties (State Machine URL, Cache Folder, State Machine Diagram Name, or event) are not strings.
  • Database Connection Issues: Failure to connect to PostgreSQL will cause execution to fail. Verify credentials and network access.
  • Missing Database Table: The node auto-creates a table named after the state machine diagram if it does not exist.
  • State Machine Code Fetch Failures: If the URL is unreachable or returns a non-OK status, the node throws an API error. Check the URL and network connectivity.
  • File System Permissions: Errors accessing or creating the cache folder may occur if permissions are insufficient.
  • Invalid Event or State: If the event or current state is not recognized by the state machine code, an error is thrown and included in the output under error.
  • Reset Flag: Setting reset to true in input JSON forces ignoring the stored state and starting fresh.

Links and References

Discussion