Microsoft Graph Teams

Overview

Important:  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.

Important:  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. 3Sixty uses the Get messages across all chats for user method.

Note:  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 require an Authentication Connection to function. Authentication connectors are used to authenticate repository/output connections that need certain authentication fields like access tokens or refresh tokens.

Creating an Authentication Connection:

1. Select Authentication from the navigation menu or the dashboard.

2. Click the New Authentication button

3. Enter a unique name for the connection and give it a description

4. Select the connection type from the drop-down and click save.

5. Fill in the configuration settings on the edit connection page and click save.

Authentication Connections Overview

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

• ChannelMessage.Read.All

• Chat.ReadBasic.All

Discovery Connection

Discovery makes mapping to and from your sources easier for data migration and ensures the data gets connected to the right fields. Discovery requires an Authentication Connection

Creating a Discovery Schema Instance:

1. Select Schema Instance from the Navigation Menu or the Dashboard under Discovery

2. Select the new connection button

3. Enter a name for your Discovery Connection

4. Select your connection type from the drop down

5. Click save on the Create Connection form

6. In the edit connection page fill out any addition fields and click save

Guide to Discovery Connections

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 3Sixty which contains all messages sent in a channel during a time period.

Integration Connection

Every job requires an integration connection for both the source repository connection and the output connection. Also known as input an output connections. Their job is to query or crawl remote systems for files, folders, metadata, versions, and renditions. . In repo mode, it will retrieve list items and all of their relevant metadata from a list or library on the specified site. In output mode, the connection will write content and assign the mapped content type (from type mappings), or simply leave the new list item as a Document. Click here for more information on setting up an integration connection.

Creating an Integration Connection:

1. Select integration and click on the new connection button.

2. Enter the name and description of your connection.

3. Select the connection type from the drop down list.

4. Click Save on the Create Connection form.

5. Click Save on the Edit Connection page.

There are no fields to configure in an integration connection.

Guide toIntegration connections

Note:  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

A 3Sixty Job is the process of moving or syncing content (including versions, ACL's, metadata) from one CMS (content management system) to another. Add tasks to your job to have better control over how your data gets migrated. Click here for details on how to set up an integration job.

Guide to Integration jobs

Creating a simple integration job:

1. Select List Jobs under integration on the navigation menu or the dashboard

2. Click the create job button

3. In the New Job form

   1. Name the job

   2. Select Simple Migration from the job type drop down

   3. Select the Repository Connection

   4. Select the Output connection

   5. Select your Content Service Connection

      (Only required if you will be using Federation)

   6. Click Save to open the Edit Job page

   7. Fill in the configurations for the Repo and Output Configuration tabs

4. Click save to save your new integration job

Running an Integration Job

1. Select Run and Monitor Jobs under Integration in the navigation menu

2. Click the play button next to the job you want to run

3. Click the refresh button to view your completed job status

   (Larger jobs will take longer to run)

Repository Specification

Also known as an input connection. It's job is to query or crawl remote systems for files, folders, metadata, versions, and renditions. When using this connector as a source repository filling out the following configuration fields will tell 3Sixty how to locate the files you want migrated.

Team Chats or Files

• 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

Get Private Chat

• 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.

Note:  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

• Connector ID: Give your connector a unique name

• Description: Provide a description for this connection

• Type: Select the Filesystem Content Service Connector

• Keep Connection Alive: Keep this connection active

• Keep alive in Milliseconds (300000 is 5 minutes): How long until connection expires if unused

• Connection URL: The web address for your connection

• Security Mode: None needed for this connection

• Mapping Type: Choose single map or group mapping if you are using mapping for jobs

• 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 the steps below about retrieving your tenant name.

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

Supported Methods

• checkIn

• checkOut

• createFile

• createFolder

• deleteACL

• deleteFolder

• deleteObjectByID

• findTypeDefinition

• getACLs

• getFileContent

• getObjectProperties

• getTypes

• listFolderItems

• listVersions

• lockDocument

• setACLs

• unlockDocument

• updateFile

• updateProperties

Retrieving your tenant name

If you do not know your tenant name (it's usually your organisations 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

Need help integrating Microsoft Graph Teams? We can help.