Help & Documentation

Everything you need to know to build powerful workflows with Xelflow.

Xelflow is a powerful business logic engine that operates on JSON definitions. By combining flows, tables, and events, you can build complex applications without writing a single line of traditional backend code.

Flows

Flows define your application's logic. They consist of a series of steps that are executed sequentially.

Key Elements

Parameter	Description
Name req	Name of the flow (e.g., `SaveMessageFlow`).
Version req	Version of the flow (e.g., `1.0`).
Status req	Status of the flow (`Active` or `Inactive`).
StartStepId opt	ID of the first step to be executed.
ErrorStepId opt	ID of the step called if an error occurs.
Steps req	An object containing all step definitions.

Variables & Interpolation

Every flow has a flow context. This contains, for example, the event and the user, as well as results from steps.

You can use dynamic data to access information in the context using the ${variableName} syntax:

${event.data.fieldName} - Data sent from the client.
${error} - Error message from a previous step.
${user.Email} - User's email address.

In addition to variables, you can also use Functions with the ${FUNCTIONA(FUNCTIONB(variableName,'value'))} syntax, for example ${NOT(EMPTY(event.data.email))}. More functions will follow as needed; the current list is below.

Function	Description
EMPTY	Returns `true` if the value is empty or `null`, otherwise `false`.
NOT	Returns `true` if the value is empty or `null`. (Wait, the Dutch said: "Geeft true terug als de waarde leeg of null is". That sounds same as EMPTY. Let's assume it means boolean NOT).
AND	Returns `true` if all values are `true`, otherwise `false`.
OR	Returns `false` if all values are `false`, otherwise `true`.
SUM	Returns the sum of all values.
MIN	Returns the minimum of all values.
MAX	Returns the maximum of all values.
AVG	Returns the average of all values.
NOW	Returns the current date and time in UTC or the specified TimeZone.
TODAY	Returns the current date in UTC or the specified TimeZone.
DATEPART	Returns the specified part (`year`, `month`, `day`, `hour`, `minute`, `second`) of the given date.
EQUALS	Returns `true` if the values are equal, otherwise `false`.
GREATER	Returns `true` if the first value is greater than the second, otherwise `false`.
LESS	Returns `true` if the first value is less than the second, otherwise `false`.
GREATER_OR_EQUAL	Returns `true` if the first value is greater than or equal to the second, otherwise `false`.
LESS_OR_EQUAL	Returns `true` if the first value is less than or equal to the second, otherwise `false`.
CONTAINS	Returns `true` if the first value contains the second, otherwise `false`.
IF_ELSE	The first value is a condition. Returns the second value if the condition is `true`, otherwise the third value.
MAP	Executes an expression for each item in a list and returns it as a new list. Syntax: `MAP(list, 'item', expression)`.
FILTER	Filters a list based on a filter expression. Syntax: `FILTER(list, 'item', expression)`.
CONCAT	Joins lists together. Syntax: `CONCAT(list1, list2, ...)`.
COUNT	Returns the number of elements in a list. Syntax: `COUNT(list)`.
COALESCE	Returns the first non-EMPTY element among the values. Syntax: `COALESCE(value1, value2, ...)`.
RANDOM	Returns a random value based on type and length. Syntax: `RANDOM(type, length)`, type can be `BASE64`, `INT`, `GUID`, `CHAR`, `ALFANUMERIC`, `PASSWORD`.
LOWER	Returns the value in lowercase: `LOWER(value)`.
UPPER	Returns the value in uppercase: `UPPER(value)`.
CAPITALIZE	Returns the value with the first letter capitalized and the rest in lowercase: `CAPITALIZE(value)`.
TRIM	Returns the value without leading and trailing spaces: `TRIM(value)`.

Step Types

Each step in a flow has a type that determines which action is performed and which parameters are required.

General

General parameters for every step.

Parameter	Description
Idreq	Unique identification of the step.
Typereq	See below for available Step Types.
Parametersreq	Parameters depend on the Step Type. See below.
Aliasopt	Name of the results in the flow context. If not filled, the alias is equal to the id.
NextStepIdreq	Id of the next step to be executed. If not filled, the flow is finished.
AuthenticationIdopt	Id of the authentication to be used.

QueryDatabase

Executes a SQL query on the database.

Parameter	Description
QueryTypereq	Query type: `Insert`, `Select`, `Update`, `Delete`.
QueryTextTypereq	Query text type: `Text`, `Dynamic`.
Query (Text)req	The SQL query to be executed. Use `@ParameterName` for parameters.
Query (Dynamic)req	A list of SQL query parts. Each part has `Sql`, `Part`, and `Conditions` properties. If the `Conditions` are not met, the `Sql` is not included in the query. Use `@ParameterName` for parameters.
Parametersreqvar	An object mapping values to SQL parameters. Variables and Functions can be used here, e.g., `${event.data.limit}`.

SendEmail

Sends an email via the configured SMTP server. AuthenticationId is required.

Parameter	Description
Toreqvar	Recipient of the email.
Fromreqvar	Sender of the email.
Subjectreqvar	Subject of the email.
Bodyreqvar	Content (supports HTML and variables).
IsHtmlopt	Set to `true` to send the body as HTML.

SendMessageToUser

Sends data or status information back to the client application using Server-Sent Events (SSE).

Parameter	Description
Eventreqvar	Name of the event triggered on the client (e.g., `MessageSaved`).
Datareqvar	An object containing the payload sent to the client.

SendNotification

Sends a notification to the client application using the VAPID protocol. AuthenticationId is required.

Parameter	Description
Endpointreqvar	Client endpoint.
P256dhreqvar	Client P256dh.
Authreqvar	Client Auth.
Messagereqvar	An object containing the payload sent to the client.

SendEvent

Sends an event to the server, which can then trigger another flow.

Parameter	Description
Namereqvar	Name of the event triggered on the server.
Versionreqvar	Version of the event triggered on the server.
Listoptvar	A list can be specified for sending multiple events (e.g., `${subscriptions}`). The list will also be used to retrieve the correct variables (e.g., `${subscriptions.*.Endpoint}`).
ContinuationEventreqvar	Event sent back from the started flow. Data is added to the context.
CorrelationIdoptvar	A combination of GUID and index identifying which flow and list ID this event belongs to.
MaxConcurrencyreq(Default 1)	Number of events sent simultaneously (`1` to `5`).
ContinueOnFailureopt (Default false)	If false, the flow stops if an event fails. If true, the flow continues with the next event.
Datareqvar	An object containing the payload sent with the event.

HttpsAction

Sends an HTTP request to an external API.

Parameter	Description
Endpointreq	API URL.
Methodreq	HTTP method (GET, POST, PUT, DELETE).
Headersopt	Headers for the HTTP request.
Bodyopt	Body for the HTTP request.
ContentTypeopt	Content type of the HTTP request.
Streamopt	Response is a stream (`true` or `false`).
StreamEventopt	Event and Version sent per chunk of the stream (e.g., `StreamChunk@1.0`).

ValidateContext

Validates the context based on a set of rules. If validation fails, the flow stops and the error step is executed.

Parameter	Description
Key Value pairreq	The Key is the name of the validation rule. The Value is the value to be checked.

AddDataToContext

Adds data to the context. This can be used to pass data to other steps.

Parameter	Description
Keyreq	The Key is the name of the variable being added to the context.
Valuereq	The Value is the value being added to the context.

Decision

Makes a decision based on a condition. If the condition is true, TrueStepId is executed. If false, FalseStepId is executed.

Parameter	Description
Conditionreq	The condition to be checked. This is an expression that is evaluated.
TrueStepIdreq	The step executed if the condition is true.
FalseStepIdreq	The step executed if the condition is false.

Send to AI Agent

Sends a question to the AI agent. The agent provides an answer based on information it can request from the application. This step returns a ConversationId and an Answer, which are either placed in the context or, in the case of streaming, sent via the streamEvent.

Parameter	Description
ChatMessagereq	The question sent to the AI agent.
ConversationIdopt	The conversation ID used to identify the conversation.
StreamEventopt	Event for streaming the AI agent's answers.
Versionopt	Version of the stream event.

Events

Events trigger flows based on the event's Name and Version. They often contain validation rules to ensure input correctness.

Parameter	Description
Idreq	Always null, filled when stored in the database.
Namereq	Event name.
Versionreq	Event version.
Statusreq	Event status (`Active` or `Inactive`).
Cronopt	A cron expression that determines when this event is created by the scheduler, possibly combined with a number of repetitions until the event becomes `Inactive` (e.g., `0 13 * * *;1` means once at 1:00 PM).
Rolesopt	List of user roles that can execute this event.
Validationopt	List of validations.

Validation Rules

First, it is checked whether an event is Active and that the user has the correct role.

Use the Validation array to perform checks before the flow starts.

                    "Validation": [
                    {
                    "Check": "${NOT(EMPTY(event.data.email))}",
                    "Message": "Email is required"
                    }
                    ]
                

Authentications

Authentications manage access to external systems or the database. A list of available authentications is maintained in the Authentications folder.

Parameter	Description
Idreq	Used in flow steps via the `AuthenticationId` property.
Typereq	Must match the step type for which it is used.

Note: NEVER store API keys or secrets in JSON files. Use the Xelflow Admin Panel for secure configuration.

Tables

Table JSONs define the database schema. This schema is primarily for your own reference or for the AI.

Table Properties

Property	Description
Name	Table name
Version	Table version
Status	Table status (`Active` or `Inactive`)
Description	Table description
Columns	List of columns in the table

Column Properties

Property	Description
Name	Column name
Type	SQL Data Type (e.g., `int`, `nvarchar(255)`, `datetime2`, `bit`).
IsPrimaryKey	Set to `true` for the table's unique ID.
IsNullable	Determines if the field can be empty.
ForeignKey	Establishes a relationship between tables by configuring `ForeignKey` with `Table` and `Column`.
DefaultValue	Default value (e.g., `SYSUTCDATETIME()` or `0`).

Migrations

Migration JSONs define the SQL scripts needed to achieve the correct tables in the database. With the command npm run sync-tables, the migration scripts are executed and moved to the processed folder.

Property	Description
Name	Name of the migration script
Scripts	List of SQL commands