Microsoft 365 - Outlook data source

This topic provides details on how to capture Microsoft 365 Outlook mailbox, calendars, contacts, and archive mailboxes with Collect.

Considerations

Note the following considerations about Microsoft 365 Outlook data sources:

  • Relativity can collect standard mailboxes and archived mailboxes, but treats those mailboxes as two different data sources. Each type has specific permissions that you must include in the Azure application registration.

  • Microsoft limits pre-collection filtering. Search does not mimic search capabilities in either Microsoft Purview or Relativity dtSearch. This can cause confusion with search operators and data being searched.

  • The Outlook data source supports collection of linked attachments.

  • You cannot collect private, one-on-one Teams chats with the Outlook data source. You can use the Teams data source to collect private, one-on-one Teams chats. For more information, see Microsoft 365 - Teams data source.

  • Authentication for collecting archived mailbox should use modern authentication. When using modern authentication, client ID and secret, the Exchange Web Services full_access_as_app permission must be applied to the Azure app registration—TenantId, ClientId, ClientSecret. This permission is required for collecting online archived mailboxes.

  • If you have a GCC high tenant, than you need to use the GCC High connector when setting up a data source. For more information, see Microsoft's GCC High endpoints documentation. Also, if in GCC only, you can use the same Microsoft 365 commercial tile.

  • Government 365 collections include archive mailboxes.

Accessing Microsoft 365 Outlook

Register the Collect application to access Microsoft 365. When registering the application, the Microsoft 365 administrator creates a Microsoft Application ID and secret. Relativity uses this ID and secret to configure data sources in Collect and provides 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 data through Integration Points.

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.

Registering the Collect application

Register your application permissions through Azure Portal to access tenants.

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.

Setting permissions

From the app's page, add permissions to the web API. To add correct permissions based on your selected Microsoft 365 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: 
    • Calendars.Read
    • Contacts.Read
    • Files.Read.All
    • Mail.Read
    • Sites.Read.All
    • User.Read.All
  6. Click Add permissions.
  7. Click Grant Permission.

To add permissions for Microsoft 365 online archived mailboxes:

  1. In the left-hand navigation, select Manage>Manifest.

  2. Locate the requiredResourceAccess property in the manifest, and add the following JSON script inside the requiredResourceAccess square brackets ([ ]):
    {
        "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
            {
                "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40",
                "type": "Role"
            }
        ]
    }
  3. Click Save.
  4. Click API Permissions.
  5. Click Add a permission.
  6. Click Microsoft Graph.
  7. Select Application Permissions.
  8. Select the following options from the Application Permissions section: 
    • Calendars.Read.
    • Contacts.Read.
    • Files.Read.All.
    • Mail.Read.
    • Sites.Read.All
    • User.Read.All
  9. Click Add permissions.
  10. Confirm that the full_access_as_app permission is listed.
    Microsoft's list of permissions.
  11. 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 will need to find an Admin that can consent.

Once clicked, the window will show all permissions granted.

  1. Verify 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 frame to the maximum time of 24 months. The client secret will expire after this time frame.

      Notes: Once the client secret expires, you must create a new client secret in the Azure portal as described in these steps, and then you will need to update your Collect data sources with it. For further assistance with client secrets, please contact the Azure Admin in your organization.
  7. Click Add.
  8. Click on the clipboard and copy the secret value to the clipboard and paste it in your text document.
      Notes: 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 and there is no way to recover a secret.

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

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 access to 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 via Powershell

You can use the Remove-MsolServicePrincipal script in Powershell to revoke access. 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 in Collect

The Collection Admin tab is where you create, edit, and remove data sources from your workspace. You 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 a Microsoft 365 Outlook data source.

    Note: Collect automatically collects any data that is preserved due to an in-place hold or litigation hold. Data on a hold is stored 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 Fields settings.
  5. Click Save.

After clicking Save, Relativity verifies the parameters and connectivity to the Microsoft 365 data source. If successful, Relativity 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. The data source will save when it is corrected and is verified.

Once you set up the data source, you will see the data source information on the Collect Admin page.

Fields settings

To connect Relativity to a Microsoft Outlook 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 intended 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 Outlook.

After clicking Save, Collect verifies the parameters and verifies them with Microsoft 365. The parameters are saved when verified. If the parameters cannot be verified, you are presented with an error message. If the connection failed, confirm the parameters, re-enter them, and click Save. The parameters will not be saved 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.

Configuring the data source in Collect

Configure the data sources chosen in the Collection Details step.

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.

Criteria

Filter a data source's data that you want to collect by adding criteria. This section covers the different criteria for each data source. It also includes what can be searched within each data source. The criteria options change based on the Microsoft 365 Outlook data source.

Microsoft 365 Outlook mailbox

Relativity collects all items in visible folders within Outlook's inbox and custom folders. Relativity collects hidden folders that exist under the Top of Information Store.

Note: The Microsoft 365 Outlook mailbox data source does not include soft deleted mailboxes, archived mailboxes, conversation history, notes, or tasks in the collections. To collect archived Outlook mailbox data, see Microsoft 365 archive mailboxes.

Another difference is the separation of calendar items and outlook contacts. Microsoft combines those two items with the Outlook mailbox. Relativity separates them into different data sources. For more information, see Microsoft 365 Outlook contacts and Microsoft 365 Outlook calendar.

The following list is a list of file classes included in Outlook mailbox collections.

Collect all emails with attachments regardless of criteria

This data source also includes the Collect all emails with attachments regardless of criteria toggle. If you are using keyword search criteria, we recommend enabling the toggle, regardless of keyword search results, because searching email attachments is not supported through the Microsoft Graph API. Use the Collect all emails with attachments regardless of criteria to collect all emails with attachments, including ones that do not match the selected keyword search criteria. Toggle on to collect emails that match the keyword search criteria, emails that match other criteria such as date range, and all emails with attachments regardless of keyword search criteria. For example, if you add a date range and keywords, Collect pulls emails with keywords in the body, emails within the specified date range, and emails with attachments within the date range. Toggle off to collect only emails that match the search criteria.

Other filter criteria still applies to the collection. For example, if you specify a date range along with keywords, Collect does not return any emails outside the date range. It returns the emails within the date range that are either responsive to the keywords or have an attachment.

Outlook mailbox criteria

The following table lists the filter criteria supported for mailbox collections.

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

When using search criteria to filter for Outlook Mailbox, different operators can return different results. For example, the search criteria uses Search In and it does not use Contains. When using the Search In operator:

  • Search for a phrase by entering the phrase without any OR operators into the Value text box.
    Example: acme corp contract
  • Search for individual keywords by entering the keywords and separating them with an OR in the Value text box.
    Example: cat OR dog OR mouse
      Notes: Enter the OR operator with all capital letters. You should add keywords and phrases lower case only.
  • Keywords hit on matches and if a word is prefixed with a keyword.
    Example: "Work" will return "workday" and "workplace"

The following table lists the filter criteria supported for mailbox collections.

Criteria Operators Description Example

Email BCC

Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email BCC field. If you search “@example.com,” your results include all blind carbon copied messages received by people with the @example.com in their email address.
Email CC Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email CC field. If you search “@example.com,” your results include all carbon copied messages received by people with the @example.com in their email address.
Email From Equals, Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email From field. If you search “@example.com,” your results include all messages sent by people with the @example.com in their email address.
Email Received Date Does Not Equal, Equals, Greater Than, Greater Than or Equals, Less Than, Less Than or Equals When you use the Email Received Date property in a query, the search returns all messages that equal/doesn’t equal, greater/less than the date entered. If you search “Less Than 1/1/2020,” your results include all emails received before January 1, 2020.
Email Sent Date Does Not Equal, Equals, Greater Than, Greater Than or Equals, Less Than, Less Than or Equals

When you use the Email Sent Date property in a query, the search returns all messages that equal/doesn’t equal, greater/less than the date entered.

If you search “Greater Than 1/1/2001,” your results include all emails sent after January 1, 2001.
Email To Contains When you use the Email To property in a query, the search returns all messages that contain the text in the Email To field. If you search “@example.com,” your results include all messages sent to people with the @example.com in their email address.

Has Attachments

Does Not Equal, Equals When you use the Has Attachments property, the search returns emails with or without attachments based on the True or False setting. If you mark “True,” your results include all messages that include an attachment.
Keyword Search - Email Body Search In When you use the Keyword Search – Email Body property in a query, the search returns all messages email message contains the text you’re searching for. If you search “Dear John,” your results include all messages that contain the text in email body. Note that this is not the same as searching for “Dear” OR “John.” In order to do that, you need to separate keyword by OR
Keyword Search - Email Metadata Search In When you use the Keyword Search – Email Metadata property in a query, the search returns all messages which the Email To, Email From, Email CC, or Email BCC fields contain the text you’re searching for. If you search kritter@example.com, your results include all messages that have the text in the Email To, Email From, Email CC, or Email BCC fields.
Parent Folder Name Contains, Does Not Equal, Equals When you use the Parent Folder Path property in a query, the search returns all messages in the folder that equal, does not equal, or contains the name entered. When using the Parent Folder Name criteria, listing a parent folder includes the child folders in the returned results. If you search "RelativityOne," your results include all emails in the folder and all emails within the child folders listed under the "RelativityOne" parent folder.
Subject Contains When you use the Subject property, the search returns all messages that contains the search word or phrase in the email's title.  If you use the Subject property in a query, the search returns all messages that the subject line contains the text you’re searching for. In other words, the query does not return only those messages that have an exact match. For example, if you search for subject “Quarterly Financials,” your results include messages with the subject “Quarterly Financials 2018.”

Microsoft 365 Outlook calendar

The following table lists the filter criteria supported for calendar collections. You're required to enter the start date and end data criteria for calendar collections. The maximum supported date range is five years. For example, it can be 1/1/2001 to 12/31/2006 but not 1/1/2000 to 12/31/2007.

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

You're required to enter the start and end dates when using an Microsoft 365 Outlook Calendar data source.

The following table lists the filter criteria supported for Outlook calendar collections.

Criteria Operators Description Example
Start Date Equals When you use the Start Date property in a query, the search returns calendar items that exist the day of and after the entered date. When you search a Start Date of 1/1/2001 and an End Date of 1/1/2020, Collect returns all calendar items on and between the two dates.

End Date

Equals When you use the End Date property in a query, the search returns all calendar items the day of and before the entered date. When you search a Start Date of 1/1/2001 and an End Date of 1/1/2020, Collect returns all calendar items on and between the two dates.

Microsoft 365 Outlook contacts

These properties are available for users to configure contacts, also called personal contacts, located in the personal address book of a user's mailbox. Relativity collects all contacts and no filter criteria is necessary.

Microsoft collects cached contacts, which are not contacts the user implicitly creates in Outlook. These contacts are not collected by Relativity.

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

Microsoft 365 archive mailboxes

The following table lists the filter criteria supported for archive mailbox collections. Setting criteria for Microsoft 365 Email Archives is not required.

The Less Than operator is only supported when used in conjunction with Greater Than or Equals.

The following table lists the filter criteria supported for Outlook archived mailbox collections.

Criteria Operators Description Example
Email Sent Date Equals, Greater Than, Less Than When you use the Email Sent Date property in a query, the search returns all messages that are greater than or equal/less than the date entered. Less then operator is only supported together with the greater than or equals. If you search “Greater Than 1/1/2001,” your results include all emails sent after January 1, 2001.

Collecting preserved files

When running a collection with Microsoft data sources, Relativity collects all available files including preserved files. You do not need to take extra steps to collect preserved files as they are automatically included in the collection.For more information on preserving data, see Preservation hold (Legacy).

When Microsoft places a data source on a preservation hold, Microsoft creates a preservation hold library, a Recoverable Items folder. The addition of the Recoverable Items folder to Microsoft Exchange is another folder that you can collect. Relativity can collect this folder because the Recoverable Items folder is an additional folder within a Microsoft data source.

When emails and files are on a preservation hold in Microsoft 365, Microsoft preserves original copies of any deleted or modified items. Find preserved emails in the Recoverable Items folder. Find preserved files in the Preservation Library. Collect automatically collects from these file locations.

Relativity collects all versions of the document available in the preservation library. Collecting all versions of a document means that Relativity collects multiple versions of the same file with the corresponding SHA-256 hashes for each version of the data. If there were changes in the file version, the hash should be unique. For more information on hash identifiers, see Hash identifier - SHA-256

Viewing collected data

When Relativity collects the data, Relativity accepts the path names and file names that the source provides. On occasion, the collection source modifies the path name or file name.

File names for Outlook email

Relativity collects Microsoft 365 Outlook emails as individual .eml files. Collect maintains the original folder structure of the mailbox on disk. Each .eml resides in its respective mailbox folder.

Files names on a preservation hold

A randomly generated and unique ID is appended to the original file name of the document if someone moves a deleted document to the Preservation Hold library, . For example, there is a document with the file name of FY2017Budget.xlsx. If someone deletes that document and then moves it to the Preservation Hold library, the file name of the document is modified. For example, the file name becomes something like FY2017Budget_DEAF727D-0478-4A7F-87DE-5487F033C81A2000-07-05T10-37-55.xlsx.

When a document on a site that is on hold is modified and versioning for the document library in the site has been enabled, a copy of the file is automatically created in the Preservation Hold library. In this case, a randomly generated and unique ID is also appended to the file name of the document that is copied to the Preservation Hold library.

The reason why file names of moved or copied documents to the Preservation Hold library is to prevent conflicting file names. For more information about placing a hold on sites and the Preservation Hold library, see Overview of in-place hold in SharePoint Server 2016.

Email considerations

Emails containing double byte characters and illegal characters will be HTML encoded to allow writing to the file system.

Troubleshooting

This table includes troubleshooting for Microsoft's archived mailboxes.

Error Cause Resolution
The remote server returned an error: (403). Permissions have not been applied properly to the service account or application registration when using basic authentication or OAuth 2.0 respectively. Apply the permission defined in the requirements section depending on your authentication method.
The specified folder could not be found in the store. The mailbox does not have an archive. Remove the mailbox from the list of targets.
Mailbox '...' doesn't have a valid license. The owner of the mailbox does not have a valid license applied to their account. Review the requirements section of this document and check if this user has a valid license. You can then choose to remove this user from the list of targets or apply a valid license.
The mailbox database is temporarily unavailable. This error occurs if the mailbox database is not reachable. This can happen because the database is corrupt, in the process of being migrated, updated, or is offline for any other reason. Wait an hour and retry the job to resolve this issue. If the issue persists, open a ticket with Microsoft.
The ExchangePrincipal object contains outdated information. The mailbox may have been moved recently. The mailbox databases are separated in a way that causes inconsistent mailbox connections. Retry the collection at a later time.
The request failed. Unable to connect to the remote server. A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond to microsoft_ip:443. This is generally caused by a networking configuration either blocking access to the Exchange Online IP addresses—https://learn.microsoft.com/en-us/microsoft-365/enterprise/urls-and-ip-address-ranges?view=o365-worldwide or Exchange Online blocking access to itself via an allow list. Perform the necessary network, firewall, or allowed IP address configuration to allow the connector to access Exchange Online.