Custom connectors

You can integrate into the Contracts Analysis pipeline through custom connectors. A custom connector is a framework that customers can use to wrap around their existing machine learning (ML) and artificial intelligence (AI) pipelines, applications, or third-party services, allowing seamless integration to the Contracts Analysis pipeline. You can use custom connectors to integrate an internal entity extraction application without having to manually export/import data from Relativity, connect to a third-party contract analytics tool you are currently using, and more.

Contracts custom connectors support the following functionality:

  • Document classification
  • Segmentation
  • Annotations
  • Field Population

Configuring a custom connector

To configure a custom connector:

  1. Create a New Contracts Model.
  2. For Model Type select External Analysis.
  3. Enter your API's endpoint URL for External API Endpoint.
  4. Click Check to verify connection.
    Note: This verification is performed from your Relativity web server. Depending on your Relativity infrastructure setup, connectivity may be different from your agent servers compared to your web servers. Check with your Relativity IT administrator if you experience problems.
    • Use the @ character to trigger a list of Relativity fields to select and map to a JSON property.
    • To send the document’s native file, use the Contracts Native field. This provides a base64 encoded version of the Relativity document in the request body.
  5. Click Edit Body to enter your API's JSON request body.
    • Use the @ character to trigger a list of Relativity fields to select and map to a JSON property.
    • To send the document’s native file, use the Contracts Native field. This provides a base64 encoded version of the Relativity document in the request body.
  6. Click Save once all mapping is complete.
    Note: Validation will occur to verify the input API Body is valid JSON. If not, a message will appear.
  7. Select a Relativity Object to populate from your API’s response.

Field mapping is done after saving the Model first and then going back to edit it.

Token mapping

To set up token mapping:

  1. After saving the model, you'll see three new sections appear:
    • Object Mapping
    • Document Mapping
    • Authentication Headers.
  2. Click the Edit button on the Object Mapping card to view a mapping interface with the Relativity Object Fields on the left and Response Properties on the right.
  3. Select the Relativity object fields from the list on the left.
  4. Click the Paste Response button on the right, then paste in a sample response from your API.
  5. Click the Generate Properties button at the bottom. Contracts's custom connector framework will parse the sample, extract the properties and display them to map to the Relativity object fields.
    Note: If your sample response does not contain all properties you can use the Add Tokens field at the top of the list to add any additional tokens needed for mapping.
  6. Once you have all fields mapped, click Save.
  7. The page will refresh and display the new token mappings at the bottom.
  8. For Authentication Headers, click New and add a Parameter Name, Parameter Value, and Parameter Location, header or URL.
  9. When the request is sent, we will append the headers so that each request or document includes the headers, allowing you to send custom headers for each request to support authentication requirements of third party services.

Custom connector developer documentation

This section provides an overview of custom connectors for developers.

Authentication

Custom connectors support the use of one of the following standard authentication methods: API Key.

Request

We provide you with a simple configuration interface to map Relativity fields to the properties in your API's request schema.

Requirements

  • All HTTP requests will be sent using the POST method.
  • HTTP version 1.1 is required. 2.0 is currently not supported.
  • Requests may be sent using HTTP or HTTPS. However, HTTPS is recommended.

Examples

Below are examples of API calls.

Extracted text example

In the following example, let’s say your API requires two fields to be sent for a request.

Name Description
id The document ID
text The extracted text of the document

An example JSON request body would look like the following:

An image showing an example JSON request body.

Native document example

In this example we show how you would send the native document API requires two fields to be sent for a request:

Name Description
id The document ID
fileType The native file type
fileData The base64 encoded native Document data

An example JSON request body would look like the following:

An image showing an example JSON request body.

Response

To take advantage of Contracts’ rich document viewer functionality in Relativity, Custom Connectors accepts the following fields in your API’s JSON response payload.

Name Type Use case Description Relativity field
documentId number ALL The Relativity ArtifactID of the document used to match the response of your API back to the document. Artifact ID (read only)
category string Classification The category of the contract Contract Type
probability decimal Classification The confidence score for the categorization of the contract Contract Type Confidence Score
title string ALL The title of the contract Contract Title
sections array Segmentation An array of sections Section
annotations array Annotation An array of Annotations Annotation
fields array Relativity Field Population An array of Fields Field

Section (Relativity document)

The following table provides descriptions and use cases for Section fields.

Name Type Use case Description Relativity field
text string Segmentation (required) The text of the section Contracts Extracted Text
heading string Segmentation (optional) The heading of the section Section Heading
start integer Segmentation (required) The start offset of the Section in relation to the original Relativity Document Contracts Extracted Text Contracts Section Start
end integer Segmentation (required) The end offset of the Section in relation to the original Relativity Document Contracts Extracted Text Contracts Section End
category string Segmentation (optional) The category of the section Section Type
probability decimal Segmentation (optional) The confidence score for the categorization of the section Section Type Confidence Score

Annotation (RDO)

The following table provides descriptions and use cases for Annotation (RDO) fields.

Name Type Use case Description RDO field
text string Annotation (required) The text of the annotation Text
category string Annotation (required) The category or type of the annotation Category
offset integer Annotation (required) The start offset of the Annotation in relation to the original Relativity Document Contracts Extracted Text Length
length integer Annotation (required) The length of the Annotation string Offset

Field (Contracts internal)

The following table provides descriptions and use cases for fields.

Name Type Use case Description RDO field
field string Relativity Field Population (required) The unique name of the field Contracts Internal Field
value string Relativity Field Population (required) The value of the field Contracts Internal Field
locations array Relativity Field Population (required) An array of locations for boundary boxes for the field Location

Location (Contracts internal)

The following table provides descriptions and use cases for Location fields.

Name Type Use case Description RDO field
page number integer Relativity Field Population (required) The page number of the boundary box of the field in the document Contracts Internal Field
left decimal Relativity Field Population (required) The left coordinate of the bounding box as a ratio of the overall document page width Contracts Internal Field
top decimal Relativity Field Population (required) The top coordinate of the bounding box as a ratio of the overall document page height Contracts Internal Field
height decimal Relativity Field Population (required) The height of the bounding box as a ratio of the overall document page height Contracts Internal Field
width decimal Relativity Field Population (required) The width of the bounding box as a ratio of the overall document page width Contracts Internal Field

Examples

Following are examples of API calls.

Annotation, segmentation, and classification

The following are example responses your API would return to support the use cases of annotations, segmentation, and classification.

Annotations

This example will save an Organization annotation on document 12345 with the text of “Acme & Sons Bank”. This annotation will be visible to users when viewing the document with the Contracts Viewer.

An image of an example API response.

Segmentation

This example will create two sections on document 12345. These sections will be visible to users when viewing the document with the Contracts Viewer.

An image of an example API response.

Classification

This example will classify document 12345 as a Loan Agreement and save that classification to the Contract Type Relativity field.

An image of an example API response.

Relativity field population

The following is an example response your API would return to support the Relativity Field Population use case.

This example identifies in document 12345 the fields Invoice ID and Invoice Amount which can be setup to map to a Relativity Object when running Contracts Analysis.

An image of an example API response.