Variable Namespaces

Accessing Variables

Overview and Discussion

All variables within a Journey have an associated namespace, which defines where the variable is stored, as well as how and when the variable is accessible. This places limitations on the scope of individual variables, which is important for the sake of both security and application efficiency.

Sometimes the namespace of a variable can be left implied; for instance, if you've worked with the Text Input Web Control to bind user input to an automatically-generated variable, then you already have experience working with a variable in the activity namespace – it's just that Activity Variables are so narrowly-scoped that the activity namespace can be left implicit.

Activity Variables are only accessible within a particular Activity (such as an individual Web Page or Decision Menu). This contrasts with Activity Group Variables, which are accessible within a whole Activity Group (such as a full Web Flow or a Voice Bot), and Global Variables, which are accessible throughout a Journey.

Each of these variable types is associated with a particular namespace:

  • Global Variables - found under the session namespace, as in a value must be referenced as session.value
    • Activity Group Variables - found under the activityGroup namespace, as in a value is referenced as activityGroup.value
      • Activity Variables - found under the activity namespace, though explicitly referencing it is optional.

Defining the namespace of a variable is a core part of variable creation. Sometimes this is done under the hood. For instance, the variable automatically created upon the addition of a Text Input Web Control is tied to the activity namespace as a matter of course. When you manually create a new variable, however, you need to define its namespace more explicitly.

For example, Global Variables, Activity Group Variables, and Activity Variables are all managed in the Variable Tree, which is found at the bottom left of the Studio regardless of which Builder you're in:

2396

To create a new variable, open the Variable Tree and select the relevant type from the menu on the left:

1902

Click on the '+' icon in the center menu and select the data type you want to associate with your new variable.

1862

Once created, a variable can be edited in the center menu of the Variable Tree. The fields available for editing depend on the scope of the variable.

Activity Variables

Activity Variables are only accessible within a particular Activity, such as an individual Web Page or Decision Menu. Variables that are automatically created to bind the data collected by Input Web Controls (such as the Text Input Control or the Phone Input Control) are created as Activity Variables by default.

Activity Variables are found under the the activity namespace. For example, an Activity Variable designated value would be referenced as:

activity.value

or simply as

value

because Activity Variables are so narrowly-scoped that the activity namespace can be left implied.

Editable fields in the Variable Tree

Once an Activity Variable has been created, the interface in the Variable Tree can be used to designate the variable's name and the Activity that the variable will be accessible within. The latter is done by first selecting the Activity Group that the Activity is a part of, and then selecting the Activity.

1466

Activity Group Variables

Activity Group Variables are only accessible within a particular Activity Group, such as a Web Flow or a Voice Bot. They are found under the activityGroup namespace. For example, an Activity Group Variable designated value would be referenced as:

activityGroup.value

Depending on the nature of your application, you might have the option to leave the namespace implied, and reference this value as:

value

🚧

Unstated namespaces imply the narrowest relevant scope.

When a namespace is unstated, Airkit will reference the available variable in the narrowest relevant scope. For instance, if you an Activity has access to both Activity Variable and an Activity Group Variable designated value, then referencing value within that Activity will return activity.value, not activityGroup.value. If you want to leave the activityGroup namespace implied, it is best practice to make sure none of your Activity Variables share a name with any of your Activity Group Variables.

Editable fields in the Variable Tree

Once an Activity Group Variable has been created, the interface in the Variable Tree can be used to designate both the variable's name and the Activity Group that the variable will be accessible within.

1460

Global Variables

Global Variables are accessible throughout a Journey. They are found under the session namespace. For example, a Global Variable designated value would be referenced as:

session.value

Editable fields in the Variable Tree

Because Global Variables are available at any point throughout a Journey, there is no need to define their scope further. The only aspect of a Global Variable that can be edited in the Variable Tree is the Global Variable's designation.

1460

Other Variable Types and Namespaces

Standard Journey Data

Every Journey automatically records standard data about the interface being used to access the application. This includes things like the timezone associated with the device and the dimensions of the web browser (if applicable). Standard Journey Data is collected in five different namespaces:

  • browser
  • session
  • journey
  • profile
  • channels

These namespaces are accessible at any point throughout a Journey.

For more information on the values automatically stored in each namespace, see Standard Journey Data.

The Actor

Information saved in the actor namespace is used to automatically establish omni-channel interactions with the users of your applications.

All Airkit apps come pre-generated with an empty Actor. The structure of the Actor is defined by the Identity Object, which also comes pre-generated in every application and is accessible in AirData Builder.

The actor namespace is assessable at any point throughout a Journey. However, while the structure of the actor namespace is set automatically, the properties will be blank by default, and each one must be set explicitly. The variables stored in the actor namespace are locally-stored variables that can be assigned using the Set Variable Action and referenced like any other locally variable. For instance, the phone property of the Actor is accessible as:

actor.phone

After a value has been assigned to a property in the actor namespace, the Initialize Actor Action can be used to copy the relevant values into Airkit's actor_internal database. This is what allows Airkit to establish omni-channel communication with application users.

Because actor properties are used to automatically establish communication channels, their associated values must conform to expected formats. For more on the properties associated with the actor namespace and how they're used, see Actors.

Event Variables

Event Variables are variables associated with and only accessible within a particular Event. They are accessible within the event namespace, although, because Event Variables are inherently small in scope, the event namespace is implied while working within an Event.

For example, say an Event is associated with the Event Variable value. Within the Event, this value can be called up either as

event.value

or simply as

value

The details of defining and working with Event Variables depend on the nature of the Event. For instance, some Events, such as Session Events or Activity Group Events can be customized such that they require input which can be manipulated as local variables within the Event. Other Events, such as Control Events, might generate variables in the process of being fired. For more information, see Events.

Profile Variables

Each application contains different profiles. Each profile has a unique set of values and resources associated with them. For a deeper dive into profiles, see Profiles and Deployment Settings.

Profile Variables contain profile-level configuration variables. They are found under the profile namespace. For example, a Profile Variable designated value would be referenced as:

profile.value

Some Profile Variables are a collected automatically, as discussed in the Standard Journey Data section above. It is also possible to create your own Profile Variable, allowing you to easily manage variables across different deployments. For more information, see Tying Variables to Deployments.

Theme Variables

The appearance of an application depends on the styling defaults defined in the Theme Builder. Themes keeps track of Variants, which are similar to CSS classes.

Airkit handles most of styling associated with Themes under the hood, but there are occasionally instances where it is useful to reference some styling element directly. For instance, the variable brandPrimary refers to a color code, which is automatically referenced in out-of-the-box Web Controls in order to keep the color palette of the application consistent. You might also want to reference this color code independently, such as when styling an email to send as a Notification. In such cases, you would reference the color code stored to brandPrimary as:

theme.brandPrimary

In doing so, future edits to brandPrimary in the Theme Builder will be automatically applied not just to your web app, but the associated Email Notification as well.

Control Variables

Custom Controls are customized Web Controls, made by combining out-of-the-box Web Controls into reusable elements. They can be made to reference internal variables, available only within the Custom Control. These internal variables are called Control Variables, and they are available on the control namespace. For example, if your Custom Control expects an input named value , then you would reference that variable within the Control as:

control.value

For more on Custom Controls, see Custom Controls.

Variables Outside a Journey

All variables within a Journey have an associated namespace, but not everything created in the Studio is part of a Journey directly. In particular, Data Flows are connections that can be incorporated into a Journey, but they are not part of a Journey in and of themselves.

Data Flows

Data Flows are custom connections that are used to send, receive, and manipulate data.

While they can be easily tied to Journeys, Data Flows exist outside of Journeys, and do not have direct access to a Journey's variables – not even the Journey's Global Variables. Instead, each Data Flow is defined to expect input, which is bound to variables that exist only locally within the Data Flow. If you want your Data Flow to have access to a variable associated with your Journey, you will need to explicitly give it to the Data Flow as input when calling on the Data Flow using the Run Data Flow Action. For the purposes of direct testing in the Connections Builder, you will need to assign dummy values to all input variables.

Variables that exist within Data Flows can be conceptualized as existing in their own separate environment. They do not need an associated with a namespace because the only variables available within a Data Flow are its own. A variable designated value within a Data Flow would simple accessed as

value

within the Data Flow, and unaccessible in all other places.

When creating a Data Flow in the Connections Builder, all available variables will be tracked and displayed in the Inspector to the far right. These variables include both expected input, and internal variables generated in the process of running the Data Flow.

For example, the following Inspector tracks the variables available within a Data Flow that takes a single text value (example input) as input and runs a single Transform Data Operation, which returns the internal variable transform:

872

Once a variable is generated by a Data Operation, it can be used in any number of downstream Data Operations.

For more on Data Flows, see Data Flows.