# Basic Concepts
This section cover the basic concepts to understand of Kumologica and explains the technical details of how Kumologica works.
# Nodes
A Kumologica API or service integration can be represented as a connected network of nodes, each node is responsible to take a message (request) and produce zero or many outputs, which in turn becomes the input to the next node.
Each node can be seen as a "black-box" or function that manipulates the message and produces some desirable side-effects: writing into an external database, send an email or SMS, etc.
There are three type of nodes:
- Inbound nodes: They are listening to external events: API requests, Queues, Topics, DB Triggers. The become the entry points to the flows, the main role is to convert those external events into an standard Kumologica message (
msg
). You can recognize these nodes as they have no explicit inputs defined in the designer. - Standard nodes: They are connected to other standard nodes, and they are responsible to accept messages and produce one or many outputs based on their internal logic. You can recognize these nodes as they have one explicit input and one or many outputs in the designer.
- Outbound nodes: As the standard nodes, they are connected to other standard nodes, but unlike those ones, their role is to produce a valid response (HTTP response) to the source of the event (original trigger of the flow).You can recognize these nodes as they have one explicit input and zero outputs in the designer.
# Message
A message, encoded as the internal object msg
, represents a piece of information that nodes
use to communicate with each other. Inbound nodes convert external trigger events into a msg
and it will pass it to its connected nodes
. Outbound nodes will convert a msg
into a HTTP response back to the client. In between, standard nodes will performed their predefined logic based on the received msg
and they they will modify the msg
accordingly.
The basic structure of a msg
is as follows:
- _msgid: Unique execution identifier created for each execution. During local development this id will be equal to the testCaseId.
- error: This property will hold the error being caught by the Error Node. Refer to Error Handling section for more details.
- header: This property is an object hold metadata added by a node. Information contained in this object should not be modified by other nodes.
- payload: This property is an object hold information added by node. Unlike the header property, this property is meant to be mutable, and it has a special meaning for some nodes. For example: the body of HTTP Response produced by the EventListenerEnd node is taken from the payload object.

# Flows & Context
A Kumologica project encapsulates the logic within a deployment unit (e.g. Container, FaaS function). We will refer to this project moving forward as Kumologica Flow App.
The Kumologica Flow app is broken into one to many flows. These flows can be understood as logical layers in traditional development, and help to organize logically big projects into separate concerns. The flows are represented as tabs within the Designer.
Each flow has attached a context that defines the visibility of variables, and the scope of the errors.
In order to improve the reusability and testability of our flows, we can group a subset of nodes into subflows.
The following diagram illustrates the relationship of Kumologica Flow App, the flows and subflows:

# Predefined Variables
As we have seen in the previous section, a msg
can hold information that can be exchanged between nodes
. In addition to msg
there are other two variables that can be used to store information at the level of the flow.
These two variables are:
vars
env
Kumologica is not prescriptive of when to use one over the other, but it is considered a good practice to hold information about the environment in env
, and use vars
for temporary and non business related information.
For AWS Lambda execution environments, env
variable will hold all the environment variables passed to the lambda function during deployment.
WARNING
Unlike msg
variable. Both variables: env
and vars
will keep their state across multiple invocations. Thus, be extra careful when you mutate these variables.
# Variable Visibility
In Kumologica, variables play a crucial role in managing data within your flows. There are three types of variables: vars
, msg
, and env
, each with distinct visibility and lifecycle characteristics.
# Global Scope: msg
and env
Both msg
and env
are global variables accessible throughout the entire flow. However, msg
is ephemeral and gets reset with each response from the flowApp, providing a clean slate for each request. In contrast, env
persists across multiple requests.
Always use msg
when passing parameters to a subflow.
# Local Scope: vars
vars
are local variables visible only within the specific flow or subflow in which they are defined. While vars
offer persistence across multiple requests within the same flow, using them for this purpose is discoraged as in serverless platforms, such AWS Lambda, the vars
will be forced to reset when the function gets terminated.
DANGER
Do not use vars
to pass parameters to a subflow; it will not work. Use msg
instead.
Understanding the visibility and lifecycle of these variables is crucial for effective data management within Kumologica flows."
# Dynamic Expression
Nodes are defined as a set of properties. Sometimes these properties are defined not as a static value (string or number) but as a dynamic expression. What it means is that the value will be computed dynamically at runtime.
This is very useful when the value of a property is dependant of another property that is only known during the execution of the flow.
For example, the name of a database name is suffixed with the name of the stage where this flow is executed: "my-database-dev", "my-database-test", "my-database-uat", "my-database-prod".
The developer can recognized fields accepting dynamic expressions in Kumologica Designer, as they will be highlighted in purple as the image below:

The format of the dynamic expression follows the one defined in JSONata string expressions (opens new window).
Keep in mind that the variables: msg
, var
and env
are available during the composition of those expressions.
String literals must be enclosed with either double quotes "
or single quotes '
.
In the event of a parsing error of the dynamic expression, the field will return the same value entered as an input.
Examples:
"my-database-" & env.stage
: Suffix the name of the database with the stage is running in."Message payload: " & msg.payload & " received"
: Inject the payload in the middle of a string. Useful for logging purposes.