From 4e78d1b3893f4f845cbb431a0834e8628fae965b Mon Sep 17 00:00:00 2001 From: Sam Poyigi <6567634+sampoyigi@users.noreply.github.com> Date: Thu, 9 May 2024 15:28:37 +0100 Subject: [PATCH] Update docs to v4 Signed-off-by: Sam Poyigi <6567634+sampoyigi@users.noreply.github.com> --- README.md | 294 ++++++++++++++++++++++++++++++++++++++++++++++---- docs/index.md | 219 ------------------------------------- 2 files changed, 275 insertions(+), 238 deletions(-) delete mode 100644 docs/index.md diff --git a/README.md b/README.md index d92b7b5..8494a52 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,287 @@ -### Introduction +## Introduction -Automation within TastyIgniter fire when other specific actions have taken place. Rules are run through every time an -order state is changed and triggered if the changes match the conditions defined in the rule. +The TastyIgniter Automation extension allows you to automate certain actions within your TastyIgniter application. These automations are triggered when specific events occur, such as a change in order state. Actions can include sending an email to a customer or sending print jobs to a printer when an order status. -An action is attached to the automation, such as send mail to customer or send print jobs to printer. +## Features -### Documentation +- Event-driven automation system +- Customizable automation actions +- Conditional automation rules +- Background processing using [Laravel Queue](https://laravel.com/docs/queues) +- Global parameters available to all automation rules +- Extendable with custom events, actions, and conditions -Documentation for TastyIgniter Automation extension can be found on -the [TastyIgniter website](https://tastyigniter.com/docs/extensions/automation). +## Installation -### Contributing +You can install the extension via composer using the following command: -Thank you for considering contributing! The contribution guide can be found in -the [TastyIgniter documentation](https://tastyigniter.com/docs/contribution-guide). +```bash +composer require tastyigniter/ti-ext-automation:"^4.0" -W +``` -### Code of Conduct +Run the database migrations to create the required tables: + +```bash +php artisan igniter:up +``` -In order to ensure that the [TastyIgniter community](https://forum.tastyigniter.com) is welcoming to all, please review -and abide by the [Code of Conduct](https://tastyigniter.com/docs/code-of-conduct). +## Automation workflow -### Security Vulnerabilities +The Automation extension follows a specific workflow when an automation is triggered: -Please review [our security policy](https://github.com/tastyigniter/ti-ext-automation/security/policy) on how to report -security vulnerabilities. +1. The extension registers associated actions, conditions, and events using the registerAutomationRules method. +2. When a system event is triggered, the parameters of the event are captured, along with any global parameters. +3. These captured parameters are then attached to a job and placed onto the queue for background processing. +4. The job retrieves all automation rules that match the triggered system event and runs them. +5. The automation conditions are checked to ensure that any required conditions are met. +6. Finally, the automation actions associated with the triggered rules are executed using the captured parameters. -### License +## Usage -TastyIgniter Automation extension is open-sourced software licensed under -the [MIT license](https://github.com/tastyigniter/ti-ext-automation/LICENSE.md). +You can manage automations in the admin panel by navigating to Tools > Automations. + +### Defining events + +An event class is responsible for preparing the parameters passed to the conditions and actions. + +Automation Event classes are typically stored in the `src/AutomationRules/Events` directory of an extension. The Event class is a simple class that extends `Igniter\Automation\Classes\BaseEvent` and defines the `eventDetails` and `makeParamsFromEvent` methods. + +Here is an example of an event class: + +```php +namespace Author\Extension\AutomationRules\Events; + +class CustomerRegisteredEvent extends \Igniter\Automation\Classes\BaseEvent +{ + public function eventDetails(): array + { + return [ + 'name' => 'Registered', + 'description' => 'When a customer registers', + 'group' => 'customer' + ]; + } + + public static function makeParamsFromEvent(array $args, $eventName = null): array + { + return [ + 'user' => array_get($args, 0) + ]; + } +} +``` + +The `eventDetails` method returns information about the event, including the name and description. The `makeParamsFromEvent` method prepares the captured parameters passed to the conditions and actions. + +These are the available options for the `eventDetails` method: + +- `name` - The name of the event. This is displayed in the admin panel. +- `description` - A description of the event. This is displayed in the admin panel. +- `group` - The group to which the event belongs. This is used to group events in the admin panel. + +### Defining actions + +A action class defines the final step in an automation and performs the automation. + +Action classes are typically stored in the `src/AutomationRules/Actions` directory of an extension. The Action class is a simple class that extends `Igniter\Automation\Classes\BaseAction` and defines the `actionDetails`, `defineFormFields`, and `triggerAction` methods. + +```php +namespace Author\Extension\AutomationRules\Actions; + +class SendMailTemplate extends \Igniter\Automation\Classes\BaseAction +{ + public function actionDetails(): array + { + return [ + 'name' => 'Compose a mail message', + 'description' => 'Send a message to a recipient', + ]; + } + + public function defineFormFields(): array + { + return [ + 'fields' => [ + 'template' => [ + 'label' => 'lang:igniter.user::default.label_template', + 'type' => 'select', + ], + 'send_to' => [ + 'label' => 'lang:igniter.user::default.label_send_to', + 'type' => 'select', + ], + ], + ]; + } + + public function triggerAction($params) + { + $email = $this->model->send_to; + $template = $this->model->template; + + Mail::sendTo($email, $template, $params); + } +} +``` + +The `actionDetails` method returns information about the action, including the name and description. The `defineFormFields` method defines the form fields required for the action, see [TastyIgniter's available form field types](https://tastyigniter.com/docs/advanced/forms#available-field-types). You can access fields defined in the `defineFormFields` method using `$this->model->field_name`. The `triggerAction` method performs the automation action. + +These are the available options for the `actionDetails` method: + +- `name` - The name of the action. This is displayed in the admin panel. +- `description` - A description of the action. This is displayed in the admin panel. + +### Defining conditions + +A condition class is used to check whether a condition is true or false. + +Automation condition classes are typically stored in the extensions's `src/AutomationRules/Conditions` directory. The Condition class is a simple class that extends `Igniter\Automation\Classes\BaseCondition` and defines the `conditionDetails` and `isTrue` methods. + +```php +namespace Author\Extension\AutomationRules\Conditions; + +class MyCondition extends \Igniter\Automation\Classes\BaseCondition +{ + public function conditionDetails(): array + { + return [ + 'name' => 'Condition', + 'description' => 'My Condition is checked', + ]; + } + + public function isTrue(&$params): bool + { + return true; + } +} +``` + +The `conditionDetails` method returns information about the condition, including the name and description. The `isTrue` method checks whether the condition is true for the specified parameters. + +These are the available options for the `conditionDetails` method: + +- `name` - The name of the condition. This is displayed in the admin panel. +- `description` - A description of the condition. This is displayed in the admin panel. + +### Defining model attribute conditions + +Just like the condition class above, a model attribute condition class applies conditions to sets of model attributes. + +Automation model attribute condition classes are typically stored in the extensions's `src/AutomationRules/Conditions` directory. The model attribute condition class is a simple class that extends `Igniter\Automation\Classes\BaseCondition` and defines the `conditionDetails`, `defineModelAttributes`, and `isTrue` methods. + +```php +namespace Author\Extension\AutomationRules\Conditions; + +class CustomerAttribute extends \Igniter\Automation\Classes\BaseCondition +{ + public function conditionDetails(): array + { + return [ + 'name' => 'Customer attribute', + ]; + } + + public function defineModelAttributes(): array + { + return [ + 'first_name' => [ + 'label' => 'First Name', + ], + 'last_name' => [ + 'label' => 'Last Name', + ], + ]; + } + + public function isTrue(&$params): bool + { + return true; + } +} +``` + +The `defineModelAttributes` method defines the model attributes and labels required for the condition. + +### Registering automation events, actions, and conditions + +After creating the [event](#creating-an-event-class), [action](#creating-an-action-class) and [condition](#creating-a-condition-class) classes, you can make them available in the admin panel by registering them in the `registerAutomationRules` method of the extension class. + +The `registerAutomationRules` method should return an array with the following keys: + +- `events` - an array of event class that triggers an automation. +- `actions` - an array of action class that performs a task when an automation is triggered. +- `conditions` - an array of condition class that checks whether a condition is true or false before an action is performed. +- `presets` - predefined automation rules available in the admin panel. + +```php +public function registerAutomationRules(): array +{ + return [ + 'events' => [ + \Igniter\User\AutomationRules\Events\CustomerRegistered::class, + ], + 'actions' => [ + \Igniter\User\AutomationRules\Actions\SendMailTemplate::class, + ], + 'conditions' => [ + \Igniter\User\AutomationRules\Conditions\CustomerAttribute::class + ], + 'presets' => [ + 'registration_email' => [ + 'name' => 'Send customer registration email', + 'event' => \Igniter\User\AutomationRules\Events\CustomerRegistered::class, + 'actions' => [ + \Igniter\User\AutomationRules\Actions\SendMailTemplate::class => [ + 'template' => 'igniter.user::mail.registration_email' + ], + ] + ] + ], + ]; +} +``` + +### Registering global parameters + +Global parameters are available to all automation rules. You can register global parameters in the `boot` method of the extension class. + +```php +use Igniter\User\Facades\Auth; +use Igniter\Automation\Classes\EventManager; + +public function boot() +{ + resolve(EventManager::class)->registerGlobalParams([ + 'customer' => Auth::customer() + ]); +} +``` + +### Permissions + +The Automation extension registers the following permissions: + +- `Igniter.Automation.Manage`: Control who can manage automations in the admin area. + +For more on restricting access to the admin area, see the [TastyIgniter Permissions](https://tastyigniter.com/docs/extend/permissions) documentation. + +## Changelog + +Please see [CHANGELOG](https://github.com/tastyigniter/ti-ext-automation/blob/master/CHANGELOG.md) for more information on what has changed recently. + +## Reporting issues + +If you find a bug in this extension, please report it using the [Issue Tracker](https://github.com/tastyigniter/ti-ext-automation/issues) on GitHub. + +## Contributing + +Contributions are welcome! Please read [TastyIgniter's contributing guide](https://tastyigniter.com/docs/contribution-guide). + +## Security vulnerabilities + +For reporting security vulnerabilities, please see our [our security policy](https://github.com/tastyigniter/ti-ext-automation/security/policy). + +## License + +TastyIgniter Automation extension is open-source software licensed under the [MIT license](https://github.com/tastyigniter/ti-ext-automation/blob/master/LICENSE.md). diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 3c333e2..0000000 --- a/docs/index.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: "Automation Extension" -section: "extensions" -sortOrder: 20 ---- - -## Introduction - -Automation within TastyIgniter fire when other specific actions have taken place. Rules are run through every time an -order state is changed and triggered if the changes match the conditions defined in the rule. - -An action is attached to the automation, such as send mail to customer or send print jobs to printer. - -## Installation - -To install this extension, click on the **Add to Site** button on the TastyIgniter marketplace item page or search -for **Igniter.Automation** in **Admin System > Updates > Browse Extensions** - -## Admin Panel - -Automations are managed in the admin panel by navigating to **Tools > Automations**. - -## Automation workflow - -When an automation is triggered, it uses the following workflow: - -- Extension registers associated actions, conditions and events using `registerAutomationRules` -- When a system event is fired `Event::fire`, the parameters of the event are captured, along with any global parameters -- A command is pushed on the queue to process the automation `Queue::push` -- The command finds all automation rules using the event class and triggers them -- The automation conditions are checked and only proceed if met -- The automation actions are triggered - -## Usage - -**Example of Registering Automation Rules** - -The `presets` definition specifies automation rules defined by the system. - -``` -public function registerAutomationRules() -{ - return [ - 'events' => [ - \Igniter\User\AutomationRules\Events\CustomerRegistered::class, - ], - 'actions' => [ - \Igniter\User\AutomationRules\Actions\SendMailTemplate::class, - ], - 'conditions' => [ - \Igniter\User\AutomationRules\Conditions\CustomerAttribute::class - ], - 'presets' => [ - 'registration_email' => [ - 'name' => 'Send customer registration email', - 'event' => \Igniter\User\AutomationRules\Events\CustomerRegistered::class, - 'actions' => [ - \Igniter\User\AutomationRules\Actions\SendMailTemplate::class => [ - 'template' => 'igniter.user::mail.registration_email' - ], - ] - ] - ], - ]; -} -``` - -**Example of Registering Global Parameters** -These parameters are available globally to all automation rules. - -``` -resolve(\Igniter\Automation\Classes\EventManager::class)->registerCallback(function($manager) { - $manager->registerGlobalParams([ - 'customer' => Auth::customer() - ]); -}); -``` - -**Example of an Event Class** - -An event class is responsible for preparing the parameters passed to the conditions and actions. - -``` -class CustomerRegisteredEvent extends \Igniter\Automation\Classes\BaseEvent -{ - /** - * Returns information about this event, including name and description. - */ - public function eventDetails() - { - return [ - 'name' => 'Registered', - 'description' => 'When a customer registers', - 'group' => 'customer' - ]; - } - - public static function makeParamsFromEvent(array $args, $eventName = null) - { - return [ - 'user' => array_get($args, 0) - ]; - } -} -``` - -**Example of an Action Class** - -Action classes define the final step in an automation and perform the automation itself. - -``` -class SendMailTemplate extends \Igniter\Automation\Classes\BaseAction -{ - /** - * Returns information about this action, including name and description. - */ - public function actionDetails() - { - return [ - 'name' => 'Compose a mail message', - 'description' => 'Send a message to a recipient', - ]; - } - - /** - * Field configuration for the action. - */ - public function defineFormFields() - { - return [ - 'fields' => [], - ]; - } - - /** - * Triggers this action. - * @param array $params - * @return void - */ - public function triggerAction($params) - { - $email = 'test@email.tld'; - $template = $this->model->template; - - Mail::sendTo($email, $template, $params); - } -} -``` - -**Example of a Condition Class** - -A condition class must declare an `isTrue` method for evaluating whether the condition is true or not. - -``` -class MyCondition extends \Igniter\Automation\Classes\BaseCondition -{ - /** - * Returns information about this condition, including name and description. - */ - public function conditionDetails() - { - return [ - 'name' => 'Condition', - 'description' => 'My Condition is checked', - ]; - } - - /** - * Checks whether the condition is TRUE for specified parameters - * @param array $params - * @return bool - */ - public function isTrue(&$params) - { - return true; - } -} -``` - -**Example of a Model Attribute Condition Class** - -A condition class applies conditions to sets of model attributes. - -``` -class CustomerAttribute extends \Igniter\Automation\Classes\BaseCondition -{ - /** - * Returns information about this condition, including name and description. - */ - public function conditionDetails() - { - return [ - 'name' => 'Customer attribute', - ]; - } - - public function defineModelAttributes() - { - return [ - 'first_name' => [ - 'label' => 'First Name', - ], - 'last_name' => [ - 'label' => 'Last Name', - ], - ]; - } - - /** - * Checks whether the condition is TRUE for specified parameters - * @param array $params - * @return bool - */ - public function isTrue(&$params) - { - return true; - } -} -```