diff --git a/README.md b/README.md index 043ab88..18fe2cb 100644 --- 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 + web UI: + +1. Select or create a new connection (e.g., ) 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) + - 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) + + + +[o365-connector-retirement-announcement]: "Retirement of Office 365 connectors within Microsoft Teams" +[workflow-channel-post-from-webhook-request]: "Post to a channel when a webhook request is received" +[linkedin-teams-webhook-security-article]: "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]: [adaptivecard-user-mentions]: [adaptivecard-table]: + +