Work with Microsoft Adaptive Cards
Before exploring bot creation, you should have a deeper understanding of the technology that is used to display content to agents in the Productivity pane. You can present agents with information, such as suggested knowledge articles, in the Productivity pane by using Microsoft Adaptive Cards.
Microsoft Adaptive Cards is a portable, open-source solution that helps you deliver content to applications. Adaptive cards use a single format for delivering content that minimizes the number of schemas that developers need to learn. This approach helps lower the cost of developing content and helps the content work across a broader set of applications. Another advantage of Adaptive cards is that the content natively renders inside a host application such as the Productivity pane in Omnichannel for Customer Service. The content is automatically styled to match the host application UX and brand guidelines so that it has the appearance and behavior of the host application. As a result, users have a consistent experience, regardless of how they're accessing the content.
For example, an organization creates an Adaptive card by using the Microsoft Bot Framework, which is used to deliver knowledge articles to users. When a user consumes this information while using Skype, it appears and behaves similar to a typical Skype card. If someone in an application such as Microsoft Teams consumes this same payload, it appears and behaves similar to Microsoft Teams. No matter where the information is consumed, the same payload activates inside applications that support Adaptive cards and still feels entirely native to the app.
This concept is important when you're working with smart assist inside Omnichannel for Customer Service. Smart assist bots search and use data payloads from different systems or components such as cases from Dynamics, Calendars, or Office, or from native or other management systems. Regardless of where the data comes from, it's presented to the user in Omnichannel for Customer Service using the same user interface as other omnichannel components.
Core design principles of Adaptive cards
Adaptive cards are significant parts of any Omnichannel for Customer Service implementation where smart assist is used. As you consider using Adaptive cards, keep in mind some guiding principles that have been useful in helping to keep the design process on track:
Focus on using semantic values. The host application uses semantic values and concepts as opposed to pure pixel-perfect layouts such as colors, item sizes, and images, to make better decisions about the actual appearance and behavior of content that is related to the application that it's being rendered in.
Card authors own the content; the host app owns the appearance and behavior. When authors create cards, they own what data should be presented in the card. This data might consist of information from a knowledge article that should be included or actions such as the ability to email the article. After that content has been delivered, the hosting application takes over and controls the appearance and behavior of the card to most accurately render it in the context of their application.
Keep the card simple but expressive. Adaptive cards should be expressive and general purpose. The goal isn't to build a UI framework but to be an intermediate layer that is similar to Markdown, where a simple and consistent description of document content is created. Adaptive cards can create a simple, expressive means of describing card content.
When in doubt, keep it out. It's easier to add something later rather than endure a mistake. When you're defining what to include on the card, if you're not sure whether the information should be included, it's best to leave it out. Adding a property later is better than persisting with a legacy that you wish you didn't have to support.
Typically, the people who deploy smart assist into a Dynamics 365 Omnichannel for Customer Service environment aren't the same people who write the Adaptive card content. Developers typically create adaptive card content. Likely, the developers might not be familiar with Dynamics 365 products. After they have finished creating the card content, the developer will hand off the Adaptive card to a Dynamics 365 administrator to deploy into the Omnichannel for Customer Service environment by using smart assist. For this reason, this module doesn't provide an in-depth explanation of the process of writing and rendering content. Rather, it focuses on providing a high-level overview of key concepts.
Write cards
The basic structure of a card is as follows:
AdaptiveCard - Root object that describes the Adaptive card, including items such as what elements comprise the card, what actions it includes, how it's spoken if it's read back, and the schema version that is required to render it.
Body - The body consists of building blocks that are known as elements. Elements might include images to render, text to include, media files, input parameters, and more. Elements can be composed in nearly infinite arrangements to create many types of cards.
Actions - Many cards could have a set of actions that a user might take on it. This property describes those actions that are typically rendered in an action bar at the bottom of the card.
The following example shows a simple card that includes a single line of text followed by an image.
Work with elements
Elements are the key components that make up the body of the card. Multiple elements are defined to help determine the overall layout of the card. Every element has a type property that identifies what kind of object it is. Each type has different properties that define more details about the element. Notice that the preceding card has two elements: TextBlock and Image.
The three primary types of elements that are used in cards are:
Adaptive elements - The most fundamental elements that are used in cards. These elements include TextBlock and Image, which are used for adding and controlling the appearance of text and images in cards.
Container elements - Help to arrange a collection of child elements for easier consumption and/or delivery. Containers are typically used for groups of items such as columns or images.
Input elements - Allow you to ask for native UI information, such as text, dates and times, numbers, and so on, to build simple forms.
Work with actions
Many cards benefit from adding actions that can help provide better usability to the person who is consuming the card. For example, you might use an action to open an external URL or to open a subcard that provides additional information.
Microsoft Learn contains an extensive library of information that is related to writing adaptive card content.
To explore this content in more detail, select the following links:
Render cards inside your application
After a card has been created, it can be rendered inside applications. SDKs have been provided for all common platforms and provide a detailed specification for creating your own Adaptive card renderer. The following table defines the different Adaptive card SDKs that are available.
| Platform | Install |
|---|---|
| JavaScript | npm v1.2.6 |
| .NET WPF | NuGet v1.2.4 |
| .NET HTML | NuGet v1.2.4 |
| Windows UWP | NuGet v1.2.9 |
| Android | maven-central v1.2.9 |
| iOS | pod v1.2.9 |
After you've deployed the correct SDK, you need to:
Create an instance of the renderer (AdaptiveCardRenderer). This action acquires the card payload and connects the action events.
Render a card. After you acquire a card payload, call the renderer and pass in the card. You receive a native UI object that consists of the card contents. Now, you can place this UI somewhere in your app.
Microsoft Learn contains an extensive library of information that is related to rendering adaptive card content and working with SDKs.
To explore this content in more detail, select the following links: