@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 components in your product

$3

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

ℹ️ Example: Adding Groups memberships to the bus

$3

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

#### Trigger resource

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

Example from Groups:

``ruby
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:

`ruby
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
`

$3

ℹ️ Example: Core automations in Groups

#### Installation

`bash
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

`jsx
import { Automations } from "@planningcenter/core-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):
ℹ️ You can pass in null for the trigger if you only need the Incoming Automations section to render.
- 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

$3

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 s and 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.

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

For more information about theming in Tapestry-React, see .

$3

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.

$3

- 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.