Building with Adaptive Cards? 7 things you need to consider

Adaptive Cards are 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 an Adaptive Card for Microsoft Teams

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. However this is now changing with Adaptive Cards moving 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 that let you write a card with a “placeholder” syntax, 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.

There are many popular business apps that can be readily integrated into your Adaptive Card design, such as ServiceNow, Hubspot, Zendesk, Github, Jira, and many others.

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 adenin’s All Cards menu (see here, requires free account).

B. How do you get your data into a card?

Microsoft’s big on seeing Adaptive Cards as an output from Power Automate. For example you could have your card sent to a Microsoft Teams chatbot as part of a Flow.

Power Automate is also the only way Microsoft allows you to directly embed data from over 300 Connectors into your design.

But this is a pricey endeavour, many Connectors cost a premium, custom connectors are cumbersome to make, and there isn’t a good interface to the Adaptive Cards editor – so you’ll forever copy and paste your layout to AdaptiveCards.io.

Power Automate also lacks capabilities to embed the output into SharePoint, Outlook, webpages or intranets. This kind of flies in the face of “Write once, deploy everywhere”. (Read the this 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

Customizing the design

We covered that Adaptive Cards are separating design and functionality and that it’s overall a great move. That is unless your organization wants to customize the design.

That’s because with Adaptive Cards it’s the host that decides how to style the Card, i.e. in SharePoint buttons will be inline with the theme of the page, in Microsoft Teams the accent color will be Team’s signature purple, etc.

Some people may consider this a dealbreaker, but others might find that it takes some of the guesswork out and ensures Cards look ‘native’ wherever they are embedded.

If you like the idea of Adaptive Cards

Then you should perhaps try adenin’s Card maker solution. Basically it tries to marry together every aspect a business needs to make Adaptive Cards work for them:

1. Apps
   With a ton of ready-to-go Connectors from the App Directory you can directly hit the ground running and don’t have to waste any time sifting through developer docs, debugging, etc.
2. Card designer
   A built-in version of the Adaptive Card designer lets you conveniently edit and manage your Card’s layout, and you can directly use Templating provided by your app. There are also further enhancements for businesses (such as notifications, a dashboard, etc.). Browse templates that work with the designer to get started.
3. Intranet embedding
   Whether it’s SharePoint, Viva Connections or simply WordPress, with the Channels provided by the platform your Cards become as portable as a YouTube video and can be embedded anywhere
4. Chatbot interfaces
   Both the Microsoft Teams app and adenin’s ChatGPT have tremendous potential to help users get quick answers from their work apps without taking away from their concentration. A great way to boost your team’s productivity.

And there you are, a primer of everything administrators ought to know before deciding on whether Adaptive Cards could be best standard to base your next project off of. Anything to add? Have you used Adaptive Cards in your organization? Share your thoughts below.