# 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.

← Error Handling →