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.
- Team Chats or Files
- Get Private Chat
- 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
- The display name of user's whose chats to pull: List of user's to pull. Each private chat thread will be output under its own folder.
- Preferred licensing and payment requirement model. The API used to retrieve private messages has limited usage. Usage beyond certain amounts require payment. For testing, stick to the default, but note that you will run out after 500 messages.
- Retrieve attachments attached to chat logs: Will attach documents as additional binaries for each message.
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