@planningcenter/core-automations

A package for implementing core automations in a product.

How does it work?

Core automations are built on top of Webhooks. Automation definitions are stored in the Webhooks database, and this package of React components creates/reads/updates/deletes them via the Webhooks API. Any message bus event can be registered as a trigger for an automation, and an automation can run any pco-people-list Operation.

Usage

Implementing core automations in a product requires the following:

1. 🚌 Add your event triggers to the message bus
2. 🙋 Tell Webhooks how to parse your event messages
3. 🔐 Build an encrypted parameter to secure the automations requests from your product to Webhooks
4. 🖼️ Install and render the <Automations> components in your product

1. 🚌 Add your event triggers to the message bus

Automations are triggered by message bus messages, so make sure you're broadcasting the appropriate messages.

ℹ️ Example: Adding Groups memberships to the bus

2. 🙋 Tell Webhooks how to parse your event messages

When Webhooks receives the trigger message, it needs to know how to:

1. extract the person_id from the message payload
2. build a URL to the page where the automation components live (for notifications)

You'll need to open a PR into Webhooks to add new products/trigger events.

ℹ️ Example: Teach Webhooks to handle automations triggered by groups events

3. 🔐 Build the encrypted parameters to secure the automations requests from your product to Webhooks

Trigger resource

All requests to the Webhooks Automations APIs must include this encrypted parameter. Webhooks uses this to authorize the requests.

Example from Groups:

module GroupAutomationsHelper
  def encrypted_group_trigger_resource(group)
    trigger_resource = {
      # The resource that owns the automations (e.g. the Group/Form/List)
      trigger_resource: "groups/v2/groups/#{group.id}",
      # The person making the requests
      requested_by_id: Person.current.account_center_id,
      # Used to prevent replaying old messages
      time_of_request: Time.current,
      # Can this person edit these automations?
      updates_permitted: policy(group).edit?
    }

    PCO::URL::Encryption.encrypt(trigger_resource.to_json)
  end
end

ℹ️ Example: encrypted_group_trigger_resource

Incoming automations

If you want to show automations that target this resource as well as ones that originate here, you'll need another parameter that describes how to find such automations.

Example:

def encrypted_group_incoming_automations_param(group)
  operation_params = {
    operation_app_name: "groups",
    # Used to find automations that target our resource (the group, this case).
    # Needs to be a subset of the automation's `operation_params`.
    operation_params: { group_id: group.id },
    requested_by_id: Person.current.account_center_id,
    time_of_request: Time.current
  }

  PCO::URL::Encryption.encrypt(operation_params.to_json)
end

4. 🖼️ Install and render the <Automations> components in your product

ℹ️ Example: Core automations in Groups

Installation

yarn add @planningcenter/core-automations

Peer dependencies: Core automations requires that react, react-dom, and @planningcenter/tapestry-react be installed in your product.

Rendering the Automations components

import { Automations } from "@planningcenter/core-automations"

...

<Automations
  blankStateDescription="Automations supercharge your form..."
  currentOrganization={{
    dateFormat: "%m/%d/%Y",
    olsonTimeZone: "America/Los_Angeles",
    twentyFourHourTime: false,
  }}
  currentPersonCanCreate={true}
  currentPersonId={123456789}
  defaultApp="people"
  incomingAutomationsParam="..."
  theme={theme} // Tapestry-React theme object
  trigger={{
    conditions: { data: { relationships: { form: { data: { id: form.id } } } } },
    events: [{
      description: 'Submits this form',
      name: 'people.v2.events.form_submission.created',
    }],
    resource: "vzfnx3tc87lx1c1d8Ak1clkrwqZfnA294t...",
  }}
/>

Props

• blankStateDescription (string): Text to be displayed when there are no current automations
• blankStateLink (string) optional: A URL for the link to "Learn more", that will display below the blankStateDescription when there are no current automations. It defaults to the link to this zendesk article.
• currentOrganization (object): Date formatting info from the current org:
  • dateFormat (string): The org's desired date format, in Ruby strftime format
  • olsonTimeZone (string): The org's time zone
  • twentyFourHourTime (boolean): Whether the org wants to see 12 or 24 hour times
• currentPersonCanCreate (boolean): Can the user create an automation?
• currentPersonId (number): ID of current user
• defaultApp (string): Which app should be selected as the default target when creating a new automation?
• incomingAutomationsParam (string): The encrypted incoming automations param (from step 3)
• theme (object) optional: Accepts a Tapestry-React theme object
• trigger (object):
  • conditions (object): The specific conditions for triggering this automation: Should be a subset of the message payload
  • dynamicConditions (DefinitionField[]): An array of extra fields that can be used to customize the trigger conditions
  • events (object[]): An array of objects describing the possible trigger events (created/deleted/etc)
    • name (string): The event name (matches the webhooks message routing_key)
    • description (string): Human-readable description of this event (the words after "When a person...", e.g. "Joins this group")
    • conditions (object) optional: The specific conditions for triggering this automation: Should be a subset of the message payload
    • dynamicConditions (DefinitionField[]) optional: An array of extra fields that can be used to customize the trigger conditions
    • triggerParams (object[]) optional: An array of objects describing additional parameters which the trigger can use for determining whether to run etc.
      • key (string): The parameter key
      • defaultValue (any): What the parameter value defaults to
      • inputType ("checkbox"): Currently only "checkbox" is supported
      • description (string): The text which will be shown in the UI for the admin ("Also apply to joint donors?" for instance)
  • resource (string): The encrypted trigger resource param from Step 3 (👆)
• afterCreateOptions (object) optional: Show a custom checkbox to optionally perform an action after the automation is created
  • label (string): Description of the action to perform (e.g. "apply to everyone on this list")
  • onConfirm (function): The function that will perform after the automation is created
• permissionDeniedReason (string) optional: Message to display when current person is unable to create an automation

Theming

Each host app can pass in a Tapestry-React theme file to the theme prop to customize the colors and styles of the component. Although some UI elements will remain consistent across all apps, the colors and styles of <Button>s and <Link>s will be directly affected by the theme oject passed in. If none is passed in, the default Tapestry-React theme will be used.

If your app is already using Tapestry-React, you can simply reuse whatever you normally pass to ThemeProvider. If your app is not currently using Tapestry-React, you can create a simple theme object that defines the primary colors to be used. Although there are plenty of other values that can be defined, the following colors that start with primary* are the most important.

  const theme = {
    colors: {
      primary: "#4076e2",
      primaryLight: "#6590e7",
      primaryLighter: "#adc3f0",
      primaryLightest: ...,
      primaryDark: ...,
      primaryDarker: ...,
      primaryDarkest: ...,
    }
  }

For more information about theming in Tapestry-React, see https://planningcenter.github.io/tapestry-react/theming.

Development

Storybook is installed for documentation and a quick development feedback loop. It runs at people.pco.test:6006 by default so that pco-api session auth works automatically.

Troubleshooting

• If the modals are visually cut off when they are rendered, check to see if any elements higher in the DOM are using the transform property. This property creates a "new local coordinate system" which will affect the positioning of the modal and its overlay.

Contributing

If you'd like to contribute, you can find details for getting started in the contribution guide.