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.

The Relativity Services API supports the same functionality for this service as available through the REST API. For more information, see Field Manager (.NET).

This page contains the following information:

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.

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:

<host>/Relativity.rest/api/Relativity.Fields/workspace/{{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.

Guidelines for the Field Manager service

Review the following guidelines for the Field Manager service.

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 fields. Set these fields as follows:

  • Set the ImportBehavior field 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.
  • Optionally, set the value for the FileName field for the pane icon.
  • Convert the value for the ImageBase64 field to the base64 format. Check for web sites that convert images to this format.

Overlay behavior

Set the value for the OverlayBehavior field to one of the following values. For more information, see the OverlayBehavior enumeration in the Relativity.Services.Field.Models namespace in the Relativity API reference.

  • 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 field to one of the following values. For more information, see the FilterType enumeration in the Relativity.Services.Field.Models namespace in the Relativity API reference.

  • 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 and multiple choice field types.
  • Popup - used for single choice, multiple choice, single object, and multiple object field types.
  • 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.

Note: If you want to set PopupPickerView field, make sure the value for the FilterType field equals Popup.

Filter types for date and user fields

The Field Manager API currently sets the filter type for the date and user fields as follows. In a future release, the API will be updated to provide the expected behavior when the field type is displayed. 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 field

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

Formatting fields

Set the Formatting field to one of the following values. For more information, see the Formatting enumeration in the Relativity.Services.Field.Models namespace on Relativity API reference.

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

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 to a URL with the following general format:
    <host>/relativity.rest/api/Relativity.Fields/workspace/{{workspaceID}}/fields/{{fieldArtifactID}}
  • Retrieve extended metadata for a field - send a GET request to a URL with the following general format:
    <host>/relativity.rest/api/Relativity.Fields/workspace/{{workspaceID}}/fields/{{fieldArtifactID}}/true/true

For both requests, set the {{WorkspaceID}} variable to the Artifact ID of a workspace or use -1 to indicate the admin-level context. Set the {{fieldArtifactID}} variable to the Artifact ID of the field that you want to read, and leave the body of the request 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.

Note: You can optionally add the LastModifiedOn field to an update request. This field is only required if you want to restrict the update of an instance setting to the date that it was last modified. The value must match the LastModifiedOn date for the field stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.

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 to a URL with the following format:

<host>/relativity.rest/api/Relativity.Fields/workspace/{{workspaceID}}/fields/{{fieldArtifactID}}

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.Set the {{fieldArtifactID}} variable to the Artifact ID of the field that you want to delete.

The body of the request 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 POST request to a URL with the following format:

<host>/Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/availableobjecttypes

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

The body of the request 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. See the ArtifactType enumeration in the Services API.
  • 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 to a URL with the following format:

<host>/Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/availableobjecttypeviews

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

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. See the ArtifactType enumeration in the Services API.
    • Name - the user-friendly name of the object type.
{
   "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 to a URL with the following format:

<host>/Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/availablepropagatetofields

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

The body of the request 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 to a URL with the following format:

<host>/Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/availablesingleassociativeobjecttypes

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

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. See the ArtifactType enumeration in the Services API.
    • Name - the user-friendly name of the object type.
{
   "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. See the ArtifactType enumeration in the Services API.
  • 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 to a URL with the following format:

<host>Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/availablemultiassociativeobjecttypes

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

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. See the ArtifactType enumeration in the Services API.
    • Name - the user-friendly name of the object type.
{
   "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. See the ArtifactType enumeration in the Services API.
  • 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 to a URL with the following format:

<host>/Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/availablekeyboardshortcuts

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace.

The body of the request 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 to a URL with the following format:

<host>/Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/keys

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace.

The body of the request 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 to a URL with the following format:

<host>/Relativity.REST/api/Relativity.Fields/workspace/{{workspaceID}}/associativefields/availablerelationalorder

Set the {{WorkspaceID}} variable to the Artifact ID of a workspace.

The body of the request 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.
[
    {
        "Name": "Family",
        "Type": "GroupIdentifier",
        "Order": 0
    },
    {
        "Name": "Duplicates",
        "Type": "MD5Hash",
        "Order": 1
    },
    {
        "Name": "My Test Relational",
        "Type": "TestRelational",
        "Order": 10
    }
]

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

   
Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget