# Basic Concepts

This section cover the basic concepts to understand of Kumologica and explains the technical details of how Kumologica works.

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

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

# Context

Context in Kumologica defines the visibility of variables, environment and message object in a flow. Kumologica classify context into two types. i.e Main flow context and Sub flow context.

Main flow context

Main flow context also called as parent flow context is the default context when you build a Kumologica flow. This context starts from the EventListener node to EventListener End node. The variables defined in the main flow will be visible across all the nodes in the main flow but will not be visible on the sub flow context. Environment variables and message object will be visible across all the nodes placed on a main flow or a sub flow.

Sub flow context

Subflow context is the context defined when the flow is having a processor node with subflow operation selected. This context starts from the Processor in node to Processor out node. The variables defined in the sub flow will be visible across all the nodes in the sub flow but will not be visible on the main flow context or on any other subflow context. Environment variables and message object will be visible across all the nodes placed on a main flow or a sub flow.

TIP

Variables defined in main flow is accessible only within main flow and variables defined in subflow is accessible only within the subflow. When variable value in the main flow to be passed on to a subflow or vice versa then need to set the variable value to message object using a set-property or a function or a datamapper node.

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