Field Mapping Manager (REST)

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 RelativityOne Documentation site.

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

You can also use the Field Mapping service through the .NET API. For more information, see Field Mapping.

Note: See the topic Get started with the Processing API for general guidance on the Processing API, and links to documentation for the other interfaces and services in this API.

Client code sample

You interact with the Field Mapping service by sending an HTTP request to the target URL. Use PostAsync() for POST requests, GetAsync() for GET requests, and PutAsync() for PUT requests. You specify query conditions in the body of the request. See the base URL for this service:

Copy 
<host>/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/

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 PostAsync() to retrieve data.
  • Return the results of the request.
Copy 
public List<Guid> GetAutoMappedFieldGuids(int workspaceId)
{
    string endpoint = $"relativity-processing/v1/workspaces/{workspaceId}/field-mappings/auto/guids";
    HttpResponseMessage response = SendProcessingKeplerGetRequest(endpoint);
    string responseContent = response.Content.ReadAsStringAsync().ConfigureAwait(false).GetAwaiter().GetResult();
    var guids = JsonConvert.DeserializeObject<List<Guid>>(responseContent);
    if (!response.IsSuccessStatusCode)
    {
        string genericErrorMessage = "Failed to get automapped field guids.";
        throw ConstructHttpException(genericErrorMessage, response);
    }
    return guids;
}

private HttpResponseMessage SendProcessingKeplerGetRequest(string apiEndpoint)
{
    string relativityRestApi = ExtensionPointServiceFinder.ServiceUriProvider.RestUri().AbsoluteUri;
    string fullEndpoint = $"{relativityRestApi}/{apiEndpoint}";
    HttpClient client = new HttpClient();
    Credentials credentials = new BearerTokenCredentials(ClaimsPrincipal.Current.Claims.AccessToken());
    string credentialParameter = credentials.GetAuthenticationHeaderValue().Replace("Bearer ", "");
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", credentialParameter);
    client.DefaultRequestHeaders.Add("X-CSRF-Header", "");
    return SendGetRequest(client, fullEndpoint);
}

private HttpResponseMessage SendGetRequest(HttpClient client, string fullEndpoint)
{
    HttpResponseMessage response = client.GetAsync(fullEndpoint).ConfigureAwait(false).GetAwaiter().GetResult();
    if (response.StatusCode == HttpStatusCode.NotFound)
    {
        throw new HttpException("Unable to complete GET Processing request, service is not up or unreachable.");
    }
    return response;
}

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 GET request to this URL for the Field Mapping service:

Copy 
<host>/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/available

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 GET request to this URL for the Field Mapping service:

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/data-sources/0/field-mappings/relativity

The request body must have the following 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.

Copy 
{
    "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 Product Documentation 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.

JSON response for mapped Relativity fields

Copy 
[
  {
    "MappingId": 1016,
    "FieldArtifactId": 1035380,
    "FieldGuid": "8bb7059c-07cc-453a-8b84-981296d7263d",
    "RelativityFieldName": "Number of Attachments",
    "FieldTypeId": 1,
    "EnableDataGrid": false,
    "ExternalFieldName": "AttachmentCount",
    "ExternalFieldSource": "Invariant",
    "FriendlyName": "Number of Attachments",
    "UseUnicodeEncoding": false,
    "CatalogLength": 0,
    "ObjectType": 10,
    "IsArtifactBaseField": false,
    "FieldCategory": 0
  },
  {
    "MappingId": 1004,
    "FieldArtifactId": 1058862,
    "RelativityFieldName": "Author",
    "FieldTypeId": 0,
    "EnableDataGrid": false,
    "ExternalFieldName": "Author",
    "ExternalFieldSource": "Invariant",
    "FriendlyName": "Author",
    "UseUnicodeEncoding": true,
    "CatalogLength": 50,
    "CurrentLength": 50,
    "ObjectType": 10,
    "IsArtifactBaseField": false,
    "FieldCategory": 0
  },
  {
    "MappingId": 1019,
    "FieldArtifactId": 1035373,
    "FieldGuid": "4946a783-90e3-4acb-8171-f915e5b6fe5a",
    "RelativityFieldName": "Bates Beg Attach",
    "FieldTypeId": 0,
    "EnableDataGrid": false,
    "ExternalFieldName": "BatesBeginAttach",
    "ExternalFieldSource": "Invariant",
    "FriendlyName": "",
    "UseUnicodeEncoding": true,
    "CurrentLength": 50,
    "ObjectType": 10,
    "IsArtifactBaseField": false,
    "FieldCategory": 0
  },
  {
    "MappingId": 1018,
    "FieldArtifactId": 1037987,
    "RelativityFieldName": "Attachment Name",
    "FieldTypeId": 4,
    "EnableDataGrid": false,
    "ExternalFieldName": "Email/x-attach-name",
    "ExternalFieldSource": "Invariant",
    "FriendlyName": "",
    "UseUnicodeEncoding": true,
    "ObjectType": 10,
    "IsArtifactBaseField": false,
    "FieldCategory": 0
  },
  {
    "MappingId": 1021,
    "FieldArtifactId": 1035356,
    "FieldGuid": "8bf21905-fa72-47c8-bd04-070d451a3c3d",
    "RelativityFieldName": "Delivery Receipt",
    "FieldTypeId": 3,
    "EnableDataGrid": false,
    "ExternalFieldName": "EmailDeliveryReceiptRequested",
    "ExternalFieldSource": "Invariant",
    "FriendlyName": "Delivery Receipt Requested",
    "UseUnicodeEncoding": false,
    "CatalogLength": 0,
    "ObjectType": 10,
    "IsArtifactBaseField": false,
    "FieldCategory": 0
  },
  {
    "MappingId": 1005,
    "FieldArtifactId": 1035360,
    "FieldGuid": "6e891164-cb1c-4c1d-8172-a39c27110747",
    "RelativityFieldName": "Control Number Beg Attach",
    "FieldTypeId": 0,
    "EnableDataGrid": false,
    "ExternalFieldName": "RelativityBegAttach",
    "ExternalFieldSource": "Invariant",
    "FriendlyName": "Control Number Beg Attach",
    "UseUnicodeEncoding": true,
    "CatalogLength": 50,
    "CurrentLength": 255,
    "ObjectType": 10,
    "IsArtifactBaseField": false,
    "FieldCategory": 0
  }
]

Retrieve Invariant fields available for mapping

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/invariant

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.

JSON response for available Invariant fields

Copy 
[
    {
        "Category": "Child",
        "SourceName": "AttachmentCount",
        "FriendlyName": "Number of Attachments",
        "Description": "Number of files attached to a parent document.",
        "DataType": "Whole Number"
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "AttachmentNumber",
        "DataType": "Int32"
    },
    {
        "Category": "Email",
        "SourceName": "Author",
        "FriendlyName": "Author",
        "Description": "Original composer of document or sender of email message.",
        "DataType": "Fixed-Length Text",
        "MappedFields": [
            "Author"
        ]
    },
    {
        "Category": "Child",
        "SourceName": "BatesBeginAttach",
        "FriendlyName": "Control Number Beg Attach",
        "Description": "The identifier of the first page of the first document in a family group. This is used for page-level numbering schemes.",
        "DataType": "Fixed-Length Text",
        "MappedFields": [
            "A long"
        ]
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "BatesBeginDoc",
        "DataType": "String"
    },
    {
        "Category": "Child",
        "SourceName": "BatesEndAttach",
        "FriendlyName": "Control Number End Attach",
        "Description": "The identifier of the last page of the first document in a family group. This is used for page-level numbering schemes.",
        "DataType": "Fixed-Length Text"
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "BatesEndDoc",
        "DataType": "String"
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "BatesPageNumber",
        "DataType": "String"
    },
    {
        "Category": "Child",
        "SourceName": "ChildFileNames",
        "FriendlyName": "Attachment List",
        "Description": "Attachment file names of all child items in a family group, delimited by semicolon, only present on parent items.",
        "DataType": "Long Text"
    },
    {
        "Category": "Child",
        "SourceName": "ChildMD5Hashes",
        "FriendlyName": "Child MD5 Hash Values",
        "Description": "Attachment MD5 Hash values of all child items in a family group, delimited by semicolon, only present on parent items.",
        "DataType": "Long Text"
    },
    {
        "Category": "Child",
        "SourceName": "ChildRelativityControlNumbers",
        "FriendlyName": "Attachment Document IDs",
        "Description": "Attachment document IDs of all child items in family group, delimited by semicolon, only present on parent items.",
        "DataType": "Long Text"
    },
    {
        "Category": "Child",
        "SourceName": "ChildSHA1Hashes",
        "FriendlyName": "Child SHA1 Hash Values",
        "Description": "Attachment SHA1 Hash values of all child items in a family group, delimited by semicolon, only present on parent items.",
        "DataType": "Long Text"
    },
    {
        "Category": "Child",
        "SourceName": "ChildSHA256Hashes",
        "FriendlyName": "Child SHA256 Hash Values",
        "Description": "Attachment SHA256 Hash values of all child items in a family group, delimited by semicolon, only present on parent items.",
        "DataType": "Long Text"
    },
    {
        "Category": "General",
        "SourceName": "Comments",
        "FriendlyName": "Comments",
        "Description": "Comments extracted from the metadata of the native file.",
        "DataType": "Long Text"
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "ContainerExtension",
        "DataType": "String"
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "ContainerID",
        "DataType": "Int64"
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "ContainerName",
        "DataType": "String"
    },
    {
        "Category": "Email",
        "SourceName": "ConversationFamily",
        "FriendlyName": "Conversation Family",
        "Description": "Relational field for conversation threads.  This is a 44-character string of numbers and letters that is created in the initial email.",
        "DataType": "Fixed-Length Text"
    },
    {
        "Category": "General",
        "SourceName": "CreatedOn",
        "FriendlyName": "Date Created",
        "Description": "Date and time from the Date Created property extracted from the original file or email message.",
        "DataType": "Date",
        "MappedFields": [
            "Date Created"
        ]
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "DataGridDocMetadataId",
        "DataType": "Int32"
    },
    {
        "Category": "Matter (Common)",
        "SourceName": "DataGridId",
        "DataType": "Guid"
    },
    {
        "Category": "General",
        "SourceName": "DeDupedCustodians",
        "FriendlyName": "DeDuped Custodians",
        "Description": "Custodians associated with the de-duped records of this document.",
        "DataType": "Multiple Object"
    },
    {
        "Category": "General",
        "SourceName": "DeDupedPaths",
        "FriendlyName": "DeDuped Paths",
        "Description": "Folder structure and paths to this document's duplicates. Each path will contain the associated custodian.",
        "DataType": "Long Text"
    },
    {
        "Category": "(Saved Fields)",
        "SourceName": "DedupeHash",
        "DataType": "String"
    }
...
]

Retrieve an external field mapping

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/external?fieldID={your field artifact ID}&fieldSource={field source, usually 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.

JSON response for an external field mapping

Copy 
{
    "MappingId": 4,
    "FieldArtifactId": 1039415,
    "RelativityFieldName": "Other Properties",
    "FieldTypeId": 4,
    "EnableDataGrid": false,
    "ExternalFieldName": "OtherProps",
    "ExternalFieldSource": "Invariant",
    "FriendlyName": "Other Props",
    "UseUnicodeEncoding": true
}

Update an external field mapping

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings?fieldID={your field artifact ID}

The request must have the following 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".
  • FieldID - the Artifact ID of the Relativity field being mapped.
Copy 
{
    "model": {
        "FieldID": 1086017,
        "RelativityFieldName": "test",
        "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. This method retrieves a list of GUIDs that Invariant uses to identify these fields.

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/auto/guids

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 Manager.

JSON response for an external field mapping

Copy 
[
    "a37f5152-2354-4102-88bd-09e2387a0c83",
    "ab44a773-e968-454f-92d7-a29f4f61dc9f",
    "9876411c-1e32-436a-bedf-19267b590c17",
    "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438",
    "8ac3cec2-cebe-4c11-9e5a-e934df45aaf5",
    "1618195a-b7f1-4732-a57d-b2b5efd4d2db",
    "ef3210e4-a53b-4498-ada4-7183607eeeb4",
    "1aba1dc9-69ca-4eb6-a044-7ad8d01ed9c1",
    "aecaee0a-76ba-4860-ba55-d63b97525d41",
    "58d35076-1b1d-43b4-bff4-d6c089de51b2",
    "adb35bd6-9ffb-426f-ae71-4c2bf923ff81",
    "42bbfad4-f0fd-441b-bea7-79319976bcce",
    "61020401-15e7-4101-8082-d5276a60430a",
    "192c52b2-869e-4262-95f0-2c6a3f056610",
    "93e1cfeb-f21e-4386-adc3-846066525fe8",
    "b68a1fe7-f8df-4461-afae-4fb3e1169e6e",
    "6130fe12-5dba-46c9-8918-217329942da9",
    "a5768969-ead6-4160-a8d9-22aa9bae413a",
    "3163e7fc-b01e-4048-8423-c6f6eaff6114"
]

Get Invariant fields available for mapping with pagination

Retrieves an array of fields from Invariant that are available for field mapping and then paginated for performance.

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/pages?skip=0&top=10

Request Body example:

Copy 
{
    "fieldMappingRequest":{
        "Filter":{
            "NameFilter": "test"
        },
        "SortingOption":{
            "FieldName":"Name",
            "SortingDirection":"Asc"
        }
    }
}

Retrieve metadata fields

Retrieves an array of metadata fields from Invariant.

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

Copy 
Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/metadata-fields?skip=0&top=10

Request Body example:

Copy 
{
    "fieldMappingRequest":{
        "Filter":{
            "NameFilter": "test"
        },
        "SortingOption":{
            "FieldName":"Name",
            "SortingDirection":"Asc"
        }
    }
}

Retrieve non-metadata fields

Retrieves an array of non-metadata fields from Invariant

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/other-fields?skip=0&top=10

Request Body example:

Copy 
{
    "fieldMappingRequest":{
        "Filter":{
            "NameFilter": "test"
        },
        "SortingOption":{
            "FieldName":"Name",
            "SortingDirection":"Asc"
        }
    }
}

Retrieve field given source name

Returns field given source name

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/source-field?sourceName={your source field name}

Retrieve the contents of the Catalog Field table

Returns the contents of the Catalog Field table

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

Copy 
/Relativity.Rest/API/relativity-processing/v1/workspaces/{your workspace id}/field-mappings/catalog-fields