Newsletter robot
Enjoyed the read?

Don't miss our next article

Digital Workplace, Intranets

Building with Adaptive Cards? Here's what you should consider (Updated May '20)

Make your Assistant Build your free AI-powered Digital Workplace platform in minutes, with our free forever plan. Yes please

What is Adaptive Cards?

Adaptive Cards is a Card UI framework announced by Microsoft in 2017 that aims to standardize the layouting of Cards independent of the platform.
The goal is to define a Card just once, make it portable and leave it to the different platforms to skin it according to its own requirements.

Example of 4 different Adaptive Card styles
Overview of one Adaptive Card across different styles

Adaptive Cards are obviously best supported by other Microsoft products, like Microsoft Teams or Bot Framework. As of October 2019 another rival to Microsoft Teams, namely Webex Teams, also made the switch to Adaptive Cards. You can see an up-to-date list of supported platforms on the Microsoft website.

If you're reading this article chances are you're already working (or considering to work) with Bot Framework. Maybe you're making a chatbot for your organization and are wondering if there any hidden implications of committing your project to the hands of Microsoft.

So here we have a few thoughts you might want to take into consideration:

Benefits of using Adaptive Cards

Adopting more Card-based UX is generally a great move for any business that wants to create better employee experiences. Adaptive Cards specifically are Microsoft's attempt to be part of this development, and there are many solid aspects to it:

1. Write once, deploy everywhere

Adaptive Cards are written in JSON. They're just a simple 'description' or a 'recipe' for how a Card should be structured, where the list goes, where a button goes, etc.

As part of the JSON in which Cards are defined, admins can even specify what should be read from the Card if voice output is available in the host app. This was probably designed for Cortana, although since her retirement, there isn't another voice assistant that is compatible with Adaptive Cards.

2. Native look

Following the point above, each host application that displays your Card will tweak the it's styling to make the Card look like a native part of the app.

This means the same Card payload could be skinned completely differently in Microsoft Teams compared to how it looks in Webex Teams, even though they would be identical in functionality.

This separation of design and functionality is a great way to ensure long-term usability of Cards, even as apps and their features evolve.

3. Rich functionality

Microsoft has included a lot interactivity for Adaptive Cards. They offer a wide range of inputs like dropdowns, text boxes and button and individual sections can be dynamically shown or hidden. This exceeds the range of functions, that Alexa Presentation Language or Slack Block Kit offers.

4. Built-in data-binding

Originally announced for version 2.0, data binding is now available as a Preview. Microsoft calls it Templating, and, in a nutshell, it allows you to directly embed the data from your JSON into the payload of your Card.

For example, say you want to display someone's phone number you can just write out the path under which the number is showing in your JSON (each indent is separated by dots). Adaptive Card will then follow the same in the JSON until it reaches the correct node and paste it's content 1:1 into the Card.

Example of the Adaptive Card templating system

5. Card CMS (introduced April '20)

Originally Adaptive Cards' mission was to just be a standard, like HTML is a standard. But obviously managing HTML pages is not possible without also using a CMS.

Obviously having a CMS for Cards was an oft-requested addition and Microsoft now added this feature which they call "ACMS". You can try the release candidate here.

Adaptive Cards ACMS for card management
Screenshot of Card CMS showing versioning and external sharing of Adaptive Cards

Challenges when using Adaptive Cards

However there are also some drawbacks to using Adaptive Cards, namely:

1. Little cross-platform support

Aside from Webex Teams, there isn't a single provider outside of Microsoft that supports Adaptive Cards. If your project should work on either Slack, Alexa or Google Assistant, then you will need to support their respective frameworks separately.

Arguably, even within Microsoft there isn't universal support for Adaptive Cards as neither SharePoint, nor the (admittedly) outgoing Skype support it. That is kind of a bummer as all the talk of "write once, deploy everywhere" completely hinges on widespread compatibility.

2. Business logic gaps

Adaptive Cards are a simple JSON "recipe"; they just show you what you gave them. Apart from conditional layouting and announced addition of a CMS, there isn't a whole lot of heavy lifting Adaptive Cards will do. (At least yet.)

Thus, for typical business use cases you'll have a lot more to think about that requires separate implementation efforts. Some of the below blind spots are actually addressed by other Microsoft products, and others are not.

First, we start with issues where you may find help from other Microsoft products:

  • Triggering Cards
    How will your Card know to appear at all? Is there a service or listener that sends Cards to your users when they need to see them?

    Microsoft offers a solution with Power Automate, but that may or may not be open enough for your other 3rd party apps to be integrated. There are platforms that are more open that let you create your own Connectors to any API.
  • Natural language understanding
    How can the user ask for a specific Card? What will take care of understanding what the user wants? And is this easy enough to maintain without escalating into an entirely separate project?

    Microsoft would again offer a solution with Bot Framework, but it is separate and may be too pricey for some. On top of that, some organization are averse to having NLU data be processed in the cloud for commercial or privacy concerns.

But there are also some other quite fundamental issues to running your own Card infrastructure where you'll be own your own, namely:

  • User authentication
    For anything other than completely public Cards you need to know "Who's looking at the Card?" Will users log in separately to see your Cards or should they share a session with, say, your SharePoint?
  • Permissions
    What Cards may a user see or find? What will they see if there they don't have permission?
  • Audiences
    Will users be able to personalize what Cards they see? If so, where will these preferences be stored? And what Cards may have to be mandatory for everyone?
  • Multi-lingual
    If you speak French you want to see French buttons, user help and labels everywhere. Not to mention that the natural language processing should understand you, too.
  • Dates and formats
    Oftentimes JSON shows time as Unix time, but don't expect Adaptive Cards to be able to cleverly reformat this into user-friendly timestamps like "X minutes ago." Or in Europe they need dates to be formatted DD.MM, not MM/DD as commonly used in the US.
  • Updated data detection
    Let's say the API with your "Open Helpdesk tickets" has changed. How will this update be detected? And how will the Card know to get refreshed or recalled?
  • Transforming data
    Sometimes what you get in JSON, say from an API, isn't immediately ready for your use case. For example, you may need to run one endpoint's results against another endpoint for more details, or you may want to reformat or truncate inputs or change various aspects about the incoming data. A JS runtime like Node.js could be an answer, but that isn't part of Adaptive Cards.

3. Updates and fragmentation

Despite only a handful of platforms supporting Adaptive Cards, they adopt new versions at different paces. This can mean immense differences in functionality.

According to Microsoft the latest stable version of Adaptive Cards is version 1.0, yet Microsoft Teams is using version 1.2.

This could spell some odd constraints for making universally useful (and beautiful) Cards. For example:

  • you need v1.1 to show specific image sizes
  • step up to v1.2 so you can show Action buttons in places other than on the bottom
  • with the announced v1.3 it looks like we might get media queries for responsive layouts, as well as GIF and SVG support

While it's great Microsoft continues to create new features, the sluggish implementation kind of makes it hard to make a pretty Card that will work everywhere.

4. Customizing the design

We covered above how Adaptive Cards are separating design and functionality and that it's overall a great move, unless your company wants to customize the design.

It isn't uncommon that organizations would like to infuse Cards with their own corporate style, but remember it's the host app that fully controls that aspect about Adaptive Cards. If this isn't a compromise you're happy to make, you may have to consider workarounds.

Are there alternatives?

There are platforms that actually work alongside Adaptive Cards to augment them with all the features organizations typically require. With Digital Assistant for example users get the most native experience for the platform they're using.

In a browser environment, we have our own Assistant Cards which are HTML5. But for Microsoft Teams we translate this Card into an Adaptive Card on the fly (see example on the right).

And for other platforms we use their native layouts, too: For Slack the Assistant shows Cards as Block Kit, with Alexa the native format is called APL and Google Assistant responses are in the Rich responses format.

It is this cross-platform compatibility that makes it easy for organizations to truly write a Card once, and deploy it everywhere without having to familiarize yourself with every nuance of every target channel.

Editor's tip:
If you're not convinced it's that easy, just try it for yourself with a free Digital Assistant account including all the above channels.

Hopefully this guide gave you a quick primer on Adaptive Cards and helped you decide whether it's for you. Are you a seasoned Apative Cards developer? If so, let us know if you think we missed anything in the comments below.

Article by: Henry Amm

I’m the Senior Director for the Digital Assistant Platform. Prevously gained 6 years of experience as an Intranet consultant. Fluent in German.

Join the discussion

This field is required.
This field is required.
This field is required.

0 responses

Be the first to leave a comment!