# Variable Namespaces

## 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-controls/text-input-web-control) 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](../../studio/studio/variable-tree), which is found at the bottom left of the Studio regardless of which Builder you're in:

![](https://2599974655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRF6etABDVMr59RdpyGw%2Fuploads%2Fgit-blob-8e13b61db71747b1e768cd0c193bd2681bc9fe40%2Fvariable-namespaces-v184-0.png?alt=media)

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

![](https://2599974655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRF6etABDVMr59RdpyGw%2Fuploads%2Fgit-blob-c82f884764ed243d7cd54f65a2410d204689b4ec%2Fvariable-namespaces-v184-1.png?alt=media)

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

![](https://2599974655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRF6etABDVMr59RdpyGw%2Fuploads%2Fgit-blob-881e951b88a6f13a0508b99582fa0e0ae797a5d0%2Fvariable-namespaces-v184-2.png?alt=media)

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](../../web-controls/text-input-web-control) Control or the [Phone Input](../../web-controls/phone-input-web-control) 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:

```javascript
activity.value
```

or simply as

```javascript
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**.

![](https://2599974655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRF6etABDVMr59RdpyGw%2Fuploads%2Fgit-blob-618e52d2e110c7534e4be3f5325e7455e936aa45%2Fvariable-namespaces-v184-3.png?alt=media)

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

```javascript
activityGroup.value
```

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

```javascript
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.

![](https://2599974655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRF6etABDVMr59RdpyGw%2Fuploads%2Fgit-blob-7e0416c385835592c7481b3d31b608f3e0667a5c%2Fvariable-namespaces-v184-4.png?alt=media)

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

```javascript
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.

![](https://2599974655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRF6etABDVMr59RdpyGw%2Fuploads%2Fgit-blob-5d3ecd5344ce31c94934e3be49027f03afda0da5%2Fvariable-namespaces-v184-5.png?alt=media)

## 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](standard-session-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](airdata/identity-app-object), which also comes pre-generated in every application and is accessible in [AirData Builder](../../studio/studio/builder-bar/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](../../actions/the-set-variable-action) Action and referenced like any other locally variable. For instance, the `phone` property of the Actor is accessible as:

```javascript
actor.phone
```

After a value has been assigned to a property in the `actor` namespace, the [Initialize Actor](../../actions/the-initialize-actor-action) 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](../../concepts/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

```json
event.value
```

or simply as

```json
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](../../studio/studio/events/session-events) or [Activity Group Events](../../studio/studio/events/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](../../studio/studio/events/control-events), might generate variables in the process of being fired. For more information, see [Events](../../studio/studio/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](../../building-apps/publishing/publish-and-manage-deployments).

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:

```javascript
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](../../building-apps/publishing/tying-variables-to-deployments).

### Theme Variables

The appearance of an application depends on the styling defaults defined in the [Theme Builder](../../studio/studio/builder-bar/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](../../emails/email-notification-basics). In such cases, you would reference the color code stored to `brandPrimary` as:

```javascript
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:

```javascript
control.value
```

For more on Custom Controls, see [Custom Controls](../../building-apps/advanced/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](../../actions/the-run-data-flow-action) Action. For the purposes of direct testing in the [Connections Builder](../../studio/studio/builder-bar/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

```javascript
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-operations/data-operation-overview/the-transform-data-operation) Data Operation, which returns the internal variable `transform`:

<figure><img src="https://2599974655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIRF6etABDVMr59RdpyGw%2Fuploads%2Fgit-blob-9cf5b75ac83f7cd6ad42e7dda50d8a3d3b29f7dd%2Fvariable-namespaces-v184-6.png?alt=media" alt="" width="300"><figcaption></figcaption></figure>

Once a variable is generated by a [Data Operation](../../data-operations/data-operation-overview), it can be used in any number of downstream Data Operations.

For more on Data Flows, see [Data Flows](../../studio/studio/data-flows).
