Field Manager (REST)

The Field Manager service provides multiple endpoints for programmatically working with field types supported by Relativity, including multiple choice, fixed-length text, date, and others. This service supports create, read, update, and delete operations on fields. Additionally, it includes helper endpoints for retrieving the following information:

  • Object types available to create fields on.
  • Associative object types for creating single object fields.
  • Associative object types for creating multiple object fields.
  • Views available for a specific object type.
  • Keyboard shortcuts that are currently defined in a workspace.
  • Keys that are valid for use in a keyboard shortcut.
  • Fields available for use with propagation.
  • Order of relational field icons in the Related Items pane of the core reviewer interface.

Sample use cases for the Field Manager service include programmatically adding new fields to a custom application as data requirements change, or creating new keyboard shortcuts for fields to support modified workflows for users.

You can also use the Field Manager service through .NET. For more information, see Field Manager (.NET).

Guidelines for the Field Manager service

Review the following guidelines for the Field Manager service.

URLs

The URLs for REST endpoints contain path parameters that you need to set before making a call:

  • Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1.
  • Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.
    • To indicate the admin-level context, set the {workspaceID} path parameter to -1.

For example, you can use the following URL to delete a field:

Copy 
<host>/relativity.rest/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/{fieldArtifactID}

Set the path parameters as follows:

  • {versionNumber} to the version of the service, such as v1.
  • {WorkspaceID} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.
  • {fieldArtifactID} variable to the Artifact ID of the field that you want to delete.

Supported field types

Use the Field Manager service to work with the same field types available through the Relativity UI. For general information about fields, see Fields on the RelativityOne Documentation site.

Helper endpoints

Use the helper endpoints to facilitate creating fields.

Relational fields

To edit properties for relational fields, the IsRelational field must be set to true. You can then edit the FriendlyName, ImportBehavior, PaneIcon, Order, and RelationalView properties. Set these fields as follows:

  • Set the ImportBehavior property to one of the following values:
    • None - indicates that no import behavior is specified.
    • LeaveBlankValuesUnchanged - indicates that the values for the fields are imported as blank.
    • ReplaceBlankValuesWithIdentifier - indicates that blank relational fields are updated with an identifier.
  • Set the properties on a PaneIcon object as follows:
    • Optionally, set the value for the FileName field for the pane icon.
    • Set the ImageBase64 property to the base64 format.

Overlay behavior

Set the value for the OverlayBehavior property to one of the following values. For more information, see the OverlayBehavior enumeration in the Relativity.ObjectModel.{versionNumber}.Field.Models namespace.

  • ReplaceValues - replaces existing field values with the new ones from the load file.
  • MergeValues - merges existing values with the new ones from the load file.

Filter types

Set the FilterType property to one of the following values. For more information, see the FilterType enumeration in the Relativity.ObjectModel.{versionNumber}.Field.Models namespace.

  • None - used for all field types.
  • List - used for currency, decimal, fixed-length text, multiple choice, single choice, user, and whole number field types.
  • MultiList - used for single choice, multiple choice, and multi-object field types.
  • Popup - used for single choice, multiple choice, single object, and multiple object field types. Only usable when the FilterType property is set to Popup.
  • Boolean - used for Yes/No field types.
  • TextBox - used for currency, date, decimal, fixed-length text, long text, single object, multiple object, and whole number field types.
  • Custom - used for currency, date, decimal, fixed-length text and whole number field types.
  • DatePicker - used for date field types.

Filter types for date and user fields

The Field Manager API currently sets the filter type for the date and user fields as follows. See the following descriptions:

  • Date field - You can now set the FilterType for this field to DatePicker through the API. However, the field type displays a TextBox filter when you access it.
  • User field - You can now set the FilterType for this field to MultiList through the API. However, the field type displays a List filter when you access it.

Source property

Only use the Source property for mapping processing fields on the Document object.

Formatting fields

Set the Formatting property to one of the following values. For more information, see the Formatting enumeration in the Relativity.ObjectModel.{versionNumber}.Field.Models namespace.

  • None - used for all field types except currency or date.
  • Formatted - used for decimal and whole number field types.
  • Date - used for the date field type.
  • DateTime - used for the date field type.
  • Currency - used for the currency field type.

Client code sample

To use the Field Manager service, send requests by making calls with the required HTTP methods. See the following base URL for this service:

Copy 
<host>/Relativity.rest/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/

You can use the following .NET code as a sample client for creating a fixed-length text field. This code illustrates how to perform the following tasks:

  • Instantiate an HttpClient object for sending requests to the Field Manager service.
  • Set the required headers for the request. For information on setting headers, see HTTP headers.
  • Initialize variables with the values for the field to create.
  • Set the url variable to the URL for the workspace where the field is to be added. For more information, see Create a field.
  • Set the JSON input required for the operation.
  • Use the PostAsync() method to send a POST request.
  • Return the results of the request and deserialize it.

Postman sample file

You can use the Postman sample file to become familiar with making calls to endpoints on Field Manager service. To download the sample file, click FieldAPIPostmanFile.zip.

To get started with Postman, complete these steps:

  1. Obtain access to a Relativity environment. You need a username and password to make calls to your environment.
  2. Install Postman.
  3. Import the Postman sample file for the service. For more information, see Working with data files on the Postman web site.
  4. Select an endpoint. Update the URL with the domain for your Relativity environment and any other variables.
  5. In the Authorization tab, set the Type to Basic Auth, enter your Relativity credentials, and click Update Request.
  6. See the following sections on this page for more information on setting required fields for a request.
  7. Click Send to make a request.

Create a field

You can create a field by sending a POST request to the appropriate URL for the field type. For general information about fields, see Fields on the RelativityOne Documentation site.

Click the following drop-down links to view URLs and sample requests for fixed-length text, multiple choice, single object, and date fields. You can find the URLs and JSON request formats for other field types in the Postman file provided for this service. For more information, see Postman sample file.

When a request is successful, the response contains the Artifact ID of the new field. It also returns the status code of 200.

Read a field

You can retrieve basic or extended metadata for a field. The extended metadata also includes operations that user has permissions to perform on the field.

  • Retrieve basic metadata for a field - send a GET request with a URL in the following general format:
    Copy
    <host>/relativity.rest/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/{fieldArtifactID}
  • Retrieve extended metadata for a field - send a GET request with a URL in the following general format:
    Copy
    <host>/relativity.rest/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/{fieldArtifactID}?includeMetadata=true&includeActions=true

The request body is empty.

Update a field

You can update a field by sending a PUT request to the appropriate URL for the field type. For general information about fields, see Fields on the RelativityOne Documentation site.

Click the following drop-down links to view URLs and sample requests for fixed-length text, multiple choice, single object, and date fields. You can find the URLs and JSON request formats for other field types in the Postman file provided for this service. For more information, see Postman sample file.

To view a list of field descriptions, see Create a field.

When you want to ensure you only update a field if it hasn't been modified since you read it, provide the LastModifiedOn field. The update will fail if the field has been changed in the meantime and return a 409 error. You can get the value of this property from an FieldResponse object, which is returned by the ReadAsync() method.

When the field is successfully updated, the response returns the status code of 200.

Delete a field

To remove a field from Relativity, send a POST request with a URL in the following format:

Copy 
<host>/relativity.rest/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/{fieldArtifactID}

The request body is empty.

When the field is successfully deleted, the response returns the status code of 200.

Retrieve available object types

You create fields on object types available in a workspace. To retrieve parent object types in a specific workspace, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/available-object-types

The request body is empty.

The response contains the following fields for each object type:

  • Name - the user-friendly name of the object type.
  • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
  • ArtifactID - the Artifact ID of an object type.
  • Guids - an array of GUIDs used to identify the object type.

Retrieve available views for an object type

You can retrieve a list of available views for a specific object type that you can then use when creating or updating a new field. The following endpoint is used to retrieve this information for the field tree, pop-up picker, and relational views. The relational view is available only for documents. For more information, see Fields on the RelativityOneDocumentation site.

Send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/available-object-type-views

The request contains the following fields:

  • ObjectType - contains the following fields:
    • ArtifactID - the Artifact ID of the object type on which you are adding the field.
    • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
    • Name - the user-friendly name of the object type.
Copy 
{
   "ObjectType":{
      "ArtifactID":1035231,
      "ArtifactTypeID":10,
      "Name":"Document"
   }
}

The response contains the following fields for each view:

  • Secured - indicates whether the current user has permission to view the settings in the Value field.
  • Value - contains the following fields:
    • Name - the user-friendly name of the view.
    • ArtifactID - the Artifact ID of the view.
    • Guids - an array of GUIDs used to identify the view.

Retrieve available fields for propagation

When creating a field, you can determine whether coding values propagate to a specific group of related items. For more information about propagation, see Fields on the RelativityOne Documentation site.

To retrieve the fields used for propagation in a workspace, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/available-propagate-to-fields

The request body is empty.

The response contains the following fields:

  • Name - the user-friendly name of the relational field, such as Duplicates or Family.
  • ArtifactID - the Artifact ID of the field.
  • Guids - an array of GUIDs used to identify the field.

Retrieve object types for a single object field

You can retrieve an array of object types that you can use to create a single object field type. For more information about single object fields, see Fields on the RelativityOne Documentation site.

Send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/available-single-associative-object-types

The request contains the following fields:

  • ObjectType - contains the following fields:
    • ArtifactID - the Artifact ID of the object type on which you are adding the field.
    • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
    • Name - the user-friendly name of the object type.
Copy 
{
   "ObjectType":{
      "ArtifactID":1035231,
      "ArtifactTypeID":10,
      "Name":"Document"
   }
}

The response contains the following fields for each object type:

  • Name - the user-friendly name of the object type.
  • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
  • ArtifactID - the Artifact ID of an object type.
  • Guids - an array of GUIDs used to identify the object type.

Retrieve object types for a multiple object field

You can retrieve an array of associative object types that you can use to create a multiple object field. For more information about multiple object fields, see Fields on the RelativityOne Documentation site.

Send a POST request with a URL in the following format:

Copy 
<host>Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/available-multi-associative-object-types

The request contains the following fields:

  • ObjectType - contains the following fields:
    • ArtifactID - the Artifact ID of the object type on which you are adding the field.
    • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
    • Name - the user-friendly name of the object type.
Copy 
{
   "ObjectType":{
      "ArtifactID":1035231,
      "ArtifactTypeID":10,
      "Name":"Document"
   }
}

The response contains the following fields for each object type:

  • Name - the user-friendly name of the object type.
  • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
  • ArtifactID - the Artifact ID of an object type.
  • Guids - an array of GUIDs used to identify the object type.

Retrieve keyboard shortcuts

You can retrieve a list of keyboard shortcuts currently defined in a workspace. In the Relativity UI, this list is displayed when you click the Keyboard Shortcuts Legend icon. For more information, see Keyboard shortcuts on the RelativityOne Documentation site.

Send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/available-keyboard-shortcuts

The request body is empty.

Retrieve valid keys

When creating or updating a field on a Document object, you can assign a keyboard shortcut to it. The shortcut key is a combination of a CTRL, ALT, or SHIFT key, and an alphanumeric or other key. For more information, see Fields on the RelativityOne Documentation site.

You can use the following endpoint to retrieve all keys available for use when creating a keyboard shortcut. Send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/valid-keys

The request body is empty.

Retrieve the order of relational field icons

You can retrieve the current order for relational field icons displayed in the Related Items pane of the core reviewer interface. The order assigned to a relational field icon determines its position relative to other icons in the Related Items pane. A relational field icon with a lower order number is displayed on the left, while those with the same order number are sorted alphanumerically.

In the Relativity UI, you can add or edit fields in the Fields layout, which contains the View Order button for relational field properties. Click this button to display the current order for icons in the Related Items pane. For more information, see Fields on the RelativityOne Documentation site.

To retrieve the current display order for the icons of relational fields available in a specific workspace, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Object-Model/{versionNumber}/workspaces/{workspaceID}/fields/available-relational-order

The request body is empty.

The response contains the following fields:

  • Name - the user-friendly name of the relational field
  • Type - a string indicating the type of the field, such as GroupIdentifier, MD5Hash, or others.
  • Order - an integer representing the position of a relational field icon in the Related Items pane of the core reviewer interface.
Copy 
[
    {
        "Name": "Family",
        "Type": "GroupIdentifier",
        "Order": 0
    },
    {
        "Name": "Duplicates",
        "Type": "MD5Hash",
        "Order": 1
    },
    {
        "Name": "My Test Relational",
        "Type": "TestRelational",
        "Order": 10
    }
]