Connectors / Service / Microsoft Teams

Artisan IMG > Microsoft (microsoft-teams)

Microsoft Teams

A team-based communication platform from Microsoft.

Overview

The Microsoft Teams connector allows you to interact with groups, teams, channels, and users inside your Teams workspace.

Authentication

Within the workflow builder, highlight the Microsoft Teams connector.

In the Microsoft Teams connector properties panel to the right of the builder, click on the Authenticate tab and the 'New authentication' button. This will result in a Tray.io authentication pop-up modal.

microsoft-teams-add-new-auth

Name the authentication something that will easily identify it in a larger list. For example, using the service account's name, whether it is a Sandbox or Production OAuth, etc.

When choosing between the type of authentication you wish to create ('Personal' or 'Organisational'), consider who and how many people will need access to it.

The second page asks you for Service permissions. Select the appropriate permissions of your choice.

If required, you can also optionally provide 'Extra permission scopes'.

microsoft-teams-popup

Once you have selected the permissions on the Tray.io authentication pop-up window, click the 'Create authentication' button.

Go back to your settings authentication field (within the workflow builder properties panel), and select the recently added authentication from the dropdown options now available.

Your connector authentication setup should now be complete.

Microsoft Teams Trigger

If you wish your workflow to be kicked off by a particular action in Microsoft Teams, you can use the Microsoft Teams Trigger.

The Microsoft Teams trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

Trigger Operations available:

Microsoft Teams supports 'On action (button or menu click)' operation.

The operation fires the trigger when a Submit action is performed in Teams.

PLEASE NOTE: The Microsoft Teams trigger works only with the Adaptive card

To learn more about the Adaptive card and how to use it to make the trigger work, refer to the Webhook Setup section below.

Webhook Setup

Select the Microsoft Teams trigger. This can be done either at the create new workflow stage or updated within the workflow builder itself.

Highlight the Microsoft Teams trigger. In the Microsoft Teams trigger properties panel to the right of the builder, click on the Authenticate tab.

At this stage you can create a new authentication using the steps specified in the Authentication section above.

Or you can select the already created authentication from the available list.

Once done with the authentication, follow the below-mentioned steps to set up the trigger:

  1. Setup a Microsoft Teams trigger with operation as 'On action (button or menu click)'

microsoft-teams-trigger
  1. Add the bot to Microsoft Teams.

  2. Create an adaptive card.

Once done with the above steps, go to the Microsoft teams app and send a message using the adaptive card you just created. The associated Microsoft Teams Trigger will receive the sent message along with the date and name details.

microsoft-teams-trigger-op

Notes on Operations usage

Adding the bot to Microsoft Teams

To start with you need a bot package that should be uploaded to your Microsoft Teams workspace. This can be found here. Once you have downloaded the package you can add it to Microsoft Teams using the following steps.

Navigate to Apps > Upload a customised app from the left-hand navigation menu and choose the downloaded bot package from your local machine.

microsoft-teams-upload-bot

Once uploaded you can see the Tray.io app under built for your org section. Click the app.

teams-app-select

From the popup window that appears, select Add to add the bot to your teams workspace. Once added it will redirect you to the Tray.io-bot app page.

teams-app-add

Adding the bot to Chats or Teams

Navigate back to the Apps tab from the left-hand navigation menu and select the Tray.io app.

Select the down arrow next to the Open button. This will reveal two options; Add to a team and Add to a chat.

teams-chat-add

Select one of the options depending on whether you want to add to a private chat or a team.

The next window allows you to search the Team name, Channel name, or User name for which conversation you want to add the bot to. Once you have found the correct channel, select Set up in the bottom right-hand corner to add the bot.

teams-chat-search

The bot can send adaptive cards to this conversation and is ready to use with the 'Create adaptive card' operation.

Create an adaptive card

IMPORTANT!: Before you create the adaptive card, make sure you have added Tray.io-Bot to your Microsoft Teams workspace, as well as any conversations you would like the bot to be able to send adaptive cards to.

As of version 1.3, a new operation 'Create adaptive card' has been added to the Microsoft Teams connector that allows you to create interactive messages known as adaptive cards within Teams.

As of version 1.4, a new operation 'Update adaptive card' has been added to the Microsoft Teams connector that allows you to update interactive messages known as adaptive cards within Teams.

microsoft-teams-create-adaptive-card

The operation requires 'Conversation', 'Group ID', and 'Channel ID'. These IDs indicate where the adaptive card is to be sent.

The 'Card' parameter accepts the JSON of the adaptive card.

A sample JSON for the adaptive card:

{
"type": "AdaptiveCard",
"body": [
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"items": [
{
"type": "Image",
"style": "Person",
"url": "https://us-api.asm.skype.com/v1/objects/0-cus-d15-b9b9f1d5cf270abab39f8092d9333233/views/imgpsh_fullsize",
"size": "Small"
}
],
"width": "auto"
}
]
},
{
"type": "TextBlock",
"size": "Large",
"weight": "Bolder",
"text": "Adaptive card to send messages"
},
{
"type": "TextBlock",
"text": "Once you click the 'OK' button and send a message, the action workflow connected with this adaptive card will receive a notification via Tray.io's Microsoft Teams trigger.",
"wrap": true
},
{
"type": "Input.Date",
"id": "currentDate",
"placeholder": "Date"
},
{
"type": "Input.Text",
"id": "name",
"placeholder": "Name"
},
{
"type": "Input.Text",
"id": "comment",
"placeholder": "Message",
"isMultiline": true
}
],
"actions": [
{
"type": "Action.Submit",
"title": "Send Message"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.3"
}

You can use the Adaptive Card Designer to craft the JSON based on your tailored needs. To learn more about the adaptive cards refer to the Microsoft teams documentation.

At last, provide the 'Workflow URL' where you have set up your Microsoft Teams trigger. You can find the public URL of your workflow under Workflow settings > General settings.

microsoft-teams-wf-public-url

Based on the above-specified JSON the adaptive card should look like this:

microsoft-teams-adaptive-card

@Mentions

You can also add @mentions to adaptive cards in teams. This can be done one of two ways:

  1. Using the 'Mentions' input in the properties panel.

From within the properties you can select Add to Mentions. This will add a mention object to the array. Here you can select the User ID of the user to mention, the Replace text and the Display text.

The Replace text is text within the card that is to be replaced by the mention. This must be found in the card exactly the same format. The text must also be surronded by

<Content type in custom component at TBD>

.

The Display text is the text that will show highlighted as a mention within the card in teams. This can be anything you wish to display.

A sample JSON for the adaptive card with mention text:

{
"type": "AdaptiveCard",
"body": [
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"items": [
{
"type": "Image",
"style": "Person",
"url": "https://tray.io/apple-touch-icon.png",
"size": "Small"
}
],
"width": "auto"
}
]
},
{
"type": "TextBlock",
"size": "Large",
"weight": "Bolder",
"text": "Adaptive card to mention someone"
},
{
"type": "TextBlock",
"text": "Hey <at>Adam Tarrant</at>. This card has been sent from tray.io. Welcome to the team.",
"wrap": true
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.3"
}

Here the Replace text in the card is <at>Adam Tarrant</at>.

microsoft-teams-mention-input

The mention input would look be:

User ID - Adam Tarrant

Replace text - <at>Adam Tarrant</at>

Display text - Adam

microsoft-teams-adaptive-card-mention
  1. Adding the mentions data directly to the card.

To add mentions directly to the card JSON, they be to added in a specific format.

This is done by adding a msteams object to the JSON schema.

A sample JSON for the adaptive card with the msteams object included:

{
"type": "AdaptiveCard",
"body": [{
"type": "ColumnSet",
"columns": [{
"type": "Column",
"items": [{
"type": "Image",
"style": "Person",
"url": "https://tray.io/apple-touch-icon.png",
"size": "Small"
}],
"width": "auto"
}]
},
{
"type": "TextBlock",
"size": "Large",
"weight": "Bolder",
"text": "Adaptive card to mention someone"
},
{
"type": "TextBlock",
"text": "Hey <at>Adam Tarrant</at>. This card has been sent from tray.io. Welcome to the team.",
"wrap": true
}
],
"msteams": {
"entities": [{
"type": "mention",
"text": "<at>Adam Tarrant</at>",
"mentioned": {
"id": "296c4fed-512e-4922-af63-5e3ad8acebed",
"name": "Adam"
}
}]
},
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.3"
}

Where text is the text to replace in the card, id is the user's teams ID and name is the text that is displayed in teams. Multiple entries can be added to the entities array.

List Operations

All the List operations in Microsoft Teams connector accept OData query fields that enable the user to customise the output. These fields are not available for all the List operations, but where they are available they can make finding data much easier.

Some of these useful fields are:

Select

The Select field allows you to specify which fields you want to be returned. If left blank, all fields in the output schema will be returned (if available). This enables you to cut out unnecessary information in responses from the Teams API.

teams-select

Filter

The Filter field allows the results of a List operation to be filtered according to user-defined criteria. For the operations that support this feature, there are two ways to define filters. The Query builder provides a template for simple queries:

teams-filter-builder

On the other hand, for more complex queries, you can also input a custom Query string, according to the guidance provided by Microsoft's documentation:

teams-filter-string

If you define multiple filters, you can specify how they are joined together using the Condition field:

teams-filter-condition

Selecting 'And' means that only results will be returned which match all specified filters, whereas selecting 'Or' means that any result will be returned if it matches at least one filter.

All Operations

Latest version:

1.4

Add member to group

Adds a member to an Office 365 group (unified), a dynamic group or security group.

List group owners DDL

Unarchive team

Unarchives a team (makes it writable).

Add owner to group

Adds an owner of an Office 365 group (unified), a dynamic group or security group.

Add tab to channel

Adds a tab to a channel.

Archive team

Archives a team (makes it read-only).

Clone team

Clones a team and its corresponding group.

Create adaptive card

Create an adaptive card in a channel.

Create channel

Creates a new channel in a Microsoft Team.

Create chat message

Create a chat message in a channel.

Create group

Creates an Office 365 group (unified), a dynamic group or security group.

Delete channel

Deletes a channel.

Delete group

Deletes a specified group.

Get channel

Returns information about a channel.

Get channel tab

Returns information about a specific tab.

Get group

Returns information about a group.

Get group OneDrive item

Returns an item from the group's OneDrive.

Get group notebook

Returns information about a notebook associated with a group.

Get signed in user

Retrieve signed in user's details.

Get user

Returns information about a user.

List channel tabs

Returns a list of tabs in a channel.

List channel tabs DDL

List channels

Returns a list of channels for a specific group.

List channels DDL

List group members

Returns a list of members for a specific group.

List group members DDL

List group notebooks

Returns a list of notebooks associated with a group.

List group owners

Returns a list of owners of a specific group.

List group plans

Returns a list of plans associated with a group.

List groups

Returns a list of groups (an AD group, Office 365 group, a team group, a dynamic group or a security group).

List groups DDL

List organization users

Returns a list of users in the organizatiobn.

List organization users DDL

List recently modified groups

Return information about groups that have recently been created, updated, or deleted.

List team apps

Returns a list of apps installed in the team.

List user teams

Returns a list of teams that a specific user is a member of.

List user teams DDL

Raw HTTP request (advanced)

Perform a raw HTTP request with some pre-configuration and processing by the connector, such as authentication.

Remove member from group

Removes a member from an Office 365 group (unified), a dynamic group or security group.

Remove owner from group

Removes an owner from an Office 365 group (unified), a dynamic group or security group.

Remove tab from channel

Removes a tab from a channel.

Search group OneDrive items

Returns a list of items in the group's OneDrive according to search criteria.

Update adaptive card

Update an adaptive card in a channel.

Update channel

Updates a channel.

Update channel tab

Updates a tab inside a channel.

Update group

Updates an Office 365 group (unified), a dynamic group or security group.

Update team

Updates a team.