Microsoft Teams

The JSSP-based Microsoft Teams connector allows you to create, update, list, and read objects in Microsoft Teams, including: teams, channels, tabs, and apps. . You can obtain the Microsoft Teams JSSP Connector from GitHub at https://github.com/k2workflow/Microsoft-Teams-Connector. See the ReadMe.md file in this GitHub repository for information on installing and configuring the connector in your environment.

What you can do with the Microsoft Teams connector

A team in Microsoft Teams is a container for channels and tabs. Apps functionality is limited to listing available apps that can be added as a tab in a channel

The following operations are available in the Microsoft Teams connector:

  • Retrieve a list of teams that someone is a member of
  • Retrieve a list of all teams available in an environment
  • Maintain a team, such as get details about a team, update a team, add and remove members, add owners, archive a team and unarchive a team

  • Create, update, delete channels and tabs within channels

  • Send a message to a channel

The following operations are not available:

  • Delete a team using the connector
  • Install new apps
  • Get messages in a channel

Permissions

Microsoft Azure Active Directory is now Microsoft Entra ID

The Azure Active Directory app that you create requires Graph permissions to both Groups and Teams objects. Since teams are associated with groups and email addresses, performing operations in Microsoft Teams through this service and SmartObjects requires these Graph API Permissions to function. Sending a message to a channel requires the Group.ReadWrite.All Graph API permission. This is a Microsoft Azure requirement that the product does not control. See the table below for the Azure/Graph API Permissions required for each method, and refer to the section Creating the Azure App and Add Permissions in the Readme.md file for details on the required API permissions.

Register a Microsoft Teams connection

To register a connection of the Microsoft Teams connector you must first access the connector using the GitHub repository. The repository contains a readme.md file where the following is detailed:

  • Creating the Azure App (setting the proper permissions, copying the client ID, and generating a secret)

  • Creating the OAuth Resource

  • Registering a Microsoft Teams connector
  • Creating an instance of the Microsoft Teams connector

Service Objects

The connector exposes the following Service Objects: App, Channel, Tab and Team. See the tables below for details on the properties and methods of each Service Object.

Properties

Name Notes
App ID (id) The ID of the app.
Team ID (teamid) The ID of the team to which the app is installed.
App Display Name (displayName) The app’s display name.
Version (version) The app’s version.
Teams App Definition ID (teamsAppDefinitionId) The app’s definition ID in the team.
Teams App ID (teamAppId) The apps ID in the team.

Methods

Name Notes and Permissions
List installed apps

Gets a list of all apps in a team. Requires Team ID.  

Azure/Graph API Permissions: Group.Read.All, Group.ReadWrite.All

Properties

Name Notes
Channel ID (id) The ID of the channel. Note that this ID is not a GUID but a longer string that contains the word ‘thread.skype’ at the end.
Display Name (displayname) The display name of the channel.
Description (description) The description of the channel.
Email (email) The email address of the channel.
Web Url (weburl) The web URL of the channel.
Is Successful (isSuccessful) Indicates whether the method was successful.
Team ID (teamid) The ID of the team containing the channel.
Message Subject (messageSubject) The subject of the message. Used when executing the Send Message method.
Message Is Important (messageIsImportant) The importance of the message sent to a channel. Used when executing the Send Message method.

Methods

Name Notes and Permissions
Create

Creates a channel. Requires a Team ID.  

Azure/Graph API Permissions: Group.ReadWrite.All
Delete

Deletes a channel. Requires Team ID and Channel ID.  

Azure/Graph API Permissions: Group.ReadWrite.All
Get

Gets details about a channel. Requires Team ID and Channel ID.  

Azure/Graph API Permissions: Group.Read.All, Group.ReadWrite.All
List

Lists channels in a team. Requires Team ID.  

Azure/Graph API Permissions: Group.Read.All, Group.ReadWrite.All
Send Message

Sends a message to a channel. Requires Team ID, Channel ID, and Message Body. Message subject and importance are optional.

The underlying API (chatMessage) that sends a message is in preview/beta in the Microsoft Graph API. It’s the only API used in the connector that uses the beta endpoint, however due to this, the functionality is subject to be changed by Microsoft.
 

Azure/Graph API Permissions: Group.ReadWrite.All

Update

Updates an existing channel. Requires Team ID, Channel ID, the updated Display Name and the updated Description.

Azure/Graph API Permissions: Group.ReadWrite.All

Properties

Name Notes
Tab ID (id) The ID (GUID) of the tab.
Display Name (displayname) The display name of the tab.
Entity ID (configEntityId) The entity ID of the tab.
Content URL (configContentUrl) The content URL of the tab which has a view configured for the tab.
Website URL (configWebsiteUrl) The website URL of the tab which points to the URL from which the tab’s contents are shown.
Remove URL (configRemoveUrl) The uninstall URL of the tab.
App ID (teamsAppAppId) The app ID of the tab, such as com.microsoft.teamspace.tab.wiki.
App Display Name (teamsAppAppDisplayName) The app display name of the tab, such as Wiki.
Distribution Method (teamsAppDistMethod) The distribution method of the tab, usually ‘store.’

Methods

Name Notes and Permissions
Create custom tab

Creates a custom tab. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All

Create Document tab

Creates a document tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.  

Azure/Graph API Permissions: Group.ReadWrite.All

Create Excel tab

Creates an Excel tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create Forms tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create OneNote tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create PDF tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create Planner tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create Power BI tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create PowerPoint tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create SharePoint tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create Stream tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All

Create Website tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All

Create Wiki tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Create Word tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Delete tab

Creates a forms tab in a channel. Requires Team ID, Channel ID, App ID, and Display Name. You can optionally include an Entity ID, Content URL, Website URL, and Removal URL. If you don’t specify some of these option parameters, you’ll have to configure it in the Teams app.

Azure/Graph API Permissions: Group.ReadWrite.All
Get

Gets details about a tab. Requires Team ID, Channel ID, and Tab ID.

Azure/Graph API Permissions: Group.ReadWrite.All

List

A list of all the tabs in a channel. Requires Team ID and Channel ID, and returns ID, Display Name, and URL. To get more properties of a particular tab, use the Get method.

Azure/Graph API Permissions: Group.ReadWrite.All
Update tab

Allows you to change the display name of a tab. Requires Team ID, Channel ID, Tab ID and an updated display name for the tab.  

Azure/Graph API Permissions: Group.ReadWrite.All

Properties

Name Notes
Team ID (id) The ID (GUID) of the team.
Web URL (weburl) The web URL of the team.
Display Name (displayname) The display name of the team.
Created On (creationDate) The date the team was created.
Description (description) The description of the team.
Email (email) The email address of the team.
Mail Enabled (mailEnabled) Whether the team is enabled with an email address.
Mail Nickname (mailNickname) The nickname of the email address.
Archive Status (archiveStatus) Indicates true or false whether the team is archived (read-only).
Is Successful (isSuccessful) Indicates whether the method was successful.

Methods

Name Notes and Permissions
Add Member

Adds a member to an existing team. Requires Team ID and user’s email address. Note: If you add a current team owner as a member, they are removed from the Owner listing in the team.

Azure/Graph API Permissions: GroupMember.ReadWrite.All, Group.ReadWrite.All and Directory.ReadWrite.All

Add Owner

Adds an owner to a team. Requires Team ID and user’s email address. You cannot remove an owner using the connector. If you need to do that, you must remove using the Teams application.

Azure/Graph API Permissions: GroupMember.ReadWrite.All, Group.ReadWrite.All and Directory.ReadWrite.All
Archive

Archives a team. Requires Team ID. Note that this locks the content in a team and prevents any new content from being added. When you archive a team, you see this message at the top:

Azure/Graph API Permissions: Group.ReadWrite.All
Copy/Clone

Creates a new team based on an existing one.

  Azure/Graph API Permissions: Group.ReadWrite.All
Create

Creates a team. Requires Display Name, true or false if the team is enabled for mail, and a mail nickname. You can optionally specify a description for the team. You still need to provide a mail nickname even if you set Mail Enabled to false.

Azure/Graph API Permissions: Group.ReadWrite.All
Get

Retrieves details about a team. Requires Team ID.  

Azure/Graph API Permissions: Group.Read.All, Group.ReadWrite.All
List

Lists all groups. Groups that are associated with a team include the tag Team in the Resource Provisioning Options column. You can specify a Display Name Starts With parameter to filter the results.

Azure/Graph API Permissions: Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
List My Teams

Gets a list of the teams the current user is a member of.

  Azure/Graph API Permissions: User.Read.All, User.ReadWrite.All
Remove Member

Removes a member from a team. Requires Team ID and users’s email address. Note that you cannot remove owners from a team.

Azure/Graph API Permissions: GroupMember.ReadWrite.All, Group.ReadWrite.All, Directory.ReadWrite.All
Unarchive

Makes a previously archived team available again for new content. Requires Team ID.

Azure/Graph API Permissions: Group.ReadWrite.All
Update

Updates a team’s settings. Requires Team ID and allows you to set true or false to the following settings:

Copy

Update a team’s settings

"memberSettings": {
        "allowCreateUpdateChannels": true,
        "allowDeleteChannels": true,
        "allowAddRemoveApps": true,
        "allowCreateUpdateRemoveTabs": true,
        "allowCreateUpdateRemoveConnectors": true
    },
    "guestSettings": {
        "allowCreateUpdateChannels": false,
        "allowDeleteChannels": false
    },
    "messagingSettings": {
        "allowUserEditMessages": true,
        "allowUserDeleteMessages": true,
        "allowOwnerDeleteMessages": true,
        "allowTeamMentions": true,
        "allowChannelMentions": true
    },
    "funSettings": {
        "allowGiphy": true,
        "giphyContentRating": "moderate",
        "allowStickersAndMemes": true,
        "allowCustomMemes": true
    }
    

Each one of these settings has a corresponding Yes/No parameter that you can set when you execute the method. Leaving a parameter blank (not supplying true or false) leaves the setting unchanged. If you need to control these settings after creating a team, use the Create method first, then the Update method.

Azure/Graph API Permissions: Group.Read.All, Group.ReadWrite.All

SmartObjects

The following SmartObjects are created when you check the Generate SmartObjects for this Service Instance option at the bottom of the Create Service Instance page, or use the Generate SmartObjects button when you have the service instance selected. You can then use these SmartObjects in SmartForms and workflows. You can also use the advanced mode SmartObject designer to create your own SmartObjects for the Service Objects exposed by the Teams Service Type. .

Considerations

  • When creating custom steps for the Microsoft Teams connector in the Workflow Designer for specific methods of this connector, you can use the following icons in the Icons folder of the readme.md file for the following methods:
    • Send Message to Channel
    • Create Team
    • Update Team
    • Create Channel
  • Remember to check the Cache OAuth token for the service account for using SmartObjects in workflow steps option when you register the connection.
    • When selecting the "Cache OAuth token..." option, the retrieved token is saved against the Service account. You may have signed in with your credentials to retrieve the token, but the token that is retrieved through the OAuth flow is saved against the service account. When a workflow executes a Teams-based SmartObject, the service uses the cached/saved token to make the call to the MS Teams API.
    • The OAuth token will expire after some interval (typically 1 hour). Once the cached token has expired, you may encounter messages like "Service: MS_Teams_JSSP Severity: Error Error Message: Forbidden: Forbidden". To refresh the cached token, you must refresh the Service Instance.
  • Adding an Owner to a team and then adding them as a Member of the team might remove them from the Owners role in the Teams app, but they still have owner rights. This is an issue with the way the Graph API works.