Inside the Viva Connections desktop app, or BYO Viva app

Yesterday Microsoft released the anticipated set of scripts required for you to add the Microsoft Viva Connections app to your Microsoft Teams environment. It’s a very simple approach that only requires you to download a PowerShell script, install the latest Microsoft SharePoint Online PowerShell module and then answer a set of questions, and voila you have the Viva Connections Desktop app ready for installation in Microsoft Teams.

Note: as the time of writing this and testing the PowerShell script, I was not able to download the required SharePoint Online PowerShell module and received an error while running the script. The latest module I could install/find did not have the Get-SPOIsCommSite cmdlet. However, it’s only required for validation that the site you specify is a Communications Site, and if you’re sure about this you can safely just comment out those lines in the beginning of the script.

So, what’s so special about this script? What do I do if I already created a Teams app for my SharePoint Online intranet? How can I add other Teams app features to the Viva Connections app? This is how my mind works and let me share the answer to most of these questions?

What’s the secret sauce with the script?

The script does not do any magic or fancy things. All it does is that it creates a Microsoft Teams app manifest, using schema 1.9, and creates the required .zip file with the colored and outline icon that you then upload to your Microsoft Teams app store. However, there are a few safeguards built in to the script to make the experience smooth if you’ve never built or configured a Teams app before. First of all it validates that the site you want to use is a SharePoint Communications Site and it helps you make the zip file, as well as it ensures you have all the required valid domains (to get the single-sign-on experience to work for instance).

What if I already have an Intranet Teams App for SharePoint?

If you do, then you’re in a great position. You can continue to use the app, but just update the manifest with a few items and then update the app. Your end-users will barely notice. Well, they will once they see some of the new features in Viva Connections.

The Viva Connections static tab

The core of the Viva Connections app is the static tab which points to your SharePoint Online Communications site. If you already deployed an Intranet app you probably already have this static tab defined - all you need to do is to update it with a few important parameters/settings. It should look like the following snippet:

"staticTabs": [
  {
    "entityId": "1c1636ef-d898-479b-97ab-b3400f1d70c9",
    "name": "Portals-Wiwa",
    "contentUrl": "https://contoso.sharepoint.com/_layouts/15/teamslogon.aspx?spfx=true&dest=https://contoso.sharepoint.com/sites/Home?app=portals",
    "websiteUrl": "https://contoso.sharepoint.com/sites/Home",
    "searchUrl": "https://contoso.sharepoint.com/sites/Home/_layouts/15/search.aspx?q={searchQuery}",
    "scopes": [
      "personal"
    ],
    "supportedPlatform": [
      "desktop"
    ]
  }
]

The contentUrl must have the parameter app=portals, this is the configuration that ensures that the SharePoint site is displayed with the navigation at the top and that the global navigation appears when clicking on the app icon in the Teams left rail. Without it you won’t see the header and you won’t have access to the global navigation. The websiteUrl isn’t really required, but that’s the fallback when opening the site outside of Teams. The searchUrl is also optional but gives the users the opportunity to search in the Teams search bar, and select to search in your Viva Connections app (unfortunately the search results opens up in an external browser). Finally scopes should be set to personal and supportedPlatforms should only have the desktop value (mobile and meeting devices are not supported).

So if you already have a static tab defined - ensure that you append the app=portals to the contentUrl in that existing tab. Keep the entityId and there will be no changes for your users.

NOTE: If you have an existing manifest you MUST update the version (and schema) to version 1.9 to support the required configurations.

Or - if you already have deployed a bot for instance into Teams, you can just add this new staticTabs entry to your existing Teams app.

NOTE: When updating an existing Teams app you need to increment the version number in the manifest file to avoid removing it and then adding it again.

Other important settings

To get Viva Connections (or any SharePoint site tab) to work you need to add a couple of additional configurations into your manifest to ensure that single-sign-on works and so that SharePoint can download scripts etc from the their CDN’s. The validDomains entry should look like the following urls, starting with your SharePoint domain name and then the by Microsoft required domains.

"validDomains": [
  "contoso.sharepoint.com",
  "*.login.microsoftonline.com",
  "*.sharepoint.com",
  "*.sharepoint-df.com",
  "spoppe-a.akamaihd.net",
  "spoprod-a.akamaihd.net",
  "resourceseng.blob.core.windows.net",
  "msft.spoppe.com"
]

You must also ensure that your webApplicationInfo entry looks like the following. It probably already does if you already have a SharePoint Intranet Teams App.

"webApplicationInfo": {
  "id": "00000003-0000-0ff1-ce00-000000000000",
  "resource": "https://contoso.sharepoint.com"
}

There’s on additional thing that you should configure/add to the manifest as well to ensure that you use the full real estate of Teams and that is to set isFullScreen to true.

What if I want to add more stuff to my Viva Connections app?

If you want to add a bot, a messaging extensions, configurable tabs or even meeting extensions - then just create a new Teams app and add the static tab as described above and ensure you have the other required configuration. You can for instance generate a full project using the Microsoft Teams app generator (yo teams) and then just modify the manifest.json file. Your imagination is the limit!

Summary

The buzz and hype around Microsoft Viva Connections has been huge over the last few weeks, and we can now finally take advantage of this experience! As described in this post you can just run the script and have your Connections app up and running in minutes, you can modify your existing SharePoint Intranet app in Teams to take advantage of the new Connections features or you can be innovative and bundle Viva Connections with your applications to amazing employee experiences.