Connection Builder Connection Builder

Connection Builder

Chandra Bergmann Chandra Bergmann

Use and modify data.

The Connection Builder is designed to be your gateway to the outside world, as well as the place where you can design complex data interactions. It's the Builder that makes it easy to use and modify data, both internal and external.

In this document, we will discuss the broad functionality of each component of the Connection Builder and provide links to additional resources that discuss specific tools in more detail. 

Basic Layout

Like most Builders, the layout of the Connection Builder maps comfortably onto the general anatomy of the studio: to the immediate right of the Builder Bar is the Tree, to the right of which is the Stage, to the right of which is the Inspector. Note that the Inspector will not always be visible; depending on what's being displayed in the Stage, there might not be a need to access the Inspector. For instance, when examining a Data Flows, the Inspector will be present to show the variables that are available within the Data Flow:

Connection_Builder_Flow.png

On the other hand, when examining a Web Links, all relevant information is displayed in the Stage, and so there is no need to access the Inspector:

Connection_Builder_Links.png

Tree

The Tree is where you'll find an expandable and collapsible breakdown of the connections you have built out as part of your app. Airkit automatically splits these connections up into four types: Data Flows, Web LinksSubscriptions, and Periodic Tasks If you want to create a new connection, click the '+' sign to the right of the type of connection you want to add. If you want to delete a connection after it's been created, click on the trash icon to the immediate right of the undesired connection.

2021-07-07_14-16-40__1_.gif

Stage

The Stage displays a visual representation of the connection you are accessing. Exactly what is displayed in the Stage varies depending on the type of connection you are building or editing.

Inspector

The Inspector is where you can examine and modify details associated with Data Flows and Periodic Tasks. The Inspector will not appear when examining Web Links or Subscriptions, as all relevant information is displayed in the Stage.

Connection Types

Data Flows

Data Flows are custom connections. Conceptually, Data Flows work like functions: they take in input, process it, and return the resulting output. Once a Data Flow has been built, it can be initiated as a Periodic Task (see below) or as an Action within your application.

Data Flows are made up of component parts called Data Operations, which define how input is processed. Processing input might entail anything from making HTTP requests to sending emails to running another Data Flow. A single Data Flow might consist of any number of interconnected Data Operations, though these Data Operations do not appear nested underneath them in the Tree; building Data Flows out of Data Operations is done in the Stage.

Stage

When working with Data Flows, the Stage is where you'll see and build out the individual connections within. Upon creating a new, custom Data Flow, the Stage appears as follows. The top box, Start, keeps track of the input the Data Flow requires and the bottom box, End, is where you'll declare which of the internal variables the Data Flow will return. Note that, as this newly-created Data Flow is blank, no input is defined, and there are no return values to choose from. Also note that there is no way to add input values within the Stage; keeping track of the variables a Data Flow has access to – including the direct input – is the domain of the Inspector:

2021-07-07_15-08-17.png

The individual Data Operations that the Data Flow consists of go between the Start box and the End box. You can add a new Data Operation between connections by clicking on the '+' icon between them directly in the middle of the stage. Individual Data Operations can be deleted by clicking on the trash icon to their immediate right:

2021-07-07_14-39-21__1_.gif

Once a Data Operation has been added, its details can be edited directly within the Stage. There are many different types of Data Operations, and how each one appears and can be edited will differ according to functionality. For a closer look into the different types of Data Operations, check out the Data Operation Overview.

In the process of creating and editing Data Operations within a Data Flow, it is a good idea to test how they run to ensure they work as intended. This can be done by clicking on the 'Run' button within a Data Operation. Often, however, a Data Operation requires access to other variables – most commonly, direct input – in order to run. To streamline the process of testing, dummy input can be defined directly in the Stage. Once the required input has been defined in the Inspector, example input of the correct data type is automatically generated. This dummy input can be both examined and edited in the Start box, and when individual Data Operations are run, they will use the dummy values in place of the input variables:

image.gif

When Data Operations are built out, relevant variables will be auto-generated to account for their output, which can be used as input in downstream Data Operations. The more complex a Data Flow, the more of these variables will be generated, making it important to designate precisely which one is the desired output of the Data Flow as a whole. Once a Data Flow has been fully built out, you can specify which internal variable it will return by selecting the desired output from a dropdown menu in the End box.

2021-07-07_15-05-50__1_.gif

For more on how internal variables are generated and how dummy values are stored for the sake of testing, see the Inspector section.

Inspector

When examining Data Flows, the Inspector displays the relevant internal variables. These are separated into two expandable and collapsible sections: Start, and Variables

Start

The Start section in the Inspector is where you can define input that the Data Flow requires. This is done by clicking on the '+' icon to the right of 'Inputs' and selecting the desired data type of the additional input. Upon creation, you will be directed to name the input variable, after which a dummy value of the correct data type will be attributed to the variable for testing purposes. This dummy value will not be accessible outside of the Connection Builder; it will certainly not influence the behavior of the Data Flow when used as part of your app. It will only be used to when a value for that variable is required in order to test Data Operations within the Web Flow within the Stage.

The following example shows how to add a number input, named input_number, to a Data Flow. Note that input_number is automatically set to the value '1' for testing purposes. This is not because the number one has any particular significance in the context of this Data Flow; it is only because 1 is an arbitrary Number, and thus makes a passible dummy variable. Dummy variables can be changed in the Stage:

2021-07-07_14-53-20__1_.gif

Variables

The Variables section keeps track of all internal variables that are not required as input. (Remember: Data Flows might consist of any number of Data Operations, and Data Operations often produce their own output, which can be used as input for Data Operations downstream.) All variables automatically generated by Data Operations are found under Variables.

The following example shows what appears in the Inspector after a Transform Data Operation has been added has been added but before it has been run. Note that the automatically-generated variable, called transform, is present but undefined:

Screen_Shot_2021-07-08_at_12.48.11_PM.png

Once the Transform Data Operation has been defined – in this example, so that it outputs the sine of input_number – and run, the value of transform will change to reflect that:

Screen_Shot_2021-07-08_at_12.52.34_PM.png

When downstream Data Operations call upon the transform variable, they will, when run for testing purposes, use the value 0.8414709848078965 – at least until that value changes as a result of the Transform Data Operation being modified and run again to yield a different result.

Web Links

The Web Links section allow you to define Web Links and App APIs that can be incorporated into your application. These can be made into Events, including Starting Events, which trigger the start of a Journey.

Stage

When working with Web Links and App APIs, the Stage can be used to view and modify what the link or the API call fundamentally is. You can define the URL associated with a link, designate the exact HTTP request that will be sent to an API, and access the details of Journey Mapping.

Subscriptions

Subscriptions are a mechanism by which Airkit apps can receive (and subsequently respond to) to data updates from external sources. These can be made into Events, including Starting Events, which trigger the start of a Journey.

Stage

When working with Subscriptions, the Stage can be used to view and modify the data source and the category of webhook. I can also be used to access the details of Journey Mapping.

Periodic Tasks

Periodic Tasks schedule Data Flows to run at specific times. 

Stage

When working with a Periodic Task, the Stage displays a log of all instances where the Periodic task has been run.

Inspector

When examining a Periodic Task, the Inspector is where you can can view and modify the Data Flow being run periodically. You can select when Data Flow to run as well as when to run it.

Further Reading