index.md

Documentation

• Prerequisite
• Installation
• Quick setup
• Cookbooks
  • Launch a CSV import from a form with file upload
  • Schedule a recurring process
  • Launch a process through the HTTP API
  • Notify the failures of the processes on Slack and by email
• Reference
  • Bundle configuration
  • Process UI options
  • Users & security
  • Process executions & logs
  • Scheduler
  • HTTP API
  • Console commands
  • Messenger & asynchronous execution
  • Notifications
• Troubleshooting
• CleverAge/ProcessBundle documentation

Prerequisite

CleverAge/ProcessBundle must be installed.

This bundle provides a web UI, built on EasyAdmin, on top of the process bundle. It does not provide any process task. Its features are:

• a process list, where each public process can be launched (with a confirmation modal, a form to set input and context, or directly),
• the history of every process execution (whatever the way it was launched: UI, console, HTTP, scheduler), with its status, duration, report and logs (stored in database and in a log file),
• a scheduler to run processes periodically (cron or periodical expressions),
• user management (login form, roles, API tokens),
• an HTTP endpoint to launch a process from another application,
• notifications of the end of the process executions (failures, warnings...), with Symfony Notifier.

It relies on Doctrine ORM (users, executions, logs, schedules), Symfony Messenger (asynchronous execution), Symfony Scheduler and Monolog.

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Open a command console, enter your project directory and install it using composer:

composer require cleverage/ui-process-bundle

With Symfony Flex, the recipe registers the bundle, imports its routes (config/routes/clever_age_ui_process.yaml) and creates its configuration (config/packages/clever_age_ui_process.yaml, see configuration). The recipes of its dependencies configure the security password hasher and the Doctrine naming strategy expected below: go straight to the database step.

The recipe comes from the recipes-contrib repository: Flex asks before applying it. In a non-interactive install (CI, Docker, composer require -n), it is skipped unless the contrib recipes are allowed, and the bundle is then not registered (no /process route, no cleverage:ui-process:* command). The recipe of cleverage/process-bundle is skipped too. Allow them and install the recipes:

composer config extra.symfony.allow-contrib true
composer recipes:install cleverage/process-bundle cleverage/ui-process-bundle --force -v

Without Flex, add the following line to config/bundles.php, then follow the quick setup:

CleverAge\UiProcessBundle\CleverAgeUiProcessBundle::class => ['all' => true],

Quick setup

Import routes

# config/routes/clever_age_ui_process.yaml
clever_age_ui_process:
    resource: '@CleverAgeUiProcessBundle/config/routes/*.yaml'

This imports the bundle controllers and the EasyAdmin routes (do not import easyadmin.routes a second time). If EasyAdmin routes are already imported (e.g. config/routes/easyadmin.yaml, created by the EasyAdmin recipe), import only the controllers, as the recipe does:

# config/routes/clever_age_ui_process.yaml
clever_age_ui_process:
    resource: '@CleverAgeUiProcessBundle/config/routes/controllers.yaml'

The former route names, deprecated since 3.3, are then not defined: if your application still uses them, also import @CleverAgeUiProcessBundle/config/routes/deprecated_aliases.yaml.

See routes.

Security

The bundle automatically configures a user provider and the main firewall (login form, logout, API token authenticator), overriding the provider, login form and logout of your main firewall. You only need a password hasher for the bundle User entity, which is the Symfony default:

# config/packages/security.yaml
security:
    password_hashers:
        Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'

To configure the security in your application instead (e.g. on a dedicated firewall), set clever_age_ui_process.security.configure_firewall to false. See users & security.

Database

Supported databases: MySQL / MariaDB and PostgreSQL (maintained versions).

The tables and columns of the entities have explicit names, those created by the migrations of the bundle: they do not depend on the Doctrine naming strategy of the application.

With Doctrine ORM 2, the lazy ghost objects must be enabled (also set by the Symfony recipe of the DoctrineBundle): the entities of the bundle have readonly properties, which the legacy proxies of ORM 2 cannot handle. Without it, the container compilation fails with an explicit message. Doctrine ORM 3 always uses lazy ghost (or native lazy) objects.

# config/packages/doctrine.yaml, with Doctrine ORM 2 only
doctrine:
    orm:
        enable_lazy_ghost_objects: true

The bundle registers its own Doctrine migrations (CleverAge\UiProcessBundle\Migrations). Run them, then create a first user:

bin/console doctrine:migrations:migrate
bin/console cleverage:ui-process:user-create admin@example.com 'my-password'

Assets

The default logo is served from the bundle public/ directory:

bin/console assets:install

Workers

Processes launched from the UI, the HTTP API (queued) or the scheduler are executed asynchronously with Symfony Messenger. Keep the following workers running (see messenger):

bin/console messenger:consume execute_process
bin/console messenger:consume scheduler_cron

Now you can access the UI via http://your-domain.com/process.

Configuration

The bundle works without configuration. Every option is described in bundle configuration:

# config/packages/clever_age_ui_process.yaml
clever_age_ui_process:
    security:
        roles: ['ROLE_ADMIN']
    logs:
        store_in_database: true
        database_level: Info # Debug on dev environment
        file_level: Info # Debug on dev environment
        report_increment_level: Warning
        database_max_days: ~ # Log retention, see the cleverage:ui-process:purge-logs command
        file_max_days: ~
    design:
        logo_path: 'bundles/cleverageuiprocess/logo.jpg'

The way each process is displayed and launched from the UI is configured in the process itself, under options.ui (see process UI options):

clever_age_process:
    configurations:
        app.import_products:
            entry_point: read
            options:
                ui:
                    source: ERP
                    target: Database
                    ui_launch_mode: form
                    form:
                        input:
                            type: Symfony\Component\Form\Extension\Core\Type\FileType
            tasks:
                read:
                    # ...