How to: Reference a Global Variable in a Component

Overview

Let's explore how to reference a global variable Global variables are variables you can create and reference across all applications in an environment stage. in a component. Global variables help you avoid hardcoding reference values in your application's environment stages. They also help you avoid issues during your application's promotion. Global Variables Administration lets you standardize the way you create and reference custom variables. A custom variable is an identifier (or key) paired to a stored value. Once paired, you can reference the key anywhere in your application. This separation of the key from its value lets you use your key independent of the data it represents.

You can reference variables in all components that let you reference submission data objects. This includes data source URLs, and Calculator and Decisions components. To reference a global variable, you need its key and the prefix vars. So, the formatting is vars.Key. Alternatively, you can use vars getter in combination with a GET formula.

In this how-to guide, you'll create a variable to reference your current environment stage using Global Variables Administration. After creating your global variable, you can reference it using a Calculator component. It's important to note that the global variable you create is only available in the environment stage where you created it. To have your global variable resolve in another environment stage, you must promote it. Or, create it manually in another environment stage. That way, your values can resolve dynamically based on the environment stage your application is running in.

WARNING  Don't use Global Variables Administration to store sensitive data, like APIs and secrets. Global variable values display to users while building applications in Unqork.

TIP  To learn more about promoting global variables, visit our Global Variables Administration: Global Variables Promotion article.

Here’s how your completed module looks in the Module Builder:

A static image displaying how the module looks after completing the how-to guide.

What You'll Learn

In this how-to guide, you’ll learn how to add a global variable and configure a Calculator component to reference it.

What You Need

To add and reference a global variable, you need:

NOTE  These instructions assume you have a module open, saved, and with a title.

Preconfiguration

Add a Global Variable

First, add a global variable for your current environment's URL. This how-to guide focuses on creating a global variable for your Staging environment.

1. At the top right of the Unqork Designer Platform, click the Settings ▾ drop-down.
2. Click Administration.
3. Under Environment, select Global Variables.
4. At the bottom of the Global Variables page, click New Global Variable.
5. In the Enter Key field, enter envUrl.
6. In the Enter Description field, enter Staging URL.
7. Clear the Server-Side Only (Unchecked) checkbox.
8. In the Enter Value field, enter your Staging environment's URL. The formatting is: {your-environment}-staging.unqork.io.

A static image displaying how to create the EnvUrl global variable in the Global Variables Administration.

9. In the Actions column, click Save.

Configuration

Configure the Initializer Component

Now that you have your global variable, configure a module to reference your global variable.

1. In the Module Builder, drag and drop an Initializer component onto your canvas.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text Canvas Label Text indicates the purpose of the corresponding field or component. For non-input components, the Canvas Label Text isn't end-user facing, and only appears in the . fields, enter initOnLoad.
3. Set the Trigger Type Deteremines how the component triggers. as New Submission The component fires when the page or called module loads without an existing submission ID. Dashboards and remote execute modules are great uses for this trigger..
4. In the Outputs table, enter the following:
Property ID Type Value

calcEnvUrl

trigger

GO

NOTE  This Property ID corresponds to the Calculator component you'll set up next.

A static image displaying how to configure the Initializer component to trigger the Calculator component.

5. Click Save & Close.

Configure the Calculator Component

Next, configure a Calculator component to reference the global variable. To reference your global variable, you must input it as vars.Key. In the case of this how-to guide, the input is vars.envUrl. Then, output the value into a Hidden component that you set up next.

1. Drag and drop a Calculator component onto your canvas, placing it below your Initializer component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text Canvas Label Text indicates the purpose of the corresponding field or component. For non-input components, the Canvas Label Text isn't end-user facing, and only appears in the . fields, enter calcEnvUrl.
3. From the component's configuration window, click the Actions Icon Actionstab.
4. In the Inputs table, enter the following:
Property ID Alias Required

vars.envUrl

E

(checked)
5. In the Outputs table, enter the following:
Property ID Formula

envUrl

=E

A static image displaying how to configure the Calculator component to reference the EnvUrl global variable.

6. Click Save & Close.

TIP  Alternatively, you can input vars as the Property ID and use the output formula: =GET(E, 'envUrl'). This formatting works for any global variable key: =GET(E,'Key').

Configure the Hidden Component

Lastly, set up a Hidden component to store the value of your global variable.

1. Drag and drop a Hidden component onto your canvas, placing it below your Calculator component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text Canvas Label Text indicates the purpose of the corresponding field or component. For non-input components, the Canvas Label Text isn't end-user facing, and only appears in the . fields, enter envUrl.
3. Set the Store Data in Database toggle to (ON).
4. Click Save & Close.
5. Save your module.

You must be an Administrator to create global variables, but you can still view the environment stage’s variables in the DevTools Console if Server-Side Only is deselected. If your Administrator selected Server-Side Only, use the Server Side Execution Testing page to view the global variable. Knowing where to look for your global variables will help if any issues arise.

Here’s your global variable in the DevTools Console:

A static image displaying the vars object in the DevTools Console.

Here’s your global variable in the Remote Execute Debugger of the Server Side Execution Testing page:

A static image displaying the vars object in the Remote Execute Debugger.

TIP  Alternatively, you can also use global variables directly in a Calculator and Plug-In component using the following syntax: vars.globalVarName.

Resources