Documentation
What's NewUKG.comMarketplaceUKG Pro status

Variables

Store and reuse values across workflows with custom variables.

Variables

Note: Compose is only available for Beta testing. See Welcome to UKG Compose > Beta Disclosure for more information.

Variables allow you to store and reuse values across your workflows without hard-coding them in workflow logic. Use variables for configuration values, API endpoints, or any data that multiple workflows need to access.

What Variables Are

Variables are read-only key-value pairs that you define once and reference from any workflow in your Compose project.

Key characteristics:

  • Created by administrators or instance owners
  • Read-only during workflow execution (cannot be changed from workflow logic)
  • Available in expressions and Code nodes
  • Support global scope (available to all workflows) or project scope (available to specific project only)
  • All values are stored as strings

Think of variables as: Configuration settings or constants that you want to manage in one place and use across many workflows.

When to Use Variables

API Endpoints and Base URLs

Store API endpoint URLs that workflows need to call.

Use cases:

  • Base URL for external API integrations (e.g., https://api.vendor.com/v2)
  • Webhook URLs for external systems
  • Environment-specific endpoints (test vs production API URLs)

Why use variables:

  • Change the endpoint once instead of editing dozens of workflows
  • Switch between test and production environments by updating a single variable
  • Avoid hard-coding URLs that might change

Example:

  • Variable: api_base_url = https://api.vendor.com/v2
  • In workflow HTTP Request node: {{ $vars.api_base_url }}/employees

Configuration Values

Store business rules, thresholds, or configuration settings used across workflows.

Use cases:

  • PTO approval thresholds (e.g., pto_auto_approve_days = 3)
  • Email notification addresses (e.g., hr_team_email = [email protected])
  • Timecard rounding rules (e.g., rounding_interval_minutes = 15)
  • Default shift codes or location IDs

Why use variables:

  • Update business rules without modifying workflow logic
  • Ensure consistency across workflows (all workflows use the same threshold)
  • Centralize configuration management

Example:

  • Variable: pto_auto_approve_days = 3
  • In workflow IF node: Check if {{ $json.pto_days }} is less than or equal to {{ $vars.pto_auto_approve_days }}

Environment-Specific Settings

Differentiate between test, staging, and production environments.

Use cases:

  • Database connection strings (test vs production)
  • Feature flags (enable/disable features per environment)
  • API keys or tenant IDs that differ between environments

Why use variables:

  • Deploy the same workflow to different environments and control behavior with variables
  • Avoid accidentally running test workflows against production data
  • Simplify environment-specific configuration

Example:

  • Variable: environment = production
  • In workflow IF node: Only send real notifications if {{ $vars.environment }} equals production

Shared Reference Data

Store reference values used across multiple workflows.

Use cases:

  • Default job codes or pay codes
  • Department or location mappings
  • Standard notification templates
  • Common approval routing rules

Why use variables:

  • Single source of truth for reference data
  • Easy to update across all workflows simultaneously

Example:

  • Variable: default_job_code = ADMIN001
  • In workflow: Use {{ $vars.default_job_code }} when creating new employee records

Variable Scope

Global Variables

Global variables are available to all workflows across all projects in your Compose instance.

When to use global variables:

  • Configuration values that apply to the entire organization (company name, base API URLs)
  • Widely-used reference data (HR team email, default values)
  • Cross-project shared settings

Who can create global variables:

  • Only administrators or instance owners

Project-Scoped Variables

Project-scoped variables are available only within a specific project.

When to use project-scoped variables:

  • Configuration specific to a project or team
  • Values that should override global variables for a particular project
  • Isolated settings for testing or development projects

Who can create project-scoped variables:

  • Administrators or instance owners

Note: If a project-scoped variable has the same key as a global variable, the project-scoped variable takes precedence within that project.

Creating Variables

Variables are managed from the Variables tab in Compose.

To create a variable:

  1. Navigate to the Variables tab (accessible from the overview page or a specific project).
  2. Select Add Variable.
  3. Enter a Key (e.g., api_base_url).
    • Maximum length: 50 characters.
    • Allowed characters: A-Z, a-z, 0-9, _ (underscores).
  4. Enter a Value (e.g., https://api.vendor.com/v2).
    • Maximum length: 1000 characters.
    • Allowed characters: A-Z, a-z, 0-9, _ (underscores).
  5. Select the Scope (if creating from the overview page):
    • Global - Available across all projects.
    • Project - Available only within a specific project (select which project).
    • Note: When creating from a project page, scope is automatically set to that project.
  6. Select Save.

The variable is now available for use in workflows according to its scope.

Using Variables in Workflows

Access variables in expressions and Code nodes using the $vars helper:

In expressions:

{{ $vars.variable_name }}

In Code node:

const apiBaseUrl = $vars.api_base_url;
const threshold = $vars.pto_auto_approve_days;

// Variables are strings, so convert if needed:
const thresholdNumber = parseInt($vars.pto_auto_approve_days, 10);

Example workflow usage:

Scenario: Send notification to HR team email stored in a variable.

  1. Variable: hr_team_email = [email protected].
  2. In Send Email node:
    • To: {{ $vars.hr_team_email }}
    • Subject: New PTO Request
    • Body: A new PTO request has been submitted.

Result: Email is sent to the address stored in the variable. If HR team email changes, update the variable once instead of editing every workflow.

Editing and Deleting Variables

To edit a variable:

  1. Navigate to the Variables tab.
  2. Hover over the variable you want to chang.
  3. Select Edit.
  4. Update the key or value.
  5. Select Save.

To delete a variable:

  1. Navigate to the Variables tab.
  2. Hover over the variable you want to delete.
  3. Select Delete.
  4. Confirm deletion.

Warning: Deleting or renaming a variable will break workflows that reference it. Check which workflows use the variable before deleting or renaming.

Variables vs Workflow Static Data

Use Variables when:

  • You need a read-only configuration value.
  • The value is shared across multiple workflows.
  • Administrators should control the value (not workflow logic).
  • The value should be easy to change without modifying workflows.

Use Workflow Static Data when:

  • The workflow needs to set and update custom data during execution.
  • Data is specific to a single workflow (not shared).
  • Workflow logic needs to write data, not just read it.

Key difference: Variables are read-only and managed via the UI. Workflow static data can be set and updated by workflow logic using Code nodes.

Common Patterns

Pattern 1: Environment-Specific Behavior

  1. Create variables:

  2. In workflow IF node:

    • Condition: {{ $vars.environment }} equals "production"
    • True: Send to {{ $vars.production_recipient_email }}
    • False: Send to {{ $vars.test_recipient_email }}

Why this works: Same workflow runs in test and production environments. Change environment variable to switch behavior without editing workflow logic.

Pattern 2: Centralized API Configuration

  1. Create variables:

  2. In HTTP Request node:

    • URL: {{ $vars.api_base_url }}/employees
    • Timeout: {{ $vars.api_timeout_seconds }}

Why this works: If API base URL changes, update one variable instead of dozens of HTTP Request nodes across multiple workflows.

Pattern 3: Consistent Business Rules

  1. Create variable:

    • max_auto_approve_pto_days = "3"

  2. In workflow IF node:

    • Condition: {{ $json.pto_days }} <= {{ $vars.max_auto_approve_pto_days }}
    • True: Auto-approve PTO request
    • False: Send to manager for approval

Why this works: All PTO workflows use the same auto-approval threshold. Change threshold once to affect all workflows.

Considerations and Limitations

Read-Only During Execution

Variables cannot be modified from workflow logic. If you need to set or update values during workflow execution, use:

  • Workflow static data (for workflow-specific state)
  • Data Tables (for cross-workflow shared data that workflows can update)

String Data Type

All variable values are strings. If you need numeric or boolean logic, convert the value in your workflow:

// In Code node:
const threshold = parseInt($vars.max_days, 10);
const isEnabled = $vars.feature_enabled === "true";

Variable Precedence

When a project-scoped variable has the same key as a global variable, the project-scoped variable takes precedence within that project.

Use this behavior to:

  • Set global defaults and override them for specific projects
  • Test new configuration values in a single project before rolling out globally

Undefined Variables

If a workflow references a variable that doesn't exist, the value is treated as undefined. Workflows don't automatically fail when referencing missing variables.

Best practice: Test workflows after creating or deleting variables to ensure references are correct.

Character Limitations

Variable keys and values are limited to:

  • Letters (A-Z, a-z)
  • Numbers (0-9)
  • Underscores (_)

If you need to store complex data (JSON, special characters), consider using Data Tables instead.

Related Pages

Workflow building:

Operational guidance:

Advanced concepts:

Updated 8 days ago