Monitoring job history and errors

Note: We’ve streamlined our Staging boundaries to more effectively separate staging data from workspace and system data. With this change, you can no longer write to or access data outside of the four defined staging area folders. The four defined staging area folders: ARM, ProcessingSource, StructuredData, and TenantVM.
Folders removed in the update include FTA, Temp, Export, and dtSearch. In addition to any other folders you manually created. Refer to the Staging Area topic and Staging Area FAQ in Community for more details.

After you create an integration point and initiate the import process, you can monitor the job status on the Job History tab and resolve errors on the Job History Errors tab.

Job History

This tab lists an entry for each integration point job, and also provides you with the ability to view additional details for a specific job.

The Job History tab lists the following information that you can use to monitor the status of an integration point job:

Start Time (UTC)—the date and time that a job started running in Coordinated Universal Time (UTC).
Artifact ID—the artifact ID of the workspace.
Name—the name for a specific job run by the integration point.
Integration Point—the name of the integration point used to run the job.
Job Status—the current status of an integration point job. The following job statuses are available:
- [blank]—the job has not started or was not run.
- Pending—the job has been submitted but an agent hasn't picked it up, so the import process hasn't started.
- Suspending—the system is performing the application update. The job prepares for being suspended, completing the current task.
- Suspended—the system is performing the application update. The job has been suspended, and waits for the Integration Points agent to pick it up.
- 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 job is currently running.
- Error - Job Failed—a job-level error occurred and the import wasn't completed. The integration point may have been able to import some of the records before the error occurred.
- Completed with Errors—the import job completed but at least one item-level error occurred. If you set the Log Errors field to Yes for the integration point, you can view the item-level errors in the section called Job History Errors on the Job Details layout. See Viewing job history details.
  Notes: When transferring custodians and associating them to managers, errors can occur. If transferring custodians and the manager isn't associated with a manager, the custodian transfer is completed successfully. It will show up as Completed with Errors even though the Items Transferred field and Total Items field will match, while the Items with Errors field states zero errors. This is because the custodian has been imported correctly, but the manager wasn't associated correctly.
- Completed—the import job completed without any item-level errors.
Destination Workspace—the workspace specified as the destination for the transferred files.
Items Read—the number of records successfully read from the job source and passed for transferring.
Items Transferred—the number of records successfully transferred when the job ran.
Total Items—the total number of items originally designated to be transferred, including those that ended up having errors.
Items with Errors—the number of records that the integration point failed to import due to item-level errors.

Viewing job history details

To view additional history information, click the name of a specific job listed on the Job History tab. The Job Details layout displays basic job information, import statistics, and a detailed list of errors.

The Job History Error section always logs job-level errors. If you set the Log Errors field to Yes, then it also logs item-level errors. For more information on setting the Log Errors field, see Importing data through Integration Points.

The Job Details layout includes many of the same fields displayed on the Job History tab. The following list includes the additional fields displayed in this layout:

End Time (UTC)—the date and time that a job completed in UTC.
Source Unique ID—the unique identifier for the record in the source that caused an error.
Error—a brief description of the error that occurred.
Timestamp—the date and time that a job error occurred in UTC.
Error Type—indicates whether the error occurred at the job or item level.

Job History Errors

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.

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. You'll see any of the following values for the status field:
- New—the error is new and no action has been taken on it yet.
- 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 Now 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 at which the error was created by the agent 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 errors 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.
When you click Retry Errors on an integration point that contains item- and job-level errors, the entire job is re-run.

Relativity handles item-level errors in the following way:

When you click Run, the entire job is re-run.
When you click Retry Errors, a retry job starts, including only those documents that caused errors.

Relativity handles job-level errors in the following way:

It registers only one job-level error for an integration point.
When you click Run, the entire job is re-run.
The Retry Errors button is not available.

Clicking the Retry Errors button starts a new job only for documents that caused errors in the previous run. If you edit an integration point settings before running the retry job, they will be applied to the retry job (except data source changes).

You can change, for example, Fields Mapping or Overwrite settings to allow the documents that caused errors to be transferred successfully.

Note: When you run Retry Errors for a job configured to copy physical files like natives or images in Append mode, the retry job mode is automatically set to Append/Overlay.
This intended behavior is to ensure consistency between copied metadata and native and image files. It may happen that during a job that has failed, only part of a given document (either metadata or files) has been transferred successfully. In such case, Append/Overlay mode allows transferring all the document data.
If you want to have the documents that caused errors transferred in other mode, you need to edit the integration point before running the Retry Errors job.

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:

The destination workspace is missing.
The destination field is missing.
You do not 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.
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.
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.
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.