Deployment guide - OfficeDev/microsoft-teams-apps-requestateam GitHub Wiki

Prerequisites

To begin, you will need:

  • Power Apps Studio
  • Power Automate
  • Azure Subscription with Global Administrator access level
  • Service account with Power Apps, Power Automate, Teams, SharePoint and Exchange Licenses (must have an Exchange mailbox). This Service Account is used by Logic Apps to connect to SharePoint, send e-mails and post a welcome message to Teams. The account requires User permissions only and does NOT need to be a Global Administrator.
  • SharePoint
  • Office 365 Groups connector
  • A copy of the Request-a-team app zip package

Step 1: Deployment Script

Please follow the steps below to execute the deployment script which will create and configure the SharePoint site and Azure resources (Azure AD App registration, Logic Apps and Key Vault).

  1. Download the latest release

  2. Open PowerShell as an administrator and navigate to deploy.ps1 on your local machine.

  3. Before running the script, some installations are needed for the user who is running the script for the first time. Please find the steps below:

    • In the above-navigated path in PowerShell, run the command "Set-ExecutionPolicy -ExecutionPolicy unrestricted". This command will allow the user to run deploy.ps1 as the execution policy is restricted by default. You can change this back to restricted after the deployment.
    • Install Azure CLI module by running the command below: "Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile .\AzureCLI.msi; Start-Process msiexec.exe -Wait -ArgumentList '/I AzureCLI.msi /quiet'"
    • Reboot the machine after installing the CLI.
    • Open a new PowerShell window as an administrator. Go to the path of deploy.ps1 script file.

  4. Execute the following script (make sure to specify all parameters with your own values)

The script requires the following parameters:

  • TenantName - Name of the tenant to deploy to (excluding onmicrosoft.com) e.g. contoso

  • TenantId - Id of the tenant to deploy to (If you are not sure how to get Tenant ID, please check Azure Active Directory in Azure Portal. Under Manage, click Properties. The tenant ID is shown in the Directory ID box).

  • RequestsSiteName - Name of the SharePoint site to store the requests, can include spaces (URL/Alias automatically generated). If the site exists, it will prompt to overwrite and will apply the provisioning template.

  • RequestsSiteDesc - Description of the site that will be created above.

  • ManagedPath - Managed path configured in the tenant e.g. 'sites' or 'teams' (no forward slash).

  • SubscriptionId - Azure subscription to deploy the solution to (MUST be associated with the Azure AD of the Office 365 tenant that you wish to deploy this solution to.)

  • Location - Azure region in which to create the resources. The internal name should be used e.g. uksouth. The location MUST support Automation and Logic Apps. See Valid Azure Locations.

Please DO NOT enter spaces in the location name or the logic apps will fail post deployment. It should be all one word e.g. uksouth.

  • ResourceGroupName - Name for a new resource group to deploy the solution to - the script will create this resource group.

  • AppName - Name for the Azure AD app that will be created e.g. Request-a-team.

  • ServiceAccountUPN - UPN of Service Account to be used for the solution - used to connect the Logic App API connections. Service account is nothing but an Office 365 user who has Teams licenses enabled. Refer Assign a Teams license to know more details.

  • IsEdu - Specifies whether the current tenant is an Education tenant. If set to true, the Education Teams Templates will be deployed. These will be skipped if set to false or left blank.

  • KeyVaultName - Name to use for the Key Vault that is provisioned by the deployment script. The Key Vault stores the app id and secret of the Azure AD app that this solution uses. This ensures that these are held securely. The name of the key vault must be unique and cannot be used already in an existing Azure subscription (globally). The script will validate that the name is available and if not, an alternative name will need to be provided.

  • TenantId : This will be asked as a parameter when you run the script. (If you are not sure how to get Tenant ID, please check Azure Active Directory in Azure Portal. Under Manage, click Properties. The tenant ID is shown in the Directory ID box.)

  • EnableSensitivity: Enable the Sensitivity Label functionality. See Sensitivity Labels. Note - this will require you to have a Service Account with NO MFA, this can be the same service account as above if you wish.

>.\deploy.ps1 -TenantName "M365x023142" -TenantID "xxxxxxxx-xxxx-xxx-xxxxxxxxxxx" -RequestsSiteName "Request a team app" -RequestsSiteDesc "Used to store Teams Requests" -ManagedPath "sites" -SubscriptionId 7ed1653b-228c-4d26-a0c0-2cd164xxxxxx -Location "westus" -ResourceGroupName "teamsgovernanceapp-rg" -AppName "Requestateamapp" -ServiceAccountUPN "[email protected]" -IsEdu $false -KeyVaultName "requestateam-kv" -EnableSensitivity $false

The script will prompt for authentication during execution. Please login using a Global Administrator account except for the prompts below.

  1. When the script asks for the Service Account password, please enter the password for your Service Account created earlier.*

  2. When the message "LOGIC APP CONNECTIONS AUTHORIZATION" is displayed, login to any authentication prompts using the Service Account specified above.*

  3. When the script has completed a "DEPLOYMENT COMPLETED SUCCESSFULLY" message will be displayed.

  4. Navigate to the newly created SharePoint site and click on 'Site Contents' located on the left-hand navigation and confirm that there are 3 SharePoint lists created successfully (Teams Requests, Teams Templates and Team Request Settings).

Register Azure AD app as a SharePoint add-in

This step is required for the solution to check if the requested Team exists before creation.

  1. Enabling ACS -

This solution relies on ACS to work which has been retired but is still available. For tenants created after August 2020, the option to use an ACS app-only token is disabled and this MUST be enabled to work. More details can be found here - Granting access using SharePoint App-Only.

  1. Before proceeding further, enable ACS on the tenant by carrying out the following steps below:

    • Using the PnP PowerShell module (the script will have installed this), connect to your SharePoint tenant admin center using the following cmdlet: Connect-PnPOnline -Url "https://yourtenantname-admin.sharepoint.com" -Interactive
    • Run the following cmdlet: Set-PnPTenant -DisableCustomAppAuthentication $false
    • Wait 1 hour to allow this setting to be applied.

  2. Navigate to the following page in the SharePoint Admin Center - https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx and enter the following information (replace contoso with the name of your tenant):

    • App Id: Application ID of the Azure AD app (Locate the Azure AD app created by the deployment script in Azure Active Directory and copy the Application ID).
    • Click 'Lookup'
    • In the 'App Domain' text box, enter a suitable domain. You can specify any domain you want but do not include protocols (https) or slashes(/). For example you can use your companies SharePoint URL e.g. contoso.sharepoint.com.
    • In the App's Permissions Request XML text box, enter the following XML -

<AppPermissionRequests AllowAppOnlyPolicy="true"> <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" /> </AppPermissionRequests>

  1. Click 'Create'

Notes:

  • If PowerShell script errors during execution, check if the resource group and SharePoint site is created. If created, please consider deleting them before running the script again.

  • Please copy the name of the site as it will be used in further steps.

  • Please share the SharePoint site to Request-a-team application admins by adding them as Owners, so that they would be able to Approve requests from Power Apps and would see all requests.

  • Please share the SharePoint site to all Request-a-team application users by adding them as Members.

Deployment script errors/issues

The following errors can occur when running the deployment script. If you receive any of these errors, please follow the steps listed to resolve them.

Logic app connections failed to authorise - Status=Error

If you receive any of the following error messages when signing in as the service account to authorize the logic apps, please follow the steps below to authorize the connections manually in the Azure portal.

Connection requestateam-spo now @{status=Error;target=token;error=}

Connection requestateam-o365outlook now @{status=Error;target=token;error=}

Connection requestateam-o365users now @{status=Error;target=token;error=}

Connection requestateam-teams now @{status=Error;target=token;error=}

API connection authorization error

  1. Launch the Azure portal and sign in as a Global Administrator.
  2. Locate the 'API Connections' blade - use the search box at the top and search for 'API Connections'.

API connections blade

  1. Click on the name of the connection that displayed the error message e.g. requestateam-spo.
  2. Click 'Edit API connection' on the left menu.
  3. Click the blue 'Authorize' button.

Authorizing API connection

  1. Sign in with the Service Account that you specified when running the script.
  2. Click the 'Save' button
  3. Repeat this process for each connection that displayed an error status.

The API connections are now authorised and the Logic Apps will function correctly.

Step 2: Create Admin group

Please ignore this step from 1-7 if you already have a team of admins(who have the privilege to manage approval and rejection of team creation requests) and continue with #8.

  1. Open Teams desktop app or open https://teams.microsoft.com/go#

  2. Click on the Teams tab in the left menu bar

  3. Click on Join or create team > click Create team button

  4. Select Build your team from scratch > Select Private

  5. Provide Team name and description > Click Next

  6. After that a popup will open where you need to add members in your created team. Add all the members and then close the popup.

  7. Confirm if a new team is created successfully.

  8. Next to the team name, click on the "..." and select "Get link to team".

    Create Team

  9. Click on "Copy" to copy the link to clipboard.

    Copy Team ID

  10. Get the groupID and channelID query string value as shown below:

    Get Channel ID from query string

tip: you can try online decoder to decode channel ID

  1. Copy the groupId and channelId as it will be used in further steps.

  2. Navigate to Team Request Settings list and edit TeamsTeamID and TeamsChannelID rows and In the 'value' column of these rows, add the copied groupID and channelID under TeamsTeamID and TeamsChannelID respectively.

    Set Team ID and Channel ID in settings

Step 3: Importing the Power App

NOTE - The below steps MUST be done under the context of the Service Account i.e. login as the Service Account to import the app and create/configure the connections. Once imported you may share the app with other admins/makers who required edit access.

  1. Navigate to Power Apps. Click here

  2. Click on Apps in the left side pane and click on Import canvas app.

    Request a team step 1

  3. Download the package zip file and click Import.

    Request a team step 2

  4. Under Related resources, you will be required to change the SharePoint connections. Click on wrench icon for SharePoint connection > Create new (you will be redirected to a new tab) > Click on SharePoint > switch back to main tab > click Refresh list > select name > Save.

  5. Click on Import button.

    Request a team set up step 3 for import

Configuring the Power App

  1. Click on Open app link when zip package is successfully imported. You will be redirected to Power Apps portal.

  2. Click on Open menu at the left side > Power Apps > Request-a-team App which you have imported.

  3. The app will request your permission to use all the listed data connections.

    Request a team Permission

  4. Once the app opens, click the Data pane on the left menu (database symbol). Remove the three existing demo SharePoint connections by clicking on "..." and remove. This ensures that the dummy SharePoint connections are removed, and the app is ready to connect to your SharePoint site.

  5. Click Add data, search for SharePoint and click on the connection.

    Edit SharePoint connection

  6. Enter the URL for the Request-A-team SharePoint site in the pop-up window.

    Enter SharePoint site URL

  7. Choose the 'Teams Requests', 'Teams Templates', 'Team Request Settings', 'IP Labels' lists and click Connect.

    Select Teams Template

  8. Click on the Tree view pane on the left menu and select the App object. Locate the 'OnStart' function in the formula bar, paste the groupId of the admin group which you have created and saved previously.

    Power Apps OnStart

Step 4: Import and Configure the the Power Automate Flows

  1. Navigate to https://flow.microsoft.com using an account with 'Maker' permissions. Ideally use the Service Account above so that all flows are owned by this account.
  2. Click My Flows > Import.
  3. Browse to the file location of the provided flow package - TeamRequestApproval.zip.
  4. Update the Outlook Office 365, SharePoint and Approvals connection to use an existing connection or create new ones. Under Related resources, you will be required to change the connection. Click on wrench icon for SharePoint connection > Create new (you will be redirected to a new tab) > Click on SharePoint > switch back to main tab > click Refresh list > select name > Save.
  5. Click Import.

Configuring Flows and Logic App

Team Request Approval

  1. Navigate to My Flows.
  2. Select the 'Team Request Approval' flow.
  3. Click 'Edit'.
  4. Update SharePoint site address for the trigger “When a team request item is submitted” to the URL of your SharePoint site for Request-a-team. Clear the value in the 'List Name' box and reselect the 'Teams Requests' list.
  5. Update the value for the 'Teams Request Site URL variable to the URL of the Request-a-team SharePoint site.

Edit Team Request Approval Flow

  1. Update the value of the 'Admin mail id' variable to a valid UPN of an admin who can approve requests (only used if you do not use the approval adaptive cards).
  2. Click Save
  3. Navigate back using the left arrow icon and turn on the flow by clicking 'Turn on' on the top menu bar.

Turn on Team Request Approval Flow

Check Team Availability

  1. Navigate to the Power Apps portal (https://make.powerapps.com/) and sign in.
  2. Select 'Flows' from the left menu.
  3. Select the 'Check Team Availability flow.
  4. Click 'Edit'.
  5. Update the value for the 'Teams Request Site URL variable to the URL of the Request-a-team SharePoint site.

Edit CheckTeamAvailability Flow

  1. Click Save
  2. Navigate back using the left arrow icon and turn on the flow by clicking 'Turn on' on the top menu bar.

Turn on CheckTeamAvailability Flow

Logic App

  1. Open the Azure portal and under the new resource group, search for the Logic App (ProcessTeamRequest). Edit the Logic App to confirm

    • SharePoint site address:

    Logic Apps step

    Logic Apps step 2

    • You can change the Interval and Frequency in first step When an item is created or modified in order to process team requests at given interval. It will execute to read all Approved team requests to create SharePoint. The default setting is 1 hour.

Step 5: Share Power App and SharePoint site

  1. An Admin needs to share the app to all individuals who will be using the app.

  2. Open https://make.preview.powerapps.com/

  3. Go to Apps menu in the left menu bar and you will be able to see the app you have imported.

    Power Apps menu bar

  4. Click on 3 dots (Options) for your app and click on Share.

  5. Enter the group name meant for users in the popup and click on Share. You can also add additional members if needed. This is required to allow members to access Request-a-team App.

  6. Share the SharePoint site to all admins and users

    • Please share the SharePoint site to Request-a-team application admins by adding them as Owners, so that they would be able to Approve requests from Power Apps and would see all requests.

    • Admin needs to share the SharePoint site to all individuals who will be using the app. For giving access of SharePoint site, please follow below steps:

    • Go to SharePoint site created during deployment > click on Settings icon at top right corner > click on the "Site permission":

    Share SharePoint Site

    • Click on "Advanced Permissions settings".

    • Click on the Grant Permission option from top menu bar and search the user name or type the email address of the user to whom you want to share the site.

    Share SharePoint Site

    Note: Every user accessing the app for the first time will be prompted to provide permissions to the App to access the SharePoint source. User should click on 'Allow' to proceed ahead.

Step 6: Install Teams Package

  1. Open https://make.preview.powerapps.com/

  2. Go to Apps menu in the left menu bar and you will be able to see the app you have imported.

  3. Click on 3 dots (Options) for your app and click on Add to Teams.

    Export application

  4. Click on Download App in the popup to download a zip package.

  5. Extract the contents of the zip file on your computer.

  6. Edit the manifest.json file and replace the value in the id property with the following id -

61b83224-8e49-44c0-961b-4d0b4c00d1db

The line should read as follows - "id": "61b83224-8e49-44c0-961b-4d0b4c00d1db",

Note - You only need to replace the line at the top of the manifest file, ignore any other places where this id appears.

  1. Save the file

  2. Re-zip the extracted files (manifest.json,color.png and outline.png) ensuring they are in the root of the zip file and not inside a subfolder.

Step 7: Adding app to Teams

  1. Go to Teams > Apps (in the left menu) > Upload a Custom App.

  2. Select the zip package from the previous step.

  3. Click on Add > Add to a team in the popup.

  4. Select a team or channel name.

  5. Click on Setup a tab.

    Set up as a tab

  6. The description for the app will be shown in the popup, click on Save.

  7. You will be able to see the app in the tab.

    Application in Teams

If you come across any issues using the App e.g. the 'Owners' and 'Members' combo boxes not working correctly, please follow the steps in the Troubleshooting guide.

NOTE - When making a request please ensure this is NOT done in the context of the Service Account AND that the Service Account is not requested to be a member or an owner of the team. If this happens then the provisioning will fail with the following error - "object '' can only be present once as an add/remove change"