Skip to main content

MS Graph Teams Connector

Beta

This connector is currently in beta and will be available in the 3.1.1 release. It is currently available as part of the 3.1.1-SNAPSHOT, available for download on Simflofy Launch

Protected API Usage

Due to the potentially sensitive nature of Teams' content, Microsoft has restricted the usage of apis that can retrieve chat messages. In order to use these APIs, an additional approval process is required. The form is found here . The response will usually take 1 to 2 business days.

Licensing and payment requirements for Microsoft Teams APIs

In order to retrieve private chat messages, a payment model is required after a certain number of messages. See this link. Simflofy uses the Get messages across all chats for user method.

The Relationship between Teams and SharePoint

Microsoft Teams file storage for a team is actually just a SharePoint site, with each channel being a folder in the Documents library. You can view your teams files in SharePoint by going to https://[tenant].sharepoint.com/sites/[teamName].


Authentication Connection

This connector requires a standard Microsoft Graph Authentication Connection.

The application will require the following permissions:

  • TeamSettings.Read.Group
  • Channel.ReadBasic.All
  • User.Read.All
  • File.Read.Group
  • ChannelMessage.Read.All
  • Chat.ReadBasic.All

Discovery Connector

The Teams connector has some static content types. The Teams Discovery connector does not require authenticating to the service, so you can simply create the schema instance and hit Run. The three types are:

  • Chat Message: Represents any message sent privately or in a channel
  • Attachment: Represents a file associated with chat messages
  • Chat Log: A chat log generated by Simflofy which contains all messages sent in a channel during a time period.

Integration Connector

Running Errors

As of the 3.1.1 release, MSGraph connectors cannot rerun errored documents. We are aware of the issue, and it will be addressed in the next release.

The Teams connectors has two modes of operation. Public Chats and Private The first mode allows you to export a teams files, but crawling the backing SharePoint site. It also lets you extract messages from the public channels

The second mode allows you to pull the private chats for a user.


Job Configuration

  • Team Name: Required for either mode. The name of the team.
  • What would you like to retrieve? This will select the mode, and will change available options.
  • Channels to migrate: Tag input to list channels to migrate.
  • Retrieve files associated with the team (will retrieve files for all channels): This is essentially identical to migrating the Documents library of the team's SharePoint site. These files will appear in their sharepoint folder structure, sites/<TeamName>/Shared Documents/<Channelname>
  • Get messages from listed channels from between configured times: Retrieve chat messages in the form of a single text file. The chat log will be in /<TeamName>/<Channelname>/ChatLog
  • Break down each chat message into an individual document: Instead of a single chat log, each message and its direct replies will become an html document. Attachments will be added to the document as additional binaries, if they are being retrieved.
  • Select a format for chat messages: If you are breaking down chat messages, this will determine the format. There are two options:
    • Plain Text: Each message will be a simple text file with no additional formatting. See below for export structure
    • HTML: Each message and its direct replies will become an html document. Attachments will be added to the document as additional binaries, if they are being retrieved.
  • Only retrieve chats from the listed users. Leave blank to retrieve all messages: Will filter chat messages based on the sender. Use the same as it would appear in the 'from' line of a message.
  • Retrieve attachments attached to chat logs: If only retrieving a single chat log the attachments will appear in /<TeamName>/<ChannelName>/ChatLog/Attachments. See the export structure below for how they are handled when retrieving individual chats
Plain Text Export Structure
<ChannelName>/
โ”œโ”€ <MessageId>/
โ”‚ โ”œโ”€ <MessageId>.txt
โ”‚ โ”œโ”€ attachments/
โ”‚ โ”‚ โ”œโ”€ attachment.pdf
โ”‚ โ”œโ”€ replies/
โ”‚ โ”‚ โ”œโ”€ <ReplyId>/
โ”‚ โ”‚ โ”‚ โ”œโ”€ attachments/
โ”‚ โ”‚ โ”‚ โ”‚ โ”œโ”€ replyattachment.pdf
โ”‚ โ”‚ โ”œโ”€ <ReplyId1>.txt
โ”‚ โ”‚ โ”œโ”€ <ReplyId2>.txt
Event Job Limitations

If you wish to process a message via push event, there are some restrictions.

  • Private Chats are not available. Attempting to execute the push event against private chats will cause an error.
  • The output for an event chat will always be in html format.
  • If attachments are included, they will be additional binaries on the document.

Content Service Connector

The Content Service Connector for Teams is an extension of the one for SharePoint. The configuration simply points the connector at the team you wish to manage. Alternatively you can use the SharePoint connector with a site path of sites/[teamName] and a list name of Documents. Not that Content services cannot update, create or change chat messages at this time.

Configuration

  • Tenant Name: The name of the tenant. All O365 SharePoint instances use the structure [tenant].sharepoint.com. We use this to construct urls and gather site IDs. If you do not know your tenant follow these steps.

  • Team Name: The name of the team you wish to manage with this connector.


Retrieving your tenant name

If you do not know your tenant name (it's usually your organizations name), you can retrieve it in teams.

  • Go to Files
  • Click the ellipses ... next to any file
  • Click Copy Link
  • This will produce a sharepoint url in the format https://[tenant].sharepoint.com