Job Execution Engine

info

The Job Execution Engine is considered as @internal and might be subject to change. Please avoid directly using the Job Execution Engine in custom implementations.

Job execution engine

• executes jobs asynchronously via Symfony Messenger.
• traces and visualizes state of job runs.
• manages (start, cancel, restart) job runs.

Register Job Step Implementations

The implementation of job steps contains all the logic that a step should execute and is accomplished through Symfony Messenger messages and their corresponding handlers.

Implement and register custom step:

• Create message class implementing Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Messenger\Messages\JobExecutionEngineMessageInterface (there is an abstract class Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Messenger\Messages\AbstractExecutionEngineMessage to be used for convenience).
• Create a message handler capable of handling the message and doing all the desired logic. There is an abstract class Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Messenger\Handler\AbstractAutomationActionHandler providing some convenience functions in working with Job Runs.
• Make sure the message class is registered in Symfony Messenger routing accordingly.

Define Jobs

Jobs are defined and configured via Pimcore\Bundle\CopilotBundle\JobExecutionEngine\Model\Job objects which contain a name, steps (with defined message class and optional step specific configuration), subject and selected elements as well as environment data (e.g. content that is entered by a user and that should be available in job step handlers).

Create a job as follows

$job = new Job(
  'my-first-job',
  [
    new JobStep(MyFirstTestMessage::class, []),
    new JobStep(MySecondTestMessage::class, []),
  ],
  new ElementDescriptor('object', 234),
  [],
  [
     'foo' => 'bar'
  ]
);

Executing Jobs and Managing Job Runs

Execution of jobs is done via [Pimcore\Bundle\CopilotBundle\JobExecutionEngine\JobExecutionAgentInterface] service, which provides all sorts of methods for executing and managing running jobs.

caution

Be aware that the job execution engine does not retry failed messages.

pimcore_job_execution_engine:
    dsn: 'doctrine://default?queue_name=pimcore_job_execution_engine'
    retry_strategy:
        max_retries: 0 # no retries to prevent data corruption

Job Runs

Job Runs are the entity for storing information about runs of a job. There is the [Pimcore\Bundle\CopilotBundle\Repository\JobRunRepository] for all kind of CRUD operations on job runs.

Localization of Current Message

The current message of a job run can be localized. That means, that in user interface, the message is translated into the user's language. To ease handling of these messages, the JobRunRepository provides a specialized updateLogLocalized method, which helps you to create a localized log entry. It writes the untranslated message to the job run object, but translates the message to english and adds it to the job run log.

You can pass the message to the method, which then again can be translated using Pimcore's Translations menu by selecting the pimcore_copilot domain. In addition, it is also possible to add a translation directly in the corresponding pimcore_copilot.<language>.yaml file.

As example see:

$this->jobRunRepository->updateLogLocalized(
    $jobRun, 'pimcore_copilot_job_execution_job_cancelled', ['%job_run_id%' => $jobRun->getId()]
);