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:

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:

Classes and enumerations

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

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

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 RelativityOne 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:

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.

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.

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:

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.

Create a field

You can create fields by using the methods available on the IFieldManager interface. For general information about fields, see Fields on the RelativityOne 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 Fields on the RelativityOneDocumentation 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 Fields on the RelativityOne 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 Fields on the RelativityOne 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 Fields on the RelativityOne 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 RelativityOne 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 Fields on the RelativityOne 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 Fields on the RelativityOne

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));
        }
    }
}

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