Field Mapping service

The Field Mapping service available in the REST API supports multiple operations required to map fields in Relativity to fields in an external data source. You can use this service to retrieve a list of fields that are available for mapping from an external data source, and to retrieve a list of fields in Relativity that are already mapped. Additionally, you can use it to update and read existing field mappings.

Note: Currently, this service supports only managing the mappings between fields in Relativity and Invariant. This functionality supports the processing feature available in Relativity. For more information, see Processing on the Relativity Documentation site.

For example, you can use this service to populate a custom dialog in your application with fields for available for mapping.

The Relativity Services API also provides functionality for mapping fields from Invariant to those in Relativity. For more information, see Field Mapping API.

This page contains the following information:

• Client code sample
• Check field mapping availability
• Retrieve mapped Relativity fields
• Retrieve Invariant fields available for mapping
• Retrieve an external field mapping
• Update an external field mapping
• Retrieve GUIDs for automapped fields
• Clear cached data

Client code sample

You interact with the Field Mapping service by sending an HTTP request that uses the POST method. You specify query conditions in the body of the request. See the base URL for this service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/

You can use the following .NET code as the REST client for executing field mapping calls. The code illustrates how to perform the following tasks:

• Instantiate an HttpClient object for sending requests and responses using the URL for the Field Mapping service.
• Set the required headers for the request.
• Set the url variable to the URL for the operation that you want to perform.
• Set the string represented by payload variable to the JSON input required for your operation.
• Use the PostAsJsonAsync() method to send a post request.
• Return the results of the request.

public async Task<MappableSourceField[]> GetMappableFields()
{
    Task<MappableSourceField[]> result = null;

    using (HttpClient httpClient = new HttpClient())
    {
 
        httpClient.BaseAddress = new Uri("http://localhost/relativity.rest/api/Relativity.Services.FieldMapping.IFieldMapping/");
 
        //Set the required headers.
        httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
        httpClient.DefaultRequestHeaders.Add("Authorization", "Basic c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");
 
        string url = " GetInvariantFieldsAsync ";
 
        int workspaceArtifactId = 1234567;
        bool catalogFieldsOnly = true;
 
        var payload = @"{
                    workspaceArtifactID:{0},
                    catalogFieldsOnly:{1}
}";
 
        result = await httpClient.PostAsJsonAsync(url, string.Format(workspaceArtifactId, catalogFieldsOnly);
    }

    return result;
}

Check field mapping availability

Before attempting to map fields, you can make a REST API call that checks for the availability of an external data source.

Note: The Field Mapping service currently only supports field mapping between Invariant and Relativity. You can use the IsFieldMappingAvailableAsync() method on the service to confirm that Invariant is running.

To check data source availability, send a request to this URL for the Field Mapping service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/IsFieldMappingAvailableAsync

The request must have the Artifact ID of the workspace where you want to map fields.

{
    "workspaceArtifactId":1046331
}

The response contains a value of true or false. When this method returns false, your data source isn't currently available. You may want to contact your system admin to troubleshoot this issue.

Retrieve mapped Relativity fields

To retrieve a list of Relativity fields mapped to a corresponding field in the data source, send a request to this URL for the Field Mapping service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/GetAllMappedFieldsAsync

The request must have the following fields:

• workspaceArtifactId – the Artifact ID of the workspace that contains the mapped Relativity fields.
• fieldsToAppend – a list of GUIDs corresponding to Relativity fields, which have field data returned for them regardless of whether they are mapped to a data source. Only Invariant currently uses this field. For general use, send in the empty set ([]) for this parameter.
• dataSourceId – the Artifact ID of the processing data source used to populate the mapped fields.

  Note: Set this value only if you want an audit of the mapped fields added to the corresponding data source in Relativity. In all other cases, pass the integer 0 as the parameter.

{
    "workspaceArtifactId": 1046331,
    "fieldsToAppend": [],
    "dataSourceId": 0
}

The following list contains information about fields in a response that have specialized functions or usage requirements:

• MappingId – the identifier of the database record that contains the mapping between a Relativity field and a data source field.
• FieldGuid – the GUID of the field in Relativity. This property won't have a value unless the associated field is part of a Relativity application.
• RelativityFieldName – the name of the field as it appears in Relativity.
• FieldTypeID – the value that corresponds to the kCura.Relativity.Client.FieldType enumeration.
• EnabledDataGrid – a flag indicating whether a field is enabled for Data Grid. This flag is valid only for text fields.
• ExternalFieldName – the name of the field in the external data source.
• ExternalFieldSource – the name of the external data source associated with the mapping. Currently, this fields should always be set to "Invariant".
• FriendlyName – the user-friendly name of the source field. The service populates this field only for members of the Field Catalog. The Field Catalog is a collection of industry best practice fields used with processing. It currently includes 127 fields consistently populated with document metadata. For more information, see Mapping processing fields on the Documentation Server2021 site.
• UseUnicodeEncoding – indicates that the field uses Unicode encoding. This setting only applies to text fields. The service only maps a text field if this value is true.
• CatalogLength – the maximum length for a fixed-length catalog field.
• CurrentLength – the current maximum length of a fixed-length field in the Relativity database.
• ObjectType – the integer representing the field’s object type. This value corresponds to the kCura.Relativity.Client.ArtifactType enumeration. The service uses this value for validation. Only Artifact Type 10, which corresponds to the Document object, is valid for field mapping.
• IsArtifactBaseField – a Boolean flag indicating whether the field is a base field. A base field is a type of system field, and isn't valid for field mapping.
• FieldCategory – an integer indicating the category of the field. This value corresponds to the kCura.Relativity.Client.FieldCategory enumeration. The following field categories are system fields, which aren't valid for field mapping: AutoCreate, Batch, FolderName, FullText, GenericSystem, MarkupSetMarker, ParentArtifact, ProductionMarker, Reflected, and MultiReflected.
• AssociativeArtifactTypeID – the Artifact Type of an associated object. If the associated ArtifactTypeID is equal to Batch (8), the field isn't valid for field mapping.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Retrieve Invariant fields available for mapping

To retrieve Invariant fields that are available for mapping, send a request to this URL for the Field Mapping service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/GetInvariantFieldsAsync

The request must have the Artifact ID of the workspace that contains the Invariant fields available for mapping.

{
    "workspaceArtifactId":1046331
}

The response always returns the following fields:

• Category – the category of the metadata stored in the field, such as child, email, matter, and others.
• SourceName – the name of the field used by the external data source.
• DataType – the type of data stored in the field, such as fixed-length text, whole number, or others.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Retrieve an external field mapping

To retrieve an external field mapping for a field with the specified Artifact ID, send a request to this URL for the Field Mapping service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/ReadExternalMappingAsync

The request must have the following fields:

• workspaceArtifactId – the Artifact ID of the workspace that contains the field for retrieval.
• fieldArtifactId – the Artifact ID of the field with a mapping that you want to retrieve.
• fieldSource – the string that identifies the field source. This service currently supports only Invariant as the field source.

{
    "workspaceArtifactId":1046331,
    "fieldArtifactId":1039415,
    "fieldSource":"Invariant"
}

For descriptions of specialized fields in the following JSON response, see Retrieve mapped Relativity fields.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Update an external field mapping

To modify or add field mapping data, send a request to this URL for the Field Mapping service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/UpdateExternalMappingAsync

The request must have the following fields:

• workspaceArtifactId – the Artifact ID of the workspace where you want to update the mapped fields.
• model – an ExternalMapping object with the updated data. For descriptions of specialized fields in the model, see Retrieve mapped Relativity fields.

On the model, you must set the following properties to make a successful UpdateExternalMappingAsync() method call:

• ExternalFieldName - the name of the field in the external data source. Set this property to null if you want to remove the field mapping.
• ExternalFieldSource - the name of the external data source associated with the mapping. Currently, this fields should always be set to "Invariant".
• FieldArtifactId - the Artifact ID of the Relativity field being mapped.

In addition, you should also set specific fields that are used for validation. If you don't set these fields correctly, the field mapping may not update. The following list includes fields used for validation:

• CurrentLength - For fixed-length catalog fields, you must set this property to a minimum field length required for validation. For example, if the CurrentLength property is set to 0 when you attempt to map a fixed-length catalog field, the validation fails.
• FieldTypeId - The service validates the property against the data type that Invariant uses for the field source. For example, you may want to map a source field that Invariant identifies as a Date type. If you set the FieldTypeId property to 0 indicating a fixed-length text field, then the validation fails and the field isn't mapped. The values for this property correspond to the kCura.Relativity.Client.FieldType enumeration.
• ObjectType - You must set this property to 10.
• UseUnicodeEncoding - For text fields, you must set this property to true.

{
    workspaceArtifactId: 1046331,
    model: {
        "FieldArtifactId": 1039415,
        "RelativityFieldName": "Parent Document ID",
        "FieldTypeId": 0,
        "EnableDataGrid": true,
        "ExternalFieldName": "ParentRelativityControlNumber",
        "ExternalFieldSource": "Invariant",
        "UseUnicodeEncoding": true,
        "CurrentLength": 50,
        "ObjectType": 10,
        "IsArtifactBaseField": false,
        "FieldCategory": 0
    }
}

The response returns the status code of 200. The Relativity UI displays the field update, such as an ExternalFieldName called BCC Address, which is renamed to BatesBeginDoc.

Retrieve GUIDs for automapped fields

During a publish operation, Invariant automatically maps certain processing system fields. The GetAutomappedFieldGuidsAsync() method retrieves a list of GUIDs that Invariant uses to identify these fields.

To retrieve this list of GUIDs, send a request to this URL for the Field Mapping service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/GetAutomappedFieldGuidsAsync

The request must have the Artifact ID of the workspace where you want to map fields.

{
    "workspaceArtifactId": 1046331
}

The response returns a list of GUIDs for the corresponding ExternalMapping objects. These objects represent mappings between Relativity and an external data source fields. For more information, see Field Mapping API.

Clear cached data

The ClearCachedDataAsync() method removes all cached data from Relativity, Invariant, and the Field Catalog. You can use this method for testing purposes, and for clearing cached data that may be corrupt.

To clear the cache, send a request to this URL for the Field Mapping service:

<host>/Relativity.Rest/api/Relativity.Services.FieldMapping.IFieldMappingModule/FieldMappingService/ClearCachedDataAsync

You don't need to provide any information in the body of the request. The response returns the status code of 200.