Building with Adaptive Cards? 7 things you need to consider (Updated Oct ’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.

For the first couple years, whether to make an Adaptive Card was a question for people developing with Bot Framework. But recently they have moved into new territory, such as Viva Connections or Windows 11 Widgets.

Pro and cons of using Adaptive Cards

Whatever you’re working on (or about to work on) you may wonder whether there any hidden implications of committing your project to the hands of Microsoft’s Adaptive Cards.

Generally, adopting more Card-based UX is a great move for any business that wants to create better employee experiences.

Microsoft’s attempt to be part of this wave offers organizations many benefits, but also a few caveats, as you will see:

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.

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

Previously, there was a distinct lack of channels you could deploy your Adaptive Cards to, mainly just Teams or Bot Framework.

This is now changing: Adaptive Cards have moved into Sharepoint-based intranets, and are announced for Windows 11 widgets.

Still, these are all in the Microsoft ecosystem. Natively supported 3rd party platforms are very rare – it’s really only Webex. Slack and Alexa have competing standards, Block Kit and Alexa Presentation Language.

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.

With v1.6 there is even going to be the option of image carousels. (Source)

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.

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.

Built-in data-binding

Adaptive Cards have logic to easily write your Card with “placeholders”, that get replaced with real data at runtime. Microsoft added this in 2020 and calls it Templating and it allows you to directly embed the data from your API’s JSON response 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.

Half-supported business use cases

Apart from Templating, there are more features that are of importance for enterprise use cases. None of these are perfect, so it’s up to you to decide what compromises you are willing to make.

A. Where do you store your Cards?

If you make many Cards, you need somewhere to store and govern them. Microsoft has released a basic ACMS – Adaptive Card Management System – in 2020 however it’s never left alpha stage since.

If you’re looking for an Adaptive Card CMS that offers at least fundamental version history, deployment option and governance, then you’re best bet might be Digital Assistant’s All Cards menu (see here).

B. Triggering Cards

Adaptive Cards don’t just statically appear on a page; usually there needs to be some kind of trigger that tells your Cards when to appear. This could as part of a chatbot’s response. 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. It also doesn’t have any Connectors that could embed Adaptive Cards in 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.)

C. How do you make them part of a chatbot?

Adaptive Cards have a speech output that let’s you write a verbal response that can be read along with your Card being displayed. That’s great, but where do you define what the user asks before they get the Card? for your team, have you asked yourself how your users will ask for a specific Card? Microsoft would be happy to sell you another solution with Bot Framework that’s entire chatbot platform that integrates Adaptive Cards into its responses. But, again, it’s separate and may be too pricey for some.

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

Really big business logic gaps

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? And what Cards may have to be mandatory for everyone on the team?
• Personalization
  Will users be able to personalize what Cards they see? Should the Card store user preferences, such as their sort order, weather forecast location, etc.? If so, where will these preferences be stored?
• Localization
  If you speak French you want to see French buttons, French user help and French labels and dates everywhere. Not to mention that the natural language processing should understand you, too.
• Date formatting
  If your Card gets a timestamp from an API, that’s usually going to be in UNIX. But don’t expect Adaptive Cards to be able to cleverly reformat this into user-friendly timestamps like “X minutes ago.”
• 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? Does the Card auto-refresh or will the user be notified to refresh it manually, at least?
• Transforming data
  Sometimes what you get in JSON 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 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.
• 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.

This may however soon change. Windows 12 widgets show their Adaptive Cards have a height dependant layout. Perhaps this could make it’s way into into upcoming version 1.6 of Adaptive Cards.

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.

Related: Roundup of Adaptive Card versions and roadmap

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

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.

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?

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.