Connecting Microsoft Teams Chatbot to Metric Insights

This article details how to establish connectivity between the Microsoft Teams Bot App and a Metric Insights Server. 

PREREQUISITES:

  1. MI Chatbot deployment
  2. Building a bot app for Microsoft Teams

1. Build a Dataset for MI Chatbot

The Dataset for MI Slackbot will contain information about all elements in Metric Insights.

Before building a Dataset:

  1. Make sure you are logged in as Admin User
  2. Check that there is at least one Element in Metric Insights.
    • If there are no elements in the MI application, it will be impossible to Validate the Dataset (as the SQL query will not return any results)
1.1. Access Dataset Editor > Data tab
  1. Access Dataset Editor > Data tab via New > Datasets > Create New
  2. Configure the Settings:
    1. Data Source for the Dataset should be set to "Dashboard DB"
    2. Enter the SQL statement (exact statement is provided in Section 1.2)
  3. Validate
  4. Save
  5. Dataset ID: copy the Dataset ID from the URL
    • It will be required for MI Chatbot configuration. See details in Section 3

For more information on how to create a Dataset, refer to Create a Dataset from any Data Source

1.2. Copy the SQL statement from this section 
select
    de.element_id,
    IFNULL(last_sv.segment_value_id, 0) as segment_value_id,
    IFNULL(de.segment_id, 0) as segment_id,
    IFNULL(last_sv.element_short_name, concat(de.name,' ', IFNULL(sv.value_display_name,''))) as name,
    de.name as element_name,
    sv.value_display_name as segment_value,
    seg.name as segment_name,
    de.type,
    ert.reporting_tool_name as external_report_type,
    de.certified_ind,
    last_sv.metric_last_measurement_value_formatted as metric_last_measurement_value,
    last_sv.last_measurement_time,
    GROUP_CONCAT(t.name separator ',') AS keywords,
    '' AS slack_channels,
    de.description,
    mint.name as interval_name,
    IFNULL(devl.view_count, 0) as view_count
FROM dashboard_element AS de
JOIN dashboard_category AS dc ON (dc.category_id=de.category_id)
LEFT JOIN measurement_interval mint on mint.measurement_interval_id = de.measurement_interval_id
LEFT JOIN segment as seg on (de.segment_id=seg.segment_id)
LEFT JOIN dashboard_element_topic AS det ON (det.dashboard_element_id=de.element_id)
LEFT JOIN topic AS t ON (t.topic_id=det.topic_id)
LEFT JOIN last_dashboard_element_segment_value as last_sv on (last_sv.element_id=de.element_id)
LEFT JOIN segment_value as sv ON (last_sv.segment_value_id=sv.segment_value_id)
LEFT JOIN external_report_type as ert ON (ert.external_report_type_id=de.external_report_type_id)
LEFT JOIN (
        select sum(total_view_count) as view_count, element_id, segment_value_id
        from dashboard_element_view_log
        group by element_id, segment_value_id) AS devl
    ON devl.element_id=de.element_id and devl.segment_value_id=last_sv.segment_value_id
WHERE last_sv.last_measurement_time_flag='Y'
GROUP BY de.element_id, last_sv.segment_value_id
ORDER BY de.element_id, last_sv.segment_value_id
Click to copy

2. Create credentials in the MI Application

Application ID and Application Key credentials are used to configure the MI Chatbot (Chatbot ".ini" file) as described in Section 3.

These credentials will be encrypted to prevent third-party breaches.

2.1. Go to Admin > Credentials > External Applications
2.2. Name your External Application
  1. Access External Applications page > click [+ New External Application]
  2. Name: provide a meaningful name for your External Application
  3. Save to proceed
2.3. Get credentials for External App
  1. User management access: set to "yes" in order for the Microsoft Teams Bot App to be able to access MI Users
  2. Cross Domain access: switch from default to "yes" if your MI Chatbot is installed on a different server than the main MI application
  3. Show credentials: click to obtain access credentials
    1. Application ID and Application key are required to configure Chatbot configuration (.ini) file. The details on how they are used are provided in Section 3

3. Configure MI Chatbot ".ini" file

To access the .ini configuration file, you must be an admin with root privileges.

In order to allow the MI Chatbot to communicate with the Microsoft Teams Bot App, you need to connect via SSH to the server with the installed MI Chatbot and modify the Chatbot configuration file.

MI Chatbot .ini file is to be found at /opt/mi/iv/engine/config/<file_name.ini>

NOTE:

  1. When the MI Chatbot is installed, the emtpy .ini file is generated
  2. The first time the MI Chatbot is launched, its configuration file will contain the following parameters (view below)
  3. "bot_instance" does not need to be configured manually
  1. instance_hostname: name of the server where the MI App is installed
  2. instance_bot_hostname: hostname of the server where the Bot is installed
    • Should be specified only if the MI Chatbot is installed separately from the MI App
  3. url_path: part of the URL between the domain name and the bot-endpoints
    • Defaults to  "/slack"
    • Should be changed only if the corresponding changes were made in the apache configuration file
  4. api_token: leave empty if not using MI Chatbot for Slack Integration 
    • Otherwise, specify Bot User OAuth Access Token
  5. bot_token: leave empty if not using MI Chatbot for Slack Integration 
    • Otherwise, specify OAuth Access Token
  6. app_id: Application ID
    • Obtained from External Application in Metric Insights
    • See details in Section 2
  7. app_key: Application Key
    • Obtained from External Application in Metric Insights
    • See details in Section 2
  8. app_user: Username of a Metric Insights User with admin rights
  9. dataset_id: replace the default "0" value with the ID of the Dataset built for the MI Chatbot
  10. send_broadcasts: enables broadcast messages
    • These are notification messages for all channels where the bot is participating
    • Such messages can be sent on restarts or sync fails
    • This variable is used for Slack Integration only
  11. slack_signing_secret: leave empty if not using MI Chatbot for Slack Integration
  12. ms_id: Microsoft Teams Bot ID
  13. ms_key: Microsoft Teams Bot key (password)
  14. slack_enabled: if not using MI Chatbot for Slack Integration, set to "False"
  15. ms_teams_enabled: to enable Microsoft Teams Integration, set to "True"

4. Restart the MI Chatbot

In order to restart the MI Chatbot, run the following command:

sudo docker restart mi-slackbot

5. What's next?

Having restarted the MI Chatbot, you can make full use of the available functionality (getting data from Metric Insights and sharing it in a Microsoft Teams Channel).