This is part 1 of the Custom Actionable Messages with Microsoft Flow series

With Microsoft Flow, there are two ways of sending out-of-the-box Actionable Messages:

• Start an approval
• Send email with options

Things I ran into by using these actions are:

• The comment boxes with the Start an approval action are optional and cannot be set to required
• The Send email with options action does not provide the option of adding text boxes
• The lay-out of the Actionable Message is pre-defined and cannot be customized
• Each Flow can run for a maximum of 30 days. This means that if of of these actions has been triggered, the response has to come within 30 days. Otherwise the Flow will time-out. In general, 30 days will be more then enough, but what if you have that one user in your organization that always needs more time?..

The solution is (quite) simpel: use custom Actionable Messages!

Actionable Messages

First things first, what are Actionable Messages exactly?

According to this article on docs.com, ‘Actionable Messages enable you to take quick actions right from within Outlook and Teams. Developers can now embed actions in their emails or notifications, elevating user engagement with their services and increasing organizational productivity.

Office 365 provides two solutions to enhance productivity with Outlook Actionable Messages: actionable messages via email, and actionable messages via Office 365 Connectors.‘

In this blog, I will focus on sending out a Actionable Message via email, which will be triggered from SharePoint where a user can provide some feedback on newly created items. In part 2, I will explain how you can get the response back into SharePoint by using Microsoft Flow.

Please note that Actionable Messages do not work on every mail client. For a full overview of supported Outlook versions, check this article.

Configuring the Actionable Message

An Actionable Message is basically an email with a JSON body. Not everybody is skilled in JSON (me neither), but luckily there are some tools available which make your life easier. The one I use is MessageCard PlayGround V2. On this site, you can choose between a few predefined messages, such as a CRM opportunity and a Microsoft Flow Approval.

For this example, I will choose the Microsoft Flow Approval. This example provides you with a hero image, header, body, action buttons and a footer.

Of course, I want to customize this message a bit to make sure the header body and actions are suitable for my solution. In my example, I don’t want the hero image, make changes to the body to make sure it is suitable for my item, only have one option to provide feedback (which is required) and remove the footer.

You can customize the JSON at the left side. Each change will be shown in real-time on the right side. After I made my changes, the message looked like this:

As you can see, some sections have three dots. That’s because I want to have dynamic content on that sections. I will configure that later inside the Flow.

By default, an input textfield is optional. To make a textfield required, you should add the following line to the inputs section of your ActionCard:

"isRequired": true,

Configuring your Flow

Now that we have configured our Actionable Message JSON body, we can proceed and configure our Flow.

I made a simple custom List in SharePoint with no further customization (so only the Title field is available). After that, I created a Flow that will be triggered when a new item will be added to that list.

As said before, an Actionable Message is just an email with a JSON body, so we do need the Send an email action. To make sure the JSON gets correcly parsed into that email, we also need a Compose action. The Compose action contains the JSON, generated by the MessageCard Playground, placed within the following script tags:

<script type="application/ld+json">
</script>

We have four sections that need dynamic content:

• Created by Displayname
• Created by Email
• Created
• Link to item

After adding putting the JSON within the script tags and replacing the dots with dynamic content, the Compose action looks like this:

<script type="application/ld+json">
{
    "@type": "MessageCard",
    "@context": "http://schema.org/extensions",
    "summary": "This is the summary property",
    "themeColor": "0075FF",
    "sections": [
        {
            "startGroup": true,
            "title": "**A new item requires your feedback**",
            "activityTitle": "New item added by **@{triggerBody()?['Author']?['DisplayName']}**",
            "activitySubtitle": "@{triggerBody()?['Author']?['Email']}",
            "facts": [
                {
                    "name": "Date submitted:",
                    "value": "@{triggerBody()?['Created']}"
                },
                {
                    "name": "Details:",
                    "value": "Please provide your feedback for this new item."
                },
                {
                    "name": "Link:",
                    "value": "[Click here to view the item](@{triggerBody()?['{Link}']})"
                }
            ]
        },
        {
            "potentialAction": [
                {
                    "@type": "ActionCard",
                    "name": "Approve",
                    "inputs": [
                        {
                            "@type": "TextInput",
                            "id": "feedback",
                            "isMultiline": true,
                            "isRequired": true,
                            "title": "Feedback (required)"
                        }
                    ],
                    "actions": [
                        {
                            "@type": "HttpPOST",
                            "name": "Respond",
                            "target": "http://..."
                        }
                    ]
                }
            ]
        }
    ]
}
</script>

Please notice the final target parameter within the last actions section. This is where you configure the action that happens after the user clicks on the Respond button in Outlook.

Now that we have composed our JSON body, we can proceed and configure the Send an email action. You can use the output from the Compose action as body. Make sure you set the ‘Is HTML property’ to ‘Yes’.

That’s it, we can now test our Flow by adding a new item to our list. If everything has been set up correctly, the Actionable Message will be sent to the specified receiver. It contains the dynamic content we added in Flow and the textbox is required.

Because we haven’t configured the Respond button yet, clicking it will give you an error. I will describe how to configure this button in Part 2, so stay tuned!