Challenge 005 | Use Adaptive Cards in your solutions

Because last month’s challenge was quite time consuming to fulfill, this months challenge will put less stress on your agenda. This month we will dive into the power of Adaptive Cards. We will build a card ourselves, ask the recipient for some input and collect that input. Pretty straightforward.

Challenge Objectives

🎯 Learn about Adaptive Cards

🎯 Get familiar with the Adaptive Cards designer

🎯 Implement Adaptive Cards in Teams

🎯 Collect the input

🎯 Share your connector

🤓 What Are Adaptive Cards

Adaptive Cards are an 🔓 open card exchange format enabling developers to exchange UI content in a common and consistent way, written in JSON. Each app or service supporting Adaptive Cards will transform the content file into native UI elements, automatically adapting to the look and feel of the host. In practice, this means that you will only have to worry about the content you want to bring across to your end-user. The host application or service will make sure it looks and scales as it should.

A good example of Adaptive Cards are the messages you receive when an ✔️ Approval is implemented in your flow. The first image 👇🏼 below shows the initial Adaptive Card. It asks the recipient to approve or reject. Once the request has been approved, the Adaptive Card adapts accordingly (see the second image). This is a key 🦸🏻 advantage over a regular email with a static link embedded in it.

There is an Adaptive Card designer available where you can drag and drop elements to your adaptive card. It will generate the card payloader (the JSON schema) for you. The Schema explorer show which information is required and in which format it must be provided.

A Static Card

  1. In the Adaptive Card designer, create a New card from blank

  2. Make sure you select Microsoft Teams (dark of light). Notice that when you select a different host app it might change the target version. This way you are sure the functionality you add will work appropriately.

  3. Add a TextBlock element to the Adaptive Card

  4. Set the text property to Hello my friend!. Notice it will update your card payloader. In the Schema explorer, review what information is required. As you can see, only the type and text property are required. These are now in your payloader, so this element should work by now.

  5. Add an Image element to the Adaptive Card and search what information is required in the Schema Explorer. Notice that PNG, JPEG, and GIF are accepted formats.

  6. The Image element requires an URL to the image location. You right click the image below and copy the image link. now paste it into the URL property. If you’re not a fan of Matthew, feel free to browse for another image.

  7. Click Copy card payload.

  8. Create a new Power Automate with a manual trigger.

  9. Add the action Post adaptive card and wait for a response.

  10. Post as a Flow bot in a Chat with Flow bot.

  11. Enter your email at the Recipient field.

  12. Paste the copied card payloader in the Message field. By now, it should look like this:

  13. Save and run the flow.

You will receive the Adaptive card in Teams. A nice first step. In a later step we will add some user input. But first, we will see what it will look like it an Outlook message.

Give It A Spin In Outlook

We learned that we only need to specify the content of an Adaptive card and the host app or service will handle the rest. At the moment of writing, the presumed supported version for Outlook Actionable Messages is 1.4, but it did not work on my machine. I switched it back to version 1.0, which did work. For help with debugging, I recommend installing the Actionable Messages Debugger for Outlook PLUGIN.

  1. Create a new flow or adjust the flow you created earlier.

  2. After the manual trigger, create a new action called Send an email (v2).

  3. Address it to yourself with Adaptive Card in the subject.

  4. In the body, switch to code view (see image above). You will have to specify the body in HTML.

  5. Because it is in HTML, the JSON itself is not sufficient. Every adaptive card you will send this way needs to be wrapped in some HTML text. Don’t worry if you are not familiar with HTML. Just copy the snippet below and paste the card payloader where it is instructed.

  6. Save and run.

<html><head><script type="application/adaptivecard+json">REPLACE THIS WITH YOUR CARD PAYLOADER</script></head></html>

You will now receive the same adaptive card in your email. If you switch theme, the Adaptive card will change accordingly. For the rest of this challenge we will continue to work with Teams because nobody likes to receive emails, but if your use case requires sending emails, you now know a bit about it. The actions on Outlook differ a bit from the Teams actions. A Universal Action Model is being developed, but not solid yet this blogpost by @Tomasz Poszytek is a valuable resource if Outlook is your only option.

Add User Input We Want To Collect

Just sending a welcome and an image is not something why we would implement an Adaptive Card. We want to get some user input. In this step, we will ask the recipient to tell us if they like Matthew McConaughey and if they are really sure. Please don’t shoot me, I had to think of something right? I assume your creativity will manage to translate this example to something useful in your scenario.

  1. Add an Input.ChoiceSet element to your Adaptive card.

  2. The input will be received in Power Automate. We will be collecting two inputs, so we must be able to identify which input is which. That’s why the Id field is required. Lets name this input Rating.

  3. At the label field, enter How much do you like Matthew McConaughey?

  4. For the first input we want to have a dropdown, so we can leave the style to Compact. We want instruct the recipients what we want from them. We can do this by entering a placeholder. I entered Please give me your thoughts.

  5. We want to make sure the input is given before it is submitted. We can do this by checking the Required checkbox under the validation tab. If it’s required an error message must be specified too. I entered You should rate it buddy!

  6. Now we will enter the possible options the recipient can select. I made five options:

Title

Value

🤮 Can’t stand him

1

👎🏻 Don’t like him

2

👌🏻 He is OK

3

👍🏻 He is pretty cool

4

😍 Total rockstar

5

That’s it for the first input. Now select the preview mode to see how your dropdown works. The second will be a 🍰 piece of cake.

  1. Add another Input.ChoiseSet to the Adaptive Card

  2. Id = Confirmation, Label = Are you sure?, Make it required and enter and error message like Please let us know if you are sure.

  3. For the choices, select Yes and No, Both for the title and value.

  4. The only change we will make compared to the previous Input.ChoiseSet is that we will set the style to Expanded. This way there are radio buttons besides the options that can be selected.

Nothing special, but now we have all the information that we wanted to collect. Good job!

Submit The Input

We don’t just want the end-user to select some items, we want to collect that input as well. The last addition to the Adaptive Card will be a submit button. Let’s add it!

  1. Add an ActionSet element to the bottom of the Adaptive Card.

  2. Hover over the element and select Add an action. You can see there are multiple options. Action.OpenURL is a nice way is you want to direct them somewhere else (e.g. DEEP LINKING to an item in an app). As mentioned before, A Universal Action Model is being developed. Eventually you want to use the Action.Execute option form submitting. Until then, we will use the dedicated Teams submit action, which is Action.Submit.

  3. Rename the Title to Submit.

Nicely done! Copy the card payloader and update your Power Automate flow. If you manually trigger the flow, you should receive the updated card in a teams chat. The card payloader should look like something below. Note that I have made some minor styling adjustments, so don’t worry about that too much.


{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.4",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hello my friend!",
            "wrap": true,
            "horizontalAlignment": "Center",
            "fontType": "Default",
            "size": "Large",
            "color": "Default",
            "weight": "Bolder"
        },
        {
            "type": "Image",
            "url": "https://media0.giphy.com/media/BElb9DVpHezcZufOhl/giphy.gif",
            "horizontalAlignment": "Center",
            "id": "acImage"
        },
        {
            "type": "Input.ChoiceSet",
            "choices": [
                {
                    "title": "🤮 Can't stand him",
                    "value": "1"
                },
                {
                    "title": "👎🏻 Don't like him",
                    "value": "2"
                },
                {
                    "title": "👌🏻 He is OK",
                    "value": "3"
                },
                {
                    "title": "👍🏻 He is pretty cool",
                    "value": "4"
                },
                {
                    "title": "😍 Total rockstar",
                    "value": "5"
                }
            ],
            "id": "Rating",
            "errorMessage": "You should rate it buddy!",
            "isRequired": true,
            "placeholder": "Please give me your thoughts",
            "label": "How much do you like Matthew McConaughey?"
        },
        {
            "type": "Input.ChoiceSet",
            "choices": [
                {
                    "title": "Yes",
                    "value": "Yes"
                },
                {
                    "title": "No",
                    "value": "No"
                }
            ],
            "id": "Confirmation",
            "label": "Are you sure?",
            "isRequired": true,
            "errorMessage": "Please let us know if you are sure",
            "style": "expanded"
        },
        {
            "type": "ActionSet",
            "horizontalAlignment": "Left",
            "actions": [
                {
                    "type": "Action.Submit",
                    "title": "Submit"
                }
            ]
        }
    ]
}

Additional Info

After you’ve made a selection and submitted, the values for Rating and Confirmation are received in Power Automate. Obviously, you can use that dynamic content in subsequent actions of your flow. You can also add dynamic content to your adaptive card. Simply replace a static text field by a dynamic one, just like you would do with any other message you would be sending. In our example, we could personalize our Adaptive Card by replacing the Hello my friend! with some output of the Office 365 Users connector. We created a fairly simple Adaptive Card intentionally. The reason for that is that these are the most important items you will be using. You can go all out, and I do encourage you to just try it. If you are looking for inspiration, just browse the templates. This is also a great resource to see how it is done and maybe copy-paste a few parts that you can use for your use-case. Last but not least, the Adaptive Card designer work bi-directional. That means that if you have a JSON snippet of an Adaptive Card, you can simply paste it in card payload editor, and your Adaptive Card will be visualized. This is a great way to update earlier developed Adaptive Cards.

Community examples of Adaptive Cards can be found here. You are more than welcome to share what you’ve created!

🎒 Key takeaways

👉🏻 You deliver the content, the host application or service will do the styling

👉🏻 The Adaptive Card designer is your go-to place if you want to develop Adaptive Cards

👉🏻 Selecting the right Adaptive Card version for the target app or service is key