To begin, you will need:

• An Azure subscription where you can create the following kinds of resources:
  • App service
  • App service plan
  • Bot channels registration
  • Application Insights
  • Azure SQL DB
• A team in Microsoft Teams with all users who will use Brainy.
• A team in Microsoft Teams with your group of managers.
• A copy of the Brainy GitHub repository

Register two Azure AD applications in your tenant's directory: one for the bot, and another for the configuration app.

1. Log in to the Azure Portal for your subscription, and go to the “App registrations” blade at https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps.

2. Click on "New registration", and create an Azure AD application.

   1. Name: The name of your Teams app - if you are following the template for a default deployment, we recommend "Brainy".
   2. Supported account types: Select "Accounts in any organizational directory"
   3. Leave the "Redirect URI" field blank.

   

3. Click on the "Register" button.

4. When the app is registered, you'll be taken to the app's "Overview" page. Copy the Application (client) ID; we will need it later. Verify that the "Supported account types" is set to Multiple organizations.

   

5. On the side rail in the Manage section, navigate to the "Certificates & secrets" section. In the Client secrets section, click on "+ New client secret". Add a description for the secret and select an expiry time. Click "Add".

   

6. Once the client secret is created, copy its Value; we will need it later.

7. Go back to “App registrations”, then repeat steps 2-3 to create another Azure AD application for the configuration app.

   1. Name: The name of your configuration app. We advise appending “Configuration” to the name of this app; for example, “Brainy Configuration”.
   2. Supported account types: Select "Account in this organizational directory only"
   3. Leave the "Redirect URI" field blank for now.

1. Click on the "Deploy to Azure" button below. When prompted, log in to your Azure subscription.

   

2. Azure will create a "Custom deployment" based on the ARM template and ask you to fill in the template parameters.

3. Select a subscription and resource group.

   • We recommend creating a new resource group.

4. Enter a "Base Resource Name", which the template uses to generate names for the other resources.

   • The app service names [Base Resource Name], [Base Resource Name]-config must be available. For example, if you select contosobrainy as the base name, the names contosobrainy, and contosobrainy-configmust be available (not taken); otherwise, the deployment will fail with a Conflict error.
   • The SQL server name [Base Resource Name].database.windows.net must be available. In addition, the username and password entered during deployment must adhere to the password policy.
   • Remember the base resource name that you selected. We will need it later.

5. Fill in the various IDs in the template:

   1. Bot App ID: The application (client) ID of the Microsoft Teams Bot app
   2. Bot App Password: The client secret of the Microsoft Teams Bot app
   3. Config App ID: The application (client) ID of the configuration app
   4. Tenant ID: The tenant ID where the bot will be restricted to

   Make sure that the values are copied as-is, with no extra spaces. The template checks that GUIDs are exactly 36 characters.

6. Fill in the "Config Admin UPN List", which is a semicolon-delimited list of users who will be allowed to access the configuration app.

   • For example, to allow Megan Bowen [email protected] and Adele Vance [email protected] to access the configuration app, set this parameter to [email protected];[email protected].
   • You can change this list later by going to the configuration app service's "Configuration" blade.

7. If you wish to change the app name, description, and icon from the defaults, modify the corresponding template parameters.

8. Agree to the Azure terms and conditions by clicking on the check box "I agree to the terms and conditions stated above" located at the bottom of the page.

9. Click on "Purchase" to start the deployment.

10. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal. Building the app can take a while for the initial deployment, so please be patient.

Technical note: the bot and the configuration page are built on the App Services. If you'd like to make major changes to the project, it is heavily encouraged to change the deployment strategy. One example is deploying code with a ZIP/WAR file, for example via Azure Pipelines.

1. Note the location of the configuration app that you deployed, which is https://[BaseResourceName]-config.azurewebsites.net. For example, if you chose "brainy" as the base name, the configuration app will be at https://brainy-config.azurewebsites.net
2. Go back to the "App Registrations" page here.
3. Click on the configuration app in the application list. Under "Manage", click on "Authentication" to bring up authentication settings.
4. Add a new platform with type Web
5. Add an entry to "Redirect URIs": this is the URL from Step 3.1 appended with /auth/openid/return, for example https://brainy-config.azurewebsites.net/auth/openid/return
6. Under "Implicit grant", check "ID tokens".
7. Click "Configure" to commit your changes.

1. Go to the configuration app, which is at https://[BaseResourceName]-config.azurewebsites.net. For example, if you chose “brainy” as the base name, the configuration app will be at https://brainy-config.azurewebsites.net.

   NOTE: if the configuration panel does not load, the app has not yet finished building. This can be checked in the Deployment > Deployment Center blade in the configuration App Service resource. Please be patient if it is still in progress.

2. You will be prompted to login with your credentials. Make sure that you log in with an account that is in the list of users allowed to access the configuration app. If you get stuck in a log in loop, confirm that this setting is correct in the configuration App Service settings.

3. Get the link to the team with your managers. To do so, open Microsoft Teams, and navigate to the team. Click on the "..." next to the team name, then select "Get link to team".

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

4. Paste the copied link into the "Manager Team ID" field, then press "Submit".

   We will configure the user memberships after Brainy is deployed into Teams.

You have to create a single Teams app package in order to add Brainy to Teams.

1. Open the Manifest\manifest.json file in a text editor.
2. Change the placeholder fields in the manifest to values appropriate for your organization.
   • developer.name (What's this?)
   • developer.websiteUrl
   • developer.privacyUrl
   • developer.termsOfUseUrl
3. Change the <botId> placeholder to your Azure AD application's ID from above. This is the same GUID that you entered in the template under "Bot Client ID".
4. In the "validDomains" section, replace the <appDomain> with your Bot App Service's domain. This will be [BaseResourceName].azurewebsites.net. For example if you chose "contosobrainy" as the base name, change the placeholder to contosobrainy.azurewebsites.net.
5. Create a ZIP package with the manifest.json,color.png, and outline.png. The two image files are the icons for your app in Teams. Make sure to give it a recognizable name, like brainy.zip.
   • Make sure that the 3 files are the top level of the ZIP package, with no nested folders.

If your tenant has sideloading apps enabled, you can install your app by following the instructions here

1. Install Brainy (the brainy.zip package) to the Team of all end users. If a user is not in this Team, he/she won't be able to communicate with Brainy.
2. Install Brainy (the brainy.zip package) to the Manager Team. Note that this MUST be the same team which was configured in step 4.

Once Brainy is added to a Team, it adds all users to its database if they are not added already. Note that the database tables are automatically created when the Brainy bot app is deployed.

Brainy works with the following permissions:

• By default every user is able to create a new task via Brainy via a personal message chat.

• If a user wants to perform actions in the Manager team, the user needs to have a Manager membership.

• If a user wants to be selectable as a Specialist, then this user needs to have a Specialist membership.

  These memberships can be easily configured in the configuration app (https://[BaseResourceName]-config.azurewebsites.net). Simply click on the icons (✔️= the user is assigned this membership, ❌= the user is not assigned this membership) to change the membership status for a given user. You can always come back to the configuration page to edit user memberships.

Brainy is deployed using a Premium App Service plan and a single SQL database with the Basic tier. After deployment, feel free to change the pricing tiers of these services to your needs. For the App Service plan, any plan supporting the Always On option is recommended to ensure the bot is always active.