Sunday, October 31, 2021

About the Viva-connections-desktop.ps1 script

When deploying Viva Connections according to the "Add the Viva Connections desktop app to Microsoft Teams" article, we eventually need to use a script referred to as the "VivaConnections for Teams desktop" script.

This script will create the Microsoft Teams app that can be pinned for all users to access Viva Connections. The script itself is called "Viva-connections-desktop.ps1" and it comes with a "" file to explain the settings needed and asked for by the script. This article will illustrate some of these settings.


Some troubleshooting to start with 

When you run the script it will first ask you which SharePoint site you want to use for Viva Connections and next try to login to SharePoint Online PowerShell for the tenant where this SharePoint site resides (and yes, it works with MFA accounts as well). So the script needs to run by a user who has "SharePoint admin privileges in the tenant" and also have access to the site you want pin as the default landing experience in Teams. It might happen that the connection command "Connect-SPOService" gives you an error message stating, "The term ‘Connect-SPOService’ is not recognized as the name of a cmdlet, function, script file, or operable program."

This can be due to several reasons, but the most common I found is that there are multiple versions of the SharePoint Online PowerShell module installed on the computer. This is easy to check with the command

Get-Module -ListAvailable *SharePoint*

If you find multiple modules of SharePoint Online PowerShell try to remove them with Uninstall-Module, like:

Uninstall-Module -Name SharePointPnPPowerShellOnline

And even if that does not work, there is a good explanation and solution in this blog article: The term‘Connect-SPOService’ is not recognized

The reason why no SharePoint Online PowerShell module need to be installed is that the script installs it for you as one of the first things happening in the script with the command:

Install-Module -Name Microsoft.Online.SharePoint.PowerShell -MinimumVersion 16.0.20324.12000 -Force


Running the script

The "" file gives us the following guidance:

When you run this script, you will have to provide the following inputs:

1. **URL of the modern SharePoint Communication site** (starting with “https://”) that you want to be the landing experience for the app. It is highly recommended that this site be the [Homesite] of the tenant.

1. **Name:** The name of your app, as it should appear in Teams app bar

1. **App short description (80 characters):** A short description for your app which will appear in Teams app catalog

1. **App long description (4000 characters):** A long description for your app which will appear in Teams app catalog

1. **Privacy policy:** The privacy policy for custom Teams apps in your company (needs to start with https://). If you do not have a separate privacy policy, press Enter and the script will use the default SharePoint privacy policy from Microsoft.

1. **Terms of use:** The terms of use for custom Teams apps in your company (needs to start with https://). If you do not have separate terms of use, press Enter and the script will use the default SharePoint terms of use from Microsoft.

1. **Organization name:** Your organization name. This will be visible on the app page in Teams app catalog in “Created By” section.

1. **Organization website:** Your organization’s public website (needs to start with https://). This will be linked to your company’s app name on the app page in in Teams app catalog in “Created By” section.

1. **Icons:** You are required to provided two PNG icons which will be used to represent your app in Teams; a 192X192 pixel colored icon for Teams app catalog and a 32X32 pixel monochrome icon for Teams app bar.

Once you successfully provide the details, a Teams app manifest, which is a `.zip file`, will be created and saved on your device.

Viva-connections-desktop.ps1 in action.

Besides the numbering being off there are a few things that needs to be mentioned. As you can see from the example above you do not need to use any quotes ("") for the text in the short or long description. Any URL must start with https:// and you need to have two icons for the app ready to be uploaded, more information on the purpose and format of these can be found here: Create a Microsoft Teams app package

Another very important point is that you do not absolutely HAVE TO provide all these details to this script, it is perfectly fine to provide "placeholder information" and then just edit the manifest.json file inside the .zip file created by the script at a later time. Maybe you do not want to type a 4000-character long description of the app in a PowerShell window? Also, the script will give the first and only "static tab" in the app the name Portals- +the name you entered as the name of the app, in this example it would be "Portals-Viva Connections" so you probably want to edit the manifest file for that anyway.

The first tab default named to Portals-App Name.


From the example above the app created will look like this when being loaded into Teams:

The Viva Connections app being added to Teams.

I would like to end this article with the last advice from the "" file which I really agree with:

We highly recommend that you pin this app by default for users in your tenant so that they can easily access their company’s intranet resources without having to discover the app in Teams app catalog. See Manage your apps in the Microsoft Teams admin center article for more details.

Enjoy your new Viva Connections App!