diff --git a/docs/operator-manual/notifications/services/overview.md b/docs/operator-manual/notifications/services/overview.md index 265e575755088..1cfb7c2c43e54 100755 --- a/docs/operator-manual/notifications/services/overview.md +++ b/docs/operator-manual/notifications/services/overview.md @@ -47,7 +47,8 @@ metadata: * [Grafana](./grafana.md) * [Webhook](./webhook.md) * [Telegram](./telegram.md) -* [Teams](./teams.md) +* [Teams (Office 365 Connectors)](./teams.md) - Legacy service (deprecated, retires March 31, 2026) +* [Teams Workflows](./teams-workflows.md) - Recommended replacement for Office 365 Connectors * [Google Chat](./googlechat.md) * [Rocket.Chat](./rocketchat.md) * [Pushover](./pushover.md) diff --git a/docs/operator-manual/notifications/services/teams-workflows.md b/docs/operator-manual/notifications/services/teams-workflows.md new file mode 100755 index 0000000000000..15c78e84e7b32 --- /dev/null +++ b/docs/operator-manual/notifications/services/teams-workflows.md @@ -0,0 +1,370 @@ +# Teams Workflows + +## Overview + +The Teams Workflows notification service sends message notifications using Microsoft Teams Workflows (Power Automate). This is the recommended replacement for the legacy Office 365 Connectors service, which will be retired on March 31, 2026. + +## Parameters + +The Teams Workflows notification service requires specifying the following settings: + +* `recipientUrls` - the webhook url map, e.g. `channelName: https://api.powerautomate.com/webhook/...` + +## Supported Webhook URL Formats + +The service supports the following Microsoft Teams Workflows webhook URL patterns: + +- `https://api.powerautomate.com/...` +- `https://api.powerplatform.com/...` +- `https://flow.microsoft.com/...` +- URLs containing `/powerautomate/` in the path + +## Configuration + +1. Open `Teams` and go to the channel you wish to set notifications for +2. Click on the 3 dots next to the channel name +3. Select`Workflows` +4. Click on `Manage` +5. Click `New flow` +6. Write `Send webhook alerts to a channel` in the search bar or select it from the template list +7. Choose your team and channel +8. Configure the webhook name and settings +9. Copy the webhook URL (it will be from `api.powerautomate.com`, `api.powerplatform.com`, or `flow.microsoft.com`) +10. Store it in `argocd-notifications-secret` and define it in `argocd-notifications-cm` + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: argocd-notifications-cm +data: + service.teams-workflows: | + recipientUrls: + channelName: $channel-workflows-url +``` + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: +stringData: + channel-workflows-url: https://api.powerautomate.com/webhook/your-webhook-id +``` + +11. Create subscription for your Teams Workflows integration: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + annotations: + notifications.argoproj.io/subscribe.on-sync-succeeded.teams-workflows: channelName +``` + +## Channel Support + +- ✅ Standard Teams channels +- ✅ Shared channels (as of December 2025) +- ✅ Private channels (as of December 2025) + +Teams Workflows provides enhanced channel support compared to Office 365 Connectors, allowing you to post to shared and private channels in addition to standard channels. + +## Adaptive Card Format + +The Teams Workflows service uses **Adaptive Cards** exclusively, which is the modern, flexible card format for Microsoft Teams. All notifications are automatically converted to Adaptive Card format and wrapped in the required message envelope. + +### Option 1: Using Template Fields (Recommended) + +The service automatically converts template fields to Adaptive Card format. This is the simplest and most maintainable approach: + +```yaml +template.app-sync-succeeded: | + teams-workflows: + # ThemeColor supports Adaptive Card semantic colors: "Good", "Warning", "Attention", "Accent" + # or hex colors like "#000080" + themeColor: "Good" + title: Application {{.app.metadata.name}} has been successfully synced + text: Application {{.app.metadata.name}} has been successfully synced at {{.app.status.operationState.finishedAt}}. + summary: "{{.app.metadata.name}} sync succeeded" + facts: | + [{ + "name": "Sync Status", + "value": "{{.app.status.sync.status}}" + }, { + "name": "Repository", + "value": "{{.app.spec.source.repoURL}}" + }] + sections: | + [{ + "facts": [ + { + "name": "Namespace", + "value": "{{.app.metadata.namespace}}" + }, + { + "name": "Cluster", + "value": "{{.app.spec.destination.server}}" + } + ] + }] + potentialAction: |- + [{ + "@type": "OpenUri", + "name": "View in Argo CD", + "targets": [{ + "os": "default", + "uri": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}" + }] + }] +``` + +**How it works:** +- `title` → Converted to a large, bold TextBlock +- `text` → Converted to a regular TextBlock +- `facts` → Converted to a FactSet element +- `sections` → Facts within sections are extracted and converted to FactSet elements +- `potentialAction` → OpenUri actions are converted to Action.OpenUrl +- `themeColor` → Applied to the title TextBlock (supports semantic colors like "Good", "Warning", "Attention", "Accent" or hex colors) + +### Option 2: Custom Adaptive Card JSON + +For full control and advanced features, you can provide a complete Adaptive Card JSON template: + +```yaml +template.app-sync-succeeded: | + teams-workflows: + adaptiveCard: | + { + "type": "AdaptiveCard", + "version": "1.4", + "body": [ + { + "type": "TextBlock", + "text": "Application {{.app.metadata.name}} synced successfully", + "size": "Large", + "weight": "Bolder", + "color": "Good" + }, + { + "type": "TextBlock", + "text": "Application {{.app.metadata.name}} has been successfully synced at {{.app.status.operationState.finishedAt}}.", + "wrap": true + }, + { + "type": "FactSet", + "facts": [ + { + "title": "Sync Status", + "value": "{{.app.status.sync.status}}" + }, + { + "title": "Repository", + "value": "{{.app.spec.source.repoURL}}" + } + ] + } + ], + "actions": [ + { + "type": "Action.OpenUrl", + "title": "View in Argo CD", + "url": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}" + } + ] + } +``` + +**Note:** When using `adaptiveCard`, you only need to provide the AdaptiveCard JSON structure (not the full message envelope). The service automatically wraps it in the required `message` + `attachments` format for Teams Workflows. + +**Important:** If you provide `adaptiveCard`, it takes precedence over all other template fields (`title`, `text`, `facts`, etc.). + +## Template Fields + +The Teams Workflows service supports the following template fields, which are automatically converted to Adaptive Card format: + +### Standard Fields + +- `title` - Message title (converted to large, bold TextBlock) +- `text` - Message text content (converted to TextBlock) +- `summary` - Summary text (currently not used in Adaptive Cards, but preserved for compatibility) +- `themeColor` - Color for the title. Supports: + - Semantic colors: `"Good"` (green), `"Warning"` (yellow), `"Attention"` (red), `"Accent"` (blue) + - Hex colors: `"#000080"`, `"#FF0000"`, etc. +- `facts` - JSON array of fact key-value pairs (converted to FactSet) + ```yaml + facts: | + [{ + "name": "Status", + "value": "{{.app.status.sync.status}}" + }] + ``` +- `sections` - JSON array of sections containing facts (facts are extracted and converted to FactSet) + ```yaml + sections: | + [{ + "facts": [{ + "name": "Namespace", + "value": "{{.app.metadata.namespace}}" + }] + }] + ``` +- `potentialAction` - JSON array of action buttons (OpenUri actions converted to Action.OpenUrl) + ```yaml + potentialAction: |- + [{ + "@type": "OpenUri", + "name": "View Details", + "targets": [{ + "os": "default", + "uri": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}" + }] + }] + ``` + +### Advanced Fields + +- `adaptiveCard` - Complete Adaptive Card JSON template (takes precedence over all other fields) + - Only provide the AdaptiveCard structure, not the message envelope + - Supports full Adaptive Card 1.4 specification + - Allows access to all Adaptive Card features (containers, columns, images, etc.) + +- `template` - Raw JSON template (legacy, use `adaptiveCard` instead) + +### Field Conversion Details + +| Template Field | Adaptive Card Element | Notes | +|---------------|----------------------|-------| +| `title` | `TextBlock` with `size: "Large"`, `weight: "Bolder"` | ThemeColor applied to this element | +| `text` | `TextBlock` with `wrap: true` | Uses `n.Message` if `text` is empty | +| `facts` | `FactSet` | Each fact becomes a `title`/`value` pair | +| `sections[].facts` | `FactSet` | Facts extracted from sections | +| `potentialAction[OpenUri]` | `Action.OpenUrl` | Only OpenUri actions are converted | +| `themeColor` | Applied to title `TextBlock.color` | Supports semantic and hex colors | + +## Migration from Office 365 Connectors + +If you're currently using the `teams` service with Office 365 Connectors, follow these steps to migrate: + +1. **Create a new Workflows webhook** using the configuration steps above + +2. **Update your service configuration:** + - Change from `service.teams` to `service.teams-workflows` + - Update the webhook URL to your new Workflows webhook URL + +3. **Update your templates:** + - Change `teams:` to `teams-workflows:` in your templates + - Your existing template fields (`title`, `text`, `facts`, `sections`, `potentialAction`) will automatically be converted to Adaptive Card format + - No changes needed to your template structure - the conversion is automatic + +4. **Update your subscriptions:** + ```yaml + # Old + notifications.argoproj.io/subscribe.on-sync-succeeded.teams: channelName + + # New + notifications.argoproj.io/subscribe.on-sync-succeeded.teams-workflows: channelName + ``` + +5. **Test and verify:** + - Send a test notification to verify it works correctly + - Once verified, you can remove the old Office 365 Connector configuration + +**Note:** Your existing templates will work without modification. The service automatically converts your template fields to Adaptive Card format, so you get the benefits of modern cards without changing your templates. + +## Differences from Office 365 Connectors + +| Feature | Office 365 Connectors | Teams Workflows | +|---------|----------------------|-----------------| +| Service Name | `teams` | `teams-workflows` | +| Standard Channels | ✅ | ✅ | +| Shared Channels | ❌ | ✅ (Dec 2025+) | +| Private Channels | ❌ | ✅ (Dec 2025+) | +| Card Format | messageCard (legacy) | Adaptive Cards (modern) | +| Template Conversion | N/A | Automatic conversion from template fields | +| Retirement Date | March 31, 2026 | Active | + +## Adaptive Card Features + +The Teams Workflows service leverages Adaptive Cards, which provide: + +- **Rich Content**: Support for text, images, fact sets, and more +- **Flexible Layout**: Containers, columns, and adaptive layouts +- **Interactive Elements**: Action buttons, input fields, and more +- **Semantic Colors**: Built-in color schemes (Good, Warning, Attention, Accent) +- **Cross-Platform**: Works across Teams, Outlook, and other Microsoft 365 apps + +### Example: Advanced Adaptive Card Template + +For complex notifications, you can use the full Adaptive Card specification: + +```yaml +template.app-sync-succeeded-advanced: | + teams-workflows: + adaptiveCard: | + { + "type": "AdaptiveCard", + "version": "1.4", + "body": [ + { + "type": "Container", + "items": [ + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "auto", + "items": [ + { + "type": "Image", + "url": "https://example.com/success-icon.png", + "size": "Small" + } + ] + }, + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "Application {{.app.metadata.name}}", + "weight": "Bolder", + "size": "Large" + }, + { + "type": "TextBlock", + "text": "Successfully synced", + "spacing": "None", + "isSubtle": true + } + ] + } + ] + }, + { + "type": "FactSet", + "facts": [ + { + "title": "Status", + "value": "{{.app.status.sync.status}}" + }, + { + "title": "Repository", + "value": "{{.app.spec.source.repoURL}}" + } + ] + } + ] + } + ], + "actions": [ + { + "type": "Action.OpenUrl", + "title": "View in Argo CD", + "url": "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}" + } + ] + } +``` \ No newline at end of file diff --git a/docs/operator-manual/notifications/services/teams.md b/docs/operator-manual/notifications/services/teams.md index 0e44456d4de19..caea85afc702f 100755 --- a/docs/operator-manual/notifications/services/teams.md +++ b/docs/operator-manual/notifications/services/teams.md @@ -1,18 +1,46 @@ -# Teams +# Teams (Office 365 Connectors) + +## ⚠️ Deprecation Notice + +**Office 365 Connectors are being retired by Microsoft.** + +Microsoft is retiring the Office 365 Connectors service in Teams. The service will be fully retired by **March 31, 2026** (extended from the original timeline of December 2025). + +### What this means: +- **Old Office 365 Connectors** (webhook URLs from `webhook.office.com`) will stop working after the retirement date +- **New Power Automate Workflows** (webhook URLs from `api.powerautomate.com`, `api.powerplatform.com`, or `flow.microsoft.com`) are the recommended replacement + +### Migration Required: +If you are currently using Office 365 Connectors (Incoming Webhook), you should migrate to Power Automate Workflows before the retirement date. The notifications-engine automatically detects the webhook type and handles both formats, but you should plan your migration. + +**Migration Resources:** +- [Microsoft Deprecation Notice](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/) +- [Create incoming webhooks with Workflows for Microsoft Teams](https://support.microsoft.com/en-us/office/create-incoming-webhooks-with-workflows-for-microsoft-teams-4b3b0b0e-0b5a-4b5a-9b5a-0b5a-4b5a-9b5a) + +--- ## Parameters -The Teams notification service send message notifications using Teams bot and requires specifying the following settings: +The Teams notification service sends message notifications using Office 365 Connectors and requires specifying the following settings: + +* `recipientUrls` - the webhook url map, e.g. `channelName: https://outlook.office.com/webhook/...` -* `recipientUrls` - the webhook url map, e.g. `channelName: https://example.com` +> **⚠️ Deprecation Notice:** Office 365 Connectors will be retired by Microsoft on **March 31, 2026**. We recommend migrating to the [Teams Workflows service](./teams-workflows.md) for continued support and enhanced features. ## Configuration +> **💡 For Power Automate Workflows (Recommended):** See the [Teams Workflows documentation](./teams-workflows.md) for detailed configuration instructions. + +### Office 365 Connectors (Deprecated - Retiring March 31, 2026) + +> **⚠️ Warning:** This method is deprecated and will stop working after March 31, 2026. Please migrate to Power Automate Workflows. + 1. Open `Teams` and goto `Apps` 2. Find `Incoming Webhook` microsoft app and click on it 3. Press `Add to a team` -> select team and channel -> press `Set up a connector` 4. Enter webhook name and upload image (optional) -5. Press `Create` then copy webhook url and store it in `argocd-notifications-secret` and define it in `argocd-notifications-cm` +5. Press `Create` then copy webhook url (it will be from `webhook.office.com`) +6. Store it in `argocd-notifications-secret` and define it in `argocd-notifications-cm` ```yaml apiVersion: v1 @@ -31,10 +59,20 @@ kind: Secret metadata: name: stringData: - channel-teams-url: https://example.com + channel-teams-url: https://webhook.office.com/webhook/your-webhook-id # Office 365 Connector (deprecated) ``` -6. Create subscription for your Teams integration: +> **Note:** For Power Automate Workflows webhooks, use the [Teams Workflows service](./teams-workflows.md) instead. + +### Webhook Type Detection + +The `teams` service supports Office 365 Connectors (deprecated): + +- **Office 365 Connectors**: URLs from `webhook.office.com` (deprecated) + - Requires response body to be exactly `"1"` for success + - Will stop working after March 31, 2026 + +7. Create subscription for your Teams integration: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -44,12 +82,20 @@ metadata: notifications.argoproj.io/subscribe.on-sync-succeeded.teams: channelName ``` +## Channel Support + +- ✅ Standard Teams channels only + +> **Note:** Office 365 Connectors only support standard Teams channels. For shared channels or private channels, use the [Teams Workflows service](./teams-workflows.md). + ## Templates ![](https://user-images.githubusercontent.com/18019529/114271500-9d2b8880-9a4c-11eb-85c1-f6935f0431d5.png) [Notification templates](../templates.md) can be customized to leverage teams message sections, facts, themeColor, summary and potentialAction [feature](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using). +The Teams service uses the **messageCard** format (MessageCard schema) which is compatible with Office 365 Connectors. + ```yaml template.app-sync-succeeded: | teams: @@ -124,3 +170,7 @@ template.app-sync-succeeded: | teams: summary: "Sync Succeeded" ``` + +## Migration to Teams Workflows + +If you're currently using Office 365 Connectors, see the [Teams Workflows documentation](./teams-workflows.md) for migration instructions and enhanced features. diff --git a/go.mod b/go.mod index bd803f7a1180d..38738b8bc0dba 100644 --- a/go.mod +++ b/go.mod @@ -13,7 +13,7 @@ require ( github.com/TomOnTime/utfutil v1.0.0 github.com/alicebob/miniredis/v2 v2.35.0 github.com/argoproj/gitops-engine v0.7.1-0.20250908182407-97ad5b59a627 - github.com/argoproj/notifications-engine v0.5.1-0.20251129223737-e2e7fe18381a + github.com/argoproj/notifications-engine v0.5.1-0.20251223091026-8c0c96d8d530 github.com/argoproj/pkg v0.13.6 github.com/argoproj/pkg/v2 v2.0.1 github.com/aws/aws-sdk-go v1.55.7 diff --git a/go.sum b/go.sum index 8f3d9df277a51..9d0844d1e2b90 100644 --- a/go.sum +++ b/go.sum @@ -115,8 +115,8 @@ github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be h1:9AeTilPcZAjCFI github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be/go.mod h1:ySMOLuWl6zY27l47sB3qLNK6tF2fkHG55UZxx8oIVo4= github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY= github.com/appscode/go v0.0.0-20191119085241-0887d8ec2ecc/go.mod h1:OawnOmAL4ZX3YaPdN+8HTNwBveT1jMsqP74moa9XUbE= -github.com/argoproj/notifications-engine v0.5.1-0.20251129223737-e2e7fe18381a h1:tAyJp5VIEKM5OUUJJIDwSGMgYPwcSE6SAtAQ2ykVU30= -github.com/argoproj/notifications-engine v0.5.1-0.20251129223737-e2e7fe18381a/go.mod h1:d1RazGXWvKRFv9//rg4MRRR7rbvbE7XLgTSMT5fITTE= +github.com/argoproj/notifications-engine v0.5.1-0.20251223091026-8c0c96d8d530 h1:l8CrIDgqJBRyR1TVC1aKq2XdeQlLkgP60LxoYkOY7BI= +github.com/argoproj/notifications-engine v0.5.1-0.20251223091026-8c0c96d8d530/go.mod h1:d1RazGXWvKRFv9//rg4MRRR7rbvbE7XLgTSMT5fITTE= github.com/argoproj/pkg v0.13.6 h1:36WPD9MNYECHcO1/R1pj6teYspiK7uMQLCgLGft2abM= github.com/argoproj/pkg v0.13.6/go.mod h1:I698DoJBKuvNFaixh4vFl2C88cNIT1WS7KCbz5ewyF8= github.com/argoproj/pkg/v2 v2.0.1 h1:O/gCETzB/3+/hyFL/7d/VM/6pSOIRWIiBOTb2xqAHvc= diff --git a/mkdocs.yml b/mkdocs.yml index 496436f145bc7..a0849160c1b58 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -94,6 +94,7 @@ nav: - operator-manual/notifications/services/pushover.md - operator-manual/notifications/services/rocketchat.md - operator-manual/notifications/services/slack.md + - operator-manual/notifications/services/teams-workflows.md - operator-manual/notifications/services/teams.md - operator-manual/notifications/services/telegram.md - operator-manual/notifications/services/webex.md