Microsoft 365 - Teams data source

This topic provides details on how to capture Microsoft 365 Teams with Collect.

Considerations

Note the following considerations about this data source:

  • Requires enhanced licensing - E5 licensing. For more information, see Licensing requirements.

  • To enable an Azure application registration to use metered APIs and services in Microsoft Graph, you must associate the application with an Azure subscription. For more information, see Microsoft's Enable an application section in their Metered API Setup documentation. For more information, see Billing requirements.

  • We recommend limiting the date range of the collection. Extended date ranges can increase collection time and potentially create issues.

Accessing Microsoft 365 tenants

Register the Collect application to access Microsoft 365. When registering the application, the Microsoft 365 administrator creates a Microsoft Application ID and secret. You will use the ID and secret to configure data sources in Collect and they provide access to the Office 365 tenants. You can register the application through Azure Portal or by registering the application permissions through the Microsoft App Registration Portal. After registering the application, request administrator consent. From there, it is possible to revoke application access.

Use this information to create a Microsoft integration point. For more information, see Importing from Microsoft Entra ID.

Allow Relativity access by first registering the application in Microsoft 365. Register the application permissions through Azure Portal.

Depending on your RelativityOne license, commercial or government, and your Microsoft tenant, Microsoft 365 or Microsoft 365 Government, you will be able to collect from either Microsoft 365 or both Microsoft 365 and Microsoft 365 Government data sources. Commercial users can only collect from Microsoft 365 tenants. Government users can collect from Microsoft 365 and Government 365 tenants. These data sources act the same, but have different icons within Collect.

Licensing requirements

With the Teams Export API, Relativity meets compliance when collecting data. To use the API and collect Teams chats, users must meet one of the following licensing requirements. This licensing applies to individual custodian accounts.

  • Office 365 E5/A5/G5

  • Microsoft 365 E5/A5/G5

  • Microsoft 365 E5/A5/F5/G5 Compliance and Microsoft 365 F5 Security & Compliance

  • Microsoft 365 E5/A5/F5/G5 Information Protection and Governance

For more information, see relevant Microsoft documentation on the Microsoft site:

Billing requirements

To enable an Azure application registration to use metered APIs and services in Microsoft Graph, you must associate the application with an Azure subscription. For more information, see Microsoft's Enable an application section in their Metered API Setup documentation.

You must agree to Microsoft potentially billing you. Microsoft bills you if you exceed their seeded capacity, free quota, of API calls to the Teams Export API each month. For more information, see Microsoft's Payment models and licensing requirements documentation.

  • Microsoft considers Relativity a model=A application. Microsoft restricts model=A to applications performing a security or compliance function, and requires a supported license. For more information, see Microsoft's Teams licenses documentation.

  • Relativity uses the Get messages across all chats for user and Get messages across all channels APIs. Both have a seeded capacity of 1,600 messages per user per month per app. Each message over the seeded, free, capacity costs $0.00075. Microsoft charges one message for requests returning an empty list. Seeded capacity is shared between chat and channel exports.

    • Per user does not mean a custodian. It means an E5 licensed user. For example, if you have 100 E5 licenses, you have a limit of 160,000 messages per month in seeded capacity.

    • After you reach the seeded capacity limit, according to Microsoft's $0.00075 per notification charge, it takes about 1,333 messages to reach $1. To calculate your exact numbers, use Microsoft's TeamsUserActivityUserDetail report. For more information, see Microsoft's reportRoot: getTeamsUserActivityUserDetail documentation.

Registering the Collect application and setting permissions

Register your application permissions through Azure Portal to access tenants.

Note: During the process, you must associate the application with an Azure subscription to enable an Azure application registration to use metered APIs and services in Microsoft Graph. For more information, see Microsoft's Enable an application section in their Metered API Setup documentation.

Start with registering your app by following the steps below:

Note: The person completing the application registration process needs to be an Azure Administrator with sufficient privileges.

  1. Open your Azure Portal.

  2. Navigate to the App registrations page.

  3. Click New Registration to display the Register an application page.

  4. Enter an application name in the Name field.

  5. Select Accounts in this organizational directory only as the supported account type.

  6. Click Register.

For more information on registering an application in Azure, see Microsoft's documentation or Microsoft's authentication documentation.

From the app's page, add permissions to the web API. To add correct permissions to your Microsoft 365 Teams data source, follow the steps below:

Note: Most steps and some permissions are the same for each data source, but we recommend running through all steps for each data source.

  1. Click API Permissions.
  2. Click Add a permission.
  3. Click Microsoft Graph.
  4. Select Application Permissions.
  5. Select the following options from the Application Permissions section: 

    • User.Read.All

    • ChannelMessage.Read.All

    • Chat.Read.All

    • Files.Read.All
    • Group.Read.All
    • TeamsTab.Read.All
    • Team.ReadBasic.All

      Note: The Microsoft Graph API v1.0 requires this permission. If you do not apply this permission, the Teams collection will still work but will revert to a previous, less efficient version of the Graph API and it may impact performance.

    • ChannelMember.Read.All

      Note: The Microsoft Graph API v1.0 requires this permission. If you do not apply this permissions, the Teams collection will still work but will revert to a previous, less efficient version of the Graph API and it may impact performance.


  6. Click Add permissions.
  7. Click Grant Permission.

Make a note of the application ID that Microsoft assigned to the app registration. This ID is also required for setup of data sources in Collect.

    Notes: If you do not have the ability to grant Admin consent for application permissions, you'll need to find an Admin that can consent.

Once clicked, the window will show all permissions granted.

  1. Verify that all permissions have been granted.
  2. Click Accept to grant the permissions.
  3. In the left navigation menu, click Certificates & secrets.
  4. Click New client secret.
  5. Enter a description in the Description text box.
  6. Set the expiration time to the maximum time—24 months.
      Notes: After the time entered expires, the client secret expires. Once the client secret expires, you will need to create a new secret and update your Collect data sources.
  7. Click Add.
  8. Click on the clipboard and copy the secret value to the clipboard and paste it in your text document.
    • Give your Relativity Admin the Application ID and the Client Secret for setup of Collect. This application secret is also needed for setting up an Entra ID integration point. For more information, see Importing from Microsoft Entra ID.
    • In this step you should copy the secret and save it as you will need it to set up your data sources in Collect. Microsoft will only show this secret this one time, there is no way to recover a lost or forgotten secret.

  9. Finally, you must associate the application with an Azure subscription to enable an Azure application registration to use metered APIs and services in Microsoft Graph. For more information, see Microsoft's Enable an application section in their Metered API Setup documentation.

      10. Notes: You cannot use Collect with a Teams data source without completing this step. For more information, see Billing requirements.

Finding Azure credentials

If an application is already created and you need to find the application information to complete the Source Connection step, follow the steps below in the Azure Portal:

  1. Click Azure Active Directory.
  2. In the left-navigation menu, click Enterprise applications.
  3. In the list of applications, locate your application by filtering or sorting.
  4. Click your application.
    This will open the application page.
  5. In the left-navigation menu, click Properties.
  6. Click the copy icon next to the Application ID.

Limiting Application Registration access to accounts

Limit the access of Collect to specific Microsoft user accounts and mailboxes by using the New-ApplicationAccessPolicy Powershell cmdlet. For more information, see Microsoft documentation.

Revoking Application Access

You can revoke the application from https://portal.azure.com or by using a PowerShell script. For more information, see Microsoft's documentation.

To revoke access from https://portal.azure.com,

  1. Navigate to Enterprise Application.
  2. Click All applications.
  3. Locate your application.
  4. Press the application link.
  5. Press the Delete.

Collect no longer has access.

Revoking access in Powershell

Revoke access in Powershell using the Remove-MsolServicePrincipal script. See below for an example of retrieving and deleting an application registration using Powershell.

Get-MsolServicePrincipal -AppPrincipalId 19ab8a2e-ccce-4fa8-a9ee-eb16e220d602

    ExtensionData : System.Runtime.Serialization.ExtensionDataObject
AccountEnabled : True
Addresses : {}
AppPrincipalId : 19ab8a2e-ccce-4fa8-a9ee-eb16e220d602
DisplayName : Relativity-Development-Application
ObjectId : 51798fb3-e72c-4373-8c63-6e7d0dd63ad7
ServicePrincipalNames : {19ab8a2e-ccce-4fa8-a9ee-eb16e220d602}
TrustedForDelegation : False    

Remove-MsolServicePrincipal -AppPrincipalId 19ab8a2e-ccce-4fa8-a9ee-eb16e220d602

Creating the data source

The Collection Admin tab is where you create, edit, and remove data sources from your workspace. You only need to setup each data source once. You must create your data sources prior to setting up your custodian targets.

  1. Click the New Collection Source Instance button.
  2. Enter in a unique name for the data source.
  3. Select Microsoft 365 Teams. 

    Note: Collect automatically collects any preserved data in an in-place hold or litigation hold. Microsoft stored data on a hold in a preservation library and separate folders. For more information, see Microsoft Retention Policies.

  4. Enter the required information in Settings. For more information, see Settings fields.
  5. Click Save.

After clicking Save, Relativity verifies the parameters and connectivity to the Microsoft 365 data source. If successful, Collect saves the data source. If the connection fails, a message appears in the UI indicating that the connection failed. If verification fails. verify that the values are correct. Collect will save the data source when it's corrected and verified.

Once you complete the data source setup, you'll see the data source information on the Collect Admin page.

Settings fields

To connect Relativity to a Microsoft Teams data source, you need to gather and enter the information for the following fields:

  • Domain—enter the domain name of the Microsoft 365 tenant the collection is for.
  • Application Id—enter the application ID created during registering the Collect application in Microsoft 365.
  • Application secret—enter the application secret created during registering the Collect application in Microsoft 365. For more information, see Accessing Microsoft 365 tenants.

After clicking Save, Collect verifies the parameters and verifies them with Microsoft 365. Collect saves the parameters when verified. If the parameters cannot be verified, you will get an error message. If the connection failed, confirm the parameters, re-enter them, and click Save. The parameters will not save until there is a successful verification.

Depending on your RelativityOne license, commercial or government, and your Microsoft tenant, Microsoft 365 or Microsoft 365 Government, you will be able to collect from either Microsoft 365 or both Microsoft 365 and Microsoft 365 Government data sources. Commercial users can only collect from Microsoft 365 tenants. Government users can collect from Microsoft 365 and Government 365 tenants. These data sources act the same, but have different icons within Collect.

Data source details

Each data source details page includes an Action console. Each data source has different actions.

On the SharePoint data source page, you should see an Actions console. In the console, you can Validate Connection. Click to validate the client ID, certificate, and other credentials with Microsoft 365.

Configure data source

Configure the data sources chosen in the Collection Details step. If you select multiple data sources in the first step, you'll configure all sources in the step. Switch between each source by clicking the name of the data source in the left navigation menu. Clicking Next and Previous also moves you through the data sources. Select individual data sources by clicking on the checkbox and then using the right arrows to select them. After selecting the data sources to configure, fill out the criteria. Each data source has different criteria to enter.

    Notes:

  • The Microsoft 365 Teams data source collects the most recent version of each message.

  • Deleted messages are available to collect for 21 days from the time of deletion.

  • Task module content is not currently supported for collection.

Data source criteria

Add criteria to collect specific data. To configure the data sources, complete the following fields:

  • Select and unselected tabs—choose the data sources to collect from by moving unselected data sources to the selected list.

  • Field—choose the field to filter on within the data source.

    Note: This field is only required when you select a calendar source.

  • Operator—choose an operator such as equals, contains, greater than, or less than.

  • Value—enter a value to find in the selected field.

After selecting field options, you must click Add Criteria. Things to know about criteria:

  • Each criteria is then separated by an AND operator.
  • Leave the data source criteria empty to collect all data from the sources.

The following table lists the filter criteria supported for Microsoft Teams collections.

Relativity collects Microsoft Teams data in RSMF. For more information, see The Relativity Short Message Format .

Note: You must register Relativity in Microsoft 365 before using this data source. For information on registering Relativity in Microsoft 365, see Accessing Microsoft 365 tenants.

When using search criteria to filter for Teams, you must select start dates and end dates. All dates are in Coordinated Universal Time (UTC). The maximum date range supported is five years. For example, you can select Start Date 1/1/2016 and End Date 1/1/2021, but no further.

Criteria Operators Description Example
Chat Type Equals When you use the Chat Type property in a query, the search returns all messages in either Private Channels, Private Chats, or Public Channels. If you search a Chat Type with the Public Channels operator selected, Relativity collects only messages in public channels that the custodians are in.
End Date Less Than or Equals When you use the End Date property in a query, the search returns all messages the day of and before the entered date. If you search a Start Date of 1/1/2001 and an End Date of 1/1/2020, Collect returns all messages on and between the two dates.
Slice in Interval in Hours Equals When you use The Slice Interval in Hours property, the search returns all messages in a specific time range or defaults the slice interval to 24 hours. If you search with a slice interval set to one hour and a conversation spans five hours, you will end up with five RSMFs after processing. For more information, see RSMF Slicing.
Start Date Greater Than or Equals When you use the Start Date property in a query, the search returns messages that exist the day of and after the entered date. If you search a Start Date of 1/1/2001 and an End Date of 1/1/2020, Collect returns all messages on and between the two dates.

Included in the Microsoft 365 Teams criteria are two toggles:

  • Collect linked files external to M365—enable the toggle to collect modern attachments, or files linked in Teams that are external to the Microsoft 365 tenant. You must opt in to confirm that you want to collect files outside of Microsoft 365.

    Note: This option is only available for RelativityOne production environments. RelativityOne Government environments cannot collect external files.

  • Enable Dedupe—enable the toggle to exclude cards contained in Teams chat messages. Due to the nature of how Microsoft provides card information, inclusion of cards prevents deduplication of RSMFs during processing. For more information, see Microsoft's documentation.

For more information, see Microsoft Security and Compliance Center documentation.