Skip to main content
Version: Next

Migrate from Job Execution Engine to Generic Execution Engine

Introduction​

The Job Execution Engine (JEE) is the copilot internal engine used to execute automation actions in the background. We decided to extract this engine into the Pimcore core bundle and rename it to Generic Execution Engine (GEE). One of the main reasons for this change is to make the Copilot bundle more lightweight and to make the GEE available for other bundles. On top of that, we added a few improvements to the Generic Execution Engine.

With version 1.1.0 of the Copilot bundle, the Job Execution Engine is deprecated and will be removed in a future version. We recommend to switch to the Generic Execution Engine as soon as possible.

You can find the documentation for the Generic Execution Engine here.

caution

Make sure you install PimcoreGenericExecutionEngineBundle properly before you start.

Changes​

The most significant change is the parallel execution of subjects within a job. While the JEE passes all subjects to the action at once, the GEE passes one subject at a time. This improves the performance of the actions and makes it easier to handle subjects in the action. Additionally, it allows us to improve the error handling. Instead of reporting the whole job as failed or succeeded, we can now report each subject individually.

Activate the Generic Execution Engine​

To activate the Generic Execution Engine, you need to set the pimcore_copilot.execution_engine.engine configuration to the correct enum value.

    execution_engine:
        engine: !php/const Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Enum\ExecutionEngines::GENERIC_EXECUTION_ENGINE

Full example:

pimcore_copilot:
    config_location:
        automation_actions:
            write_target:
                type: 'settings-store'
        interaction_actions:
            write_target:
                type: 'settings-store'
    execution_engine:
        engine: !php/const Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Enum\ExecutionEngines::GENERIC_EXECUTION_ENGINE

Migrate existing actions​

Migrate action code​

To migrate existing actions, you need to adjust the action code to handle one subject at a time. You have to take care of namespaces as well, since they changed from Pimcore\Bundle\CopilotBundle\ to Pimcore\Bundle\GenericExecutionEngineBundle\.

JEE:

use Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Messenger\Handler\AbstractAutomationActionHandler;

GEE:

use Pimcore\Bundle\GenericExecutionEngineBundle\Messenger\Handler\AbstractAutomationActionHandler;

For more code examples and information please have a look at the src/AutomationAction/Messenger/Handler directory. In this folder you can find the built-in actions implemented for Job Execution Engine. In the Generic subfolder you can find the corresponding actions for Generic Execution Engine.

Make sure to use the correct classes​

The name of the classes and namespaces have changed. Make sure to use the correct classes and namespaces.

For example

  • Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Messenger\Handler\AbstractAutomationHandler --> Pimcore\Bundle\GenericExecutionEngineBundle\Messenger\Handler\AbstractAutomationActionHandler.
  • Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Messenger\Messages\AbstractExecutionEngineMessage --> Pimcore\Bundle\GenericExecutionEngineBundle\Messenger\Messages\AbstractExecutionEngineMessage.
  • Pimcore\Bundle\GenericExecutionEngineBundle\Extractor\JobRunExtractorInterface --> Pimcore\Bundle\GenericExecutionEngineBundle\Extractor\JobRunExtractorInterface ...

Handling the subjects​

Until now all subjects have been passed to the action at once. With the new execution engine this isn´t the case anymore. That means you have to adjust your action to handle the subjects one by one. You can use the getSubjectFromMessage method, implemented in AbstractAutomationHandler, to get the subject from the message.

    public function __invoke(GenericHuggingFaceImageToTextMessage $message): void
    {
        $subject = $this->getSubjectFromMessage($message);
        ...
    }

Migrate action configuration​

Automation actions need to be registered in the step_implementation configuration. Here it is necessary to add the enumeration value for the Generic Execution Engine too.

JEE:

    step_implementation_mapping:
      variant_generator:
        class: 'Pimcore\Bundle\CopilotBundle\AutomationAction\Messenger\Messages\VariantGeneratorMessage'
        inline_help_file_name: '@PimcoreCopilot/InlineHelp/AutomationAction/Step/variant_generator.html.twig'

GEE:

    step_implementation_mapping:
      generic_variant_generator:
        class: 'Pimcore\Bundle\CopilotBundle\AutomationAction\Messenger\Messages\Generic\GenericVariantGeneratorMessage'
        inline_help_file_name: '@PimcoreCopilot/InlineHelp/AutomationAction/Step/variant_generator.html.twig'
        engine: !php/const Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Enum\ExecutionEngines::GENERIC_EXECUTION_ENGINE

Migrate existing configurations​

To migrate existing configurations, you have to adapt the name of the step_implementation value in the configuration itself. Depending on the config location configuration, you can find the specific files either in the settings-store or in the filesystem.

JEE:

...                          
                steps:
                    -
                        name: TextToImageStep
                        step_implementation: hugging_face_text_to_image
                        condition: ''
...

GEE:

...          
                steps:
                    -
                        name: TextToImageStep
                        step_implementation: generic_hugging_face_text_to_image
                        condition: ''                
...

Worker process for Generic Execution Engine​

Last but not least you have to add a new worker (or adapt an existing one) to consume messages from pimcore_generic_execution_engine transport.

Permissions​

To allow a user to see the Job Run Log, you have to grant the corresponding permissions.

For Job Execution Engine the permissions are:

  • Pimcore Copilot Bundle - Job Run Overview - to see their own job runs
  • Pimcore Copilot Bundle - See all Job Runs - to see all job runs

For Generic Execution Engine the permissions are:

  • Pimcore Generic Execution Engine Bundle - Job Run Overview - to see their own job runs
  • Pimcore Generic Execution Engine Bundle - See all Job Runs - to see all job runs