Commands

Commands are the expected way to customize your Steps beyond the standard CRUD actions. Commands are referenced from your program definitions and are expected to be defined in the commands directory of your program.

Simple Example

# A simple but common type of Command
# this would live at app/programs/customers/commands/greet.rb

module Customers
  module Commands
    class Greet < Shared::Commands::Base
      def perform
        # default_upsert is what would happen when saving a step, but
        # obviously you can validate or whatever else here
        default_upsert(controller)

        # ... your business logic can happen here ...

        # render app/programs/customers/views/greetings/show.html.erb

        render "greetings/show", layout: false, locals: {
          workflow: parent # parent here represents a Workflow Step
        }
      end
    end
  end
end

Facts about Commands

Commands must implement a perform method.
They're expected to be referenced by a Field with a kind command and they should include the name of the program they belong to as well as the command name, for example:
```
# in a Blueprint definition
fields: [
  {
    name: "Send to CRM",
    kind: "command",
    command: "customers/send_to_crm" # fully qualified name
  },
  # ...other fields
]  
```
This allows programs to call commands from other programs.
Commands can be invoked with a PUT or PATCH to the commands controller Core::Controllers::CommandsController e.g. you'd send a PUT to /commands/customers/send_to_crm

Commands can configure a static payload object they define in a Blueprint


fields: [{
  name: "Send to CRM",
  kind: "command",
  command: "customers/send_to_crm",
  payload: {
    source: "web",
    lang: "es-ES"
  }
}]

that will get submitted on invocation from the UI.

By convention the whole Step payload is submitted with every command invocation. That way the command itself has access to pending Step changes as they are in the UI.
When commands are invoked, they are initialized with a single instance of a Rails controller. If they're invoked outside of a Rails ActionDispatch context, like in a task or background job, then they can be called with a controller-like context object like Core::FakeController.
Commands having access to a Rails controller by default makes it incredibly easy to create custom logic for your Steps while still having access to methods like render.
Background commands can be invoked as an after save hook, by defining an after_save key on the root of a Blueprint, e.g. after_save: "Customers::AddToCrmJob"
Rhizome will insert a Save button for each Step automatically, but it's fairly common to want to hide the default submit button and hijack it with your own command. To hide the default submit, include it in your fields and make it explicitly hidden:
```
fields: [
  # ... other fields ...
  {name: "Submit", kind: "meta", hidden: true}
}] 
```