Data Builder Data Builder

Data Builder

Chandra Bergmann Chandra Bergmann

Define and access your Airkit data.

The Data Builder has two primary functions: creating custom App Objects and accessing saved data. 

Like most Builders, the layout of the Data 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:

Data_Builder.png

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

Tree

The Tree is where you'll find an expandable and collapsible breakdown of the App Objects that have been created in the Data Builder. The Object or property you select in the Tree determines exactly what is displayed in the Stage and the Inspector.

The structure of the Tree is structured into two levels, which nest as follows:

  • Object
    • Properties of the object

The following example shows a fully expanded Tree in the Data Builder. In this Data Builder, there are two objects: Identity and Survey_data. Identity has six associated properties (first_name, last_name, full_name, email, phone, and time_zone) while Survey_data has three (Name, Pet, and Number_of_Pets):

Data_Tree.png

Adding App Objects

New App Objects can be added by clicking the '+' button on the upper right corner of the Tree.

2021-06-21_13-26-46__1_.gif

There are three different types of objects you can add: App, place, or schedule. Place and schedule objects are specifically designed to work with Airkit's mapping and scheduling components; they are automatically generated with the relevant properties. App Objects are user-defined objects; they can have any number of properties, which themselves might be any primitive type or even other App Objects. 

App Objects serve as custom data types that you can use through your app-building process, and creating them can help build out and scaffold forms inside your web flows

Importing Objects and Creating Datastores

In addition to allowing the creation of new App Objects, clicking the '+' button on the upper right corner of the Tree provides the option to import objects and create datastores.

Importing data allows you to directly move data saved on your computer into Airkit Data Builder, as long as the data is formatted in a spreadsheet app such that the columns match each of the AirData App Object fields. For a more detailed dive into how to import and export objects, check out Exporting and Importing Datastores.

Datastores are AirData's conceptual way of grouping tables and data. A datastore contains information about all the data stored in the AirData, and they are particularly useful for setting up different environments like Production and Staging. For more on how to work with Datastores, check out Datastores.

Brief Tangent: The Identity App Object

When you first create an app, it comes out of the box with a single object built in: Identity. As the following example demonstrates, Identity comes with six associated properties (first_name, last_name, full_name, email, phone, and time_zone):

Identity.png

Like all other objects, Identity is blank upon creation (though, unlike other objects, it is created automatically when you first create you app).

The Identity object is important because it defines the structure of data pertaining to the Actor, the customer going through an Airkit App. The actor variable is a type of Identity, and it is crucial that the actor variable have access to way the Identity object is structured. In the vast majority of use cases, no data will actually be stored under the Identity object. The presence of the Identity object is important because it structures data that is saved and accessed during the relatively short-term length of a Journey; it is not often used for long-term data storage the way most App Objects are. 

Stage

The Stage displays the data that has been saved to the App Object

Gathered data is displayed in a table. The interface is reminiscent of a spreadsheet, with each row representing an individual instance of an App Object and each column corresponding with a particular property. Every App Object has its own table.

The following example shows how the Stage appears when examining an Object with three properties: Name (a string), Pet (a string) and Number_of_Pets (a Number). There are three instances of this object stored. Note that, on the left of each instance, there's a trash symbol; clicking on it will delete the instance and all associated data: 

Screen_Shot_2021-06-21_at_4.05.53_PM.png

Visualizing your saved data in this way allows you to quickly skim through it and notice obvious trends. It also makes it easy to confirm data is being saved as intended. 

Filters

To further simplify the process of examining data, Airkit makes it possible to filter data based on specified criteria directly in the Stage. To the right of each object property is a filter icon; clicking it brings up filtering options.

2021-06-21_16-14-52__1_.gif

These filter options can ensure that a specific filed has a particular value, meets a certain threshold, or is equal to a specific value. Filtering out data unrelated to your current search cuts down on noise and makes it even easier to notice trends within the clusters of data you care about. These filter options are analogous to the filter options available in Portal Builder

Inspector

The Inspector is where you can examine and modify individual elements within the Data Builder. The exact functionality available within the Inspector varies depending on whether you're working at the Object level or the Property level. You can change which level you are working at within the Tree.

Data_Inspector.png

Unlike the Inspectors associated with most Builders, the Data Builder Inspector does not make changes that will be reflected in the Stage; most changes made in the Data Builder Inspector only define changes to how data will be displayed elsewhere. 

Display Expression (Object Level)

Immediately under Display Expression is a drop-down menu that allows you to choose which property of the object will be displayed in a cell should this object be used as a property in a separate App Object.

Immediately below that is the Export Table as CSV button, which will export all data stored in the associated table as a CSV.

Property (Property Level)

Under Property, you'll find the means to examine and edit fundamental characteristics of a property, including other names its gone by (recorded as"Field Aliases") and the data type of the property. This is also where you can set restrictions on acceptable values for that property.

Formatter/Parser (Property Level)

Formatters and Parsers allow you to modify the way that data is viewed and stored in external Portals.

  • Formatter - Changes how the data will be viewed in Portals.
  • Parser - Changes how the data will be stored in Portals.

You can utilize Airscript to alter the format of the displayed data. To reference the data, use the namespace @. The @ symbol corresponds to the field data.

The following example shows how Airscript functions can be entered as input for either Formatter or Parser. The function FORMAT_PHONE takes the data in every cell in the relevant column (which represents, ostensibly, phone numbers) and converts it into the international phone number format. If this function is entered into the Formatter, it will only change the way these phone numbers will be displayed in Portals; If this function is entered into the Parser, it will change the way the phone numbers are stored:

FORMAT_PHONE(@, "INTERNATIONAL")

Validation (Property Level)

Validation places rules on how data will be displayed in external Portals. No changes made here will impact the way data is displayed in the Data Builder Stage; they will only be noticeable when viewing Portals.

There are three validation rules that you can add to an app object field. (One other, Is Unique, appears when you click the '+' icon to the right of the Validation section in the Inspector, but this is deprecated; its functionality has been moved under Constraints.)

2021-06-24_11-04-35__1_.gif

Is Required - ensures that this field must have data if its being entered by a user. The field could still have empty data inside Object-Service. This coupled with Not Null ensures that data always is present.

Length is Within Range - allows you to set an upper and lower bound on the length of the data. This will perform the Airscript function LENGTH on your input.

Custom Rule - utilizes Airscript to allow you to create more complex validation rules. The custom expression is expected to result in a Boolean. Instances where your custom Airscript output TRUE will be marked as valid; instances where your custom Airscript output FALSE will be marked as invalid. The @ symbol should be used as a placeholder for the value the relevant object property. For instance, the following example shows how to use the function ISPHONE to validate that each instance of data is a valid phone number:

ISPHONE(@)

Constraints (Property Level)

Constraints place limits on what data can be added when attempts are made to add data via an AirData query; App Objects that do not meet the constraints will not be saved.

There are four unique Constraints that you can add to an app object field. 

2021-06-24_11-21-07__1_.gif

Unique - ensures that no two instances have the same value for this field. This signifies that this column can be used as a primary key: a way to identify a single row of data.

Not Null - ensures that this field must have a value and that value cannot be NULL. This constraint is helpful in requiring input if you decide to create a Data Grid Portal page.

Default Value - provides a default value to this field. If no data is entered by the user, this default value will be recored into AirData.

User Variable - acts as a row-level permissioning for the data.

Be careful: constraints will be applied to retroactively all data saved in the relevant App Object, and all instances where the constraints are not met will be permanently deleted as soon as the constraints are applied. 

Storing and accessing your data in Airkit

Most commonly, data is gathered as users go through their Journeys; connecting information entered by users is done by creating Data Flows – specifically, ones that include AirData Queries – in the Connection Builder. Data can also be added manually or while testing AirData Queries in the Connection Builder directly.

Once you’ve saved data, you can click on one of your objects in the tree to see all the data associated with that object. You can select on any given cell to modify data, and you can scroll to the last row to add new data to this.

You can also create Data Flows to access and analyze your data directly within your apps: AirData Queries can perform CRUD operations.

If you want to access your data outside of the Airkit Studio, your tables can easily be exported into CSV format. You can also use Portal Builder to create external portal pages that provide access select information from your Airkit app without giving them to access anything else.

Further Reading