A 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:
- 🚌 Add your event triggers to the message bus
- 🙋 Tell Webhooks how to parse your event messages
- 🔐 Build an encrypted parameter to secure the automations requests from your product to Webhooks
- 🖼️ Install and render the
<Automations>
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:
- extract the
person_id
from the message payload - 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
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
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
ℹ️ Example: Core automations in Groups
yarn add @planningcenter/core-automations
Peer dependencies: Core automations requires that react
, react-dom
, and @planningcenter/tapestry-react
be installed in your product.
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...",
}}
/>
-
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 Rubystrftime
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 messagerouting_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
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.
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.