Promoting data with Integration Points

Once you've tagged documents for inclusion in and/or exclusion from the data you want to promote for review, you can access Integration Points to start the job or jobs that will send those documents to the review workspace.

This topic provides details on Relativity Integration Points as it is used in an ECA and Investigation workflow only. For information, see Relativity Integration Points.

This page contains the following information:

Note: For workspace-to-workspace integration points, Relativity supports transfers across the Document object only and not other RDO's.

Instance-to-instance considerations

Note: The instance-to-instance functionality is available as a preview release only, so that you can evaluate it and provide us with feedback. Note that it will continue to undergo minor contract changes and further enhancements.

You can use the Relativity Instance field on the integration point layout to export data from one Relativity instance to another. Note the following details regarding this functionality:

  • Both the source and destination instances must be visible over the network. For details about configuring this through the Federated Instances tab, see Federated instances.
  • You aren't required to have Integration Points installed on the destination instance.
  • If you intend to use an integration point to export data to another Relativity Instance, make sure to copy the required Client ID and Client Secret values of the Oauth2 client to a text file before you begin creating the integration point. This way you can easily paste those values into the Authenticate window described below without having to exit the integration point layout to navigate to the Oauth2 client to get them.
  • You currently aren't able to transfer data from one RelativityOne instance another RelativityOne instance.

Special considerations - job batches for large sync workflows

We recommend configuring integration point jobs into batches for large sync workflows. The following are recommendations when creating job batches:

  • Document count should be no more than 500k documents in a single batch.
  • When including extracted text as a mapped field in the integration point job, the sum of the extracted text in the batch should not exceed 25 GBs.
  • The recommended number of fields to be mapped should be no greater than 100, but it is best to map as few long text fields as possible.
  • When using the append/overlay or overlay only configuration, the batch size recommendations should be half the amount described above, specifically:
    • 250k document count
    • 12.5 GBs extracted text sum

Creating an ECA integration point

To promote documents to the review workspace with Integration Points, perform the following steps.

Note: All Integration Points jobs are fully editable after run.

  1. Navigate to the Integration Points tab and click New Integration Point.
  2. Complete the following fields in the Setup layout.
    (Click to expand)

    • Name - the name of your integration for reference purposes.
    • Type - the type of job you're attempting to run. The options here are:
      • Import - designates the job as a data import. When you select this option, you're then able to select FTP (CSV File) or LDAP from the Source field below.
      • Export - designates the job as a data export. When you select this option, the Source field below defaults to Relativity and becomes uneditable. This is because you can only export data out of Relativity.
    • Source - this defaults to Relativity since you selected Export as the type above.
    • Destination - select Relativity since you'll be exporting data to another workspace within Relativity.
    • Transferred Object - the specific Relativity Dynamic object to which you want to import the data. Document is automatically populated here and can't be modified.
    • Profile - allows you to 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 don't have the option of selecting them. For more information on profiles, see Integration Points profiles.
    • Include in ECA Promote List - determines whether or not this integration point is available for selection in the list of destinations when you click the Promote button on the ECA Dashboard. Select Yes to make this integration point available. Select No to keep the integration point off the promote list. For more details on the ECA Dashboard, see Working with the ECA Dashboard.
    • Email notifications - the email address(es) to which Integration Points sends a notification detailing whether the sync succeeded or failed. Use semicolons between addresses.
    • Log Errors - select Yes or No to denote whether Integration Points tracks item level errors.
      • If you select Yes, each job also logs any item level errors. For example, a fixed length text field not being large enough to contain an imported value.
      • If you select No, Integration Points doesn't log these item level errors.
      • Regardless of your selection, job-level errors are always recorded in Relativity. For example, the import aborts due to a connection failure.
    • Enable Scheduler - select Yes to enable the scheduling functionality for this integration. Select No if you don't need to schedule the import and you want the option to do so ad hoc. For ECA, this determines the start of the promote-to-review job. Specifically, this determines when the documents that you've tagged and added to a saved search are promoted to the integration point.
  3. Click Next to continue to the Connect to Source layout.
  4. Complete the following fields on the Connect to Source layout.
    (Click to expand)

    • Source - select either Saved Search or Production from this drop-down list, depending on what you want to act as the source of the export.
    • Saved Search - select the saved search designated to pull documents that were tagged for inclusion.
      • This field is only available if you selected Saved Search in the Source field above. If you selected Production as the source, then the Production Set field is available here.
      • Either select the saved search from the drop-down list or click to open a folder tree view of all saved searches in the source workspace. Then select the search and click OK.

      • This drop-down list contains only public saved searches in the source workspace.
      • If your environment contains many saved searches, you can use the search bar at the top of the list to search for your saved search instead of scrolling down through the list.
    • Production Set - select the production set from the list of all available sets in the source workspace.
      • This field is only available if you selected Production in the Source field above. If you selected Saved Search as the source, then the Saved Search field is available here.
      • This drop-down list contains all production sets in the workspace.
      • When you select a production set as the source, then the Copy Images field on the Map Fields layout is automatically set to Yes and is uneditable.
      • When you use this option, then this integration point is listed as the data source on the production set's layout in the destination workspace.
      • You can't reproduce production sets into which you've pushed documents through an integration point.
      • If your environment contains many production sets, you can use the search bar at the top of the list to search for your production set instead of scrolling down through the list.
      • To create a new production set in the destination workspace, click , provide a name in the New Production Set Name, and click Create. Once Relativity creates the set, you'll see a message stating that the new set will act as the destination production set. The new set has all default values populated; you can edit those values before running the set, if need be. The Production Set field is updated to display the new set.
    • Saved Search - the saved search designated to pull documents that were tagged for inclusion. Select the saved search you created to promote documents to review. This drop-down list contains only public saved searches in the source workspace. If your environment contains many saved searches, you can use the search bar at the top of the list to search for your saved search instead of scrolling down through the list.
    • Relativity Instance - the federated instance to which you want to promote data from your source workspace. You must have a federated instance created in the source instance in order to see this field and have any option other than the default of This Instance to select here. See Instance-to-instance considerations for details. For more information, see Federated instances. If you select another instance for this field, Relativity presents you with an Authenticate window in which you enter the Oauth client credentials associated with the federated instance to which you want to export data. Specifically, you need to enter the following information:

      • Client ID - enter the value listed for the ID field on the Oauth 2 client associated with the federated instance to which you're exporting. To get this, navigate to the destination instance, select the Authentication tab, select the Oauth2 Client tab, select the client associated with the instance you selected, copy the Client Id value, and paste it into the Client Id field on the Authenticate window. For more information, see Oauth2 clients.
      • Client Secret - enter the value listed for the Client Secret field on the Oauth 2 client associated with the federated instance to which you're exporting. To get this, navigate to the destination instance, select the Authentication tab, select the Oauth2 Client tab, select the client associated with the instance you selected, copy the Client Secret value, and paste it into the Client Secret field on the Authenticate window. For more information, see Oauth2 clients.
      • Note: If you select something other than This Instance for the Relativity Instance field, you can't save the Integration Point as a profile.

    • Destination Workspace - the workspace to which you want to promote the data that you tagged for inclusion.
      •  As a system admin, you can see all workspaces in the environment in this drop-down list.
      • If your environment contains many workspaces, you can use the search bar at the top of the workspace list to search for your destination workspace instead of scrolling down through the list.
      • If you selected another instance as the destination of this export, then this field will provide all available workspaces in that instance.
      • Integration points uses the following delimiters to configure the Import API for the destination workspace. Other delimiters typically configured with the Import API, for example via the RDC, are not utilized:

        • Multi-value delimiter: ASCII 029

        • Nested-value delimiter: ASCII 030
    • Location - choose whether to export your files to a Folder or a Production Set in the destination workspace.
      • Folder - the top/parent folder inside the destination workspace into which you want to export the files.
        • This is the same folder structure found in the Documents tab of the destination workspace.
        • When you select the value for the Folder Path Information option on the Map Fields layout, the desired folder structure is created in that location.
        • If you selected another instance as the destination of this export, then this field will provide all available folders in the instance and workspace you selected for each respective field above.
        • This folder tree is ordered alpha-numerically instead of by Artifact ID.
      • Production Set - the production set in the destination workspace to which you want to transfer images.
        • Only production sets that have not yet been run are available for selection here.
        • Use this field in conjunction with the Copy Images, Image Precedence, and Production Precedence fields on the Map Fields layout to determine how the images are transferred.
    • Create Saved Search - determines whether or not a saved search automatically appears in the destination workspace when you run the export job. The default value is No. The options are:
      • Yes - select this to automatically create a saved search in the destination workspace. This allows you to more easily identify the saved search conditions that were specified for the export and eliminates the need to manually create a saved search in the destination workspace to pull back the documents that were exported.
        • When you create a saved search here, it is placed in the "Integration Points" folder of the Saved Search browser in the destination workspace with a name that includes the job name and job ID; for example, My Push - 00242342.
        • The conditions for the saved search you create here are "Relativity Source Job" and "Relativity Source Case."
      • No - select this if you don't want to create a saved search in the destination workspace. Selecting No will result in all of the exported documents being placed in the root folder of the destination workspace.
  5. Click Next to continue to the Map Fields layout.
  6. Map the fields so that Integration Points imports the targeted data into specific Relativity fields. The Map Fields wizard contains a list of Relativity fields from the destination RDO, as well as fields from the source provider. Use the Shift + click and Ctrl + click method to select multiple fields at a time, similar to field mapping in the Relativity Desktop Client. Use the single and double arrows or double-click a field to move 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.You have the option of automatically mapping the fields for the integration point you're creating by clicking the Map Fields button between the Source and Destination fields. When you click this, Relativity maps all fields with matching names by bringing them to the two center columns. If the Source and Destination field names don't match, then they remain in their respective columns.
    (Click to expand)

  7. Note: If the WebAPIPath instance setting in the kCura.IntegrationPoints section isn't configured correctly after upgrade or installation, the Source field list is empty because it can't return any attributes, and you aren't able to map fields.

  8. Complete the following fields on the Map Fields layout:
    • Field mappings - map the Destination fields on the left to the Source fields on the right.
      • You must map at least the Object Identifier field for only the Relativity source provider.
      • The field types must match. For example, you aren't able to map a single-choice field to a multi-object field.
      • You must map the Extracted Text field in order to populate this data in the target workspace.
      • When mapping single or multi-object fields in your integration point, note that you'll receive an error during export if the destination workspace doesn't contain the associated child objects found in the source workspace. The error states, "An object field references a child object which does not exist."
      • The field names in the Destination column include the type of each field listed.
    • 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've 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.
    • Copy Images - determines whether Integration Points copies images while syncing data between the source and destination workspaces. If you set this to No, then you make the option to copy native files available below. This is because you can't transfer a document's metadata or natives along with an image at the same time.
      • Select Yes to include only image links, and no documents, in the data that you promote to the destination workspace. When you select Yes here and on the Copy Files to Repository field below, the integration point will transfer physical TIFF image files to the file share of the destination workspace. If you select Yes here but No for Copy Files to Repository, then the integration point will transfer only a link to the image and not the physical TIFF file.
      • When you select Yes for this field, the Image Precedence becomes available for selection. This is where you'll decide between Original Images and Produced Images as the precedence method.
      • Select No to prevent images from making it into the destination workspace.
      • You aren't able to copy documents and natives (.xls, .doc, etc.) while copying images.
      • When you select a production set as the source, then this field is automatically set to Yes and is uneditable.
    • Image Precedence - determines the precedence of the copied images you're transferring to the destination workspace. This field is only available if you selected Yes for Copy Images above. The options are:
      • Original Images - exports only the original, non-produced images.
      • Produced Images - exports a produced version of the images. When you select this, the required Production Precedence field is made available.
    • Production Precedence - click , select one of the groups of produced documents listed in the Select Production Precedence window, and click OK. This will be the group of documents transfer to the destination workspace instead of the original images.
    • Copy Native Files - determines whether Integration Points copies any native files while syncing data between the source and destination workspaces. This field is only available if you set the Copy Images field to No. This is because you can't transfer a document's metadata or natives along with an image at the same time.

      • Physical files - select this to transfer physical files to the destination workspace.
        • This option makes your destination workspace independent, which is not the case if you select No or Links only. If you transfer physical native files and then delete the source workspace, this deletion will have no bearing on the destination because the actual native files are present in the destination, and not just links to those files.
        • Note that selecting this will cause the data transfer to take longer than if you select No or Links only.
      • Links only - select this to transfer only reference links to the destination workspace and set them as the source location of images.
        • If you select to transfer links only and then you either delete the workspace or migrate it using ARM, then the links that you added to the destination workspace through this option won't work anymore, since the source that contains them no longer exists in its expected location.
        • The benefit of transferring links only is that you save on storage and speed, as it tells the system to look for a file path in the source workspace.
      • No - select this to not create additional copies of your natives. Doing this maintains a single copy of that data file in the source workspace only.
        • The benefit of selecting No for this field is that you save on storage and speed, since only document metadata will be copied.
        • You have the option of selecting No for an initial run of an integration point and then Yes for a subsequent run. Doing this saves you time on the initial job while then retaining copies of the native files on the final job.
      • If you delete the ECA source workspace, you also delete your source files. If you need to eventually delete the ECA source workspace, then select Yes for this field.
      • If you delete the ECA source workspace, you also delete your source files. If you need to eventually delete the ECA source workspace, then select Physical files or Links only for this field.
      • When you merge back coding information from the review workspace to the ECA source workspace, you should select No here, as this will prevent the overriding or deletion of natives in case natives were removed from review workspace.
    • Copy Files to Repository - determines whether Integration Points copies files to the repository when copying images. This field is only available when you set the Copy Images field above to Yes.
      • When you select Yes here and Yes on the Copy Images field above, integration points transfers physical TIFF image files to the fileshare of the destination workspace.
      • If you select No here and Yes for Copy Images, then the integration point transfers only a link to the image and not the physical TIFF file.

      Note: When you copy files to the repository, Relativity makes a copy of all the files in the source folder on the hard drive or network share, adds those copies to the EDDS repository, sets the InRepository column on the File database table to 1(true) to indicate that a copy exists, and updates the Location column on the File table to list the new copied location. Relativity then refers to the new location when facilitating integration points or processing jobs.

    • Use Folder Path Information - allows you to use a metadata field to build the folder structure for the documents that you promote to the review workspace. This is available only if you selected No for the Copy Images field above. The options are:
      • Read From Field - select this to use a metadata field to build the folder structure for the documents that you promote to the review workspace. Selecting Yes makes the Folder Path Information and Move Existing Documents fields required below.
      • Read From Folder Tree - select this to use the existing folder tree in the Documents tab to build the folder structure for the documents that you promote to the destination/review workspace.
      • No - select this if you don't want to build a folder structure based on metadata. In this case, Relativity loads all documents directly into the folder indicated by the promote destination, and you create no new folders in the destination workspace.
      • You have the option of creating folders or re-foldering documents when you select Append/Overlay for the Overwrite field.
      • You have the option of re-foldering documents for the Overwrite field through the Move Existing Documents field below.
    • Folder Path Information - allows you to specify a metadata field to build the folder structure for the documents that you promote to the review workspace. For the purposes of ECA and Investigation, select the Processing Folder Path option. This field is only available if you selected Read From Field for the Use Folder Path Information field above.
    • Move Existing Documents - allows you to re-folder documents that were previously imported into the destination workspace, but were placed in the root case folder but not in any subfolders. This field is only available if you selected Yes for the Use Folder Path Information field above.
      • Select Yes to move existing documents into the same folder structure found in the Folder Path Information field. Selecting Yes is useful for situations in which you want to replicate the same folder structure that is found in the source workspace, specifically for when case folders were not available or not created when you originally copied the files, and now you want to create them while overlaying data.
      • Select No if you don’t want to re-folder existing documents. Selecting No would be useful for the following situation:
        • A new folder structure has been created in the destination workspace since you originally moved documents into it. For example, User A has transferred documents into the destination workspace without a folder structure, then User B creates folders in the destination workspace, then new documents become available in new folders in the source workspace, and now you want to transfer documents with the new folder structure into the destination workspace without relocating the documents already present.
  9. Click Save to move to the Integration Point Details layout, from which you can run your promote job and start moving documents to the review workspace.
    • Relativity performs validation on the integration point you're attempting to save and reports on such potential mistakes as data type mismatches for mapped fields. When you see a validation message upon saving, click OK to proceed with running the integration point or Cancel to return to the layout to make edits.
  10. Click Run to start promoting documents to the review workspace. The Run button turns to red and gives you the option of stopping the job you just kicked off, as long as that job has a status of Pending or Processing. For more information, see Stopping a job. Note that you also have the option to save the integration point you just created as a profile to be used later. For more information, See Integration point profiles.
    (Click to expand)
  11. Click OK on the run confirmation message, which informs you of where your documents will be placed.
  12. If necessary, monitor the progress of the promote job by viewing the Status field in the Status view at the bottom of the layout. You'll see any of the following status values:
    • Pending - the job has yet to be picked up by an agent.
    • Validation - an agent is validating the job to make sure it has the required settings, such as access to the source and destination objects (saved searches, workspaces, etc.). If validation fails, the status changes to "Validation failed," and Relativity logs an error. If the validation succeeds, the job moves on to a status of "Processing."
    • Validation failed - the job validation has failed, resulting in an error, the details of which are saved in the Job History Errors tab.
    • Processing - the agent has picked up the job and is in the process of completing it.
    • Completed - the job is complete, and no errors occurred.
    • Completed with errors - the job is complete and errors have occurred.
    • Error - job failed - a job-level error occurred and the job didn't complete because it failed.
    • Stopping - you clicked the Stop button, and the stop job has yet to be picked up by an agent.
    • Stopped - the job has been stopped.

Once you start the promote job, you have the option of stopping the job or viewing the documents that you've just promoted to the review workspace.

Stopping a job

Relativity gives you the option of stopping an integration points job from proceeding in the event that you need to re-prioritize it or because you made a mistake when creating it. You can do so when that job has a status of Pending or Processing. To do this, click Stop on the console.

(Click to expand)

Note: The Total of Images value displays the size of only the physically-transferred files, meaning that it doesn't count document size when only metadata is being transferred.

Relativity then informs you that you won't be removing any data by stopping the transfer and that you should check to make sure that the overwrite setting you previously entered is still appropriate for the re-run.

Click Stop Transfer to proceed.

  • Once Relativity stops the job, the Job Status field on the Status view reflects this.
  • Note the following about stopping an Integration Points job:

    • You can also stop a scheduled job if it has a status of Pending or Processing.
    • A job is unstoppable if it has any status other than Pending or Processing, or the point at which Relativity starts promoting documents with such as information as the user who tagged them and the source workspace.
    • When you click Stop, Relativity immediately stops creating new errors for that job.
    • When you click Stop on a run-now job, Relativity marks all errors associated with the current job history as Expired.
    • When you click Stop on a retry job, Relativity marks all errors associated with the current job history and the previous job as Expired.
    • You can start a scheduled job after you've already stopped it.
    • The item counts on the Integration Points layout reflect all items promoted before the agent received the signal to stop the job.

    To re-start a stopped job, click Run. When you do this, Relativity begins to transfer data again from the beginning but doesn't remove any data already transferred.

    Working with promoted documents

    To view the documents you promoted to the review workspace, perform the following steps:

    1. Navigate to the destination workspace.
    2. Select the Saved Search browser and select the search you created to bring back documents that were promoted from ECA.
    3. Note the following ECA-relevant fields on the promoted-from ECA saved search view:
      • Relativity Source Case - the name of the workspace in which you tagged documents for inclusion and exclusion and from which you promoted your tagged documents to the review workspace.
      • Relativity Source Job - the name of the Integration Point that you used to promote tagged documents to the review workspace.

    You can now review these documents and apply coding decisions for responsiveness and/or issues designation.

    Reusing coding decisions

    You can re-use the coding decisions you made on reviewed documents and promote them back into the ECA workspace through another Integration Point. For example, you could run another promote job to conduct a privilege overlay on documents in the source workspace.

    To do this, perform the following steps:

    1. Select the saved search you created to promote documents back to the ECA (source) workspace.
    2. Navigate to the Integration Points tab.
    3. Create a new integration point that specifies the following values, which differ from those you entered for the promote job you ran previously:
      1. Destination Workspace - select the original source workspace, specifically the workspace from which you previously promoted documents to the review workspace.
      2. Saved Search - select the saved search you created to promote documents back to the ECA (source) workspace.
      3. Field Mappings - map only Control Number (Object Identifier) and Privilege Designation.
      4. Overwrite - select Overlay Only.
    4. Click Run.
    5. Navigate to the ECA Dashboard and select the promoted-from-review saved search.
    6. In the widgets drop-down list, select Coding Values. Note that the widgets and document list in this dashboard reflect the coding decisions that were applied to each document in the review workspace.

    Performance baselines

    The following table presents performance baselines for using the Relativity provider in Integration Points to promote documents and metadata between workspaces.

    The jobs which yielded the following metrics were performed on a basic test environment of Relativity. Due to differences in data, infrastructure, and configuration, these should not be used as a benchmark of what you expect to see in a production environment. The results may not scale linearly.

    Document Count

    Job Size (GB)

    Copy Native Setting

    Job duration (HH:MM)

    10,000 documents

    0.85

    Copy

    00:04

    10,000 documents

    0.85

    Links Only

    00:04

    100,000 documents

    9.42

    Copy

    00:42

    100,000 documents

    9.42

    Links Only

    00:27

    100,000 documents

    0

    No

    (Metadata only)

    00:16

    100,000 documents (337,000 images)

    22.13

    Copy Images

    00:57

    100,000 documents (337,000 images)

    22.13

    Link Images

    00:43

    500,000 documents

    47.5

    Copy

    02:38

    500,000 documents

    47.5

    Links Only

    02:03

    Field information:

    Total field count Fixed length Long text Multi choice Single choice Yes/No Date Single object Multi object Decimal Whole number
    100 25 39 3 2 13 4 1 8 1 1

    Handling errors

    Errors can occur at both the item and the job-level when you run your integration point.

    The following are examples of potential error causes:

    • Relativity is unable to retrieve a workspace.
    • The user who last created or edited the integration point is deleted before a scheduled job runs.
    • You promote documents with the same control numbers from two different source workspaces to the same destination workspace, which causes control number collisions.

    Note: Any item-level errors that you encounter in your integration point are generated by the Import API.

    To view these errors, click the View Errors link on the integration point console.

    (Click to expand)

    Clicking the View Errors link takes you to the Job History Errors tab. This link is unavailable if the job has a status of Stopped.

    Job history errors view

    In the Job History Errors tab, you can use the condition lists at the top of the view to find errors based on any error-related metadata fields, such as Artifact ID, Error, Error Status, Error Type, JobHistory, Name, Source Unique ID, Stack Trace, System Created By, System Created On, System Last Modified On, and Timestamp (UTC).

    Once you specify your conditions, you can search for the targeted errors by clicking Search on the right side of the condition lists.

    You can then open any of the individuals errors returned in the list by clicking the Name value.

    Single RIP error layout

    The Job History Error Layout provides the following fields:

    • Name - the system-generated name of the error.
    • Source Unique ID - the identifier of the item in which the error occurred.
    • Job History - the name of the integration point containing the file in which the error occurred.
    • Error - the error message.
    • Error Status - the current state of the error. The possible statuses are:
      • New - the error is new and no action has been taken.
      • Expired - the state assigned to an item level error in either of the following scenarios:
        • You received an item-level error on a job, you didn't retry the error, and the job ran on a schedule, meaning the Enable Scheduler field is set to Yes on the integration point.
        • You received an item-level or a job-level error, you didn't retry the error, and you click Run on the integration point, or it is a scheduled job.
      • In Progress - the error is currently in the process of being retried.
      • Retried - the item level error in a job has been retried, meaning you clicked Retry Errors on the integration point and the retry job is complete.
    • Error Type - an indicator of whether the error is item- or job-level.
    • Full Error- the error message with details, including a stack trace of the error, when available.
    • System Created On - the date and time when the agent created the error during the integration point job.
    • System Created By - the agent that created the error during the integration point job.
    • System Last Modified By - the agent that last updated the status value of the error.

    With the information provided in the Job History Errors Layout, you can identify those files on which errors occurred. You can then access those files to manually address the causes of those errors. From there, you can return to the integration points console and retry the errors.

    Item-level versus job-level errors

    Note the following differences in the way Relativity handles item-level and job-level errors.

    Relativity handles a mix of item-level and job-level errors in the following way:

    • When you click Run on an integration point that contains item- and job-level errors, the entire job is re-run and all errors are marked as Expired.
    • When you click Retry Errors on an integration point that contains item- and job-level errors, the entire job is rerun and Relativity assigns a value of Expired to the item-level errors while job-level errors are marked as In Progress and then Retried.

    Relativity handles item-level errors in the following way:

    • When you click Run , the entire job is re-run, and Relativity assigns a value of Expired to the item-level errors.
    • When you click Retry Errors, Relativity assigns a value of Retried to the item-level errors and starts a retry job containing only those error documents.

    Note: When you retry errors for a job that contains only item-level errors, Relativity creates a temporary saved search that contains only those item-level error documents, which the Export Service Manager and Export API can refer to. This search is called "Temporary Search" and is public and visible to users in the saved search browser for the duration of the retry errors job. Once Relativity completes the retry errors job, it deletes this temporary search.

    Relativity handles job-level errors in the following way:

    • It registers only one job-level error for the integration point.
    • When you click Run , the entire job is re-run and Relativity assigns a value of Expired to the job-level error.
    • The Retry Errors and Run buttons are both available.
    • The Retry Error button re-runs the whole job, but the job-level error is marked as In progress and then retried.
    • The Run button re-runs the whole job, but the job-level error is marked as Expired.

    Scheduled job is not inserted and an error is thrown that shows up in the errors tab in Admin mode that a scheduled job did not run for this integration because the job was already running.

    Troubleshooting job history errors

    Relativity provides informative and actionable error messages when you attempt to save and run an integration point in any of the following situations:

    (Click to expand)

    • The destination workspace is missing.
    • The destination field is missing.
    • You don't have permissions to a saved search, production, or destination workspace.
    • The destination field has missing child object data.
    • The production is missing from the destination workspace.

    The following table provides some of the errors you could encounter when attempting to run an Integration Points job, along with information on how to resolve them:

    Error Likely resolution
    Destination field(s) mapped has different type. Review the mapping for the following field(s): field_1, field_2 Review the fields listed in the error message, and check if you have the same type as expected. If the reason for changing the type was to delete the file and re-create it, then it will be un-mapped. Correct the mapping saved in the Integration Point job, and run the job again.
    Destination field(s) mapped may no longer be available or has been renamed. Review the mapping for the following field(s) [field name]. Review if the failing field(s) still exist in the destination workspace, correct the mapping saved in the Integration Point job, and run the job again.
    Destination workspace is not available. Verify if destination workspace exists.
    Destination workspace on federated instance is not available. Check if destination workspace still exists or if a user has a proper permission to access it. Confirm that you still have access to the destination workspace on the federated instance. It is also required that a System Admin account is present (used by an Integration Points Agent) and has access to the destination workspace.
    Failed to copy source field into destination field due to missing child object. Review the following destination field(s): [field names] Review the list of failing fields, create the child/parent relation in the destination workspace as it is in the source workspace and try again. If that doesn't work, try to use the RDC export and import functionality to move those missing fields only.
    Saved search is not available or has been secured from this user. Contact your system administrator. Verify that you have the required permissions for the saved search, or check to see if the saved search has been deleted. If needed, contact your system administrator to verify the saved search configuration.
    Unable to connect to federated instance. Check if destination instance still exists or if a user has a proper permission to access it. There was a problem connecting to the federated instance, and you need to verify that the federated instance is still available and that the authorization token didn't expire.
    User does not have sufficient permissions to access destination workspace. Contact your system administrator. Confirm that you still have access to the destination workspace. It is also required that a System Admin account is present (used by an Integration Points Agent) and has access to the destination workspace.
    Verify if a folder in destination workspace selected in the Integration Point exists or if a user has a proper permission to access it. Verify that the folder used for the integration point still exists. Also, check the permission settings for the folders in destination workspace to confirm that it's not secured for the user's group.
    Verify if a Production Set used as the location in destination workspace exists or if a user has a proper permission to access it. Verify that the production set used as the location in the destination workspace still exists. Also, check the permission settings for productions in the destination workspace to confirm that it's not secured for the user's group.
    Verify if a Production Set used as the location in destination workspace is in New status. Verify that the production set used as the location in the destination workspace still has a status of New. Only productions with a status of New can be used as a production set in an integration point. If the production set was already staged or run, it isn't a eligible to be used for the integration point.
    Verify if production, which is the data source of this Integration Point, still exist or if user has required permissions for it. Check to see if the production used as the data source of the integration point still exists. Also, verify that you have the required permissions for the production used as the data source. If needed, contact your system administrator to verify your production permissions.
    Verify if the user still has permission to create saved search on destination workspace. Verify that you have the required permissions for creating a saved search in the destination workspace for this integrated point job. If needed, contact your system administrator to verify your production permissions. One of missing permissions could be Search in Object Security and Advanced & Saved Searches in Other Settings, both of which are set in the group permission on destination workspace.

    Retrying errors

    Once you manually address the causes of the item-level errors that occurred in your integration point, you can retry those errors through the integration points console.

    To do this, click Retry Errors. When you do this, you submit a retry job to the system, and the system starts to import data from the source provider.

    (Click to expand)

    After you start the error retry job, you have the option of monitoring its progress through the Status field at the bottom of the layout. The job you just started has a Job Type value of Retry Errors and is listed as the first job in the Status view.

    Note the following about retrying errors:

    • The Retry Errors button is only be enabled when the previous job had an error to retry.
    • You're unable to retry errors for a job with a status of Stopped.
    • If you click Retry Errors and then click Stop on the retry job, Relativity marks both the current job's errors and those from the previous job as Expired.

    Note the following overwrite behavior during error retry:

    • If the original integration points job had an overwrite mode of Append Only, then when you click Retry Errors, that retry job has an overwrite mode of Append/Overlay.
    • If the original integration points job had an overwrite mode of Append/Overlay, then when you click Retry Errors, that retry job keeps the overwrite mode of Append/Overlay.
    • If you click Run on an integration point that has errors without resolving those errors, Relativity retains the overwrite mode specified in the original job.

    Viewing job history

    To view all the audit actions associate with all integration points in your workspace, select the Job History tab.

    (Click to expand)

    job history tab in ECA

    The default All Jobs view in the Job History tab provides the following fields:

    • Start Time (UTC) - the date and time at which an agent picked up the job.
    • Artifact ID - the identifier of the job.
    • Name - the name of the job. Clicking this takes you to the Job Details layout.
      (Click to expand)

    • Integration Point - the name of the integration point from which you ran the job.
    • Job Type - the type of job you ran. This displays one of the following values:
      • Run - the job was kicked off via the Run button on the integration point console.
      • Retry Errors - the job was kicked off via the Retry Errors button on the integration point console.
      • Scheduled Run - the job was kicked off via the Enable Scheduler field and subsequent time designation on the integration point layout.
    • Job Status - the current status of the job. This will display one of the following values:
      • Pending - the job has yet to be picked up by an agent.
      • Validation - an agent is validating the job to make sure it has the required settings, such as access to the source and destination objects (saved searches, workspaces, etc.). If validation fails, the status changes to "Validation failed," and Relativity logs an error. If the validation succeeds, the job moves on to a status of "Processing."
      • Validation failed - the job validation has failed, resulting in an error, the details of which are saved in the Job History Errors tab.
      • Processing - the agent has picked up the job and is in the process of completing it.
      • Completed - the job is complete, and no errors occurred.
      • Completed with errors - the job is complete and errors have occurred.
      • Error - job failed - a job-level error occurred and the job didn't complete because it failed.
    • Destination Workspace - the workspace to which you arranged to have documents promoted.
    • Items Imported - the number of documents successfully imported through the integration point. If errors occurred, this value is lower than the Total Items value and the difference appears in the Items with Errors field.
    • Total Items - the total number of documents included in the integration point. If this value is equal to the Items Imported, then no errors occurred. If errors have occurred, this value is higher than the Items Imported value and the difference between the two appears in the Items with Errors field.
    • Items with Errors - the number of documents that generated errors. If errors have occurred, this value is equal to the difference between the Items Imported and the Total Items fields.