Adaptive cards are becoming increasingly popular in the Microsoft 365 ecosystem. We can find them in Microsoft Search, Power Apps, SPFx apps, Outlook email and many more services. So what are Adaptive Cards (AC) and Adaptive Card Extensions (ACE)? In this article, we show how you can harness the power of adaptive cards in Viva Connections.
The purpose of Adaptive Cards
Adaptive Cards are a new way for developers to exchange content in a common and consistent way. The idea behind Adaptive Cards is simple: most software developers are not known for being the best designers of forms and data presentations. In order to develop a system that would make it easy for developers to present data in attractive forms, Microsoft founded the "Adaptive Card Working Group" around 2017. This should make it easier for developers to display data in a standardized form on all possible devices. The group began developing Message Cards around 2017, which became Adaptive Cards in 2018. The latest information is publicly available on Github.
Adaptive cards consist of a simple JavaScript Object Notation (JSON) description of a form. This allows developers to define a card in their code without having to define a webpage with styles and CSS classes, or worrying about how the form will render on an Android phone, an iPad, or on a computer screen. This is the adaptive part of the map. The client renders the adaptive map as best as possible to match the appearance of the corresponding client. Developers only need to design the map and populate it with data. Adaptive Cards can be used in Microsoft Teams, SharePoint, Viva, Microsoft Search, Outlook Actionable Messages, Cortana Skills, or Windows Timeline, and can be rendered inside your own apps by using the SDKs.
Adaptive Card Extensions (ACEs) are a new SharePoint Framework component type that enables developers to create rich, native extensions to Viva Connections dashboards and SharePoint pages. Because Adaptive Card Extensions use Microsoft's Adaptive Card Framework, developers only need to focus on the business logic of their component. The SharePoint Framework (SPFx) ensures that the component looks good and works across all platforms.
Active Viva Connections
We want to use AC´s in Microsoft Viva Connections. To start using Viva Connections, check the requirements in your M365 tenant before. See the instructions at Set up and launch Viva Connections.
The online designer and usage of Adaptive Cards
Microsoft provides an online Adaptive Card designer at aptivecards.io . This website shows a number of sample forms created with AC. When a form is designed online, the designer generates the "code" for that card as a JSON document. This code can be included in an application code or directly in the services mentioned above. Of course, we can also use and generate the code in our own apps and in our own business processes, such as: in an Azure Logic App to email a decision to a manager, etc. So we have different services that can send and display ACs.
Create a static Adaptive Card
Let´s start with creating a simple AC with the designer at adaptivecards.io. We select a sample card, as an example, the Food order sample. If we want, we can adapt end extend the AC in the designer. The following screenshot shows the concept of Adaptive Cards - the JSON code, and the output.
When done, we copy the resulting JSON into the Viva Connections dashboard. There, we edit the dashboard and add a new card. Here, we open the card designer. See more about the steps at Create a Viva Connections Dashboard and add cards.
We click on the Edit menu. This opens the configuration panel on the right side. We modify the name, the design, and set the Actions to "Show the quick view" instead of "Open a link". We scroll down, and paste the JSON document into the card content. The screenshot shows the new settings of the card component.
To check the appearance and the functionality, we click on the Preview link. We see the card opened when we click on the card or the card button for our mini-app.
This was easy, right?
Create an app to show an Adaptive Card with code
Well, in most cases we want to create a map that searches for data and shows relevant content to the user. To do this, an app must be developed that reads data that AC sends and possibly also writes back data from the form. An example of such an app could be the selection of a lunch menu, an approval process or any other simple process that can be usefully integrated into the Viva Connections dashboard.
To accomplish this task, we need to develop an SPFx application that sends an AC and fills it with data. For the requirements for developing such an SPFx app, see the article at Set up your SharePoint Framework development environment. You can also follow the article at Build your first SharePoint Adaptive Card Extension.
When all components are installed on the computer, we can run the Yeoman generator to create the project for us. We open a command line (PowerShell) and switch to an empty, new directory. Here we have created a directory called "VivaConnectionsACE". In here we run the generator like this:
yo @microsoft/sharepoint
The Yeoman generator for SharePoint will open and ask for some details of our app. We give the app a name "MyFirstACE" and select the type. This is important because there is already a component that we can use to display an ACE. We select "Adaptive Card Extension".
Then, we select the ACE template. As first sample, we simply select the "Primary Text Template". This is a basic card, showing only some text we can modify. As Extension name, we also use "MyFirstACE". When this information is entered, the generator creates an almost ready to use solution for us.
Modify the project
We can now open the project, best with Visual Studio Code (you can get it from code.visualstudio.com/).
code .
Here, we actually only need to do two things: Open the config/serve.json file and adapt the initialPage key with the URL to a SharePoint site in our tenant, like "mysite.sharepoint.com". Then, we save this file. See also Update your project's hosted workbench URL.
Now, we have a look at the package.json file. Here we see all dependencies. Before we can run the application, we need to install the required Node packages. We can do so by opening the terminal with CTRL+; , and run
npm install
This will install all packages and their dependencies in our solution. This process can take several minutes.
Where´s the ACE
When done, let´s have a look at the Adaptive Card first. The ACE is named QuickViewTemplate.json, and is stored in the src\adaptiveCardExtensions\myFirstAce\quickView\template path. The ACE looks as here.
We got what we selected in the generator: An ACE with a simple text block. In the \quickView\QuickView.ts file, we see the code that is responsible for reading the card and to fill it with data from the interface.
public get template(): ISPFxAdaptiveCard {
return require('./template/QuickViewTemplate.json');}
So, we can modify the template and the code to change the application. For example, we could do an HTTP call against an API or another connector to get data from a database, or similar. There are a lot of resources and videos on the PnP YouTube channel showing how to develop such apps.
Run the SPFx app with the ACE
For developing SPFx apps, we recommend to install the "PnP Connection Toolkit" extension to your VS Code (see more about installing extensions here). This makes it easy to run and to package apps. Press F1 (see Using the Visual Studio Code Command Palette in GitHub Codespaces), enter "ext" for extensions and install. In the marketplace, search for "PnP". You should find the extension easily. Install it.
Great. Now, let´s run the app. We can either type
gulp serve
in the Terminal window, or use the PnP Viva Connections Toolkit and the menu Serve. This is the same as typing the command, but is often a quick and easy way to develop and provides a number of useful commands.
The browser opens and shows the SPFx workbench - we defined the URL to open in the serve.json file before. Here, we can add our MyFirstACE component to the workbench,.
We can try it out with the Preview link on the top right corner. When we click on the card (that is also part of our app in the src\adaptiveCardExtensions\myFirstAce\cardView folder), our QuickView opens and shows the content of the ACE in our app.
Deploy the app
The last part is to modify the app for our purposes, and to deploy it to the SharePoint app catalog. See Use the site collection app catalog and Manage apps using the Apps site for more information about these steps. For deploying, we run the Bundle project (production) menu, followed by Package (production). This generates an MyFirstACe.sppkg package file in the \sharepoint\solution directory. This file must be uploaded to the SharePoint app catalog to make this app available for Viva connections. It can then be added in the Viva connections dashboard, as the static card before.
Mission accomplished!
As we can see, generating an app for Viva Connections is just a few steps away with the right tools. Of course there is a lot to learn and develop here, but we hope we were able to give you a short introduction to developing custom apps and Viva Connections with Adaptive Card Extensions !
Have fun playing with these technologies and have fun with the other great items on the Festival Calendar 2022!