Overview

Microsoft Teams is one of the most commonly used communication platforms in business as well as personal communication. However, sending a message on a Teams channel requires logging in to a Microsoft account, and doing this from an app can be a complex task. Don’t worry! This app service enables including a Microsoft Teams Connector in your Mendix application. The connector allows you to send messages to a specific Teams channel. The connector needs minimum configuration. The workflow is simple: Include this app service in a microflow or workflow, update the configuration, and you are all set!

Documentation

Microsoft Teams

This connector is deprecated.

1 Introduction

The Microsoft Teams connector allows you to send messages and actionable message cards to a Microsoft Teams channel automatically. You can add and configure the connector in a microflow. Once the microflow that uses the connector is triggered, your app sends the message to the Microsoft Teams channel.

This connector is an add-on module.

1.1 Typical Use Cases

• Send messages to pre-configured channels in Microsoft Teams

• Let your Mendix app send an automated notification to a pre-configured channel when an event occurs in your Mendix application (for example, your Mendix app can automatically send a message to a pre-configured channel whenever a ticket is raised on the support portal application)

• Let your Mendix app send an automated message to a pre-configured channel to trigger users to perform an action (for example, your Mendix app can automatically ask users to create a Jira ticket by sending them a message in a pre-configured channel)

1.2 Features

• Send HTML, Markdown, or plain text messages

• Send Microsoft Teams actionable message cards

• Send message using Microsoft credentials

1.3 Limitation

• Supports only custom-made cards designed using HTML and plain text

1.4 Prerequisites

• The connector can only be used with Studio Pro 9.16.0 and above.

• You have access to Webhooks in Microsoft Teams.

• You have installed the Deep link module in your app.

• You have a Microsoft Account in Azure Active Directory.

2 Installation

Follow the instructions in the Importing Content from the App Explorer section in Use Marketplace Content in Studio Pro to import the Microsoft Teams Connector into your app. After the connector is installed, you can see it in the Add-ons folder in the App Explorer and in the Microsoft Teams Connector category in the Toolbox.

WARNING: The app cannot contain different versions of the Microsoft Teams Connector at the same time.

3 Usage

3.1 Generating the Webhook URL {#generate-webhook-url}

1. In Microsoft Teams, go to your Teams channel.

2. Click the ellipsis (...) icon of your Teams channel to open the pop-up menu.

3. Click Connectors to open the Incoming Webhook page.

4. Enter the details for your Webhook and copy the connector URL as shown in the image below.

5. Save the URL for later use.

6. Click Save to save the changes and close the page.

3.2 Sending Messages to a Teams Channel

3.2.1 Configuring the Send Message to Webhook Activity

You can use the Send Message to Webhook activity in a microflow to send messages to a Teams channel:

1. From the toolbox, drag the Send Message to Webhook activity into your microflow.

The following microflow contains activities with the required attributes, the Send Message to Webhook activity, and a placeholder to capture the returned object.

2. Double-click the Send Message to Webhook activity to open the Send Message to Webhook dialog box.

3. Specify the following settings with expression syntax:

WARNING: All parameters are mandatory. Setting any value to be empty or None will cause an error.

1. Set the Webhook URL parameter to the Webhook URL that was generated.

2. For Message type, select Text or Card from the drop-down list:

• If you want to send a message as plain text, HTML, or Markdown, select Text.

For more information about HTML and Markdown tags supported by Microsoft Teams, see Format Cards in Microsoft Teams.

• If you want to use an actionable message card as a message, select Card.

NOTE: For more information about message cards, see Building a Message Card.

3. For the Message parameter, set up the message content in the string format. The image below shows an example:

The example above will render in the Microsoft Teams channel like this:

4. Click OK to save the changes and close the dialog box.

After the Send Message to Webhook activity is configured, once the microflow that uses this activity is triggered, the app sends the message to the Microsoft Teams channel. When the message is sent successfully, the activity returns a SendMessageReponse object. The SendMessageReponse entity for this object has a pre-defined module:

• The Message attribute contains the respective response message.

• If the message is sent sucessfully, the value of the SentMessage attribute is true.

• If the message could not be sent, the value of the SentMessage attribute is false.

3.2.2 Building a Message Card {#build-message-card}

Microsoft Teams supports actionable message cards. You can build a message card and send it to a Microsoft Teams channel using the Microsoft Teams connector. To build a message card, perform the following steps:

1. Go to the Card Playground. This playground contains sample message cards. You can modify the JSON for any sample message card and view the corresponding generated message card immediately.

2. Edit a message card sample:

1. At the upper-left corner of the page, click Select Sample to open the drop-down list.

2. Below the Legacy MesssageCard samples category, select a sample message card.

NOTE: Do not select any sample card above the Legacy MessageCard samples. They are adaptive cards, which do not work with the Microsoft Teams connector.

3. Edit the sample message card. The preview of your message card displays on the right side of the page.

Below is the basic structure of a message card and the corresponding fields in JSON:

The example above with Add a comment action expanded looks like this:

NOTE: For more information about the design of a message card, see Design guidelines.

3.3 Sending Messages Using Microsoft Credentials

Nex to the Send Message to Webhook activity, you can also find the Send Message activity in the microflow toolbox. Use the Send Message activity to send messages with microflow credentials.

3.3.1 Registering Your Application on the Microsoft Azure Portal{#register-application-on-azure-portal}

1. Log in to the Microsoft Azure portal with your company account. If your account gives you access to more than one tenant, select your account on the upper-right corner, and set your portal session to the Azure AD tenant of your company.

NOTE: If your access is denied, contact your IT team.

2. On the left-hand navigation pane, select Azure Active Directory > App registrations.

3. Click New registration.

4. When the Register an application page opens, complete the following steps:

1. Name – Enter a meaningful application name for the app.

2. Supported account types – Select Accounts in this organizational directory only.

3. Redirect URI – Select Web in the drop-down list first, then enter the redirect URI (or reply URL) for your application in the text box. Use this format: [base URL of your app]/link/[deeplink name]. This link must be set as per deep link configuration.

4. Make a note of the URI that you entered in the step above, as you will need it later for configuration.

5. Select Register to register the new application.

Azure AD assigns a unique application (client) ID to your app and will open an overview page for your application.

5. Make a note of the Application (client) ID and the Directory (tenant) ID on the overview page.

6. On the left-side menu under Manage, click Certificates and secrets

7. To configure a new client secret, click New client secret.

8. Make a note of the client secret that you created before you leave the page.

WARNING: Once you leave the page, you cannot view the client secret anymore. You will need this value for configuration later.

NOTE: For more information bout registering an application in Azure portal, see Register an application with the Microsoft identity platform).

3.3.2 Configuring Constants

1. Go to the Azure App folder inside the Configurations folder.

2. Configure the values of constants AzureClientId, AzureClientSecret, AzureTenantId and RedirectURI with the values that were used and generated when you register the application on the Microsoft Azure portal.

3. Make sure the constant DeepLinkName contains the text after the last slash in the RedirectURI value. For example, if your RedirectURI is https://contosoapp1/link/auth, then the DeepLinkName should be auth.

3.3.3 Configuring the Microflows

1. Go to the Marketplace and log in with your Mendix account.

2. Follow the instructions in How to Use Marketplace Content in Studio Pro to install the Deep Link module to your app.

3. Give your user role access to the Deep Link module roles.

4. In the App Explorer, click Settings to open the App Settings dialog box.

5. Go to the Runtime tab, and set After startup to the StartupMicroflow from the MicrosoftTeamsConnector module.

6. In the App Explorer, click Navigation.

7. Configure the Default home page option to execute a microflow that will display your application's home page. The activity that shows the home page must be preceded by a microflow call named Configure_HomePage_Prerequisite, which is available in the MicrosoftTeamsConnector module.

3.3.4 Obtaining the Channel Link on Microsoft Teams{#obtain-channel-link}

One of the input items required for the Send Message activity is the channel link. To get this link for your channel, do as follows:

1. Open Microsoft Teams.

2. Right click the ellipsis (...) on the channel name.

3. Click Get link to channel.

A pop-up window opens and shows containing the channel link.

3.3.5 Configuring the Send Message and SignInMicroflow Activities

1. From the microflow toolbox, drag the Send Message activity into your microflow.

2. Double-click the Send Message activity to open the Send Message dialog box.

3. Specify the following settings with expression syntax:

WARNING: All parameters are mandatory. Setting any value to be empty or None will cause an error.

1. Set the channelLink parameter with the channel link that you obtained from Microsoft Teams.

2. For Message type, select Text or Card using the Enumeration Message_Types from the MicrosoftTeamsConnector module.

• If you want to send a message as plain text, HTML or Markdown, select Text.

• If you want to send a card designed using HTML and text, select Card.

3. For the Message parameter, set up the message content as a string value.

4. Click OK to save the changes and close the dialog box.

WARNING: All parameters are mandatory. Setting any value to be empty or none will cause an error.

After the Send Message activity is configured, once triggered, the activity checks whether the user is logged in. If the user is already logged in, the activity returns a SendMessageReponse object. The SendMessageReponse entity for this object comes with a pre-defined module:

• The Message attribute contains the respective response message.

• If the message is successfully sent, the value of the SendMessageReponse attribute is true.

• If the message could not be sent, the value of the SendMessageReponse attribute is false. Execute the SignIn Microflow to log in using your Microsoft credentials. The microflow below shows one of the ways to use the SignIn Microflow effectively. Introduce a decision activity after the SendMessage activity that checks the SentMessage attribute value. If the value is false, execute the SignIn Microflow activity.

NOTE: Once you are logged in by using the SignInMicroflow activity, call this microflow again to send the message.