Digital Workplace

Building with Adaptive Cards? 7 things you need to consider (Updated Jan '22)

What is Adaptive Cards?

Adaptive Cards is a universal Card UI framework released by Microsoft in 2017 which aims to standardize the layouting of Cards independent of the host 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.

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:

Pro and cons of using Adaptive Cards

Adopting more Card-based UX is generally a great move for any business that wants to create better employee experiences. Microsoft's attempt to be part of this development offers organizations many benefits, but also a few caveats as you will see:

1. Write once, deploy everywhere-ish

Adaptive Cards are written in JSON. They're just a simple 'recipe' for how a Card should be structured, where the list goes, where a button goes, etc. Each host application that displays your Card will then tweak it so it's styling look like a native part of the app.

Related: How to build and embed an Adaptive Card into SharePoint

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

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

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

There aren't that many channels you can deploy your Adaptive Cards to, though. Apart from other Microsoft products, like Teams or Bot Framework, there is only really Cisco Webex as the sole 3rd party platform to support them. Slack and Alexa have competing standards, Block Kit and Alexa Presentation Language.

Editor's tip:
If it's important to you, there are ways to "translate" your Adaptive Cards into the formats native to Slack, Alexa, etc.

2. Rich functionality

Microsoft has included a lot interactivity for Adaptive Cards. They offer a wide range of inputs like dropdowns, text boxes, buttons and individual sections that can be dynamically shown or hidden. This far exceeds the range of functions, that Alexa Presentation Language or Slack Block Kit offer. And it's not just optimized to work on desktops and mobiles, it also – frankly – looks pretty for a business application.

4 different Adaptive Cards showing sample data, including news articles, announcements, forms and request workflows
Samples of Adaptive Cards

Another little "party trick" is that, within the JSON that defines the Card, admins can specify a voice output that the host app reads out to the user. This was probably designed for Cortana, although since her retirement, there isn't another voice assistant that is currently compatible with Adaptive Cards.

3. Built-in data-binding

Microsoft added this in 2020 and calls it Templating. 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
Dot (.) delimited data binding

4. More business features

Apart from Templating, there are more features that make Adaptive Cards ready for enterprise implementations:

Card CMS

When you have many HTML sites you need a CMS, and similarly when you have many Adaptive Cards you need what Microsoft calls a "ACMS". You can try the release candidate here. Although basic, this CMS let's you share and publish Cards via the web or email.

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

Triggering Cards

PowerAutomate Flow triggering an Adaptive Card to capture leads in a Microsoft Teams channel
PowerAutomate Flow posting an Adaptive Card to Teams

For most use cases, there needs to be some kind of trigger that tells your Cards when to appear. Microsoft offers a solution with Power Automate, where you can trigger an Adaptive Card to be send to a channel as part of a Flow.

Even though PowerAutomate has over 300 Connectors, many cost a premium over the already lofty base price of the service. Further, some organization that want to create their own Connectors, find the setup to be cumbersome and prefer a more open solution based on Postman.

PowerAutomate also doesn't have any Connectors that could bring Adaptive Cards to SharePoint, Outlook, Search, third-party websites or Intranets. This kind of flies in the face of "Write once, deploy everywhere". (Read the Alternatives section if that's important to you.)

Natural language understanding

If you're wanting to build a chatbot for your team, have you asked yourself how your users will ask for a specific Card? This could quickly catapult your project to a level of complexity where it may become harder to maintain it in the future. Sure, Microsoft would be happy to sell you another solution with Bot Framework that promises to help; but it is again separate and may be too pricey for some.

Cheaper alternatives are dedicated AI Chatbot platforms that are compatible with Adaptive Cards.

5. Business logic gaps and limitations

Whilst Microsoft offers some solutions for businesses, typical enterprise use cases require a level of Card infrastructure currently unmatched by Microsoft:

  • 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.
  • Detect when data has changed
    Let's say the API's response 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.
  • Icons
    There is no way to "save" any icons into your Adaptive Card. So if your layout relies on them or uses them in any buttons, then you'll have to find another platform to host them. Moreover, it is now commonplace for UX designers to use SVG icons for applications, yet MS Teams flat out will not show vectors - requiring you to rely on PNGs instead. Lame 🤷‍♂️
  • Layout shifts are not possible
    Adaptive Cards can sometimes struggle on very narrow screens where they experience awkward truncation or cropping issues. Microsoft has started to address this partially with ActionSet overflows, but it's far from being as robust as mobile users would want it.
Unreadable text due to too many elements

6. Updates and fragmentation

The latest version of Adaptive Cards is 1.5. Although there is just a handful of applications supporting Adaptive Cards, they are pretty fragmented in terms of the version they support:

  • Microsoft Teams currently supports v1.4
  • Cisco Webex claim they support v1.2, but then don't support Media, speak or Action.ToggleVisibility within this version
  • Outlook Actionable Messages are only on v1.0, but are expected to jump straight to v1.4

There are no timelines published for any service, to find out when they want to update to a higher version. Consequently, you may be stuck with an older version which create a bottleneck for your project to restrict itself to use only the features of the lowest common denominator.

This would mean foregoing some exciting new features added each version:

  • 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 v1.3 there are some breaking changes with Templating which means Adaptive Cards made for older versions aren't forwards-compatible once the host app switches to v1.3 or above
  • To get tables (yeah, regular <table>s) you need to wait for a host app to be up to v.1.5. That version also introduced tooltips, which would help offload some explanatory texts off of the Card design
Tooltips in v1.5. Source: Microsoft

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

7. Customizing the design

We covered above how Adaptive Cards are separating design and functionality and that it's overall a great move. That is unless, and that's kind of obvious, your organization wants to customize the design.

It isn't uncommon that organizations would like to infuse Cards with their own corporate style, fonts, etc. 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 alternatives.

Are there alternatives?

There are platforms that use Adaptive Cards as their frontend, but are from the ground-up designed to be an enterprise SaaS. Free tools like Digital Assistant offer ways to connect to existing apps or custom APIs and simple project their data onto customizable Adaptive Cards.

Since Adaptive Cards are largely confined to a few Microsoft products, it's good to know that they can be embedded in other channels, too.

You could easily embed Adaptive Cards into SharePoint or show them in other chat tools like Slack or Alexa. Since these tools lack Adaptive Cards support, Digital Assistant "translates" them on the fly into their respective native formats.

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.

Author portrait

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.

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

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

Avatar placeholder
This field is required.
This field is required.
This field is required.

0 responses

Be the first to leave a comment!