Importing entities via Integration Points

The Integration Points Microsoft Entra ID Provider is a separate and standalone application that is not in the Relativity Application Library. For assistance in getting the Microsoft Entra ID Provider installed into your workspace, contact Relativity Support. For more information, see Microsoft Entra ID provider.

You will need the following to complete the setup in Integration Points:

• Application ID from Microsoft Azure
• Application Secret Value from Microsoft Azure
• Domain address of Microsoft Azure instance
• Any filtering requirements that will be used to filter imported data
• Field Mappings to map fields between Relativity and Microsoft Entra ID.

Setup

To create an integration point for importing from Microsoft Entra:

1. Complete the following fields in the Setup layout:
   

General:

• Name—the name of your integration for reference purposes.
  

  Note: Name the application in Integration Points the same as you did in Microsoft Entra ID for easy location of application when needing to make updates.

• Type—select Import to designate the job as a data import. Selecting Import makes all the possible import sources available for selection in the Source field below.
• Source—all possible third-party systems that you can import data from. Select Microsoft Entra ID.
• Destination—by default, this is set to Relativity and is not editable when you select Import as the type, since you've already designated that you want to import into a Relativity workspace. You'll select the specific workspace on a subsequent layout.
• Transferred Object—the Relativity Dynamic Object (RDO) to which you want to import the data. Select the Entity object.
• Profile—complete the remaining Integration Points settings based on the settings of a saved profile. This includes all of the fields in the Connect to Source layout, as well as field mappings. If no profiles exist in the workspace, you do not have the option of selecting them. To apply a profile that you've already created, select it from the drop-down list.

Advanced:

• Email Notification Recipients—enter the email addresses of those who should receive notifications of whether the integration point export succeeded or failed. Use semi colons between addresses.
• Log Errors—select Yes or No to denote whether Relativity tracks item level errors.
  • If you select Yes, each job also logs any item level errors.
  • If you select No, Relativity doesn't log these item level errors.
  • Regardless of your selection, job-level errors are always recorded in Relativity.

Scheduling:

• Enable Scheduler—gives you the option of scheduling additional imports. Selecting Yes makes the following fields available:

• Frequency —the interval at which Relativity syncs this integration point. Select one of the options below:
  • Daily—select this option to sync once every day.
  • Weekly—select this option to sync on a weekly basis. Then, enter data in the following fields:
    • Reoccur—enter a numeric value in the Every # week(s) field for how often you want it to occur weekly.
    • Send On—specify on which day of the week (Monday through Sunday) the sync will take place by selecting any of the days of the week listed.
  • Monthly—select this option to sync on a monthly basis. Then, enter data in the following fields:
    • Reoccur—enter a numeric value in the Every # month(s) field for how often you want it to occur monthly.
    • Send On—select the Day # of the month that you want this integration point to sync.
• Start Date—the date that you want Integration Points to start syncing the data.
• End Date—(Optional) the date that you want Integration Points to stop syncing the data. Leaving the End Date blank causes the Integration Point to run indefinitely at the scheduled interval.
• Scheduled Time—the time at which this integration point syncs. This time is local to your PC, not to the server.
• Time Zone—select the appropriate time zone.

2. Click Next to continue to the Connect to Source layout.

Connect to source

Continue to create your import integration point by connecting Relativity to your Microsoft Entra ID data source. You can select to import from your commercial or government Microsoft Entra ID profile. Follow the steps below.

1. Complete the following fields in the Connect to Source layout:
   
   • Version—select either a Commercial or Government Microsoft Entra ID version to import from.
   • Application ID—the ID of the application was created in the Azure Portal. For more information, see Finding Azure credentials.
   • Password—The associated Application Secret Value (not the Secret ID) is the password for the application that was created in the Azure Portal. For more information, see Finding Azure credentials.
   • Directory ID—The Microsoft Entra ID tenant domain the Azure application resides in.
   • Filter By—You can limit the records imported by limiting import to specific users or groups.
   • Filter—The filter condition used to identify Users or Groups that should be imported. Filters must be written using the Graph query syntax (for example, department eq ‘Engineering’). For more information on using Graph query syntax, see Microsoft's Graph REST API documentation.
   Notes:
   • A list of filterable User properties can be found in Microsoft's documentation: Support for filter by properties of Microsoft Entra ID (directory) objects - User properties.
   • A list of filterable Group properties can be found in Microsoft's documentation: Support for filter on properties of Microsoft Entra ID (directory) objects - Group properties.
   • Advanced query parameters are not currently supported by the Relativity Integration Points Microsoft Entra ID (formerly Azure AD) provider.
   • MS-Graph Version—Determines which version of the Graph API Integration Points will be used when interfacing with Azure AD. Defaults to version 1.0 of the Graph API if left blank. Another available option is Beta.
     
2. Click Next to continue to the Map Fields layout.
   

   Note: A warning message appears at the top of page if information is not valid, and you will not be able to continue to the next step until the error is resolved.

Map fields

Map the attributes or fields so that Integration Points imports the targeted data into specific Relativity fields.

1. In the Map Fields wizard, you have the following options for mapping fields:
   • Click the Map All Fields button to automatically map all Source fields with matching Destination field names, except single/multiple object fields.
   • Use the Shift+click and Ctrl+click method to select multiple fields at a time.
   • Use the single and double arrow buttons or double-click a field to move the selected fields between columns.
   • If you have Destination Fields that are mapped to fields in the Field Catalog, Relativity tries to find name matches between these Catalog Fields, as well.
   • The field names in the Destination columns include the type of each field listed.

   When mapping fields, here are some issues to note:

   • If the WebAPIPath instance setting in the kCura.IntegrationPoints section is not configured correctly after upgrade or installation, the Source field list is empty because it cannot return any attributes, and you are not able to map fields.
   • When importing Entities, you need to map the First Name and Last Name fields. In case the Full Name field is not being mapped, those two fields are combined for the Full Name value which is then written to Entity object.

2. Complete the following import Settings on the Map Fields layout:
   • Overwrite— determines how the system overwrites records once you promote data to the review workspace. This field provides the following choices:
     • Append Only—promote only new records into the review workspace.
     • Overlay Only—update existing records only in the review workspace. Any documents with the same workspace identifier are overlaid. This field acts as a link indicating to Relativity where to import the data. When you select this or Append/Overlay, you must complete the Multi-Select Field Overlay Behavior field described below.
     • Append/Overlay—adds new records to the review workspace and overlays data on existing records. When you select this or Overlay Only, you must complete the Multi-Select Field Overlay Behavior field described below.
   • Multi-Select Field Overlay Behavior—determines how the system overlays records when you promote documents to the review workspace. This field is only available if you have selected either Overlay Only or Append/Overlay above. This field provides the following choices:
     • Merge Values—merges all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace, regardless of the overlay behavior settings in the environment.
     • Replace Values—replaces all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace, regardless of the overlay behavior settings in the environment.
     • Use Field Settings—merges or replaces all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace according to the overlay behavior settings in the environment.

   • Unique Identifier—this option is only available when the Overwrite mode is set to Overlay Only. Enter a value that no other item in the workspace contains. For example, use the GUID or distinguishedName attribute.

   • Entity Manager Contains Link—this Yes/No field is visible for all import sources when the Entity RDO is selected as the destination of the imported data. Some import sources populate the manager field with a link to the manager’s profile on their internal system. Set this field to No if the FTP (CSV File) source is selected.
3. Click Save to save the Integration Point.

Once all of the settings have been entered the Integration Points job will run according to the schedule that was set. If you would like to run the job ahead of that time. For more information, see Importing entities via Integration Points.

Reporting on Azure AD imports

Reporting on Azure AD imports can be done in Integration Points. For more information, see Monitoring job history and errors.

Note: Opening a new port for your RelativityOne instance will require a Security assessment.

Setup

To create an integration point for importing an FTP (CSV file), begin by configuring the Setup parameters.

1. Complete the fields in the Setup layout:
   

General:

• Name—the name of your integration for reference purposes.
• Type—select Import to designate the job as a data import. Selecting Import makes all of the possible import sources available for selection in the Source field below.
• Source—select FTP (CSV File) to sync to a Custodian list on an FTP Server to automatically update custodian information in your workspace. We strongly recommend using a secured FTP server and not using anonymous authentication.
• Destination—by default, this is set to Relativity and is uneditable when you select Import as the type, since you have already designated that you want to import into a Relativity workspace. You will select the specific workspace on a subsequent layout.
• Transferred Object—select the specific Relativity Dynamic Object to which you want to import the data. If you are importing the entity object, select Entity here.
• Profile—complete the remaining Integration Points settings based on the settings of a saved profile. This includes all of the fields in the Connect to Source layout, as well as field mappings. If no profiles exist in the workspace, you do not have the option of selecting them. To apply a profile that you have already created, select it from the drop-down list. For more information on profiles, see Integration Points profiles.

Advanced:

• Email Notification Recipients—enter the email addresses of those who should receive notifications of whether the integration point export succeeded or failed. Use semi colons between addresses.
• Log Errors—select Yes or No to denote whether Relativity tracks item level errors.
  • If you select Yes, each job also logs any item level errors.
  • If you select No, Relativity doesn't log these item level errors.
  • Regardless of your selection, job-level errors are always recorded in Relativity.

Scheduling:

• Enable Scheduler—gives you the option of scheduling additional imports. Selecting Yes makes the following fields available:

• Frequency —the interval at which Relativity syncs this integration point. Select one of the options below:
  • Daily—select this option to sync once every day.
  • Weekly—select this option to sync on a weekly basis. Then, enter data in the following fields:
    • Reoccur—enter a numeric value in the Every # week(s) field for how often you want it to occur weekly.
    • Send On—specify on which day of the week (Monday through Sunday) the sync will take place by selecting any of the days of the week listed.
  • Monthly—select this option to sync on a monthly basis. Then, enter data in the following fields:
    • Reoccur—enter a numeric value in the Every # month(s) field for how often you want it to occur monthly.
    • Send On—select the Day # of the month that you want this integration point to sync.
• Start Date—the date that you want Integration Points to start syncing the data.
• End Date—(Optional) the date that you want Integration Points to stop syncing the data. Leaving the End Date blank causes the Integration Point to run indefinitely at the scheduled interval.
• Scheduled Time—the time at which this integration point syncs. This time is local to your PC, not to the server.
• Time Zone—select the appropriate time zone.

2. Click Next to advance to the Connect to Source layout.

Connect to source

Continue to create your import integration point by connecting Relativity to the data source by following the steps below.

1. In the Connect to Source layout, complete the following fields:
   

Connection Information:

• Host—the FTP (File Transfer Protocol) or SFTP (SSH File Transfer Protocol) server address. For example, filetransfer.example.com. If Relativity cannot locate this address, you will receive an error stating that the remote could not be resolved, and you will not be able to proceed.
• Protocol—select the FTP or SFTP protocol.
• Port—the server port to which you want to connect. The FTP protocol default Port number is 21. The SFTP protocol default Port number is 22. The standard network ports 21 or 22 should be open on both RelativityOne and FTP server for outgoing connections from RelativityOne's Web and Agent servers and for listening (FTP server). Some firewall solutions may impact the connectivity between RelativityOne and the FTP server.
  

  Note: If you need to open any port, please contact Relativity Support and allow at least three days to respond. Opening a new port for your RelativityOne instance requires a Security assessment. To successfully import an FTP (CSV file), the standard network ports should be open on both RelativityOne and FTP server for outgoing connections from RelativityOne's Web and Agent servers and for listening (FTP server). Note that the firewall solutions may impact the connectivity between RelativityOne and the FTP server. 

• Username—(Optional) the username to use for authentication. If left blank, Integration Points will use "anonymous."
• Password—(Optional) the associated password to use for authentication. If left blank, Integration Points will use "anonymous."

File Information:

• CSV Filepath—the location of the CSV file that Integration Points imports from the FTP/SFTP server. If you set the generated CSV file to always include the date, you can specify this file path value to use date wildcards so that Integration Points always imports the latest file. For example, the following file path will import the most recently dated file:
  /export/nightlyexport/*yyyy*-*MM*-*dd*_HRIS_export.csv
  • Wildcards are case sensitive.
  • The wildcard feature only pulls data from a file name with the current date.
  • You can also use hh:MM:ss for hours, minutes, and seconds, with capital M's for minutes. When using times, only file names within the last hour are found.

2. Click Next to advance to the Map Fields layout, which contains a list of Relativity fields from their destination RDO as well as attributes that the source provider pulled back.

Map fields

Map the attributes or fields so that Integration Points imports the targeted data into specific Relativity fields.

1. In the Map Fields wizard, you have the following options for mapping fields:
   • Click the Map All Fields button to automatically map all Source fields with matching Destination field names, except single/multiple object fields.
   • Use the Shift+click and Ctrl+click method to select multiple fields at a time.
   • Use the single and double arrow buttons or double-click a field to move the selected fields between columns.
   • If you have Destination Fields that are mapped to fields in the Field Catalog, Relativity tries to find name matches between these Catalog Fields, as well.
   • The field names in the Destination columns include the type of each field listed.

   When mapping fields, here are some issues to note:

   • If the WebAPIPath instance setting in the kCura.IntegrationPoints section is not configured correctly after upgrade or installation, the Source field list is empty because it cannot return any attributes, and you are not able to map fields.
   • When importing Entities, you need to map the First Name and Last Name fields. In case the Full Name field is not being mapped, those two fields are combined for the Full Name value which is then written to Entity object.

2. Complete the following import Settings on the Map Fields layout:
   • Overwrite— determines how the system overwrites records once you promote data to the review workspace. This field provides the following choices:
     • Append Only—promote only new records into the review workspace.
     • Overlay Only—update existing records only in the review workspace. Any documents with the same workspace identifier are overlaid. This field acts as a link indicating to Relativity where to import the data. When you select this or Append/Overlay, you must complete the Multi-Select Field Overlay Behavior field described below.
     • Append/Overlay—adds new records to the review workspace and overlays data on existing records. When you select this or Overlay Only, you must complete the Multi-Select Field Overlay Behavior field described below.
   • Multi-Select Field Overlay Behavior—determines how the system overlays records when you promote documents to the review workspace. This field is only available if you have selected either Overlay Only or Append/Overlay above. This field provides the following choices:
     • Merge Values—merges all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace, regardless of the overlay behavior settings in the environment.
     • Replace Values—replaces all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace, regardless of the overlay behavior settings in the environment.
     • Use Field Settings—merges or replaces all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace according to the overlay behavior settings in the environment.
   • Unique Identifier—Enter a value that no other item in the workspace contains. For example, use the UniqueID or Full Name attribute.

   Note: If the entered Unique Identifier’s value is not unique in the workspace, it may lead to unintentional overwriting of the existing data. 

   • Entity Manager Contains Link—this Yes/No field is visible for all import sources when the Entity RDO is selected as the destination of the imported data. Some import sources populate the manager field with a link to the manager’s profile on their internal system. Set this field to No if the FTP (CSV File) source is selected.
3. Click Save to save the Integration Point.

Once you save the Integration Point, you can run the import job. For more information, see Importing entities via Integration Points.

Before importing LDAP (Lightweight Directory Access Protocol), the Integration Points LDAP Provider needs to be connected to the LDAP server. To connect successfully, open the standard network ports for both RelativityOne and the LDAP Server for outgoing connections from RelativityOne's Web and Agent servers and for listening (LDAP Server). To connect these ports, contact Relativity Support.

Note: To successfully connect Integration Points LDAP Provider to the LDAP server, the standard network ports should be open on both RelativityOne and the LDAP Server for outgoing connections from RelativityOne's Web and Agent servers and for listening (LDAP Server). LDAP connection requires using 636 (Secure Socket Layer) network ports. Custom ports are not supported and may not work correctly. Please be aware that firewall solutions may impact the connectivity between RelativityOne and LDAP server.

Setup

To create an integration point for importing LDAP:

1. In the Setup layout, complete the following fields:
   

General:

• Name—the name of your integration for reference purposes.
• Type—select Import to designate the job as a data import. Selecting Import makes all of the possible import sources available for selection in the Source field below.
• Source—select LDAP here, since you want to import data from a Lightweight Directory Access Protocol source. For example, use this source provider to import an organization's people directory.
• Destination—by default, this is set to Relativity and is uneditable when you select Import as the type.
• Transferred Object—select the specific Relativity Dynamic Object to which you want to import the data. It is typical to use the LDAP source to sync the Entity object.
• Profile—complete the remaining Integration Points settings based on the settings of a saved profile. This includes all of the fields in the Connect to Source layout, as well as field mappings. If no profiles exist in the workspace, you do not have the option of selecting them. To apply a profile that you have already created, select it from the drop-down list. For more information on profiles, see Integration Points profiles.

Advanced:

• Email Notification Recipients—enter the email addresses of those who should receive notifications of whether the integration point export succeeded or failed. Use semi colons between addresses.
• Log Errors—select Yes or No to denote whether Relativity tracks item level errors.
  • If you select Yes, each job also logs any item level errors.
  • If you select No, Relativity doesn't log these item level errors.
  • Regardless of your selection, job-level errors are always recorded in Relativity.

Scheduling:

• Enable Scheduler—gives you the option of scheduling additional imports. Selecting Yes makes the following fields available:

• Frequency —the interval at which Relativity syncs this integration point. Select one of the options below:
  • Daily—select this option to sync once every day.
  • Weekly—select this option to sync on a weekly basis. Then, enter data in the following fields:
    • Reoccur—enter a numeric value in the Every # week(s) field for how often you want it to occur weekly.
    • Send On—specify on which day of the week (Monday through Sunday) the sync will take place by selecting any of the days of the week listed.
  • Monthly—select this option to sync on a monthly basis. Then, enter data in the following fields:
    • Reoccur—enter a numeric value in the Every # month(s) field for how often you want it to occur monthly.
    • Send On—select the Day # of the month that you want this integration point to sync.
• Start Date—the date that you want Integration Points to start syncing the data.
• End Date—(Optional) the date that you want Integration Points to stop syncing the data. Leaving the End Date blank causes the Integration Point to run indefinitely at the scheduled interval.
• Scheduled Time—the time at which this integration point syncs. This time is local to your PC, not to the server.
• Time Zone—select the appropriate time zone.

2. Click Next to advance to the Connect to Source layout.

Connect to source

Continue create your import integration point by connecting Relativity to the data source. Follow the steps below.

1. In the Connect to Source layout complete the following fields:
   
• Connection Path—the URL used to locate the directory. For example, “Relativity.com.” You will need to add 636 to the URL to access that port. Also, note that you can optionally include specific organizational unit references by adding a forward slash (/) after the server. The following example looks up items in the Relativity.com domain within the Employees organizational unit:

  ldap.Relativity.com:636/OU=Employees,OU=Accounts,OU=Relativity,DC=Relativity,DC=corp

  Note: Contact Relativity Support to open port 636.

• Object Filter String—this string specifies certain attributes that the requested LDAP entries must contain that Integration Points considers for import. For example, if you want to import users, you would use an object filter string such as (objectClass=user). For more information on search filter syntax, refer to this Microsoft article: Search Filter Syntax.
• Authentication—Secure Socket Layer is the only applicable authentication type for port 636.
• Username—if required by the server’s authentication, enter a username to connect to the server (connection path). For external SaaS LDAP instances, the username may need to include user ID (UID), organization unit (ou), organization's distinguished name (o) and the connection path:
  uid=johndoe,ou=Users,o=6065d44947314c4eb10ca904,dc=somesaasldap,dc=com
• Password—if required by the server’s authentication, you can enter a password to connect to the server (connection path).
• Import Nested Items—select Yes for the import to include all sub directories in the specified connection path. Select No for the import to include only the first level items brought back in the connection path.

2. Click Next to advance to the Map Fields layout, which contains a list of Relativity fields from their destination RDO as well as attributes that the source provider pulled back.

Map fields

Map the attributes or fields so that Integration Points imports the targeted data into specific Relativity fields.

1. In the Map Fields wizard, you have the following options for mapping fields:
   • Click the Map All Fields button to automatically map all Source fields with matching Destination field names, except single/multiple object fields.
   • Use the Shift+click and Ctrl+click method to select multiple fields at a time.
   • Use the single and double arrow buttons or double-click a field to move the selected fields between columns.
   • If you have Destination Fields that are mapped to fields in the Field Catalog, Relativity tries to find name matches between these Catalog Fields, as well.
   • The field names in the Destination columns include the type of each field listed.

   When mapping fields, here are some issues to note:

   • If the WebAPIPath instance setting in the kCura.IntegrationPoints section is not configured correctly after upgrade or installation, the Source field list is empty because it cannot return any attributes, and you are not able to map fields.

   • When importing Entities, you need to map the First Name and Last Name fields. In case the Full Name field is not being mapped, those two fields are combined for the Full Name value which is then written to Entity object.




2. Complete the following import Settings on the Map Fields layout:
   • Overwrite—determines how the system overwrites records once you promote data to the review workspace. This field provides the following choices:
     • Append Only—promote only new records into the review workspace.
     • Overlay Only—update existing records only in the review workspace. Any documents with the same workspace identifier are overlaid. This field acts as a link indicating to Relativity where to import the data. When you select this or Append/Overlay, you must complete the Multi-Select Field Overlay Behavior field described below.
     • Append/Overlay—adds new records to the review workspace and overlays data on existing records. When you select this or Overlay Only, you must complete the Multi-Select Field Overlay Behavior field described below. You are able to create folders or re-folder documents when you select Append/Overlay.
   • Multi-Select Field Overlay Behavior—determines how the system will overlay records when you push documents to the review workspace. This field is only available if you have selected either Overlay Only or Append/Overlay above. This field provides the following choices:
     • Merge Values—merges all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace, regardless of the overlay behavior settings in the environment. 
     •  Replace Values—replaces all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace, regardless of the overlay behavior settings in the environment.
     •  Use Field Settings—merges or replaces all values for multi-choice and multi-object fields in the source data with corresponding multi-choice and multi-option fields in the workspace according to the overlay behavior settings in the environment.

   • Unique Identifier—this option is only available when the Overwrite mode is set to Overlay Only. Enter a value that no other item in the workspace contains. For example, use the GUID or distinguishedName attribute.

   • Entity Manager Contains Link—this Yes/No field is visible for all import sources when the Entity RDO is selected as the destination of the imported data. Some import sources populate the manager field with a link to the manager’s profile on their internal system. When using LDAP as the import source, be sure to confirm and match (map) how this data is formatted in your system.
3. Click Save to save the Integration Point.

Once you save the Integration Point, you can run the import job. For more information, see Importing entities via Integration Points.