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.

  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

  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.

  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 to Integration 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

  1. Select List Jobs under Jobs 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

  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

Plain Text Export Structure

Copy 
<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

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