Wednesday, May 25, 2022

Teams Real Simple with Pictures: Setting up Viva Connections – From Scratch, End to End

This blog is part of a series on Teams. For more articles, check back often

Written: 01/05/2021 | Updated: N/A

If you haven’t already, you’ll hear a lot about Viva in the coming months. Viva – from the Latin vivere ‘to live’ is a set of apps designed to enhance employee experience. In layman’s terms, they’re made to make your day to day work life better, easier and richer so that you are (in theory) happier, more productive and (in theory) more loyal to the organisation. The idea is that you feel invested in. The organisation thinks about you and how best to support you in your role. Now, there are four apps or ‘modules’ which constitute Viva with more expected in the future. The first is Viva Topics, an AI powered app which organizes content and expertise into related ‘topics’ surfaced across existing apps such as Yammer and Microsoft Teams. You want to know what that specific acronym means? Or what that project is all about? Topics will show you a description of that, who is working on it and assets related to it. The idea being that knowledge is to hand without breaking the course of your workflow. You then have Viva Insights, an app which brings together MyAnalytics and Workplace Analytics providing data-driven insights and recommendations to improve productivity and wellbeing. In other words it’ll show you things like how much focus time you have and how long you have been working out of hours. It’ll show managers how their team members are working together. It’s also expected to include Headspace demoed to much fanfare back at Ignite last October. Third, you have Viva Learning, ‘a hub for Learning’ within Teams aggregating on demand assets from Learn, LinkedIn Learning, third party providers like EDX and a company’s own content. This is currently in preview and won’t be in GA until later this year. Finally – and what the discussion concerns today, is Viva Connections. Connections is described as being ‘the gateway to a modern employee experience’ and ‘a curated, company-branded experience that brings together relevant news, conversations, and other resources’. It is, more or less, a SharePoint home site surfaced into Teams pinned on the app rail and which will have a mobile experience later in the summer. Unlike the other apps, Connections is completely free and GA making it ideal as the first Viva app for any organisation to get to grips with without having to invest more into licencing – and it is important insofar it fuses SharePoint and Teams even closer together. To many who haven’t tried this previously through App Studio, it’s exciting stuff.

But I’m going to write this one with a twist. I have seen a few blogs on connections go up since it’s release, but since I work primarily in the SMB space, where organisations haven’t even deployed a communications site, let alone use Powershell, I thought I just would go through it all end to end, step by step from scratch. It’s not hard. Honestly.

This blog will cover

  • Adding a Communication Site
  • Downloading and Installing SharePoint Powershell Module
  • Setting the Communications Site as the SharePoint Home Site
  • Sharing the SharePoint Home Site
  • Enabling Global Navigation Links in the SharePoint App Bar
  • Creating the Viva Connections App Package
  • Uploading the App Package into the Teams Admin Centre
  • Setting the App into the App Setup Policy


  • SharePoint Administrator & Teams Administrator (Or Global Administrator Permissions)
  • Latest SharePoint PowerShell Module Installed (will be shown in this article)
  • Viva Connections for Desktop Powershell script
  • Two png icons. A 192 x 192 pixel coloured icon for Teams app catalogue and a 32×32 pixel monochrome icon for Teams app bar. This is for when the App is created later on
  • The SharePoint admin who creates the Viva Connections desktop package needs site owner permissions (or higher) to the home site in SharePoint.


We begin by creating a Communications Site in SharePoint. This is the site that will be converted into a home site and that users will ultimately land on when they click on the connections app in Microsoft Teams

1.) Log into with admin credentials

2.) Select Admin on the left navigation

3.) On the left navigation select Show All and then select SharePoint for the SharePoint Admin Centre

4.) Select Sites, then Active Sites then Create

5.) Select Communication Site

6.) Set a Site Name (In this example I used Home), add a Site Owner and a Language, then select Finish

7.) The site is now created. Click on the URL to make sure it is deployed

At this point, you may want to consider adding content to your communication site or customising the visuals

An important point to add here – at this point – is that before proceeding with the rest of the setup it is recommended to have the SharePoint App Bar available and visible on the left hand side of the Communication site. At the time of writing it’s currently rolling out and its the reason I decided to wait a few weeks before doing the rest of this blog. Why is it important? Because current best practice by Microsoft states that global navigation and customize navigational links in the app bar should be completed before the connections app package is installed


Now we have deployed the communication site and have the SharePoint App Bar visible. we need the SharePoint PowerShell Module to convert the communication site to a home site. Before installing the newest version of Powershell, ensure you have removed any older versions of the module, otherwise it will error upon installation

1.) Go to and select Download

2.) Accept the terms and Install the module. Select Finish once complete


We now need to configure the communications site we deployed as the home site.

1.) To open the SharePoint Online Management Shell command prompt, from the Start screen, type SharePoint, and then click Run as Administrator under SharePoint Online Management Shell

2.) This will open the session

7.) Enter the following commands in sequence to initiate the session. You will be asked for admin credentials during the process



$userCredential = Get-Credential -UserName $adminUPN -Message “Type the password.”

Connect-SPOService -Url https://$ -Credential $userCredential

8.) To set the communications site as the home site, take the URL from the communications site deployed earlier and enter the following command

Set-SPOHomeSite -HomeSiteUrl <siteUrl>

As in Set-SPOHomeSite -HomeSiteUrl

9.) Enter Y for Yes and continue

10.) As confirmed in the session, and as per Microsoft documentation, it may take some time to change (image 1) and this example took several minutes. Periodically check that the SharePoint Home Site change has taken place via the command Get-SPOHomeSite (image 2)


Now that the SharePoint Home Site has been created, we need to share it with everyone in the organisation

1.) Return to the SharePoint Site page and in the top right hand corner select Share

2.) Search for and select Everyone Except External Users, set the permissions (Full Access/Read/Edit), type a message if required and select Share

The home site has now been shared with all users in the organisation. In this example, read permissions have been granted


The SharePoint app bar brings together intranet resources and personalized content like sites, news, and files. Enabling global navigation allows users to easily navigate to important intranet resources anywhere in SharePoint. Getting to other SharePoint pages and navigating the organisations intranet will be important for the user experience as users begin to use the Connections app in Microsoft Teams. If global navigation is not enabled, the home icon on the app bar will simply navigate back to the SharePoint start page

1.) On the communication site select Cog (Settings), then Global Navigation

2.) Swipe Enable Global Navigation to On

3.) Add a logo if you want to replace the home icon on the SharePoint app bar (png, 20 x 20 pixels), set a title which will be displayed at the top of the navigation, and set whether you want to use home site navigation or hub or global navigation (this example uses hub or global navigation). Once done select Save

4.) The home icon in the app bar will now show the global navigation window rather than redirecting back to the SharePoint Start page. Note, per Microsoft documentation this may take up to 24 hours to populate and from experience flips back and forth between the two for a period


Now that the Communication site is set as a Home site, and global navigation is configured for the SharePoint App Bar, let’s head back to Powershell and create the Viva Connections App. But first

1.) Go to and then download the Viva Connections script

2.) Keep the script together in a place such as OneDrive along with the two png icons. One of these needs to be 192 x 192 for the Teams App store and the other – 32 x 32 monochrome – needs to be for the app rail. You can use an app such as to be able to amend existing icons so they fit these sizes and file formats

3.) Extract/copy the script viva-connections-desktop.ps1 into a folder such as C:

4.) In the SharePoint PowerShell module, run the script using the file location. I have the script in C: so I set this in the shell with the command

& “C:Viva-connections-desktop.ps1”

Now, per Microsoft documentation you need to provide the following

  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 Home site of the tenant.
  2. Name: The name of your app, as it should appear in Teams app bar
  3. App short description (80 characters): A short description for your app which will appear in Teams app catalog
  4. App long description (4000 characters): A long description for your app which will appear in Teams app catalog
  5. 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.
  6. 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.
  7. Organization name: Your organization name. This will be visible on the app page in Teams app catalog in “Created By” section.
  8. 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.
  9. 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.

5.) A nice little welcome. Let’s go through this. Add the URL of the Home Site deployed earlier and press Enter. You may need to login during this process with admin credentials

6.) Now add the name of the app. This example will use Connections

7.) Enter a short description for the app. This example will use Microsoft Viva Connections

8.) Enter a long description for the app. This example will use some blurb based on the short description

9.) Set a URL of your privacy policy or press Enter to use the default from Microsoft. This example uses default

10.) Same with the Teams of Use. This example uses default

11.) Provide your organisations name and Enter

12.) Provide your organisations public website URL. This example uses

13.) Upload your icons – which you are helped with as PowerShell opens Explorer for you to select the icons which should be in a place such as OneDrive – and once done, the app is created

14.) The app, at least in this example, is in a zip file on the desktop ready to go which contains the manifest and which needs to be uploaded into the Teams Admin Centre

Great work! Now, there are a few blogs out there which have outlined that this can be done using a single PNP cmdlet which is awesome if you are into PNP. You can find more information here:


We are now on the downhill. The zip file containing the manifest needs to be uploaded into the Teams Admin Centre

1.) Login into with admin credentials and select Admin from the left rail

2.) In the Microsoft 365 Admin Centre on the left Navigation select Show All then select Teams

3.) In the Teams Admin Centre select Teams Apps then Manage Apps

4.) Select Upload

5.) Select a File and choose the zip file which was created previously

6.) The app is now confirmed as uploaded and browse through the list to ensure it is published

7.) To ensure that the app will be visible in Teams and users will be able to use it navigate to Permission Policies and ensure that Custom Apps is either allow all or that the app is added to the allow specific apps list. Also ensure that Custom Apps are turned on in Org Wide App Settings within Managed Apps


The last step is putting the app in an app setup policy which makes it appear in a prominent place on the app rail when users are using Teams.

1.) In the Teams Admin Centre select Teams Apps and then Setup Policies

2.) Select the policy to amend. Your organisation may have several policies to amend if they deviate from the global org wide default. This example will use the global org wide default

3.) Scroll down to the section Pinned Apps and select Add Apps

4.) Search for, find the app and select Add

5.) Select the app, move it to the top and then select Save


Our job here is done.

  • Communication site setup
  • SharePoint PowerShell Module installed
  • Communication site converted to a home site
  • Home site shared out to the organisation
  • Global Navigation enabled on the SharePoint App bar
  • Viva Connections app package created
  • Viva Connections uploaded to the Teams Admin Centre
  • App Permissions and App Setup Policy set

As you can see Viva connections is now working fully within Teams, as well as the SharePoint App Bar (from clicking on the Connections app in the app rail when the app is in use. Looks good.

Chris Hoard
I am interested in literally everything across the Microsoft 365 stack including Exchange, SharePoint, OneDrive, Stream, Yammer, Forms, Flow, Power BI, Azure AD, Microsoft Threat Protection and Intune.

Related Articles

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Stay Connected


Subscribe to our newsletter

To be updated with all the latest news, offers and special announcements.

Latest Articles