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 (ornull
if none).state
: The resulting state after processing the event (ornull
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, andpg
for PostgreSQL client.
Troubleshooting
- Invalid Property Types: The node throws errors if required properties (
State Machine URL
,Cache Folder
,State Machine Diagram Name
, orevent
) 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.