TechWolf Skill Assistant for Microsoft Teams

We designed the TechWolf Skill Assistant to bring skills closer to the employee. The Skill Assistant allows employees to validate skills suggested by TechWolf. Managers can also be notified when new skills are validated by their employees. The Skill Assistant is a message-based system, and currently only Microsoft Teams is supported.

This document describes the installation, operation and configuration of the Skill Assistant for MS Teams. It is intended for anyone who wants to gain insight in how the system works, and for those who install the MS Teams Skill Assistant. If you are mostly interested in how this works, and not about the installation specifics, 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

There are two possible installation processes:

• TechWolf-hosted installation guide (preferred)
• Customer-hosted installation guide (deprecated)

For the TechWolf-hosted installation, all the necessary Azure infrastructure is hosted in TechWolf's Azure tenant, making the installation process much simpler. Whereas for the Customer-hosted installation, the Bot Service and an Entra Application must be self hosted and maintained.

To install the app for your employees, look at Installing the app for employees. This applies regardless of the installation method you choose.

TechWolf-hosted installation

An overview of the TechWolf-hosted installation process is shown below.

1. Share your Azure Tenant ID with TechWolf. TechWolf then configures the TechWolf bot backend, to be able to send and receive messages from your tenant.
2. TechWolf produces an app manifest, which can be used to install the bot in Teams. This manifest is created in line with the documentation provided by Microsoft.
3. Install the bot in your Microsoft Teams environment.
4. Lastly, we need a method to link Employees in the TechWolf API to Teams Users in Microsoft Teams. See Linking Microsoft Teams users and TechWolf Employees .

Installing the bot in Teams

In order to install the bot, you first need to upload the manifest file. In a second step, you will give the right permissions to the bot. The following steps describe how to do this:

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. After uploading the app, you should see the New app added screen. Click on this link to go to the app management page for the Skill Assistant.

   

Info
You might have to reload the page after clicking the link for the page to load properly.

6. Navigate to the Permissions tab (1).
7. Grant the app the required permissions. Do so by pressing Grant admin consent (2). This will open a pop up.
8. Select your account and log in if necessary (1).
9. Review the required permissions and grant them, by clicking Accept (2).

Customer-hosted installation

⚠️ Warning
This installation method is deprecated. However, if you are currently using this, it will continue to be supported for now.

An overview of the Customer-hosted 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 an app manifest, which can be used to install the bot in Teams. This manifest is created 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. See Linking Microsoft Teams users and TechWolf Employees .

Creating an Azure Bot

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).
   

Installing the app for employees

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 and can be tracked with the source field as "tw-teams-bot". To retrieve these sources in an employee's profile, use the query parameter &include=sources, which returns the Skill's source_event with "event_type": "skill_profile_feedback" and "source": "tw-teams-bot".

   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.

Employee Skill Management Tab

In addition to our Skill Assistant Bot:

We offer an interactive tab that enables employees to efficiently manage and track their skills. Within this tab, employees can:

• View and Reevaluate Skills: Access their validated and rejected skills for assessment and potential updates.
• Add Missing Skills: Identify and add any skills that may be lacking.

Installation Steps

These steps are only needed if you are using the Customer-hosted installation. If you have a TechWolf-hosted installation, you only have to request a new manifest that has the Skill Management Tab enabled from TechWolf.

1. Access the Azure Portal

   Navigate to the Azure Portal.

2. Configure Application Authentication

   Go to the Authentication section under the Manage tab of your application (not the bot itself).

   

   Select Add a Platform and choose Web. In the Redirect URI, enter the same {messaging endpoint} used in step 9 of Creating an Azure Bot, omitting /api/messages.

   Enable Access tokens (for implicit flows) and ID tokens (for both implicit and hybrid flows).

   Add the following Redirect URI: https://token.botframework.com/.auth/web/redirect.

   Under "Who can use this application or access this API?", select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).

   

3. Set API Permissions

   In the API permissions section, add User.Read from Microsoft Graph as Delegated Permissions.

   

4. Expose an API

   Go to the Expose an API section.

   Set the Application ID URI to api://{tab endpoint}/botid-{app-id}. The {app-id} is the same as the Microsoft App ID from step 10 of Creating an Azure Bot. Similar to the {messaging endpoint}, the {tab endpoint} will be provided by TechWolf based on your region.

   Click on Add a scope. In the panel that opens, enter access_as_user as the Scope name.

   Set "Who can consent?" to Admins and users.

   Fill in the fields for configuring the admin and user consent prompts with the following values:

   • Admin consent title: Teams can access the user's profile
   • Admin consent description: Allows Teams to call the app's web APIs as the current user.
   • User consent title: Teams can access your user profile and make requests on your behalf
   • User consent description: Enable Teams to call this app's APIs with the same rights that you have

   Ensure the scope is Enabled.

   

   Include the following client application IDs for Microsoft Teams:

   • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams Mobile/Desktop app)
   • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams Web app)

Note: After completing these steps, please ensure that TechWolf sends an updated manifest with the tab enabled.