Microsoft Power Automate / Workflows Support

[caronc]

Description:

Related issue (if applicable): #1161

Added Microsoft Power Automate / Workflows Integration into Apprise.

Known usages:

• Send notification to MSTeams

This plugin can take the Azure Webhook URL as-is (provided after it's generation).

This is in anticipation of the MS Teams Outlook Webhooks being decomissioned in mid Aug/2024

• Source: https://www.microsoft.com/en-us/power-platform/products/power-automate
• Icon Support: Yes
• Message Format: Text
• Message Limit: 1000 Characters per message

Account Setup

Create a workflow from MS Teams to generate an Azure Webhook. The webhook will look something like this:

https://prod-NO.LOCATION.logic.azure.com:443/workflows/WFID/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=SIGNATURE
       |-------------------------------| |-|             |                                                                                                  |
                    |                     |          {workflow}                                                                                          {signature}
             host information {host}      |
                                         {port}


You can use the above to assemble the URL: workflows://{host}:{port}/{workflow}/{signature}

Syntax

Valid syntax is as follows:

• workflows://{host}:{port}/{workflow}/{signature}
• https://prod-NO.LOCATION.logic.azure.com:443/workflows/.....
  • Apprise can interpret the webhook as it's provided (sometimes copy/paste is just easier

Parameter Breakdown

Variable	Required	Description
workflow	Yes	The Workflow Identifier provided in the Azure Webhook Link
signature	Yes	The Signature Identifier provided in the Azure Webhook Link (sig=)
wrap	No	Wrap body text in response.
ver	No	The Power Automate API Version to use; the default value is 2016-06-01. This is also parsed using the keyword api-version that can be found on the Azure Webhook Link.
template	No	provide a path to a template you would prefer to use instead of the Adaptive card chosen by Apprise. use double {{token}} curly braces to identify the tokens you wish to have swapped in the provided template prior to it's submission to the upstream service. (e.g {{app_body}} or {{app_title}})

Templating

The following tokens can be referenced in provided templates:

Key	Description
{{app_body}}	The body provided into Apprise
{{app_title}}	The title provided into Apprise
{{app_type}}	The notification type (either info, warning, critical or success)
{{app_id}}	The App Identifier (reads Apprise unless system owner has over-ridden)
{{app_desc}}	The App Description (reads Apprise Notification unless system owner has over-ridden this)
{{app_color}}	A HTML Color code dirctly associated with the {{app_type}}. Hence a critical message generates a red color here unless the system owner has overridden this.
{{app_image_url}}	Provides a URL to an image that reflects the notification type
{{app_url}}	Provides a URL to describe the application. This usually provides a link to the Apprise code base unless the system owner has overridden this.
{{app_mode}}	At this time, this is fixed to json

New Service Completion Status

• apprise/plugins/workflows.py
• KEYWORDS
  • add new service into this file (alphabetically).
• README.md
  • add entry for new service to table (as a quick reference)
• packaging/redhat/python-apprise.spec
  • add new service into the %global common_description

Checklist

• The code change is tested and works locally.
• There is no commented out code in this PR.
• No lint errors (use flake8)
• 100% test coverage

Testing

Anyone can help test this source code as follows:

# Create a virtual environment to work in as follows:
python3 -m venv apprise

# Change into our new directory
cd apprise

# Activate our virtual environment
source bin/activate

# Install the branch
pip install git+https://github.com/caronc/apprise.git@1161-microsoft-workflows

# Test out the changes with the following command:
apprise -t "Test Title" -b "Test Message" \
  `workflow://id/signature`

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.26%. Comparing base (9620901) to head (a448afe).

Additional details and impacted files

@@           Coverage Diff            @@
##           master    #1172    +/-   ##
========================================
  Coverage   99.25%   99.26%            
========================================
  Files         143      144     +1     
  Lines       18637    18794   +157     
  Branches     3582     3609    +27     
========================================
+ Hits        18499    18656   +157     
  Misses        126      126            
  Partials       12       12            

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[caronc]

@stelb I do not have access to MSTeams at this time, can you (or someone you know) can help with the testing? You can use the (`https://) webhook directly provided from the Microsoft workflows (as-is). Apprise should be smart enough to handle it.

[toby-coleman]

Thanks for this @caronc - I just tried the test code above. Using the https webhook, which in my case starts with "https://prod-15.uksouth.logic.azure.com:443/workflows/..." I got an unparseable URL error.

So I took the ID and signature from the URL and reformatted them to get:

apprise -t "Test Title" -b "Test Message" "workflow://XXXXX/XXXXX"
# 2024-07-22 13:30:46,772 - ERROR - Could not load Workflows (for MSTeams) URL: workflow://3...5/i...U
# 2024-07-22 13:30:46,772 - ERROR - There are no service(s) to notify

[caronc]

😔 okay, I'll dig deeper when i have some time to focus more on this.

I know we're close! The entire framework is in place now, it just needs tweaking.

My problem is i don't have a MS Teams setup to test against.

I'll keep you posted.

Thanks so much for replying and testing so quickly!

[toby-coleman]

Just tried setting the URL to "workflows://prod-15.uksouth.logic.azure.com:443/XXX/XXXX" format and it works, sending the test message correctly. Command I used is:

apprise -t "Test Title" -b "Test Message" `workflows://HOST:PORT/id/signature`

[caronc]

That's great news! It wouldn't be an Apprise plugin if it didn't also support the actual webhook as-is (provided by Azure), so I'll get this working before i merge the code.

Without disclosing your credentials, can you share the URL you are using right now (swap some characters to invalidate it - it's the structure I'm interested in).

[toby-coleman]

Sure - the format is like this (from the "When a Teams webhook request is received" workflow step):

https://prod-15.uksouth.logic.azure.com:443/workflows/3XXX5/triggers/manual/paths/invoke\?api-version\=2016-06-01\&sp\=%2Ftriggers%2Fmanual%2Frun\&sv\=1.0\&sig\=iXXXU

[toby-coleman]

One more thing... just noticed that the title is appearing in the message area, i.e. with the test title/test message command above I get:

[stelb]

I get this when using just the webhook url "https://prod-112.westeurope.logic.azure.com:443/workflows/cc938324.........../triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=giDSp171V8WXL7Sp5Sf35IHu......."

2024-07-22 14:48:21,142 - WARNING - Failed to send Workflows notification: error=202.
2024-07-22 14:48:21,142 - DEBUG - Response Details:

But it was successful anyway. Should 202 be a hint, that there might be some delay? second attempt was delivered immediately.

with workflow:id/sig I get "Unsupported URL: workflow:cc938324.........../giDSp171V8WXL7Sp5Sf35IHu......."

[caronc]

Okay, i pushed another update that should fix the double title being displayed. I also updated the documentation above which will eventually appear in the workflows wiki page (not set up yet).

I can't reproduce the issue with the webhooks not working; this appears to work correct, but i did add another test case to ensure it stays this way.

Is it possible the webhook didn't work because you fell prey to how URLs can conflict with the Linux Shell? Make sure the webhook is in quotes and it 'should' work. Keep me posted either way.

[toby-coleman]

Thanks @caronc - just tested it again.

• Confirmed that the double title problem is now fixed.
• Also managed to get the webhook URL working. I did have it enclosed in quotes, but noticed that when I copy/paste from Teams, the =, ? and & characters are all escaped with \ (see example above. When I go through and remove the \ characters then it works.
• One comment above on the message width in Teams - currently long messages don't occupy the full width, and I think the change in the comment will fix (see picture below for an example of a long message).

[toby-coleman]

...realised I only made the comment on the test, so it will need to go here as well:

Suggested change

	"type": "AdaptiveCard",
	"type": "AdaptiveCard",
	"msteams": { "width": "full" },

[caronc]

• Also managed to get the webhook URL working. I did have it enclosed in quotes, but noticed that when I copy/paste from Teams, the =, ? and & characters are all escaped with \

I saw that and wasn't sure about them, so i took them out. Let me add a test case with them re-added so they can be supported as well.

[caronc]

@toby-coleman , are the characters escaped for you right out of Azure? Or did you add them? I only ask because in @stelb 's provided example, they weren't escaped.

Edit: Anyway, escape support added (and test case to support it) but not sure if it's overkill or not as the effort to sanitize the url adds 4 lines of busy code. Will leave it in place...

Created wiki

If you guys could check the branch out one last time and give it one more go, i think we're good to merge now.

[toby-coleman]

@caronc - just tested again and it looks good to me:

• Full width card now working;
• URL working both with/without escape characters and using the workflows:// format.

Looking again at the URL:

• The escape chars don't appear in the URL in Teams;
• They do appear when I copy/paste into a WSL terminal;
• They don't appear when pasting into other applications, e.g. VSCode.

Perhaps this is a case of WSL trying to be 'helpful' - but in any case the escape char support seems like a useful feature to me Looks like this is in fact a feature of OhMyZsh - see ohmyzsh/ohmyzsh#7632

[stelb]

Hey! It works with webhook URL and with shorter workflows:// Format now :)

I missed the host:port part before for workflows://

I have no issues with escapes, but I remember ohmyzsh messing with my pasted input when I used it. Sometimes useful, sometimes not.

[caronc]

Glad it's working for you guys!

I'm hesitant about the escaping because now this plugin is different from the other 100+ plugins where the undo magic escaping put in place by a very specific shell terminal only doesn't exist (nor is it applied to regular apprise URLs in it's current state).

Personally, I'm not a fan of that auto-magic-escape feature provided by that shell you shared. You can't even copy and paste terminal commands with it being rearranged/edited on you (this baffles me). Should you ever have to debug your system in the future, online examples you find on the internet may not work (mangled before you press enter). It would make more sense if the shell feature was off by default for all users with an explanation on how to turn it on for the likes of whomever made the request to have it. It basically breaks everything for you (as an administrator). Obviously just my point of view 🙂. I do appreciate you sharing where the escaping came from though; now it makes more sense.

I will roll just this one change back (to support broken URLs with escaping) for consistency with the rest of Apprise and other URLs. After that I'll merge.

I'll also try to do an official release this weekend so all of this is available in production for you guys. You were all a fantastic help! Thank you sooo much for all your testing and shared links!!🙏🙏 It was so incredibly helpful!

[toby-coleman]

I'm hesitant about the escaping because now this plugin is different from the other 100+ plugins where the undo magic escaping put in place by a very specific shell terminal only doesn't exist (nor is it applied to regular apprise URLs in it's current state).

Agree - doesn't make sense to have this for a single plugin. I never realised it was doing this before today!

Thanks so much for getting this PR done quickly so we can all get our Teams notifications working again!