Bring your Teams provisioning order form and approvals where they matter the most — Part 1

When we build custom Teams provisioning solutions, we quite often utilise the out-of-the-box SharePoint list forms — or forms built with SharePoint Framework if the customer needs something a bit more advanced. Both of them are quick to make, offer an ample amount of complex-enough input controls, have a consistent look-and-feel, and are easy to place to several locations. A typical place for showing the form has been a page somewhere in the company’s SharePoint Online intranet.

We also often have an approval step as a part of our provisioning process. Traditionally, an adaptive card with Approve and Reject buttons has been sent in an email to the approvers’ inbox which they’ve then been able to handle via Outlook.

At one point, I started to wonder, why do we need to involve these different products (SharePoint and Outlook) when all we want to do is to set up a new team correctly and consistently? Wouldn’t it be great if we could remain within Microsoft Teams while utilising the custom team provisioning process?

Good news: we can! In this short blog post series, I’ll show you:

• Part 1: How to include the SharePoint out-of-the-box list form in the Microsoft Teams user interface so that it is available to everyone, no matter which teams they belong to. (this article)
• Part 2: How the approvers can approve the orders right within Microsoft Teams

Adding the workspace order form in Microsoft Teams

There are several ways of how you can display a SharePoint list form in Microsoft Teams.

• You can use the SharePoint tab on a team channel to display a page or a list from the SharePoint site that is connected to the team. You could, for example, display the SharePoint list that contains the orders, and users could click on New to place new orders. Or you could embed the list form on a SharePoint page and display that page on the tab.
• If you want to display a form on a team channel from some other site than the one connected to the team, you can use the Website tab.
• And if you want to display the form so that it is not under any particular team, you can create a personal Teams app using the App Studio, have it display the list form, and add the app to the left-hand side navigation for everyone to see and use.

Most people are probably already familiar with the first two options. You have a team, you add either the SharePoint or website tab to a channel, and configure it to show the list or the form. Simple. The downside of this approach is that it requires all the users who need to be able to order new teams to be members of that team. Also, a tab within a specific channel can be a bit hidden: you don’t necessarily even notice it is there before someone else points it out to you.

Creating a personal Teams app to display the order form avoids these issues. The form is accessible through the left-hand side navigation in Microsoft Teams, which makes it very visible and also available to everyone — no need to be a member of a specific team. Setting it up requires a bit more effort, though, but hey, that’s why I’m here guiding you through the process! 🙂

Creating the Teams app

There are two ways for you to create the Teams app: by using the App studio or by manually editing a JSON file. On the first time, you might find it easier to use App studio, but when you know what you are doing, writing the JSON and doing the packaging by hand is a lot quicker. I’ll walk you through App studio first, and show you an example of the JSON after that.

1. In Teams, click on the three dots in the left-hand side navigation.
2. Search for App studio, and Add (or Open if you’ve already previously added the app for yourself). If you can’t find App studio, it is disabled in the tenant. In such a situation, you need to create the package in a different tenant, such as your own developer tenant, or do the packaging manually.
3. Go to the Manifest editor tab and click on Create a new app. Fill in at least the required information:
   • Short name: For example Orders. This shold be very short because it gets displayed in the left-hand side navigation.
   • App ID: Generate a random GUID for this field.
   • Package name: com.microsoft.teams.yourcompany
   • Version: 1.0.0. If you later need to update this app manifest, you need to increase this version number before you are able to install the new version to the app catalogue again.
   • Short description: For example, Teams Order Form
   • Full description: For example, Displays the order form for the custom Teams provisioning process.
   • Developer info:
     • Name: your or your company’s/employer’s name
     • Website: Your or your employer’s website
     • Privacy statement and Terms of use: does your app or company have a privacy statement and terms of use? If not, just give random URLs
   • Branding: Create 192×192 and 32×32 sized images for the app logo that will be visible in Teams. The transparent outline logo will be shown if you pin the app in the Teams left navigation. The full-colour logo will be used everywhere else. The accent colour should be set to be the same as the background colour for your primary icon. I tend to use #6264a7 as the accent colour.
4. Go to the Tabs section (under capabilities), and add a personal tab.
   • Name: The display name of the tab in your app, e.g. A new team order. If your form has a title, it would be good if the tab name matches the title.
   • Entity ID: Generate a random GUID for this field.
   • Content URL: https://yourcompany.sharepoint.com/sites/yoursite/_layouts/15/teamslogon.aspx?SPFX=true&dest=/sites/yoursite/Lists/yourlist/NewForm.aspx
   • Website URL: https://yourcompany.sharepoint.com/sites/yoursite/Lists/yourlist/NewForm.aspx
5. Go to Domains and permissions (under Finish) and fill in the following info.
   • AAD App ID: 00000003-0000-0ff1-ce00-000000000000
   • Single-Sign-On: https://yourcompany.sharepoint.com
6. Go to Test and Distribute and download the app package (zip).

Here’s also an example of the JSON file App studio generates based on the information you enter via the UI. You can copy the JSON below as a base, edit it and then package it into a zip file with the two icon images.

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.5/MicrosoftTeams.schema.json",
    "manifestVersion": "1.5",
    "version": "1.0.0",
    "id": "GENERATE A RANDOM GUID FOR THIS FIELD",
    "packageName": "com.microsoft.teams.yourcompany",
    "developer": {
        "name": "Your Company",
        "websiteUrl": "https://yourcompany.com",
        "privacyUrl": "https://yourcompany.com/privacy",
        "termsOfUseUrl": "https://yourcompany.com/terms"
    },
    "icons": {
        "color": "your-full-color-image-192x192.png",
        "outline": "your-transparent-outline-image-32x32.png"
    },
    "name": {
        "short": "Orders",
        "full": ""
    },
    "description": {
        "short": "Teams Order Form",
        "full": "Displays the order form for the custom teams provisioning process."
    },
    "accentColor": "#6264A7",
    "staticTabs": [
        {
            "entityId": "GENERATE A RANDOM GUID FOR THIS FIELD",
            "name": "New Team Order",
            "contentUrl": "https://yourcompany.sharepoint.com/sites/yoursite/_layouts/15/teamslogon.aspx?SPFX=true&dest=/sites/yoursite/Lists/yourlist/NewForm.aspx",
            "websiteUrl": "https://yourcompany.sharepoint.com/sites/yoursite/Lists/yourlist/NewForm.aspx",
            "scopes": [
                "personal"
            ]
        }
    ],
    "permissions": [
        "identity",
        "messageTeamMembers"
    ],
    "validDomains": [
        "yourcompany.sharepoint.com"
    ],
    "webApplicationInfo": {
        "id": "00000003-0000-0ff1-ce00-000000000000",
        "resource": "https://yourcompany.sharepoint.com"
    }
}

I like to reference the NewForm.aspx directly because it displays the form in full height (left picture). If you embed the form on a SharePoint page and display the page in the app, the area for displaying the form is a lot smaller, and your users will need to scroll to be able to fill in all the fields (right picture). However, some customers want to include a long general instruction text on the form, in which case embedding a page that also contains a Text web part is the way to go — unless they’d rather have you create an SPFx web part to avoid the scrollbar issue.

Click to enlarge

Installing the form app to the tenant

When you’ve built the zip package one way or another, you need to deploy it to your tenant. As a Teams administrator, do the following:

1. In Teams, go to Apps and Upload a custom app for the tenant. Select to upload the zip package we just created.
2. If you want to test the app before you push it to all users, you can now add it for yourself by clicking on the three dots in the left-hand navigation in Teams, and searching for your app by its name.
3. After you’ve successfully uploaded (and tested) the app, go to the Teams admin center and navigate Teams apps → Setup policies
4. Edit the Global policy and add your app as one of the apps displayed in the left-hand navigation. You can also decide in which order you want the icons to appear.
5. It will take a few hours for the app to become visible to all users.

Afterword

The Teams left-hand navigation is by far my favourite spot for placing a Teams order form these days. As I mentioned in the beginning, in addition to displaying out-of-the-box SharePoint list forms, I’ve also used this method for displaying custom order forms that I’ve built with SPFx and placed on a SharePoint page. Works like a charm as well!

Next time, in part two of this blog post series, we will take a look at approvals and what it takes to move them from Outlook to Microsoft Teams. Stay tuned!

As always, thank you for reading my blog, I greatly appreciate it. If you have any questions or comments, feel free to write them below. Also, if you’d like to hear from me outside of these blog posts, make sure to follow me on Twitter, Github, LinkedIn and YouTube. And if you want to receive some extra special content, order my (news)letter where I’ll talk about other timely topics. You can find the opt-in form in the side bar.

Other than that, take care and until next time!

Laura