forked from dasrick/go-teams-notify
-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #263 from atc0005/i262-initial-doc-updates-for-wor…
…kflow-connectors Documentation refresh for Workflow connectors
- Loading branch information
Showing
1 changed file
with
210 additions
and
42 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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., <[email protected]>) 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" --> | ||