Flow Builder Overview

The purpose of this overview is to introduce Domain Experts to basic and common concepts of the Flow Builder.

Best way to experience this Overview is to run ACE and play with it as you keep reading on this Overview.

What is Flow?

The Flow is set of steps that you need to do to process the input data to the point when you have enough data in the correct format to be returned as a result of the Flow.

What is Step?

Step is the computation unit that either retrieves, send on transforms the data. All data is stored in the doc.

See more details in step overview.

What is the doc?

doc is special. It is a data container which in the beginning contains data that is provided as an input to the Flow. You can work with it, provide as an input to external configurations, transform it, store preliminary results in it.

doc receives the input when the flow is executed - that is when api endpoint gets called (it receives path, query and body variables) or when the flow is executed from scheduler it is possible to set up the initial data to provide to the flow.

If only a part of the doc needs to be returned, this can be achieved by specifying the result property path in the flow properties.

Example

Let's imagine that we have created an API endpoint /api/demo/{id}?language={language}

Let's call the api endpoint with /api/demo/1?language=en

Then the input doc for the flow would look like

doc input variables

{
  "id": "1",
  "language": "en"
}

These variables then can be used in the flow steps to build a logic around.

Expressions

danger

Developer must never pass anything that is received from the external system or from the user as an input to expression!

You can use expression evaluators to access properties inside doc, $headers and $env objects.

ACE supports these expression evaluators - @ivm, @jsonata and @eval

@ivm

@ivm is default ACE expression evaluator. Expression {{id}} is same as @ivm{{id}}.

Under the hood @ivm is using V8 isolate interface. This means that for each expression new Javascript environment will be initialized and used to execute provided expression.

doc is added as the context and variables $headers, $env are added as the properties to the context.

note

Because of the cost of creating a new environment @ivm is very costly CPU wise to be executed. Use @jsonata when possible.

In nutshell, functionally, @ivm executes javascript code in double brackets in a same way as eval() executes the javascript.

The doc properties can be used within the flow - for example with the id variable it can be utilized in flow using the double curly brace syntax {{id}} -> this allows these dynamic variables to be used to run the step logic.

Example usage in step

tip

You can access data in doc in Step configuration by putting doc node name in double curly braces.

@jsonata

@jsonata expression evaluator uses Jsonata to evaluate the expression. Same as for @ivm doc is used as context and $env and $headers are injected as variables and can be used in expressions.

@eval (deprecated)

@eval is deprecated ACE expression evaluator. To use this for legacy reasons it has to enabled. See runtime configuration options.

Under the hood @eval will create Node Worker Thread and will execute vm.runInNewContext API with the doc as the context and $headers and $env added as the properties to the context.

note

Because of the security reasons @eval is very costly CPU wise to be executed. Use @jsonata when possible.

In nutshell, functionally, @eval executes javascript code in double brackets in a same way as eval() executes the javascript.

Compatibility

Most of the basic expressions are compatible between expression evaluators.

For example:

doc

{
  "id": "ID10"
}

Both @jsonata{{id}} and @ivm{{id}}, will yield the same result ID10.

Global variables

While the doc object contains the flow input and runtime variables, there are also context variables that are available within the flow.

Some of these variables will only be present when executing an API. For example, the object $headers is only available when a user calls the flow from an API endpoint.

Here are all the global variables available in an ACE flow.

• $headers - Request headers. Used to access headers when the flow is triggered by an API endpoint. Contains the following format: $headers: { "content-type": "application/json" }.
• $env - Variables defined in the workspace. Contains the following format: $env: { "your-variable-name": "" }. Env variables act as a useful way to define global connection settings, URLs, constants, etc.
• $api - Information about the API that triggered the flow. Contains the following format: $api: { "path": "/called-api-path", "method": "get", "flow": "some-flow-name", "definition": <OpenAPI definition>, "customProperties": <object> }.

How do we return data from the flow?

Response body

In order to send back data from the flow used in the API, you must utilize result variable or specify a result property path in the flow trigger step:

Given a flow which results in the document { "result": { "userId": "111" } }, if result property path is not specified, the API will return the result node. In this case { "userId": "111" } would be returned by the API.

If we instead specified the result property path of the flow to be result.userId, the returned valued of the API would be "111".

Response headers

Response headers of the dynamic api call can be manipulated using the responseHeaders node of doc object. responseHeaders must contain valid JSON with key-value pairs.

note

Response headers won't be visible in the API Swagger UI's response headers section due to a CORS restrictions, but they are visible if you observe the response using dev tools or other software like Postman

Response status

Response status code of the dynamic api call can be manipulated using the responseStatusCode node of doc object. responseStatusCode must contain valid HTTP response code(in either string or number format).

Importing and exporting flow configurations

While the main method of versioning ACE workspace is via git or workspace import/export, it is also possible to export and import individual flows.

• Export creates a yaml configuration file that can be shared with your collaborators or sent to the ACE Core team for debugging purposes.
• Import prompts you with a window where the yaml/json file of the flow that you wish to be imported must be selected.

tip

You can copy and import in your ACE instance the examples in that are provided together with the documentation of individual steps to try and run them locally.