Skip to content
Snippets Groups Projects

docs/eca/install.md, docs/eca/usage.md

Open docs/eca/install.md, docs/eca/usage.md
michaellenahan/eca:feature/initial-review into develop
9 unresolved threads
Open Michael Lenahan requested to merge michaellenahan/eca:feature/initial-review into develop
9 unresolved threads

Merge request reports

Loading
Loading

Activity

Filter activity
  • Approvals
  • Assignees & reviewers
  • Comments (from bots)
  • Comments (from users)
  • Commits & branches
  • Edits
  • Labels
  • Lock status
  • Mentions
  • Merge request status
  • Tracking
docs/eca/install.md
16 You need to have Composer installed to manage the module dependencies.
17
18 ## Installing with Composer
19
20 Use Composer to download the `eca` Drupal module and the recommended `BPMN.iO` modeler.
21 The `BPMN.iO` modeler provides a visual interface for creating your automation models.
22
23 ```shell
13 24 composer require drupal/eca drupal/bpmn_io
14 25 ```
15 26
16 Install the ECA and BPMN.iO module and their dependencies via the GUI at `/admin/modules` or with Drush:
27 ## Enabling the modules
17 28
18 ```
29 After downloading the modules, you need to enable them in Drupal.
  • jurgenhaas
    jurgenhaas @jurgenhaas ·
    Owner

    Should we mention that drush is the tool for folks who are familiar with the console? And all others wouldn't have to worry about it?

    And also, as project browser is now a thing, we may also refer to that alternative to install new modules, as it then wouldn't even require composer.

  • Please register or sign in to reply
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on an old version of the diff
    • docs/eca/usage.md
    1 1 ---
    2 2 title: Usage
    3 3 ---
    4 # Usage
    4 # Using the ECA module
    5 5
    6 Actually, ECA is processing all enabled models in the background and there is nothing a user needs to do, when
    7 everything has been set up. In fact, there isn't anything a user could do to prevent ECA from processing all these
    8 models
    6 Once installed and configured, the Events - Conditions - Actions (ECA) module operates automatically in the background.
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on an old version of the diff
    • docs/eca/usage.md
    27 - Executes the appropriate actions when conditions are met
    42 28
    43 - `eca.eca.[MODEL-ID]`: contains all events, conditions and actions that ECA operates upon
    44 - `eca.model.[MODEL-ID]`: contains the proprietary model data of the modeller that has been used to create and edit this
    45 model
    29 ## Disabling the ECA admin UI on production environments
    46 30
    47 In other words, the config entity `eca.eca.[MODEL-ID]` is being used by ECA to operate on the Drupal site. The other one
    48 is not needed for that at any time. That second config entity is only reequired by the modeller, when the model gets
    49 edited. When editing a model with a modeller, ECA will recreate its `eca.eca.[MODEL.ID]` config entity by converting
    50 the modeller data when the model gets saved by the modeller.
    31 ECA doesn't require the UI (`eca_ui`) in order to function.
    32 We recommend that you turn off the UI and the modeler in production environments.
    51 33
    52 !!! danger
    34 For production sites, consider this recommended approach:
    • jurgenhaas
      jurgenhaas @jurgenhaas ·
      Owner

      When I was reading this, knowing that I stated that myself, it now sounds really strong. Almost as if ECA were a dangerous module and people should hide it from users. Maybe that's not positioning it well an I wonder if we could soften that? Maybe something like mentioning that if sites want to hide it like with views ui or fields ui, they could do, but they don't have to.

    • Michael Lenahan changed this line in version 8 of the diff

      changed this line in version 8 of the diff

    • Please register or sign in to reply
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on an old version of the diff
    • docs/eca/usage.md
    40 Each ECA model is a set of 2 config entities, each of which being exported by Drupal's configuration management into
    41 a separate file. The config entities (and files) for a single model are named with the following pattern:
    25 - Listens for events occurring on your Drupal site
    26 - Matches events to conditions defined in your models
    27 - Executes the appropriate actions when conditions are met
    42 28
    43 - `eca.eca.[MODEL-ID]`: contains all events, conditions and actions that ECA operates upon
    44 - `eca.model.[MODEL-ID]`: contains the proprietary model data of the modeller that has been used to create and edit this
    45 model
    29 ## Disabling the ECA admin UI on production environments
    46 30
    47 In other words, the config entity `eca.eca.[MODEL-ID]` is being used by ECA to operate on the Drupal site. The other one
    48 is not needed for that at any time. That second config entity is only reequired by the modeller, when the model gets
    49 edited. When editing a model with a modeller, ECA will recreate its `eca.eca.[MODEL.ID]` config entity by converting
    50 the modeller data when the model gets saved by the modeller.
    31 ECA doesn't require the UI (`eca_ui`) in order to function.
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on an old version of the diff
    • docs/eca/usage.md
    60 had the same modeller available to interpret the proprietary data. More about that below in
    61 [Import and export models](#import-and-export-models).
    41 This setup allows ECA to operate based on your configured models without exposing the model creation interface to users
    42 on the production site.
    62 43
    63 ## Admin UI
    44 This is similar to the approach that Drupal takes for Views and Fields -
    45 the user interfaces for those modules can also be disabled when not required.
    64 46
    65 As mentioned above, to let ECA do its work by processing available ECA models, no UI is required whatsoever. Only if
    66 you need to maintain your ECA models, the ECA UI is required. Very much like Drupal core has implemented this for the
    67 fields and views modules, where the UIs can also be disabled when not required.
    47 ## ECA admin UI is separate from the modeler
    68 48
    69 When the ECA UI is being required, you can enable it separately:
    49 The ECA admin UI does not, by itself, provide you access to the create or edit models.
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on an old version of the diff
    • docs/eca/usage.md
    72 drush en eca_ui
    53 drush pm:enable bpmn_io
    73 54 ```
    74 55
    75 This enables the admin UI which can be found in the admin menu under Administration / Configuration / Workflow / ECA
    76 with the path `/admin/config/workflow/eca`:
    77
    78 ![](/images/screenshots/eca_ui_01.png)
    79
    80 On this ECA admin page you can manage all aspects of ECA: Changing the order of the models by re-arranging them,
    81 importing new models and performing operations on each of the available models. That's all described in the chapters
    82 below.
    56 ## Site performance
    83 57
    84 ??? note "Creating and editing models"
    58 ECA efficiently subscribes to Drupal events with minimal performance impact.
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on the diff
    • docs/eca/usage.md
    80 On this ECA admin page you can manage all aspects of ECA: Changing the order of the models by re-arranging them,
    81 importing new models and performing operations on each of the available models. That's all described in the chapters
    82 below.
    56 ## Site performance
    83 57
    84 ??? note "Creating and editing models"
    58 ECA efficiently subscribes to Drupal events with minimal performance impact.
    59 The module uses cached information to quickly determine whether an event is relevant to any configured models,
    60 avoiding unnecessary processing overhead.
    61 In fact, in our own tests, we have not seen any measurable performance impact, over and above that of the Symfony
    62 event dispatching in Drupal.
    85 63
    86 The ECA admin UI does not provide you access to create new models or to edit existing ones. Those actions are only
    87 available, when at least one modeller is enabled which provides support for integrated editing, like e.g. the
    88 [bpmn.io modeller](/modeller/bpmn/bpmn_io/index.md).
    64 ## ECA model configuration
    • jurgenhaas
      jurgenhaas @jurgenhaas ·
      Owner

      It's perfectly correct what's in this chapter. That's the default and nothing wrong.

      However, in ECA 2.1 we now can optionally omit the eca.model.ID entity as we managed to upstream convert from the eca.eca.ID to the model.

      Not sure if mentioning that is too much detail at this point?

      We've implemented that for at least 2 reasons:

      • there are people who are afraid of the XML data and it was a reason for some not to use ECA
      • others have edited the ECA yml file but then lost those changes when saving the model again in the UI

      In the long term, I wonder if we will completely get rid of the second entity.

    • Please register or sign in to reply
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on the diff
    • docs/eca/usage.md
    89 ![](/images/screenshots/eca_ui_01.png)
    127 90
    128 #### Import and export models
    91 ### Models tab
    129 92
    130 Models can be imported by clicking on the `Import` button in the top right corner. This will open a form where you can
    131 select a file to import. There are actually 2 different file types supported for import:
    93 The `Models` tab allows you to:
    132 94
    133 - an `eca.model.[MODEL-ID].yml` config file, see [ECA model config files](#eca-model-config-files)
    134 - an archive file (e.g. `[MODELLER-TYPE]-[MODEL-ID].tar.gz`) which has been previously exported (see below) or
    135 downloaded from the [Library](/library/index.md)
    95 - Reorder models to change their processing sequence
    96 - Enable or disable models: disabled models are not processed by ECA
    97 - Delete an ECA model entirely from the Drupal site
    98 - Clone an ECA model with a new random model ID
  • jurgenhaas
    jurgenhaas @jurgenhaas started a thread on the diff
    • docs/eca/usage.md
    140 To export a model from your Drupal site, e.g. because you want to use it on a different Drupal site, or you need to
    141 attach it to an issue on drupal.org, select the `Export` operation in the list of models for that model, that you want
    142 to export. This will create an archive with a filename `[MODELLER-TYPE]-[MODEL-ID].tar.gz` which contains the id of
    143 the used modeller and the ID of the model itself.
    102 ### Import tab
    144 103
    145 !!! note
    104 The `Import` tab (`/admin/config/workflow/eca/import`) allow you to import a model from an archive `tar.gz` file.
    105 The archive has the name format `[MODELLER-TYPE]-[MODEL-ID].tar.gz`.
    146 106
    147 It's important to keep that filename as it is part of the validation when later importing that model again.
    107 This could be an archive you have exported previously,
    108 or one of the many examples which you can download from the [ECA Library](/library).
    148 109
    149 The exported archive contains 3 or more files:
    110 ### Settings tab
  • jurgenhaas
    jurgenhaas @jurgenhaas ·
    Owner

    Great work, Michael, as always :-)

    Have some comments, but none of them means that we need to hold back merging this. Whatever you prefer, I'm also happy to merge and publish more often.

  • Michael Lenahan added 2 commits

    added 2 commits

    • 15a14033 - Review changes to usage.md
    • 5501946a - Merge branch 'feature/initial-review' of...

    Compare with previous version

    • Please register or sign in to reply