Cireson Portal

Installation Guide: SupportBot & Teams Presence Setup

Prerequisites

  • You will need an Admin Azure account to configure and ultimately consent access 
  • Your Cireson Service Manager Portal must be public facing for Azure Bot Services to be able to communicate with it 

Note: This will not be configurable if the Cireson Service Manager Portal cannot be accessed over the internet remotely

Note as of July 13th, 2021: This documentation is reflective of deploying an Azure Bot vs a Bot Channel Registration (deprecated as of September 1st, 2021). 

To bridge the communication between MS Teams and your Service Manager Portal you must provision and configure an Azure Bot. 

 

Read the release announcement here to learn more about the features of the Teams integration.

Setup an Azure Bot

  1. Select "Create a Resource" in your Azure portal 

  2. Search for "Azure Bot" and then click it

  3. Click on Create

  4. On the next page, fill in the information needed to setup the bot.
    • Bot Handle: This is a unique name across all Azure tenants and is different than the Display Name of the bot you will see in Teams
    • Subscription: Choose which of your Azure subscriptions you wish to provision this resource in
    • Resource Group: Choose an existing Resource Group or create a new one
    • Pricing: Choose a pricing tier that works best for you
    • Type of App: Use Multi Tenant
    • Microsoft App Id: Use "Create new Microsoft App ID"


  5. At this point, you are free to add Tags to the Resource should you choose. Otherwise, choose "Review + Create" to create and deploy the resource.
  6. Once successfully deployed, click on your newly created Azure Bot

  1. Click on Channels
    • Add the MS Teams Channel located under Featured Channels


  1. Click on Bot Profile
    • Set the Display Name of your bot to "SupportBot"

  2. Click on "Configuration."
    1. Messaging Endpoint:  Enter the https://<smp-location>/api/teams/bot/messages location of your SMP instance, i.e. https://support.cireson.com/api/teams/bot/messages
      1. This endpoint must be HTTPS
    2. All applications that integrate with Azure require a unique App ID. When you created the Bot Service a new App Id was created and associated for you. The App Id is what ties the organization to the application that it is integrating with. In Azure AD it is possible to see all the enterprise applications you have integrated with. To configure you App Id click on Manage next to Microsoft App ID.
    • Take note of the App ID located in the text box, you will need this to configure SMP

  4. Click on New Client Secret and go through the steps to create a secret key
    • Take note of this, as you will need this to configure SMP (Note: You will only see this key once. If you lose it, you will need to generate a new key and update the SMP to use the new key)

  5. Now that you have the info you need to connect your Portal to this App/Bot you need to set what permissions this app will be requesting. Click on API Permissions and add the following delegated permissions from Microsoft Graph
    • People.Read
    • Presence.Read
    • Presence.Read.All
    • User.Read
    • User.ReadBasic.All

  6. Since you are an Azure Admin, you can now consent for this permissions for your organization, click "Grant admin consent for ..."

  7. Since Teams presence in the Portal requires the Portal user to also be authenticated with Teams/M365 we will need to setup authentication for this App as well. Click on Authentication
    • Add the location of SMP under Platform configurations -> Web -> Add URI
    • Enable implicit grant by checking the boxes next to Access tokens & ID tokens

Configure Service Manager Portal

Now that we have everything configured in Azure we can head over to our Cireson Service Manager Portal and connect our newly configured Bot Service. 

  1. Log into SMP, and navigate to the Admin section
  2. Click on Teams Integration Settings
  3. Enter the following pieces of information
    • For Microsoft App ID enter the application ID you noted in step 10 above
    • For Microsoft App Password enter the client secret key you created in step 11
    • For Redirect URL enter the location of SMP i.e. https://support.cireson.com 
      • This must be a HTTPS address
  4. Click Save
  5. Choose an accent color you would like for the Teams Bot, and click Download Manifest

    • Save this file to a location of your choosing, this will be uploaded into MS Teams
    • If you would like to change the default images shipped with the Teams Bot, please navigate to the zip file and overwrite the images outline.png and color.png in the package to the icons of your choosing

Configure User Presence

Once you have configured the Azure Portal and SMP, navigate to Features under the Admin Settings section, and enable Teams User Presence.


Configure MS Teams for the Bot

  1. Log into MS Teams and click on the overflow menu (...) on the left hand bar
  2. Click on More apps

  3. Click on Upload a custom app and upload the .zip package you downloaded Step 5 of Configure SMP

  4. Click the Add button

Troubleshooting

  • Upon installing the app to MS Teams, the bot should send you a welcome message with a sign in prompt. If this does not occur, please open up a chat window to the bot and type anything you'd like. It should then respond with the welcome message and sign in prompt.
  • Steps have been taken to be prompted to login once the sign in token has expired, but if this does not occur and things are not working, you can simply chat to the bot and the sign in prompt should occur.
  • If at any time you want to see what token you are using for the platform, you can type the platformtoken command to the bot, and it should return the token used for the platform api
  • If the Sign In button on the prompt does not open anything, please inspect the manifest.json and ensure the url for SMP is listed in the validDomains section.
  • In MS Teams, all action buttons that open a URL must be https, if it is http the button will do nothing.

Customization and Deployment

  • Steps to customize the bot such as branding and renaming can be found here 
  • To publish the bot for your entire organization instead of per user, please follow the steps located here (docs.microsoft.com) 

 

Read the release announcement here to learn more about the features of the Teams integration.