feat(alerting): Implement new Teams Workflow alert

JamesHillyard commented 2 months ago

Summary

Fixes #820 by introducing a new teams-workflows alert compatible with Teams Workflows. Microsoft is deprecating the O365 webhook connector for Teams Workflows with MS Power Automate (Source: Microsoft DevBlog).

The new Workflows require Microsoft Adaptive Cards and have a proprietary JSON format that means the old teams connector using a new Workflow URL will fail with this error:

The execution of template action 'Send_each_adaptive_card' failed: the result of the evaluation of 'foreach' expression '@triggerOutputs()?['body']?['attachments']' is of type 'Null'. The result must be a valid array.

Breaking Changes

There are no breaking changes. The old teams alert still exists and will work with legacy O365 Webhook URLs.

There are no breaking changes in configuring the teams and teamswebhook alerts, meaning migration is simple.

Migrating to new Teams Webhooks

End-users will need to make the following changes to migrate from the legacy teams alerts to teamswebhook alerts:

Create a Workflow in Microsoft Teams for incoming webhooks. Microsoft Documentation
Replace all occurences of teams (In alerting and endpoints[].alerts) with teams-workflows
Replace the alerting.teams.webhook-url (Now alerting.teams-workflows.webhook-url) with the new URL generated in the Teams Workflow

Configuring the `teams-workflows` Alert

MS Teams Configuration

Gatus Configuration

alerting:
  teams-workflows:
    webhook-url: "[WORKFLOW-WEBHOOK-URL-HERE]"
    default-alert:
      description: ""
      send-on-resolved: true
      failure-threshold: 3
      success-threshold: 3

endpoints:
  # Website Group
  - name: front-end
    url: https://www.google.com
    interval: 3s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 50"
    alerts:
      - type: teams-workflows
        description: "Description Lies Here"

Remaining Issues

There are a few remaining issues, none are blockers to using this feature, but likely should be addressed in the future with further investigation.

Adaptive Card Version >1.5

Using an Adaptive Card higher than 1.4 (1.6 is latest) results in the message showing

We're sorry, this card couldn't be displayed

This has been reported to AdaptiveCards (Report), but discussion around this issue seems very low.

Card Width

The cards do not show on teams as full-width. A StackOverflow post would suggest the width can be changed, but I wasn't able to get this to work.

Card Colour Strip

The red and green colour strip on the old teams cards at the top for triggered/resolved is not supported in Adaptive Cards. There are workaround options as identified in this Stack Overflow post but it doesn't look great.

Checklist

[X] Tested and/or added tests to validate that the changes work as intended, if applicable.
[X] Updated documentation in README.md, if applicable.

JamesHillyard commented 2 months ago

@TwiN Makes sense, I have renamed teamsworkflow to teams-workflows and tested it still works. Thanks for the review!

JamesHillyard commented 1 month ago

@TwiN Looks like the text was expecting a broken teams emoji.. I must have changed it last minute and not updated the test. I've now fixed it and running go test -v .\alerting\provider\teamsworkflows\ results in all tests passing.

deebify commented 1 month ago

When can I use the new teams-workflows?

codecov-commenter commented 1 month ago

:warning: Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 92.00000% with 6 lines in your changes missing coverage. Please review.

Project coverage is 79.35%. Comparing base (bb97397) to head (7cc5bd3). Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
alerting/provider/teamsworkflows/teamsworkflows.go	92.00%	3 Missing and 3 partials :warning:

:exclamation: Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #847 +/- ## ========================================== + Coverage 79.15% 79.35% +0.19% ========================================== Files 71 72 +1 Lines 4778 4853 +75 ========================================== + Hits 3782 3851 +69 - Misses 783 786 +3 - Partials 213 216 +3 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

TwiN commented 1 month ago

@JamesHillyard Great work & thank you for the contribution!

liamjones-pw commented 3 weeks ago

@TwiN not pushing you, but any idea when you'll create a new release including this code?

TwiN commented 3 weeks ago

@liamjones-pw I usually let new features soak in latest for some time to give people time to report issues. If people are already using the feature and haven't reported any issues, I can create a release for it this weekend 👀

TwiN commented 3 weeks ago

@liamjones-pw I just released v5.13.0

TwiN / gatus