Skip to content

Commit

Permalink
Update docs to v4
Browse files Browse the repository at this point in the history 
Signed-off-by: Sam Poyigi <[email protected]>
  • Loading branch information
@sampoyigi
sampoyigi committed May 9, 2024
1 parent 55737b8 commit 4e78d1b
Show file tree
Hide file tree
Showing 2 changed files with 275 additions and 238 deletions.
294 changes: 275 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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).
Loading

0 comments on commit 4e78d1b

Please sign in to comment.