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:

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:

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.

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.

Classification

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

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.