@planningcenter/core-automations 0.3.0-rc.2 → 0.3.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Changed
+
+- Change sizing of `Select`s in the `NewAutomation` form
+
+## [0.3.0] - 2023-03-29
+
+### Added
+
+- Take in a `afterCreateOptions` prop. This `afterCreateOptions` prop will contain a `label` and a `onConfirm` callback function to be executed after the automation is created.
+- Support multiple trigger events (e.g. "when person [joins|leaves] this group")
+- Added implementation guide to the README
+
+### Changed
+
+- Update `border-radius` of modals to match newest design spec
+- Migrated components to Typescript
+
+## [0.2.0] - 2023-03-21
+
+### Added
+
+- Take in a `currentOrganization` prop instead of reading from `window.currentOrganization`
+
+### Changed
+
+- Use `currentOrganization` prop for date formatting
+- Use outline `Badge` variant in history table
+
+### Fixed
+
+- Build errors: specify `jsxFragment` for microbundle when building (#15)
+- Move function definition above callsite (#16)
+
+## [0.1.0] - 2023-03-14
+
+### Added
+
+- Set up initial repo with components extracted from People's original implementation
+- Set up basic theme that includes necessary icons along with host app styles
+- Add basic usage information to README
+
+[0.1.0]: https://github.com/planningcenter/core-automations/releases/tag/v0.1.0
+[0.2.0]: https://github.com/planningcenter/core-automations/releases/tag/v0.2.0
+[0.3.0]: https://github.com/planningcenter/core-automations/releases/tag/v0.3.0

package/README.md

@@ -2,15 +2,75 @@
 
 A package for implementing core automations in a product.
 
+## How does it work?
+
+Core automations are built on top of [Webhooks](https://github.com/planningcenter/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](https://github.com/planningcenter/pco-message-bus) event can be registered as a trigger for an automation, and an automation can run any `pco-people-list` [Operation](https://github.com/planningcenter/pco-people-lists/blob/main/README_OPERATIONS.md).
+
 ## Usage
 
-### Installation
+Implementing core automations in a product requires the following:
+
+1. 🚌 Add your event triggers to the message bus
+2. 🙋 Tell [Webhooks](https://github.com/planningcenter/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](https://github.com/planningcenter/pco-message-bus#broadcaster) the appropriate messages.
+
+ℹ️ Example: [Adding Groups memberships to the bus](https://github.com/planningcenter/groups/pull/4951)
+
+### 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](https://github.com/planningcenter/webhooks/pull/368)
+
+### 3. 🔐 Build an encrypted parameter 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:
+
+```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`](https://github.com/planningcenter/groups/pull/4986/commits/c4e6fe06db11ed9a7759e19fabfad3cc678151ad)
+
+### 4. 🖼️ Install and render the `<Automations>` components in your product
+
+ℹ️ Example: [Core automations in Groups](https://github.com/planningcenter/groups/pull/4986)
+
+#### Installation
 
 ```bash
 yarn add @planningcenter/core-automations
 ```
 
-### Displaying Core Automations
+#### Rendering the Automations components
 
 ```jsx
 import { Automations } from "@planningcenter/core-automations"
@@ -42,24 +102,23 @@ import { Automations } from "@planningcenter/core-automations"
 #### Props
 
 - `blankStateDescription` (string): Text to be displayed when there are no current automations
+- `currentOrganization` (object): Date formatting info from the current org:
+  - `dateFormat` (string): The org's desired date format, in Ruby `strftime` [format](https://apidock.com/ruby/DateTime/strftime)
+  - `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
-- `currentOrganization` (object): Date formatting info from the current org:
-    - `dateFormat` (string): The org's desired date format, in Ruby `strftime` [format](https://apidock.com/ruby/DateTime/strftime)
-    - `olsonTimeZone` (string): The org's time zone
-    - `twentyFourHourTime` (boolean): Whether the org wants to see 12 or 24 hour times
-  }}
-- `defaultApp` (string): Which app should be selected by default?
+- `defaultApp` (string): Which app should be selected as the default target when creating a new automation?
 - `theme` (object) optional: Accepts a [Tapestry-React theme object](https://planningcenter.github.io/tapestry-react/theming)
 - `trigger` (object):
-  - `resource` (string): An encrypted trigger resource
-  - `conditions` (object): The specific conditions for triggering this automation
-  - `events` (array[object]): An array of objects describing the possible trigger events (created/deleted/etc)
+  - `conditions` (object): The specific conditions for triggering this automation: Should be a subset of the message payload
+  - `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")
-- `afterCreateOptions` (object) optional: Options for performing an action after the automation is created:
-    - `label` (string): Description of the action to perform
-    - `onConfirm` (function): The function that will perform after the automation is created
+  - `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
 
 ### Theming
 
@@ -83,7 +142,6 @@ If your app is already using `Tapestry-React`, you can simply reuse whatever you
 
 For more information about theming in Tapestry-React, see <https://planningcenter.github.io/tapestry-react/theming>.
 
-
 ## Contributing
 
 If you'd like to contribute, you can find details for getting started in the [contribution guide](/CONTRIBUTING.md).