Field Manager API

The Field Manager API provides multiple methods for programmatically working with field types supported by Relativity, including multiple choice, fixed-length text, date, and others. This API supports create, read, update, and delete operations on fields. Additionally, it includes helper methods 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 API 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 the REST API. For more information, see Field Manager service.

This page contains the following information:

Fundamentals for Field Manager API

The Field Manager API contains the following methods, classes, and enumerations.

Methods

The Field Manager API exposes the following methods on the IFieldManager interface in the Relativity.Services.Interfaces.Field namespace:

  • Create method for each field type - adds a new field on a specified object type. The parameters for the create methods include the Artifact ID of a workspace, and a request object for the field type. These methods return the Artifact ID of the new field.

    Note: Each field type has its own create method, and request class. For a complete list of create methods, see Create a field.

  • DeleteAsync() method - removes a field from an object type in the specified workspace. Its parameters include the Artifact IDs of the workspace and the field. This method returns a Task. See Delete a field.
  • GetAvailableKeyboardShortcutsAsync() method - retrieves a list of keyboard shortcuts currently defined in a workspace. It takes the Artifact ID of a workspace, and returns a list of KeyboardShortcut objects. See Retrieve keyboard shortcuts.
  • GetAvailableMultiAssociativeObjectTypesAsync() method - retrieves a list of associative object types that you can use when creating a multiple object field. Its parameters include the Artifact ID of a workspace, and an ObjectTypeIdentifier object. The multiple object field is created on the object type represented by the ObjectTypeIdentifier object, and the method retrieves other object types compatible with it. The method returns a list of on ObjectTypeIdentifier objects. See Retrieve object types for a multiple object field.

    Note: The ObjectTypeIdentifier class contains the Artifact ID, Name, and other identifiers for an object. It is available in the Relativity.Services.Interfaces.Shared.Models namespace. For more information, see this class in the Services API.

  • GetAvailableObjectTypesAsync() method - retrieves a list of parent object types available in a specific workspace. It takes the Artifact ID of a workspace, and returns a list of ObjectTypeIdentifier objects. See Retrieve available object types.
  • GetAvailableObjectTypeViewsAsync() method - retrieves a list of available views for a specific object type. Its parameters include the Artifact ID of a workspace, and an ObjectTypeIdentifier object. The method returns a list of DisplayableObjectIdentifier objects. See Retrieve available views for an object type.

    Note: The DisplayableObjectIdentifier class contains the Artifact ID, Guids, and Name properties. It is available in the Relativity.Services.Interfaces.Shared.Models namespace. For more information, see this class in the Services API.

  • GetAvailablePropagateToFieldsAsync() method - retrieves a list of fields used for propagation in a workspace. It takes the Artifact ID of a workspace, and returns a list of DisplayableObjectIdentifier objects. See Retrieve available fields for propagation.
  • GetRelationalOrderAsync() method - retrieves information about the order used to display relational field icons in the Related Items pane of the core reviewer interface for a specific workspace. It takes the Artifact ID of a workspace, and returns a list of RelationalFieldOrder objects. See Retrieve the order of relational field icons.
  • GetAvailableSingleAssociativeObjectTypesAsync() method - retrieves a list of associative object types that you can use when creating a single object field. Its parameters include the Artifact ID of a workspace, and an ObjectTypeIdentifier object. The single object field is created on the object type represented by the ObjectTypeIdentifier object, and the method retrieves other object types compatible with it. The method returns a list of on ObjectTypeIdentifier objects. See Retrieve object types for a single object field.

    Note: The ObjectTypeIdentifier class contains the Artifact ID, Name, and other identifiers for an object. It is available in the Relativity.Services.Interfaces.Shared.Models namespace. For more information, see this class in the Services API.

  • GetValidKeys() method - retrieves keys available for use in a keyboard shortcut. It takes the Artifact ID of a workspace, and returns a list of strings representing available keys. See Retrieve valid keys.
  • ReadAsync() method - retrieves metadata for a field, such as its name, Artifact ID, associated object type, and other properties. You can also use this overloaded method to return extended metadata, including information about the operations that you have permissions to perform on the field, such as update or delete. This method takes the Artifact IDs of the workspace and field, and two optional Boolean values for extended metadata. It returns a FieldResponse object. See Read a field.
  • Update method for each field type - modifies the properties of a field. The parameters for the update methods include the Artifact IDs of the workspace and the field, a request object for the field type, and an optional DateTime object to restrict the update to the date last modified. These methods return a Task. See Update a field.

    Note: Each field type has its own update method, and request class. For a complete list of create methods, see Update a field.

Classes and enumerations

The Field Manager API includes the following classes and enumerations available in the Relativity.Services.Interfaces.Field.Models namespace:

  • Request class for each field type - represents the data used to create or update an object type. Each create and update method takes an object of this type. For more information, see a specific request class in the Services API.
  • FieldResponse class - represents the results of a read operation. Its properties include the user-friendly name for the field, a Boolean value indicating whether the field is required, the keyboard shortcut when assigned to the field, and other properties. For a complete list of properties, see the FieldResponse class in the Services API.
  • FieldType enumeration - provides a of list integer values that represent field types supported by Relativity, such as Currency, User, FixedLength, and others. See the FieldType enumeration in Relativity.Services.Interfaces.Field.Models namespace of the Services API.
  • FilterType enumeration - provides a of list integer values that represent types of filters for lists, such as filters for Booelan values, pop-up pickers, and others. See the FilterType enumeration in Relativity.Services.Interfaces.Field.Models namespace of the Services API.
  • Formatting enumeration - provides formatting options for date, currency, whole number, and decimal fields. See the Formatting enumeration in Relativity.Services.Interfaces.Field.Models namespace of the Services API.
  • KeyboardShortcut class - represents the key combination and behavior of a keyboard shortcut. Its properties include the action performed by the shortcut, its key combination, and others.
  • OverlayBehavior enumeration - indicates whether the values in multiple object or multiple choice fields are replaced or merged when imported from a load file. See the OverlayBehavior enumeration in Relativity.Services.Interfaces.Field.Models namespace of the Services API.
  • PaneIcon class - represents an icon displayed in the Related Items pane of the reviewer interface. Its properties include the file name and a string representing the Base64 encoding of the icon.
  • RelationalFieldOrder class - represents the position of a relational field icon in the Related Items pane of the core reviewer interface. Its properties include the name and type of the relational field, and an integer value indicating the display order of the field icon. The GetRelationalOrderAsync() method returns a list of objects with this type. For more information about its properties, see the RelationalFieldOrder class in the Services API.

Additionally, this API includes the following class in the Relativity.Services.Interfaces.Field namespace:

  • FieldConstants class - provides routing information about URLs used by the Field Manager service. See this class in the Services API.

Guidelines for the Field Manager API

Review the following guidelines for the Field Manager API.

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

Helper methods

Use the helper methods 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.Services.Field.Models namespace on 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 property to one of the following values. For more information, see the FilterType enumeration in the Relativity.Services.Field.Models namespace on 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 property, make sure the value for the FilterType property 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 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.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 fields by using the methods available on the IFieldManager interface. For general information about fields, see on the Relativity Documentation site.

Click the following drop-down links to view sample code for fixed-length text, multiple choice, single object, and date fields. For more information about create methods, see the IFieldManager interface in the Relativity.Services.Interfaces.Field namespace of the Services API.

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. If you want to return extended information, use the overloaded method by passing Boolean values set to true for additional metadata and permissions as follows:

  FieldResponse response = await fieldManager.ReadAsync(workspaceId, fieldArtifactId, true, true);

The following code sample illustrates how to call the ReadAsync() method by passing only the Artifact IDs of the workspace and the field. Consequently, it returns only basic information. For a list of basic and extended properties, see Read a field in the Field Manager service for REST page.

public static async Task Read_Async()
{
    int workspaceId = 1018486;
    int fieldArtifactId = 1039509;

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            FieldResponse response = await fieldManager.ReadAsync(workspaceId, fieldArtifactId);
            string info = string.Format("Read field {0} with Artifact ID {1}", response.Name, response.ArtifactID);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Update a field

You can update fields by using the methods available on the IFieldManager interface. All field types have an overloaded update method called by passing the Artifact IDs of a workspace and a field, the appropriate request object for the field type, and an optional DateTime object.

When you want to restrict the update of a field to the date that it was last modified, pass the value of LastModifiedOn property as an argument to one of the overloaded update methods. You can get the value of this property from an FieldResponse object, which is returned by the ReadAsync() method.

Note: The MultipleChoiceFieldRequest and SingleChoiceFieldRequest objects have an AutoAddChoices property. If you change this property from No to Yes on a specific field, and applications in your workspace use this field, you must re-add the field to each application to include the choices. The RelativityApplications property on these request objects include a list of the applications containing the field.

Click the following drop-down links to view sample code for fixed-length text, multiple choice, single object, and date fields. For more information about update methods, see the IFieldManager interface in the Relativity.Services.Interfaces.Field namespace of the Services API.

Delete a field

You can remove a field from an object type by calling the DeleteAsync()method, and passing Artifact IDs of a workspace and a field to it. See the following code sample:

public static async Task Delete_Async()
{
    int workspaceId = 1018486;
    int fieldId = 1039269;

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            await fieldManager.DeleteAsync(workspaceId, fieldId);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve available object types

You create fields on parent object types available in a workspace. The GetAvailableObjectTypesAsync() retrieves a list of these objects available in a specified workspace. See the following code sample:

public static async Task GetAvailableObjectTypes_Async()
{
    int workspaceId = 1018486;

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<ObjectTypeIdentifier> response = await fieldManager.GetAvailableObjectTypesAsync(workspaceId);
            foreach (ObjectTypeIdentifier objectType in response)
            {
                string info = string.Format("Read objectType {0} with Artifact ID {1}", objectType.Name, objectType.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

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 GetAvailableObjectTypeViewsAsync() method retrieves this information for the field tree, pop-up picker, and relational views. The relational view is available only for documents. For more information, see on the RelativityDocumentation site.

The following code sample illustrates how to call this method by passing the Artifact ID of a workspace. It returns a list of ObjectTypeIdentifier instances that contain the Artifact ID and other information for each view.

public static async Task GetAvailableObjectTypeViews_Async()
{
    int workspaceId = 1018486;
    ObjectTypeIdentifier objectType = new ObjectTypeIdentifier { ArtifactID = 1425337 };

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<Securable<DisplayableObjectIdentifier>> response = await fieldManager.GetAvailableObjectTypeViewsAsync(workspaceId, objectType);
            foreach (DisplayableObjectIdentifier objectTypeView in response)
            {
                string info = string.Format("Read objectTypeView {0} with Artifact ID {1}", objectTypeView.Name, objectTypeView.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve available fields for propagation

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

Use the GetAvailablePropagateToFieldsAsync() method to retrieve a list of fields available for propagation in a specific workspace. The following code sample illustrates how to call this method by the Artifact ID of a workspace. It returns a list of DisplayableObjectIdentifier instances that contain the Artifact ID and other information for each view.

public static async Task GetAvailablePropagateToFields_Async()
{
    int workspaceId = 1018486;

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<DisplayableObjectIdentifier> response = await fieldManager.GetAvailablePropagateToFieldsAsync(workspaceId);
            foreach (DisplayableObjectIdentifier field in response)
            {
                string info = string.Format("Read field {0} with Artifact ID {1}", field.Name, field.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve object types for a single object field

A single object field defines a one-to-many relationship between the object type that the field is on, and another object type. For more information about single object fields, see on the Relativity Documentation site.

Use the GetAvailableSingleAssociativeObjectTypesAsync() method to retrieve a list of compatible object types for a single object field. The following code illustrates how to call this method by passing the Artifact ID of a workspace, and an ObjectTypeIdentifier instance containing the Artifact ID of the object type that the field is on.

public static async Task GetAvailableSingleAssociativeObjectTypes_Async()
{
    int workspaceId = 1018486;
    ObjectTypeIdentifier objectType = new ObjectTypeIdentifier { ArtifactID = 1523463 };

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<ObjectTypeIdentifier> response = await fieldManager.GetAvailableSingleAssociativeObjectTypesAsync(workspaceId, objectType);
            foreach (ObjectTypeIdentifier objectTypeResponse in response)
            {
                string info = string.Format("Read objectType {0} with Artifact ID {1}", objectTypeResponse.Name, objectTypeResponse.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve object types for a multiple object field

A multiple object field defines a many-to-many relationship between the object type that the field is on, and another object type. For more information about multiple object fields, see on the Relativity Documentation site.

Use the GetAvailableMultiAssociativeObjectTypesAsync() to retrieve a list of compatible object types for a multiple object field. The following code illustrates how to call this method by passing the Artifact ID of a workspace, and an ObjectTypeIdentifier instance containing the Artifact ID of the object type that the field is on.

public static async Task GetAvailableMultiAssociativeObjectTypes_Async()
{
    int workspaceId = 1018486;
    ObjectTypeIdentifier objectType = new ObjectTypeIdentifier { ArtifactID = 1425337 };

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<ObjectTypeIdentifier> response = await fieldManager.GetAvailableMultiAssociativeObjectTypesAsync(workspaceId, objectType);
            foreach (ObjectTypeIdentifier objectTypeResponse in response)
            {
                string info = string.Format("Read objectType {0} with Artifact ID {1}", objectTypeResponse.Name, objectTypeResponse.ArtifactID);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

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

Use the GetAvailableKeyboardShortcutsAsync() method to retrieve a list of keyboard shortcuts currently defined in a workspace. The following code sample illustrates how to this method by passing the Artifact ID of a workspace. It returns a list of KeyboardShortcut objects.

public static async Task GetAvailableKeyboardShortcuts_Async()
{
    int workspaceId = 1018486;

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<KeyboardShortcut> response = await fieldManager.GetAvailableKeyboardShortcutsAsync(workspaceId);
            foreach (KeyboardShortcut shortcut in response)
            {
                string info = string.Format("Read keyboard shortcut {0} with action {1}", shortcut.Shortcut, shortcut.Action);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

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 on the Relativity Documentation site.

Use the GetValidKeysAsync() method to retrieve keys available for use in a keyboard shortcut. The following code sample illustrates how to call this method by passing the Artifact ID of a workspace. It returns a list of strings representing available keys.

public static async Task GetValidKeys_Async()
{
    int workspaceId = 1018486;

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<String> response = await fieldManager.GetValidKeys(workspaceId);
            foreach (String key in response)
            {
                string info = string.Format("Read key {0}", key);
                Console.Write(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

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 on the Relativity

Use the GetRelationalOrderAsync() method to retrieve the current display order for the icons of relational fields available in a specific workspace. The following code sample illustrates how to call this method by passing the Artifact ID of a workspace. It returns a list of RelationalFieldOrder instances that contain the name and type of a relational field, and display order for its icon.

public static async Task GetRelationalFieldOrder_Async()
{
    int workspaceId = 1018486;

    using (Services.Interfaces.Field.IFieldManager fieldManager = serviceFactory.CreateProxy<Services.Interfaces.Field.IFieldManager>())
    {
        try
        {
            List<RelationalFieldOrder> response = await fieldManager.GetRelationalOrderAsync(workspaceId);
            foreach (RelationalFieldOrder relationalFieldOrder in response)
            {
                string info = string.Format("Read Relational Field {0} with Type {1} and Order {2}", 
                     relationalFieldOrder.Name, relationalFieldOrder.Type, relationalFieldOrder.Order);
                Console.WriteLine(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}