Environment Variables

Environment Variables are used in Automation Actions to define values that a user has to enter before starting an action. Those values are defined globally for the action and can be used in the action steps.

Environment variables provide a way to make automation actions configurable and dynamic. When a user manually triggers an automation action that has environment variables defined, they will be prompted to fill in a form with all the configured environment variables before the action is executed.

Types of Environment Variables

Following types of environment variables are available:

• Checkbox
• Date
• Matrix
• Number
• Select
• Text

Checkbox

Checkbox only has one configuration option:

required: true

Type for configuration file: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Checkbox

Date

Date has the following options:

required: true
default_value: '2024-01-01'

Type for configuration file: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Date

Matrix

A matrix can consist of multiple columns which can be again environment variables. Except another matrix type all environment variable types with their corresponding configurations.

required: true
columns:
  - configuration:
      required: true
      values:
        - key: grey
          value: Grey
        - key: beige
          value: Beige
        - key: silver
          value: Silver
    name: Color
    type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Select
  - configuration:
      required: false
    name: ProductionYear
    type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Number

Type for configuration file: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Matrix

Number

Number has the following options:

required: true
default_value: 10

Type for configuration file: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Number

Select

Select consists of one or multiple values. A value consists of a key and a value. The key is used as the value of the environment variable and the value is used as the label.

required: true
values:
- key: grey
  value: Grey
- key: beige
  value: Beige
- key: silver
  value: Silver
default_value: beige

Type for configuration file: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Select

Text

Text only has one configuration option:

required: true
default_value: 'Default text'

Type for configuration file: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Text

Using Environment Variables in Job Configuration

Once environment variables are defined for an automation action, they can be used in various parts of the job configuration:

Important: The method for referencing environment variables in step configurations varies by action type:

• Variant Generator action: Supports direct referencing (e.g., matrix_variable: Variants)
• All other actions: Must use the job_env() function (e.g., "job_env('VariableName')")

In Step Configuration

The method for referencing environment variables in step configuration depends on the specific step implementation:

Variant Generator Action (Direct Reference)

The variant_generator action supports direct environment variable referencing by name:

steps:
  - step_implementation: 'variant_generator'
    name: 'Generate Variants'
    configuration:
      class_name: 'Pimcore\Model\DataObject\Car'
      matrix_variable: Variants  # Direct reference to 'Variants' environment variable
      field_mappings:
        key: Color              # Maps to 'Color' column from matrix
        productionYear: ProductionYear  # Maps to 'ProductionYear' column from matrix

Other Actions (Using job_env Function)

For all other action types, environment variables must be referenced using the job_env() function:

steps:
  - step_implementation: 'some_other_action'
    name: 'Other Action Example'
    configuration:
      target_folder: "job_env('TargetFolder')"     # References 'TargetFolder' environment variable
      process_published: "job_env('Published')"    # References 'Published' environment variable
      batch_size: "job_env('BatchSize')"           # References 'BatchSize' environment variable

The job_env() function syntax is required for proper environment variable substitution in most step implementations.

In Step Conditions

Environment variables are available in step conditions through the environmentData variable in Symfony expressions.

Example: Using Environment Variables in Conditions

steps:
  - step_implementation: 'some_step'
    name: 'Conditional Step'
    condition: 'environmentData["Published"] == true'  # Only run if Published checkbox is checked
    configuration:
      # step configuration here
  
  - step_implementation: 'another_step'
    name: 'Object Type Specific Step'
    condition: 'environmentData["ObjectType"] == "variant"'  # Only run for variants
    configuration:
      # step configuration here

In Custom Step Implementations

When implementing custom job steps, environment variables can be accessed programmatically:

<?php

#[AsMessageHandler]
final class CustomHandler extends AbstractAutomationActionHandler
{
    public function __invoke(CustomMessage $message): void
    {
        $jobRun = $this->getJobRun($message);
        
        // Extract environment variables
        $environmentVariables = $jobRun->getJob()?->getEnvironmentData() ?? [];
        
        // Access specific environment variables
        $matrixFieldName = $this->extractConfigFieldFromJobStepConfig($message, 'matrix_variable');
        $matrixData = $environmentVariables[$matrixFieldName] ?? [];
        $objectType = $environmentVariables['ObjectType'] ?? AbstractObject::OBJECT_TYPE_OBJECT;
        $published = (bool)($environmentVariables['Published'] ?? false);
        
        // Use the values in your business logic
        if ($published) {
            // Do something when published is true
        }
    }
}

Common Usage Patterns

1. Matrix Environment Variables

Matrix environment variables are commonly used for bulk operations where multiple variants or configurations need to be processed:

environment_variables:
  - name: Variants
    type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Matrix
    configuration:
      required: true
      columns:
        - name: Color
          type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Select
          configuration:
            required: true
            values:
              - key: red
                value: Red
              - key: blue
                value: Blue
        - name: Size
          type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Select
          configuration:
            required: true
            values:
              - key: S
                value: Small
              - key: M
                value: Medium

This matrix can then be referenced in step configuration (for Variant Generator only):

steps:
  - step_implementation: 'variant_generator'
    configuration:
      matrix_variable: Variants  # Direct reference works only for variant_generator

2. Simple Configuration Variables

Simple environment variables can be used to configure step behavior:

environment_variables:
  - name: TargetFolder
    type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Text
    configuration:
      required: true
      default_value: '/Products'
  
  - name: Published
    type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Checkbox
    configuration:
      required: true

These can be referenced in conditions or step configurations (note the use of job_env() for step configuration):

steps:
  - step_implementation: 'move_objects'
    condition: 'environmentData["TargetFolder"] != ""'  # Conditions use environmentData syntax
    configuration:
      target_path: "job_env('TargetFolder')"  # Step config uses job_env() function
      publish: "job_env('Published')"         # Step config uses job_env() function

3. Conditional Step Execution

Environment variables are particularly useful for conditional step execution:

environment_variables:
  - name: ProcessType
    type: Pimcore\Bundle\CopilotBundle\AutomationAction\Configuration\Environment\Type\Select
    configuration:
      required: true
      values:
        - key: full
          value: Full Processing
        - key: quick
          value: Quick Processing

steps:
  - step_implementation: 'quick_processing_step'
    name: 'Quick Processing'
    condition: 'environmentData["ProcessType"] == "quick"'
    configuration:
      # quick processing configuration
  
  - step_implementation: 'full_processing_step'
    name: 'Full Processing'
    condition: 'environmentData["ProcessType"] == "full"'
    configuration:
      # full processing configuration

For more detailed examples, see the Variant Generator action which demonstrates comprehensive use of environment variables.