Running text migration

To run a text migration job, complete the following steps: 

1. Identify workspaces to migrate
2. Identify long text fields to migrate
3. Create a text migration job
4. Run the breakage report
5. Create or activate a dtSearch index
6. Resolve saved searches and views
7. Check the FAQ

Identifying workspaces to migrate

Identify the workspaces you want to migrate. Be sure to review the special considerations for text migration as well as the list of supported and unsupported functionality for Data Grid. For more information, see Special considerations.

Identifying long text fields to migrate

Identify the long text fields you want to migrate. For performance reasons we recommend only migrating specific fields:

• Extracted text
  
• OCR text fields
• Any fields with translated text

Creating a text migration job

To create a text migration job, complete the following:

1. Navigate to the Text Migration Jobs tab underneath the Data Grid tab.
2. Click New Text Migration Job.
3. Complete the following fields:
   • Name—enter a name for the migration job.
   • Workspaces—click the horizontal ellipses icon, and then select the from the list on the left the workspaces you want to migrate. Use the arrows to move your selections to the list on the right. Once you are finished, click Save.
   • Fields—click horizontal ellipses icon, and then select the from the list on the left the fields you want to migrate. This list contains all long text fields that are not Data Grid enabled. Use the arrows to move your selections to the list on the right. Once you are finished, click Save. You can migrate up to three fields per job.
     You can migrate up to three fields per job.
   • Email notification Recipients—enter the email addresses of the recipients you want to send a notification to when your migration job finishes running. Separate entries with a semicolon.
4. Click Save.

Running the Breakage Report

The Breakage Report lists all views, saved searches, indexes, fields, and custom objects that will stop working after you migrate SQL text to Data Grid. It is recommended to resolve these issues before running a migration job.

One of the primary functions of the Breakage Report is to identify areas where any of the objects above are tied to a keyword search or that use keyword search specific functions like Contains or Does Not Contain. Most of the issues identified can be resolved by modifying the object to use an active dtSearch index.

To run the Breakage Report, click Breakage Report from the text migration console.

The report contains the following columns:

• Workspace ID—the Artifact ID of the workspace.
• Workspace Name—the name of the workspace.
• Name—the name of the view, saved search, index, or custom object that will break upon migration. For Field, this is the field being migrated to Data Grid.
• Object Type—search, view, index, field, or custom object.
• Owner—the owner of the view, saved search, index, or custom object that will break upon migration.
• Field—the name of the field causing the object to break. For Field, this is the name of the field being computed.
• Operator—the search operator that is incompatible with Data Grid. For example, is, is not, and others.
• Term—the text string used in the broken search. For Field, this is the formula used to compute the field.

Creating or activating a dtSearch index

Most of the issues identified by the breakage report can be resolved by modifying the object to use an active dtSearch index. To create or activate a dtSearch index, see Creating a dtSearch index.

Ensure all fields you want to search on are included in the searchable set for the dtSearch index. You can include a combination of Data Grid and SQL fields in your saved search.

The Data Grid Text Migration application includes logic to automatically repair active dtSearch indexes using the <all documents in workspace> searchable set. This logic only applies if the fields being migrated have the Include in Text Index field set to Yes.

During Data Grid Text Migration, a saved search called SS_TextMigration_[JobName] is created that contains all fields for which Include in Text Index is set to Yes. It also creates a new dtSearch index called Migration_[existing dtSearch index name] that uses this newly created saved search. When text migration completes, navigate to the old dtSearch index and click Swap Index. Select Migration_[existing dtSearch index name] as the replacement index.

Data Grid Text Migration may also automatically create a saved search and dtSearch index called Data Grid Auto-Migration from SQL. It is provided to facilitate the transition to dtSearch, particularly if there is no pre-existing dtSearch index with the migrated fields. Since it is provided as a convenience, you may delete the Data Grid Auto-Migration from SQL index if it is not needed.

Resolving Breakage Report items

Use the results of the Breakage Report to help you resolve index or field-level search issues that affect saved searches and views.

We recommend copying saved searches prior to making edits.

Resolving index searches

1. Navigate to the saved search.
2. Right-click on the name, and then click Edit.
3. Click the (Index Search) condition.
4. Copy the terms in the Search Terms field.
5. Change the Index field to an active dtSearch index.
6. Paste the search terms if needed.
7. Click Apply.
8. Click Save & Search.

Resolving field-level searches

1. Navigate to the saved search.
2. Right-click on the name, and then click Edit.
3. Click the condition using the field being migrated. For example, extracted text.
4. Copy the text query for use in step 7. Also, make note of the operator (for example, is, is like, contains).
5. Click Add Condition, and then select (Index Search).
6. Next to Index, select an active dtSearch index.
7. Paste the text query you copied in step 4. Depending on the operator that was used, you may need to convert your search. For more information, see Search operator conversion.
8. Click Apply.
9. Remove the field condition.
10. Click Save & Search.

Search operator conversion

Data Grid only supports the IS SET and IS NOT SET operators. If your field-level search uses another operator, you need to convert the search as follows:

Operator	Example search	Conversion
is	Jane has a broken search	"Jane has a broken search"
is not	Jane has a broken search	NOT "Jane has a broken search"
is set	Supported operator	No modification required
is not set	Supported operator	No modification required
is less than	N/A	N/A
is greater than	N/A	N/A
is less than or equal to	N/A	N/A
is greater than or equal to	N/A	N/A
is like	Jane has a broken search	*Jane has a broken search*
is not like	Jane has a broken search	NOT *Jane has a broken search*
begins with	Jane has a broken search	Paul*
does not begin with	Jane has a broken search	NOT Paul*
ends with	Jane has a broken search	*broken search
does not end with	Jane has a broken search	NOT *broken search
contains	Jane has a broken search	*Jane has a broken search*
does not contain	Jane has a broken search	NOT *Jane has a broken search*

Resolving computed fields

A field in the Breakage Report is a type of field that calculates its value based on another field, typically one that's manually updated in Relativity's database. When this source field moves to Data Grid, the computed field loses access to its source data and can no longer calculate new values. Often, the Text Migration job will automatically replace the computed field with a static version that contains the current values, though it will no longer update automatically. If it is important to keep the value current, use an Automated Workflow to recalculate as needed, for example, you might run the Set Extracted Text Size process to update a Long Text Size column.

Review the computed columns shown in the Breakage Report:

• If the field is no longer needed, remove it. Otherwise, run the Text Migration process and allow it to replace the computed field with a standard field.
• If you need values to update, create and schedule an Automated Workflow to recalculate the field (for example, Set Extracted Text Size).
• Test the replacement and workflow in a sample workspace and verify values.
• If you see an error message similar to "The field...is referenced by one or more dependencies," this indicates that the Text Migration job could not replace the column. In this case, you may manually remove or replace the field in the application, provided the existing values are not required, thereby allowing Text Migration to continue.

Frequently asked questions

Read these FAQs before running text migration.