StandardProcedureAutomations

This module allows you to define "automations" (think IFTTT or Shortcuts but for your Rails app).

Installation

Update your Gemfile

gem "standard_procedure_automations"

Then write a configuration and define your trigger and action classes. Finally, run the automation.

Usage

There are three parts to building an automation.

Triggers

A trigger is an object that, given some parameters as a Hash, responds with a boolean. If the result is falsey, the actions will not run. If the result is truthy, the actions will run.

Each trigger is a Ruby class that takes a single config Hash parameter for initialisation. And has a call method that takes a single Hash parameter and returns a Boolean.

For example (taken from the specification):

class ConfiguredAutomation < Data.define(:config)
  def call(params) = config[:should_fire]
end

Actions

An action is a simple class that, given some parameters as a Hash, will do something and return another Hash.

Each action is, like triggers, a Ruby class that takes a single config Hash parameter for initialisation. And has a call method that takes a single Hash parameter and returns a Hash.

For example (taken from the specification):

class ConfiguredAction < Data.define(:config)
  def call(params) = {config[:key].to_sym => config[:value]}
end

Most automations consiste of sequences of actions, that are executed in order. The first action is called with the incoming parameters. The next action is called with the incoming parameters merged with the results from the first action. The next action is called with the incoming parameters merged with the results from the first and second actions.

Configuration

The configuration is a simple Hash that defines the trigger and actions for an automation. This is done by providing the class name and configuration for each item.

An example (taken from the specification):

config = {
  name: "Sequence of actions",
  class_name: "Automations::TriggerDoesFire",
  configuration: {},
  actions: [
    {class_name: "Automations::AddsFirst", configuration: {}},
    {class_name: "Automations::AddsSecond", configuration: {}}
  ]
}

Calling an automation

Use the Automations module to build your automation from a config. Then call the automation with the relevant parameters.

config = {
  name: "Sequence of actions",
  class_name: "Automations::TriggerDoesFire",
  configuration: {},
  actions: [
    {class_name: "Automations::AddsFirst", configuration: {}},
    {class_name: "Automations::AddsSecond", configuration: {}}
  ]
}
automation = Automations.create(config)
result = automation.call name: "Alice"

If the trigger does not fire, then @result will be an empty Hash, otherwise it will be the combination of the incoming parameters, merged with the outputs of each action that was called. If an action raises an exception, you will need to handle that yourself.

Built-in triggers

There are some built-in triggers available to you, useful for automations that are triggered on a schedule.

These are the DailySchedule, WeeklySchedule, MonthlySchedule and AnnualSchedule.

The simplest way to use these is to have a cron job that triggers a rake no more than once per hour. The rake task loads the automation from the configuration and then calls it, passing a time: Time.now parameter (plus any other parameters you may need). If the current time matches the trigger's configuration it will call the actions.

config= {
  name: "Weekdays at 8am",
  class_name: "Automations::DailySchedule",
  configuration: { days: [1,2,3,4,5], times: [8] },
  actions: [{...}]
}

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/standard_procedure/automations. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.