Microsoft 365 Community Community Demos, 16 Dec 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Introduction to Adaptive Card Extensions (ACEs) for Microsoft Viva Connections

Description

In this 21-minute developer-focused demo – Paolo Pialorsi opens with a high-level overview of Microsoft Viva with full integration with Microsoft Teams for developers. Developers extend Viva Connections with SPFx, exclusively. Step-by-step showing how to create your very first configurable (Property Pane) ACE with SPFx on SharePoint Workbench. Scaffold an SPFx project, register views and step through the files to understand what exactly was created. Subsequent demos will go deep in areas. This PnP Community demo is taken from the Viva Connections & SharePoint Framework Bi-weekly sync call recorded on December 16, 2021.

Demo Presenter: Paolo Pialorsi (PiaSys) | @PaoloPia

Supporting materials:
• Blog - Microsoft Viva: Empowering every employee for the new digital age | http://aka.ms/viva/blog
• Documentation - Overview of Viva Connections Extensibility | https://aka.ms/viva/connections/extensibility
• Sample Repo - Viva Connection Adaptive Card Extensions (ACEs) sample repository | https://aka.ms/spfx-aces

Learn more:
• Learn more about the Microsoft 365 Patterns and Practices community at: http://aka.ms/m365pnp
• Visit the Microsoft 365 Patterns and Practices community YouTube channel: https://aka.ms/m365pnp/videos

A

Let's talk about the adaptive card, extensions also known as aces for microsoft, viva connections.

A

So, first of all, let me try to explain you what microsoft viva is just in a nutshell, so the microsoft viva offering is the new employee experience platform provided by microsoft and introduced early this year in february 2021 this year and at the link you see on this slide, you can find additional details about the viva, offering just few words about the products that make the viva offering.

A

We have four different products: dividend sites, viva topics, learning and connections, well, design, science is the service or the product that will help people to achieve a better work life balance. So it is a service which provides insight to the user to the employees of a company in order to better understand how to manage their time and how to manage their work-life balance, and it will also provide- and it provides information, for example, to managers or leaders about how the employees are performing and managing their life and work balance.

A

Of course, in the full respect of privacy, then we have viva topics which is focused on helping people to manage and organize and find their content in the company. We have a viva learning, which is a the solution for helping people to learn and to train employees through an offering of training material, fully integrated with the maxwell 65 ecosystem, but provided not only by microsoft, but mainly by external partners, training partners and at the end we also have the viva connections offering, which is the uh we can call it. The company branded experience for employees.

A

All of these products are fully integrated with the microsoft ecosystem, accessibility and specifically, with microsoft teams and especially viva connections, can provide its own interface either through the mobile experience, with a connection or through a viva connection, desktop experience, which is fully integrated with microsoft teams.

A

Now, as developers, we can extend the microsoft viva connections using a sharepoint framework, which is, as I've wrote in this slide, the uppercase t extensibility framework for the whole micro365 ecosystem.

A

In fact, we can use spfx to extend sharepoint online clearly, but we can also use it to extend the teams and we can use it to extend microsoft, viva connections as well, and we can do that with multiple options. One is to create the so-called adaptive card, extensions that we will cover now, but we also have other options like creating web parts or application customizer with sharepoint framework. In fact, the viva connection desktop experience is nothing more than a sharepoint online page enriched with viva connections with the viva connection dashboard.

A

But at the very end we can extend it with web parts or application customizer that we're used to building with the spfx. In order to build adaptive card extensions with spfx, we need to use at least version 113 of spfx.

A

So that's why we are talking about these new capabilities and nowadays because uh they are related to the latest uh released version of spfx. Just to give you an idea. This is just a screenshot of the viva connection, desktop on the left side and, as you can see here, we have the dashboard with the set of cards, rendering different kind of information, helping employees to live a better work life in their company and on the right side we have the mobile experience still with the adaptive card extensions.

A

In fact, whenever you create an adaptive ad extension, you can leverage it either in the desktop dashboard or in the mobile experience, and that's really powerful to help people find the same user experience in different platforms and devices so we're in the head of a developer.

A

How can we create adaptive card extensions and let's try to understand what adaptive card extension are from a developer point of view? Well, an adaptive card extension is nothing more than a card, so a ui component rendered, as we already said, in the desktop or in the mobile experience of viva connection, which, from a sharepoint framework point of view, are implemented simply like a new flavor of extension that we can create with spfx.

A

So you know nowadays with spfx we create webparts. We can create application. Customizer we can create a list customize or release view customize and stuff, like that. We can also create with 113 adaptive card extensions and when we do that, we can rely on two different main flavors of ui components, the card views and the quick views, and we will dig into them shortly. In this demo.

A

The card views render a really simple ui and at the entry point of any adaptive card extension, the quick views are more complex, potentially more complex, ui components which will be rendered based on the adaptive card, json syntax provided by microsoft, not only for the adaptive card extensions but generally speaking, for a lot of or most of the workloads that we have in microsoft. 365.

A

In fact we're going to use the adapted cartridges on when we create extensions for teams when we create both what we want to extend the ui of the power platform with power automate, providing input to the users and stuff like that, so the adaptive cards are nowadays almost everywhere, including in the hpfx development experience when we create adaptive card extensions for viva connections.

A

So let me move to my demo environment and let me explain you how to create step-by-step, uh your very first adaptive card extension with fpfx and before starting to creating the real uh elliptical extension. I just want to show you what the result will be so that we can be all on the same page while I will work on the visual studio code, side of the story and in the command line tool. So this is the hello world of an adaptive card extension rendered in the workbench of sharepoint framework.

A

Well, and we are using the workbench because, as I said, it is built using hpfx. So why not using exactly the same development experience that we can already use for developing web parts with spfx? This is my hello world adapter card.

A

I can click on a button in this adaptive card and I can see an additional ui component, which is the quick view card which, despite the name, is the complex one, the one which can render much more complex content, as you will see later in this demo, and we can create rich ui experiences based on multiple card views and quick views to provide a fully integrated experience for our employees.

A

Of course, these cards can also be configurable, so I can go to the edit mode of the workbench and we can see that by clicking on the pencil, we can also configure the adaptive card extensions to define what kind of rendering we want to have and eventually what kind of properties we want to provide to configure the electric cap as like, as it happens for any other web part, that we have that we can create with spfx.

A

So now, let's see how we can do that in practice- and here I am in the terminal window on my machine and I can simply use the human generator for sharepoint framework. So you add micro, sharepoint to start the generation or the scaffolding of an usb fx project.

A

Like always, we have to provide a solution name and the target for our solution will be sharepoint online. Only in this scenario, because we are creating something which will work on the cloud only in max 365, only I'm going to use the current folder for storing the scaffolded files, and I want to make my solution tenant wide available to make it easier to use it in the in the viva connection dashboard right now.

A

I will not select to use an isolated permission model, and here we are now we can also in version 113 choose if we want to create not only a web part, an extension or a library, but also an adaptive card extension, which is the new option that we have by selecting this option, we will also have the capability to define or to choose what card view flavor. We want to create first. What do I mean?

A

Well, when you create an adaptive cut extension, you will have at least one card view defined in the adaptive card extension, and through these set of options we can select the flavor, the behavior, the ui, rendering of the very first car view that we are going to scaffold in our solution. That means that we can add additional current views and quick views if we like, and we will be able to choose different layouts, but here we can make the choice for the very first one and I will go with the default ones.

A

So the primary text template in one of the upcoming demos in the sequels. I will dig into the options that we have and on the ba viewer that we can leverage for all of these different flavors of car views. Now I will simply go for the primary text template.

A

I can call it sig very first ace just for the sake of providing a name, and I really don't care about the description and now the scaffolding tool will start. It usually takes between 30 seconds and one minute.

A

So I don't want to waste your time and I already created a solution following exactly the same steps, and it is the one that we just saw in the workbench, and so here we can see what got generated, what scaffolded got comforted by the yeoman generation for sharepoint framework, and here you can see that in the src folder we have this hello, sig call adaptive card extension and if we open this source code file, we can see that it is a nothing more than a typescript class which extends the base.

A

Adaptive card extension type that we have now in sharepoint framework. So just a new base type that we can extend to create our own extensions and components, notice that, like it happens for most of the components that we have in spfx and for sure for react. We have the definition of an interface for the properties and the state of our adaptive card extension. So the properties will be those that we can configure using the property pane in the ui.

A

So this area of the ui and as you can see here, the interface defining the properties simply defines a title. A description and an icon property, then we have this data which will be used and again we will cover more deeply. This topic: the management of state and properties in one of the upcoming sig demos. But again, through this data, we can manage the state of the adaptive graph extension in the uninit method of our ace. We simply define the initial state and then this is really important.

A

We register through a set of navigators, the card navigator and the quick view navigator. We register the cards that we want to use to render the ui of our adaptive card extension. As I told you, we have two main categories of cards. We have the card views and the quick views and we have two different navigators, one for the card views and another one for the quick views.

A

So here I'm just saying: okay, please register in the collection of card views, the card view that got generated by this folding tool, and we will see it shortly with a specific card id, which is nothing more than a unique string, identifying the card I'm going to register, and the same applies for the quick view, which will be yet another type scaffolded by the scaffolding tool. And, of course you can create your owns and it will be registered in with quick view navigator.

A

Then we also have a section, a method actually to render the property pane, and this is an interesting uh behavior for the generated code. We have the property pane stored in an external file, so there is a dedicated class this one in which we still render with the same uh behavior. We are used to using in any sharepoint framework web part, but we are rendering here the groups of properties and the fields that we want to make configurable in the ui of the property pane.

A

So again, these are the property pane fields that we see in this area in the property pane of the adaptive card extension. Okay.

A

So we have the extension, we have the properties, we define uh the card that will be rendered by default as the initial one and in this uh auto generated and folded solution, the card view id the only one that we have will be the one provided by the render card and, as such, the rendering of the ui of our ace will render this object, in instance of this class the card view which again extends a base type right now we are using the base primary texture view, because I made the choice to use the primary text flavor when I scaffolded the solution, but we'll see that there are additional options that we can choose from and again.

A

This cardview component extends this type, providing the type of the properties and of the state that will be used to manage and to provide property state to the uh current component and, as you may notice, these interfaces are exactly those that I defined in the extension class. In fact, those are exported and imported right here in these.

A

Oh sorry, in this card view source code file, you see import and I'm importing those files from the extensions meaning that they are exactly the same interfaces and that's because and again we will go deeper on this topic in one of the coming sequels. But again we are sharing the same properties in the same state across all of the card views and all of the quick views in your adapted card extensions.

A

So the properties and the state of the main extensions are also available and shared with all of the car's views, and you will see also with all of the quick views now in the card view, we have a pre-defined rendering provided by microsoft. We have three different flavors and, depending on the choice we will make, we will have a specific rendering for the card view. This one will simply render a text message.

A

In fact, if we go back to the ui, you can see that we just have a title and a text and eventually can render one or two buttons no more than that, either one or two buttons. How does it work? Well, we have a get card, buttons method, that we will be invoked by the spfx infrastructure and the result can be undefined or one I card button instance or an array of two I card button instances, meaning that we can return one button, two buttons or no buttons.

A

A single button will be defined, providing the type of the action that we want to associate with the button and right now, the action that we have is quick view, meaning show a quick view which one the one with the id that we registered defining our adaptive card extension right here.

A

So at the very end, it means by clicking on this button, simply render the quick view which is defined here in yet another class, the quick view class, which again inherits from a specific base class, the base, adaptive card view and again and one more time it leverages the same. Exactly the same properties and state interfaces that we defined in the adaptive card, extensions that we saw first so again, the properties and the state are shared. With this quick view and with any other quick view that we have in this adaptive.

A

Cab extension, but whenever you create a quickview, you also have the option to provide another interface, which will define a specific container of data which will be used to render the ui of the quick view. This is a fully customizable interface and again this folded.

A

One simply provides a subtitle, a title and description, and the purpose of this interface is that we have a get data method provided by the quick view class, which will simply return an instance of this interface and which will be used by the adapter card json associated with the quickview in which we are for rendering the actual ui of the quick field. So here we say in the get template method that the template for this quick view is defined in this json file.

A

If we have a look to this json file, we can see that it is based on the adaptica json schema.

A

Actually, this is based on version 1.2 and we can go up to 1.3 in the electric card extensions built with spfx, so you can use the skin the syntax of the adaptive card, json schema, and here we simply define through the adapter card syntax, that we have a card with a specific body which will have a text block in a bolder text which will render the title property of the interface that we defined here. So this property, which means this value, which will come from the resources of our sharepoint framework solution.

A

And then we say that we have a column set in which we want to render just one column with yet another text block still boulder, which will render the subtitle of the object that we defined in the quick view. So this property and last but not least, we render one last text block with the description still coming from the quick view. Data type definition so really simple.

A

If you think about that, it will be scaffolded for you, but it will be in a card extension extending this base type based on a set of properties and state objects. You can then render one or more card views that you will have to register with the card navigator.

A

You can render one or more actually zero more, because you could even have an ace without a quick view. At least you can.

A

Rather, if you want one quick view, creating a type in editing from base adapter card view and still providing properties in state and providing optional interface for additional data that you will render through data binding in the json of the adaptive card, that you are rendering right here and the sharepoint framework infrastructure will take care for you to do the actual rendering of the adaptive card extension and it will take care of providing the mobile experience or the desktop experience in the viva connection, desktop ui for your adaptive card extension.

A

I think that's all on my side, I'm three minutes ahead of schedule, which is not bad. Today we had a goal to finish on time. We might even finish few seconds before, which is not bad. I think so.

A

I don't know if there are any questions in the chat, because I don't see it and if not, I can give the stage back to you, patrick awesome stuff. Thank you. Paulo.