Documentation refresh for Workflow connectors

- add directions for creating new Power Automate workflow connectors - heavily emphasize deprecation of legacy MessageCard format and O365 connectors - update Supported Release section to share plans for current v2 series and upcoming v3 series refs GH-262
atc0005 · Jul 24, 2024 · 63d50cc · 63d50cc
1 parent 31c27ee
commit 63d50cc
Showing 1 changed file with 210 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -21,9 +21,17 @@ A package to send messages to a Microsoft Teams channel.
 - [Changelog](#changelog)
 - [Usage](#usage)
   - [Add this project as a dependency](#add-this-project-as-a-dependency)
-  - [Webhook URLs](#webhook-urls)
-    - [Expected format](#expected-format)
-    - [How to create a webhook URL (Connector)](#how-to-create-a-webhook-url-connector)
+  - [Setup a connection to Microsoft Teams](#setup-a-connection-to-microsoft-teams)
+    - [Overview](#overview-1)
+    - [Workflow connectors](#workflow-connectors)
+      - [Workflow webhook URL format](#workflow-webhook-url-format)
+      - [How to create a Workflow connector webhook URL](#how-to-create-a-workflow-connector-webhook-url)
+        - [Using Teams client Workflows context option](#using-teams-client-workflows-context-option)
+        - [Using Teams client app](#using-teams-client-app)
+        - [Using Power Automate web UI](#using-power-automate-web-ui)
+    - [O365 connectors](#o365-connectors)
+      - [O365 webhook URL format](#o365-webhook-url-format)
+      - [How to create an O365 connector webhook URL](#how-to-create-an-o365-connector-webhook-url)
   - [Examples](#examples)
     - [Basic](#basic)
     - [Specify proxy server](#specify-proxy-server)
@@ -46,12 +54,14 @@ inclusion into the project.
 ## Overview
 
 The `goteamsnotify` package (aka, `go-teams-notify`) allows sending messages
-to a Microsoft Teams channel. These messages can be composed of legacy
+to a Microsoft Teams channel. These messages can be composed of
+[🚫 deprecated][o365-connector-retirement-announcement] legacy
 [`MessageCard`][msgcard-ref] or [`Adaptive Card`][adaptivecard-ref] card
 formats.
 
 Simple messages can be created by specifying only a title and a text body.
-More complex messages may be composed of multiple sections (`MessageCard`) or
+More complex messages may be composed of multiple sections ([🚫
+deprecated][o365-connector-retirement-announcement] `MessageCard`) or
 containers (`Adaptive Card`), key/value pairs (aka, `Facts`) and externally
 hosted images. See the [Features](#features) list for more information.
 
@@ -64,12 +74,13 @@ Microsoft Teams.
 - Submit simple or complex messages to Microsoft Teams
   - simple messages consist of only a title and a text body (one or more
     strings)
-  - complex messages may consist of multiple sections (`MessageCard`),
+  - complex messages may consist of multiple sections ([🚫
+    deprecated][o365-connector-retirement-announcement] `MessageCard`),
     containers (`Adaptive Card`) key/value pairs (aka, `Facts`) and externally
     hosted images
 - Support for Actions, allowing users to take quick actions within Microsoft
   Teams
-  - [`MessageCard` `Actions`][msgcard-ref-actions]
+  - [🚫 deprecated][o365-connector-retirement-announcement] [`MessageCard` `Actions`][msgcard-ref-actions]
   - [`Adaptive Card` `Actions`][adaptivecard-ref-actions]
 - Support for [user mentions][adaptivecard-user-mentions] (`Adaptive
   Card` format)
@@ -78,7 +89,8 @@ Microsoft Teams.
     patterns
   - option to disable validation entirely
   - option to use custom validation patterns
-- Configurable validation of `MessageCard` type
+- Configurable validation of [🚫
+  deprecated][o365-connector-retirement-announcement] `MessageCard` type
   - default assertion that bare-minimum required fields are present
   - support for providing a custom validation function to override default
     validation behavior
@@ -96,6 +108,7 @@ In short:
 - The upstream project is no longer being actively developed or maintained.
 - This fork is now a standalone project, accepting contributions, bug reports
   and feature requests.
+  - see [Supported Releases](#supported-releases) for details
 - Others have also taken an interest in [maintaining their own
   forks](https://github.com/atc0005/go-teams-notify/network/members) of the
   original project. See those forks for other ideas/changes that you may find
@@ -107,18 +120,41 @@ For more details, see the
 
 ## Supported Releases
 
-| Series   | Example          | Status              |
-| -------- | ---------------- | ------------------- |
-| `v1.x.x` | `v1.3.1`         | Not Supported (EOL) |
-| `v2.x.x` | `v2.6.0`         | Supported           |
-| `v3.x.x` | `v3.0.0-alpha.1` | TBD                 |
-
-The current plan is to continue extending the v2 branch with new functionality
-while retaining backwards compatibility. Any breakage in compatibility for the
-v2 series is considered a bug (please report it).
-
-Long-term, the goal is to learn from missteps made in current releases and
-correct as many as possible for a future v3 series.
+| Series   | Example          | Status                                       |
+| -------- | ---------------- | -------------------------------------------- |
+| `v1.x.x` | `v1.3.1`         | Not Supported (EOL)                          |
+| `v2.x.x` | `v2.6.0`         | Supported (until approximately October 2024) |
+| `v3.x.x` | `v3.0.0`         | Planning (tentative October 2024)            |
+| `v4.x.x` | `v4.0.0-alpha.1` | TBD                                          |
+
+The current plan (now until ~ October 2024):
+
+- continue supporting the v2 branch with bugfixes and minor changes
+- update the v2 branch with support for Power Automate workflow URLs
+- refresh documentation to cover O365 connectors and Power Automate workflow
+  connectors
+
+Early October 2024:
+
+- Microsoft [drops support for O365
+  connectors][o365-connector-retirement-announcement] on 2024-10-01
+- we release a v3 branch
+  - drop support for the [🚫
+deprecated][o365-connector-retirement-announcement] O365 connectors
+  - drop support for the [🚫
+deprecated][o365-connector-retirement-announcement] `MessageCard`) format
+- we drop support for the v2 branch
+  - the focus would be on maintaining the v3 branch with bugfixes and minor
+    changes
+
+> [!NOTE]
+>
+> While the plan for the upcoming v3 series includes dropping support for the
+[🚫 deprecated][o365-connector-retirement-announcement] `MessageCard` format
+and O365 connectors, the focus would not be on refactoring the overall code
+structure; many of the rough edges currently present in the API would remain
+in the v3 series and await a more focused cleanup effort made in preparation
+for a future v4 series.
 
 ## Changelog
 
@@ -134,20 +170,130 @@ official release is also provided for further review.
 
 See the [Examples](#examples) section for more details.
 
-### Webhook URLs
-
-#### Expected format
-
-Valid webhook URLs for Microsoft Teams use one of several (confirmed) FQDNs
-patterns:
+### Setup a connection to Microsoft Teams
+
+#### Overview
+
+> [!WARNING]
+>
+> Microsoft announced July 3rd, 2024 that Office 365 (O365) connectors within
+Microsoft Teams would be [retired in 3
+months][o365-connector-retirement-announcement] and replaced by Power Automate
+workflows (or just "Workflows" for short).
+
+Quoting from the microsoft365dev blog:
+
+> We will gradually roll out this change in waves:
+>
+> - Wave 1 - effective August 15th, 2024: All new Connector creation will be
+>   blocked within all clouds
+> - Wave 2 - effective October 1st, 2024: All connectors within all clouds
+>   will stop working
+
+As noted, Existing O365 connector webhook URLs *should* continue to work until
+2024-10-01.
+
+#### Workflow connectors
+
+##### Workflow webhook URL format
+
+Valid Power Automate Workflow URLs used to submit messages to Microsoft Teams
+use this format:
+
+- `https://*.logic.azure.com:443/workflows/GUID_HERE/triggers/manual/paths/invoke?api-version=YYYY-MM-DD&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=SIGNATURE_HERE`
+
+Example URL from the LinkedIn [Bring Microsoft Teams incoming webhook security to
+the next level with Azure Logic App][linkedin-teams-webhook-security-article]
+article:
+
+- `https://webhook-jenkins.azure-api.net/manual/paths/invoke?api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=f2QjZY50uoRnX6PIpyPT3xk`
+
+##### How to create a Workflow connector webhook URL
+
+> [!TIP]
+>
+> Use a dedicated "service" account not tied to a specific team member to help
+ensure that the Workflow connector is long lived.
+
+The [initial O365 retirement blog
+post][o365-connector-retirement-announcement] provides a list of templates
+which guide you through the process of creating a Power Automate Workflow
+webhook URL.
+
+###### Using Teams client Workflows context option
+
+1. Navigate to a channel or chat
+1. Select the ellipsis on the channel or chat
+1. Select `Workflows`
+1. Type `when a webhook request`
+1. Select the appropriate template
+   - `Post to a channel when a webhook request is received`
+   - `Post to a chat when a webhook request is received`
+1. Verify that `Microsoft Teams` is successfully enabled
+1. Select `Next`
+1. Select an appropriate value from the `Microsoft Teams Team` drop-down list.
+1. Select an appropriate `Microsoft Teams Channel` drop-down list.
+1. Select `Create flow`
+1. Copy the new workflow URL
+1. Select `Done`
+
+###### Using Teams client app
+
+1. Open `Workflows` application in teams
+1. Select `Create` across the top of the UI
+1. Choose `Notifications` at the left
+1. Select `Post to a channel when a webhook request is received`
+1. Verify that `Microsoft Teams` is successfully enabled
+1. Select `Next`
+1. Select an appropriate value from the `Microsoft Teams Team` drop-down list.
+1. Select an appropriate `Microsoft Teams Channel` drop-down list.
+1. Select `Create flow`
+1. Copy the new workflow URL
+1. Select `Done`
+
+###### Using Power Automate web UI
+
+[This][workflow-channel-post-from-webhook-request] template walks you through
+the steps of creating a new Workflow using the
+<https://make.powerautomate.com/> web UI:
+
+1. Select or create a new connection (e.g., <user@example.com>) to Microsoft
+   Teams
+1. Select `Create`
+1. Select an appropriate value from the `Microsoft Teams Team` drop-down list.
+1. Select an appropriate `Microsoft Teams Channel` drop-down list.
+1. Select `Create`
+1. If prompted, read the info message (e.g., "Your flow is ready to go") and
+   dismiss it.
+1. Select `Edit` from the menu across the top
+   - alternatively, select `My flows` from the side menu, then select `Edit`
+     from the "More commands" ellipsis
+1. Select `When a Teams webhook request is received` (e.g., left click)
+1. Copy the `HTTP POST URL` value
+   - this is your *private* custom Workflow connector URL
+   - by default anyone can `POST` a request to this Workflow connector URL
+     - while this access setting can be changed it will prevent this library
+       from being used to submit webhook requests
+
+#### O365 connectors
+
+##### O365 webhook URL format
+
+> [!WARNING]
+>
+> O365 connector webhook URLs are deprecated and [scheduled to be
+retired][o365-connector-retirement-announcement] on 2024-10-01.
+
+Valid (***deprecated***) O365 webhook URLs for Microsoft Teams use one of several
+(confirmed) FQDNs patterns:
 
 - `outlook.office.com`
 - `outlook.office365.com`
 - `*.webhook.office.com`
   - e.g., `example.webhook.office.com`
 
-Using a webhook URL with any of these FQDN patterns appears to give identical
-results.
+Using an O365 webhook URL with any of these FQDN patterns appears to give
+identical results.
 
 Here are complete, equivalent example webhook URLs from Microsoft's
 documentation using the FQDNs above:
@@ -161,7 +307,12 @@ All of these patterns when provided to this library should pass the default
 validation applied. See the example further down for the option of disabling
 webhook URL validation entirely.
 
-#### How to create a webhook URL (Connector)
+##### How to create an O365 connector webhook URL
+
+> [!WARNING]
+>
+> O365 connector webhook URLs are deprecated and [scheduled to be
+retired][o365-connector-retirement-announcement] on 2024-10-01.
 
 1. Open Microsoft Teams
 1. Navigate to the channel where you wish to receive incoming messages from
@@ -191,7 +342,7 @@ This is an example of a simple client application which uses this library.
 
 - `Adaptive Card`
   - File: [basic](./examples/adaptivecard/basic/main.go)
-- `MessageCard`
+- [🚫 deprecated][o365-connector-retirement-announcement] `MessageCard`
   - File: [basic](./examples/messagecard/basic/main.go)
 
 #### Specify proxy server
@@ -201,13 +352,14 @@ route a generated message through a specified proxy server.
 
 - `Adaptive Card`
   - File: [basic](./examples/adaptivecard/proxy/main.go)
-- `MessageCard`
+- [🚫 deprecated][o365-connector-retirement-announcement] `MessageCard`
   - File: [basic](./examples/messagecard/proxy/main.go)
 
 #### User Mention
 
 These examples illustrates the use of one or more user mentions. This feature
-is not available in the legacy `MessageCard` card format.
+is not available in the legacy [🚫
+deprecated][o365-connector-retirement-announcement] `MessageCard` card format.
 
 - File: [user-mention-single](./examples/adaptivecard/user-mention-single/main.go)
 - File: [user-mention-multiple](./examples/adaptivecard/user-mention-multiple/main.go)
@@ -217,7 +369,8 @@ is not available in the legacy `MessageCard` card format.
 #### Tables
 
 These examples illustrates the use of a [`Table`][adaptivecard-table]. This
-feature is not available in the legacy `MessageCard` card format.
+feature is not available in the legacy [🚫
+deprecated][o365-connector-retirement-announcement] `MessageCard` card format.
 
 - File: [table-manually-created](./examples/adaptivecard/table-manually-created/main.go)
 - File: [table-unordered-grid](./examples/adaptivecard/table-unordered-grid/main.go)
@@ -229,18 +382,19 @@ This example illustrates setting a custom user agent.
 
 - `Adaptive Card`
   - File: [custom-user-agent](./examples/adaptivecard/custom-user-agent/main.go)
-- `MessageCard`
+- [🚫 deprecated][o365-connector-retirement-announcement] `MessageCard`
   - File: [custom-user-agent](./examples/messagecard/custom-user-agent/main.go)
 
 #### Add an Action
 
-This example illustrates adding an [`OpenUri`][msgcard-ref-actions]
-(`MessageCard`) or [`OpenUrl`][adaptivecard-ref-actions] Action. When used,
-this action triggers opening a URL in a separate browser or application.
+This example illustrates adding an [`OpenUri`][msgcard-ref-actions] ([🚫
+deprecated][o365-connector-retirement-announcement] `MessageCard`) or
+[`OpenUrl`][adaptivecard-ref-actions] Action. When used, this action triggers
+opening a URL in a separate browser or application.
 
 - `Adaptive Card`
   - File: [actions](./examples/adaptivecard/actions/main.go)
-- `MessageCard`
+- [🚫 deprecated][o365-connector-retirement-announcement] `MessageCard`
   - File: [actions](./examples/messagecard/actions/main.go)
 
 #### Toggle visibility
@@ -262,7 +416,7 @@ testing purposes).
 
 - `Adaptive Card`
   - File: [disable-validation](./examples/adaptivecard/disable-validation/main.go)
-- `MessageCard`
+- [🚫 deprecated][o365-connector-retirement-announcement] `MessageCard`
   - File: [disable-validation](./examples/messagecard/disable-validation/main.go)
 
 #### Enable custom patterns' validation
@@ -272,7 +426,7 @@ URLs.
 
 - `Adaptive Card`
   - File: [custom-validation](./examples/adaptivecard/custom-validation/main.go)
-- `MessageCard`
+- [🚫 deprecated][o365-connector-retirement-announcement] `MessageCard`
   - File: [custom-validation](./examples/messagecard/custom-validation/main.go)
 
 ## Used by
@@ -288,15 +442,27 @@ using either this library or the original project.
 - [Original project](https://github.com/dasrick/go-teams-notify)
 - [Forks of original project](https://github.com/atc0005/go-teams-notify/network/members)
 
+<!--
+  TODO: Refresh/replace these ref links after 2024-10-01 when O365 connectors are scheduled to be retired.
+-->
 - Microsoft Teams
-  - MS Teams - adaptive cards
+  - Adaptive Cards
   ([de-de](https://docs.microsoft.com/de-de/outlook/actionable-messages/adaptive-card),
   [en-us](https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card))
-  - MS Teams - send via connectors
+  - O365 connectors
   ([de-de](https://docs.microsoft.com/de-de/outlook/actionable-messages/send-via-connectors),
   [en-us](https://docs.microsoft.com/en-us/outlook/actionable-messages/send-via-connectors))
   - [adaptivecards.io](https://adaptivecards.io/designer)
   - [Legacy actionable message card reference][msgcard-ref]
+  - Workflow connectors
+    - [Creating a workflow from a chat in Teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-channel-in-teams-242eb8f2-f328-45be-b81f-9817b51a5f0e)
+    - [Creating a workflow from a channel in Teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-chat-in-teams-e3b51c4f-49de-40aa-a6e7-bcff96b99edc)
+
+<!-- Footnotes here  -->
+
+[o365-connector-retirement-announcement]: <https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/> "Retirement of Office 365 connectors within Microsoft Teams"
+[workflow-channel-post-from-webhook-request]: <https://make.preview.powerautomate.com/galleries/public/templates/d271a6f01c2545a28348d8f2cddf4c8f/post-to-a-channel-when-a-webhook-request-is-received> "Post to a channel when a webhook request is received"
+[linkedin-teams-webhook-security-article]: <https://www.linkedin.com/pulse/bring-microsoft-teams-incoming-webhook-security-next-level-kinzelin> "Bring Microsoft Teams incoming webhook security to the next level with Azure Logic App"
 
 [githubtag-image]: https://img.shields.io/github/release/atc0005/go-teams-notify.svg?style=flat
 [githubtag-url]: https://github.com/atc0005/go-teams-notify
@@ -314,3 +480,5 @@ using either this library or the original project.
 [adaptivecard-ref-actions]: <https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/getting-started>
 [adaptivecard-user-mentions]: <https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#mention-support-within-adaptive-cards>
 [adaptivecard-table]: <https://adaptivecards.io/explorer/Table.html>
+
+<!-- []: PLACEHOLDER "DESCRIPTION_HERE" -->