Skill validation bot for Microsoft Teams

We designed the Microsoft Teams Bot to bring skills closer to the employee. The MS Teams bot allows employees to validate skills suggested by TechWolf. Managers can also be notified when new skills are validated by their employees.

This document describes the installation, operation and configuration of the MS Teams bot. It is intended for anyone who wants to gain insight in how the system works, and for those who install the Teams Bot. If you are mostly interested in how this works, and not about the installation specific, feel free to skip ahead to the Suggestions and Validations chapters.

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please reach out to us to report a documentation issue at support@techolf.ai.

Installation

An overview of the installation process is shown below.

1. The first step is creating an Azure Bot Service in your Azure Portal. This will give you an App ID and a client secret.
2. Share the ID and secret from step 1. with TechWolf, in addition with your Azure Tenant ID.
3. TechWolf then configures the TechWolf bot backend, to be able to send and receive messages to and from your configured Bot Service.
4. TechWolf produces a Bot Manifest, which is a ZIP file containing configuration files for installing the bot. The content of the files will be in line with the documentation provided by Microsoft.
5. Install the bot in your Microsoft Teams environment.
6. Lastly, we need a method to link Employees in the TechWolf API to Teams Users in Microsoft Teams. To this end, we use Custom Properties. The Custom Property Definition could for example be called employee_azure_id, which is set for each employee to their Azure ID.

Creating an Azure Bot Service

1. Go to the Azure Portal.
2. select Create a resource.
3. In the search box enter bot, then press Enter.
4. Select the Azure Bot card.
   
5. Select Create.
   
6. Fill in the required fields.
   
   ⚠️ Make sure you select Multi Tenant under Type of App. While you might only have one tenant, Microsoft's own tenant is part of the system, making it Multi Tenant.
7. Select Review + Create, and finish the process by selecting Create.
8. Navigate to the Configuration section in the side-panel.
9. Add the TechWolf Messaging endpoint. This endpoint will be shared with you since this depends on your region.
   
   
10. Take note of the Microsoft App ID, and apply changes. This App ID must later be shared with TechWolf.
11. In the same view, above the Microsoft App ID field, click on Manage Password, or navigate to the Certificates & secrets page of the Bot's corresponding App registration. Create a new client secret and take note of its values. The secret must later be shared with TechWolf.
12. While you are in the App registration, navigate to the overview and take note of the `Directory (tenant) ID.
13. Under Channels in the side-panel, add Microsoft Teams as a channel. (You have to click on the actual text to add it).
    
    
14. Share (1) the previously created App ID, (2) client secret, and (3) Directory (tenant) ID with TechWolf.

Installing the bot in Teams

This section is only relevant to administrators of the Microsoft Teams environment of your company.

1. Go to your Teams admin page (https://admin.teams.microsoft.com/).
2. Go to Teams apps -> Manage apps
   
3. Click Upload new App
   
4. In the pop-up, click on Upload and select the manifest (ZIP file) you received from TechWolf (in the Installation section, step 4).
   

5. Depending on your organisation’s workflow to install apps for employees, you should now install the skill validation bot for your employees. We recommend one of the following workflows:

   • Using Setup Policies
   • Using the Microsoft Graph API

Suggestions

1. Scheduled trigger: We send out suggestions at specific time intervals. On such an interval cycle, we trigger the TechWolf Teams Bot Backend. The interval can be changed depending on your needs, but usually we send suggestions daily. This might seem like a lot, but this is only the first few days, when the integration kicks off; after the initial period, suggestions will slow down anyways (you probably do not have infinite skills).
2. Fetch suggestions: To get those suggestions, we fetch them from our own API. More specifically, from the Export Employee Skill Cluster data endpoint, for all employees.
   We also fetch the Custom Properties for all employees, so that we can figure out the Azure ID for them. This way we know how to link Employees in TechWolf with Teams Users.

3. Filter employees:

   For each employee that did not validate their previous card we do one of the following:

   • If it was ignored longer than the configured time-period, the previous suggestions are closed. We send suggestions again, with a message indicating that it is a reminder.
   • If it was more recent, we skip suggestions for them, until the next cycle.

   Filter suggestions:

   • For each Skill Cluster, we suggest a maximum number of skills (4 by default). This keeps the variety of the suggestions high. If a Skill Cluster is selected for skill suggestions, we take the maximum number of skills, unless there is less available in the cluster.
   • Enough skill clusters are gathered to reach a minimum number of skills (10 by default).
4. Send suggestions: We send out the suggestions to the azure service.
5. Azure to Teams: The azure service sends them to the correct Teams environment, and the employees receive their suggestions.

Validations

1. The user submits a card, which informs the bot service that it should send an update to the configured endpoint, which is the TechWolf bot backend.
2. The message is received by the bot backend, which receives a list of confirmed and rejected skills with their Clusters.
3. The TechWolf bot stores this information, such as which skills, but also when and by whom (might be different from the subject employee).
4. The feedback is sent to the TechWolf API, using the Employee skill profile feedback endpoint. If this is enabled, the corresponding Skill Clusters are also marked by their validation status. This information is ready to be used for more downstream applications.

Linking Microsoft Teams users and TechWolf Employees

An important step of the installation is to link Employees with Teams users. To be able to reach an Employee on Teams, we must know the Employee's corresponding Azure ID, which can be different from the external_id used in the TechWolf API.

To do so, we must find a method of mapping between the two types of IDs, and use that mapping to set a Custom Property for each Employee in the TechWolf API.

If this is set up correctly, the TechWolf Teams Bot will be able to fetch all suggestions and their corresponding Employee Azure IDs, and send them to the right Teams user.

Through Microsoft Graph (preferred)

Chances are that your company has set the Employee ID property in Azure for each employee. In that case we can automatically link the Teams user to the TechWolf employee.

To do so, add the User.Read.All permission to the application in Azure, under API permissions. Be sure to add the Application Permissions, not the Delegated Permissions.

TechWolf will read the Employee ID from the Microsoft Graph API through the following endpoint:

https://graph.microsoft.com/v1.0/users/<user id>?$select=employeeId

Notice the employeeId query parameter to filter out the Employee ID of the given Teams user.

List of customizations and decisions

Settings

The following is a checklist of decisions that can be made to tailor the TechWolf Teams Bot to your needs. The default values are indicated between brackets.

• Custom property for employee linking (employee_azure_id): What custom property will decide how Teams and TechWolf are linked for employees?
• Grouping (no grouping): Skill suggestions can be presented as a list of skills, but can also be shown grouped by their Skill Cluster, or by their Domain.
• Reminder window (3 days): How long should the reminder window be? This is the time after which a reminder is sent to employees that did not validate their skills.
• Minimum number of skills (10): How many skills should be suggested at minimum?
• Maximum number of skills per cluster (4): How many skills should be suggested at maximum per Skill Cluster?
• Manager notification (no): Should managers be notified when employees validate their skills? (if so, a custom property will also be needed for managers, see the optional section below)

Optionally, if employee skills are validated by managers instead of employees:

• Custom property for manager linking (manager_azure_id): What custom property will decide how Teams and TechWolf are linked for managers?
• Employee notification (yes): Should employees be notified when managers validate their skills?

Card messages

Card messages can also be changed from their default messaging. Those messages can contain:

• The name and basic information of the person the message was sent to.
• The name and basic information of the person the message is about (notification cards, or manager flows).
• A link that is not personalized.
• Any text of course (with a limit of 250 characters only on the suggestion cards).

The following lists all possible cards and their default text. We highly recommend customizing these messages to your company to greatly improve user experience

• Installation message: A message Teams users receive on go-live.

Hi ..., the skill validation bot was added!

• Timed suggestion message: The text above a suggestion message that is sent on the configured interval. There were no open suggestions before this one.

Hi ..., below you can find a number of suggested skills for you. Deselect skills
that you feel you do not have.

Hi ..., below you can find a number of suggested skills for some of your
employees. Deselect skills that you feel they do not have.

• Validate more message: The text above new suggestions when the Teams user requested more suggestions on the previous set.

Hi ..., below you can find a number of additional suggested skills for you.
Deselect skills that you feel you do not have.

Hi ..., below you can find a number of additional suggested skills for some of
your employees. Deselect skills that you feel they do not have.

• Reminder message: The text above a suggestion message that is sent on the configured interval. There were open suggestions before this one.

Hi ..., this is a reminder. Below you can find a number of suggested skills for
you. Deselect skills that you feel you do not have.

Hi ..., this is a reminder. Below you can find a number of suggested skills for
some of your employees. Deselect skills that you feel they do not have.

• No more skills message: When the user wants to validate more, but there are no more suggestions for now.

There are no more skills to validate at this time! Good work 🥳

• Notification message: When some other than the validator must be notified.

Hi ...! Below you can find skills that ... validated.

Hi ...! Below you can find skills that ... verified for you.

• Outdated message: Previous unsubmitted suggestions are closed, and new suggestions are sent. This is the text that is shown on the old suggestions.

This request no longer exists. A more recent reminder has been sent with a list
of skills for you to validate.

• Submitted message: When the user submits their suggestions, the text on that card changes.

Your response has been successfully submitted.