Display and manage core automations
npm install @planningcenter/core-automationsA package for implementing core automations in a product.
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.
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
Automations are triggered by message bus messages, so make sure you're broadcasting the appropriate messages.
ā¹ļø Example: Adding Groups memberships to the bus
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
#### 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:
`rubyoperation_params
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: { 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
`
ā¹ļø 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"
...
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 automationsblankStateLink
- (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 formatolsonTimeZone
- (string): The org's time zonetwentyFourHourTime
- (boolean): Whether the org wants to see 12 or 24 hour timescurrentPersonCanCreate
- (boolean): Can the user create an automation?currentPersonId
- (number): ID of current userdefaultApp
- (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 objecttrigger
- (object):null
ā¹ļø You can pass in 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 payloaddynamicConditions
- (DefinitionField[]): An array of extra fields that can be used to customize the trigger conditionsevents
- (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 payloaddynamicConditions
- (DefinitionField[]) optional: An array of extra fields that can be used to customize the trigger conditionstriggerParams
- (object[]) optional: An array of objects describing additional parameters which the trigger can use for determining whether to run etc.key
- (string): The parameter keydefaultValue
- (any): What the parameter value defaults toinputType
- ("checkbox"): Currently only "checkbox" is supporteddescription
- (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 createdlabel
- (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 createdpermissionDeniedReason
- (string) optional: Message to display when current person is unable to create an automation
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
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
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.
- 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.
If you'd like to contribute, you can find details for getting started in the contribution guide.