Object Type Manager service

Through the REST API, you can use the Object Type Manager service to programmatically create custom object types for use in your applications. This service includes the following features:

  • Support for create, read, update, and delete operations on object types.
  • Helper endpoints for retrieving parent object types and dependent objects.

Additionally, the following services provide functionality for working with event handlers, object rules, and mass operations for object types:

  • Event Handler Manager service - includes endpoints for attaching event handlers to and removing them from object types. It contains helper endpoints used for retrieving event handlers available in a workspace, and for retrieving event handlers currently attached to an object type.
  • Object Rule Manager service - includes endpoints for creating, updating, reading, or deleting object rules on an object type. It also provides helper endpoints for retrieving associative objects, layouts, choices, and choice fields used when creating an object rule.
  • Mass Operation Manager service - includes endpoints for creating, updating, reading, or deleting mass operations on an object type. It also provides helper endpoints for retrieving available object types, event handlers, and layouts for use with mass operations.

As a sample use case, you could use the Object Type Manager service to add new object types to support a custom application that you developed. You might want to implement an application that tracks vendor or customer information and decide to add different object types for each of these items. These object types could be further customized with object rules, event handlers, and mass operations.

The Relativity Services API supports the same functionality for this service as available through the REST API. For more information, see Object Type Manager API.

This page contains the following information:

Postman sample files

You can use the Postman sample files to become familiar with making calls to endpoints on the services for object types, including the Object Type Manager, Event Handler Manager, Object Rule Manager, and Mass Operation Manager services. To download the sample files, click ObjectTypePostmanFiles.zipObjectTypePostmanFiles.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 Object Type 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.objectTypes/workspace/{{WorkspaceID}}/objectTypes/

You can use the following .NET code as a sample client for creating an object type. This code illustrates how to perform the following tasks:

  • Instantiate an HttpClient object for sending requests to the Object Type Manager service.
  • Set the required headers for the request. For information on setting headers, see HTTP headers.
  • Initialize variables with the values for the object type to create, and the server where it should be added.
  • Set the url variable to the URL for the workspace where the object type is to be added. For more information, see Create an object type.
  • 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.

Note: Follow a similar process when making calls to the Event Handler Manager, Object Rule Manager, and Mass Operation Manager services.

public async Task<int?> Create()
{
    int? result = null;    
    using (HttpClient client = new HttpClient())
    {
        client.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
        client.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("test@test.com:SomePassword")));
        client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0");
        client.BaseAddress = new Uri("https://localhost/");

        int workspaceId = 1018486;
        int parentArtifactTypeId= 10;
        int parentArtifactId = 1035231;
        int applicationId = 1035699; 

        string inputJSON = $"{{ \"ObjectTypeRequest\" : {{ \"ParentObjectType\": {{ \"Secured\": false, \"Value\": {{ \"ArtifactTypeID\": \"{parentArtifactTypeId}\", \"ArtifactID\": \"{parentArtifactId}\" }} }}, \"RelativityApplications\":[ {{ \"Secured\": false, \"Value\":{{ \"ArtifactID\": \"{applicationId}\" }} }} ], \"Name\": \"Object Test 1\", \"CopyInstancesOnCaseCreation\": false, \"CopyInstancesOnParentCopy\": false, \"EnableSnapshotAuditingOnDelete\": true, \"PersistentListsEnabled\": false, \"PivotEnabled\": true, \"SamplingEnabled\": false, \"Keywords\": \"\", \"Notes\": \"\" }} }}";
        var url = $@"/Relativity.rest/api/relativity.objectTypes/workspace/{workspaceId}/objectTypes/";
        var response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json"));
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        result = JsonConvert.DeserializeObject<int>(content);
    }
    
    return result;
}

CRUD operations for object types

The Object Type Manager service supports create, read, update, and delete operations on object types. It also includes helper endpoints used to retrieve information about parent object types, and dependent objects.

Review the following guidelines for working with this service:

  • Verify that you have the appropriate permissions to access an object type before attempting to modify or delete it.
  • Verify that the Relativity application is unlocked before attempting to add an object type to it, or to modify or delete an existing object type. You also need permissions to the application and the object type to perform these tasks.

See the following subsections for more information:

Create an object type

When creating a new object type, you need to identify its parent object type. For more information, see Retrieve a parent object types.

To create an object type, send a POST request to a URL with the following format:

<host>/Relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceID}}/objectTypes/

Set the {{WorkspaceID}} variable to the Artifact ID of the workspace where you want to add the new object type, or use -1 to indicate the admin-level context.

The body of the request must contain the following fields unless specifically identified as optional:

  • ObjectTypeRequest - represents a request to create or update an object type. It contains the following fields:
    • ParentObjectType - indicates the parent object type of the object type. For example, an object type may be a child of the Document object. This field contains the following subfields:
      • Secured - indicates whether the current user has permission to view the setting in the Value field.
      • Value - contains an ArtifactTypeID, which is an identifier used to specify 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. The Value field also contains the Artifact ID of the object type.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object type is linked to the applications in this array. If the array is empty, then the object type isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
    • Name - the user-friendly name of the object type.
    • CopyInstancesOnCaseCreation - a Boolean value indicating whether instances of this object type are copied when you create a new workspace. For more information, see Fields for an object type.
    • CopyInstancesOnParentCopy - a Boolean value indicating whether the child objects are copied when the parent object is copied. For more information, see Fields for an object type.
    • EnableSnapshotAuditingOnDelete - a Boolean value indicating whether to capture audit information about the current field values for an object. For more information, see Fields for an object type.
    • PersistentListsEnabled - a Boolean value indicating whether users can save lists of these object instances.
    • PivotEnabled - a Boolean value indicating whether pivot functionality is available on objects of this type. Pivot provides the functionality to analyze and report trends or patterns by querying specific sets of data and summarizing the results. For more information, see Pivot on the Relativity Documentation site.
    • SamplingEnabled - a Boolean value indicating whether the sampling functionality is enabled on the object. You can use sampling to create a group of documents for quality control or other purposes. For more information, seeSampling on the Relativity Documentation site.
    • Keywords - optional words or phrases used to describe the object type.
    • Notes - an optional description or other information about the object type.
{
   "ObjectTypeRequest" : {
       "ParentObjectType": {
           "Secured": false,
           "Value": {
               "ArtifactTypeID": 10,
               "ArtifactID": 1035231
           }
        },
        "RelativityApplications":[
           {
            "ArtifactID": 1045231
           }
         ],
        "Name": "My Custom Object Type",
        "CopyInstancesOnCaseCreation": false,
        "CopyInstancesOnParentCopy": false,
        "EnableSnapshotAuditingOnDelete": true,
        "PersistentListsEnabled": false,
        "PivotEnabled": true,
        "SamplingEnabled": false,
        "Keywords": "",
        "Notes": ""
   }
}

When the request is successful, the response contains the Artifact ID of the new object type, such as 1042152. It also returns the status code of 200.

Read an object type

You can retrieve basic information about an object type or extended information, which also includes operations that you have permissions to perform on the object type.

  • Retrieve basic metadata for an object type - send a GET request to a URL with the following general format: 
    <host>/Relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceID}}/objectTypes/{{ArtifactID}}
  • Retrieve extended metadata for an object type - send a GET request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceID}}/objectTypes/{{ArtifactID}}/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 {{ArtifactID}} variable to the Artifact ID of the object type that you want to read, and leave the body of the request empty.

  • 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.
  • ParentObjectType - contains information about the parent object type, as follows:
    • Secured - indicates whether the current user has permission to view the setting in the Value field.
    • Value - contains the following fields:
      • Name - the user-friendly name for the parent object type.
      • ArtifactTypeID - an identifier used to specify an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
      • ArtifactID - the Artifact ID of the parent object type.
      • Guids - an array of GUIDs used to identify the parent object type.
  • CopyInstancesOnCaseCreation - a Boolean value indicating whether instances of this object type are copied when you create a new workspace. For more information, see Fields for an object type.
  • CopyInstancesOnParentCopy - a Boolean value indicating whether the child objects are copied when the parent object is copied. For more information, see Fields for an object type.
  • EnableSnapshotAuditingOnDelete - a Boolean value indicating whether to capture audit information about the current field values for an object. For more information, see .
  • IsDynamic - a Boolean value indicating whether this object type is a custom type that is user-created.
  • IsSystem - a Boolean value indicating whether this object type is available as an out-of-the-box type provided with Relativity.
  • IsViewEnabled - a Boolean value indicating whether the view for the object type is enabled.
  • PersistentListsEnabled - a Boolean value indicating whether users can save lists of these object instances.
  • PivotEnabled - a Boolean value indicating whether pivot functionality is available on objects of this type. Pivot provides the functionality to analyze and report trends or patterns by querying specific sets of data and summarizing the results. For more information, see Pivoton the Relativity Documentation site.
  • SamplingEnabled - a Boolean value indicating whether the sampling functionality is enabled on the object. You can use sampling to create a group of documents for quality control or other purposes. For more information, see on the Relativity Documentation site.
  • FieldByteUsage - an integer value indicating the number of bytes used by the fields on the object type.
  • RelativityApplications - contains the following fields:
    • HasSecuredItems - a Boolean value indicating whether the application contains items that the current user doesn't have permission to access.
    • ViewableItems - an array of identifier objects for items that are accessible to the current user. For example, an object in this array would contain the name, Artifact IDs, and GUIDs for an application. See DisplayableObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
  • CreatedOn - the date and time when the object type was added to Relativity.
  • CreatedBy - contains the Artifact ID and name of the user who created the object type. It also contains an array of GUIDs used to identify the user.
  • LastModifiedBy - contains the Artifact ID and name of the user who recently updated the object type. It also contains an array of GUIDs used to identify the user.
  • LastModifiedOn - the date and time when the object type was most recently modified.
  • Keywords - optional words or phrase used to describe the object type.
  • Notes - an optional description or other information about the object type.
  • Meta - provides additional information available as extended metadata. It includes the following fields:
    • Unsupported - an array of properties that indicate functionality not available on the current instance of this object type. For example, if a user couldn't persist objects of this type in a list, then array would include PersistentListsEnabled.
    • ReadOnly - an array of object type properties that can't be modified, such its name or parent object type.
  • Actions - an array of Action objects indicating operations that you have permissions to perform on this object type. For example, you may not have permissions to modify an object type that is part of a locked application. Each Action object contains the following fields that are available as extended metadata:
    • Name - name of an operation available through REST for the object type, such as delete, update, and so on.
    • Href - the URL used to make an HTTP request for the operation.
    • Verb - the name of the HTTP method for the operation.
    • IsAvailable - a Boolean value indicating whether you have permissions to perform the operation on this object type.
    • Reason - provides an explanation for the unavailability of an action.
  • Name - the user-friendly name for the object type.
  • ArtifactID - the Artifact ID of the object type.
  • Guids - an array of GUIDs used to identify the object type.
{
    "ArtifactTypeID": 5,
    "ParentObjectType": {
        "Secured": false,
        "Value": {
            "Name": "System",
            "ArtifactTypeID": 1,
            "ArtifactID": 1016168,
            "Guids": []
        }
    },
    "CopyInstancesOnCaseCreation": false,
    "CopyInstancesOnParentCopy": false,
    "EnableSnapshotAuditingOnDelete": true,
    "IsDynamic": false,
    "IsSystem": true,
    "IsViewEnabled": true,
    "PersistentListsEnabled": false,
    "PivotEnabled": false,
    "SamplingEnabled": false,
    "FieldByteUsage": 0,
    "RelativityApplications": {
        "HasSecuredItems": false,
        "ViewableItems": []
    },
    "CreatedOn": "2018-05-14T18:31:49.787",
    "CreatedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 9,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 9,
        "Guids": []
    },
    "LastModifiedOn": "2018-05-14T18:31:49.787",
    "Keywords": "",
    "Notes": "RDO in Admin",
    "Name": "Client",
    "ArtifactID": 1016170,
    "Guids": []
}
{
    "ArtifactTypeID": 5,
    "ParentObjectType": {
        "Secured": false,
        "Value": {
            "Name": "System",
            "ArtifactTypeID": 1,
            "ArtifactID": 1016168,
            "Guids": []
        }
    },
    "CopyInstancesOnCaseCreation": false,
    "CopyInstancesOnParentCopy": false,
    "EnableSnapshotAuditingOnDelete": true,
    "IsDynamic": false,
    "IsSystem": true,
    "IsViewEnabled": true,
    "PersistentListsEnabled": false,
    "PivotEnabled": false,
    "SamplingEnabled": false,
    "FieldByteUsage": 0,
    "RelativityApplications": {
        "HasSecuredItems": false,
        "ViewableItems": []
    },
    "CreatedOn": "2018-05-14T18:31:49.787",
    "CreatedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 9,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 9,
        "Guids": []
    },
    "LastModifiedOn": "2018-05-14T18:31:49.787",
    "Keywords": "",
    "Notes": "RDO in Admin",
    "Meta": {
        "Unsupported": [
            "SamplingEnabled",
            "PersistentListsEnabled",
            "CopyInstancesOnCaseCreation",
            "RelativityApplications",
            "CopyInstancesOnParentCopy",
            "UseRelativityForms"
        ],
        "ReadOnly": [
            "ParentObjectType",
            "IsDynamic",
            "EnableSnapshotAuditingOnDelete",
            "PivotEnabled",
            "Name"
        ]
    },
    "Actions": [
        {
            "Name": "Delete",
            "Href": "Relativity.ObjectTypes/workspace/-1/objecttypes/1016170",
            "Verb": "DELETE",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "Update",
            "Href": "Relativity.ObjectTypes/workspace/-1/objecttypes/1016170",
            "Verb": "PUT",
            "IsAvailable": true,
            "Reason": []
        }
    ],
    "Name": "Client",
    "ArtifactID": 1016170,
    "Guids": []
}

Update an object type

To modify an object type, send a PUT request to a URL with the following general format:

<host>/Relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceID}}/objectTypes/{{ArtifactID}}

Set the {{WorkspaceID}} variable to the Artifact ID of the workspace containing the object type, or use -1 to indicate the admin-level context. Set the {{{ArtifactID}} variable to the Artifact ID of the object type that you want to update.

The body of the request must contain the following fields unless specifically identified as optional:

  • ObjectTypeRequest - represents a request to create or update an object type. It contains the following fields:
    • ParentObjectType - indicates the parent object type of the object type. For example, an object type may be a child of the Document object. This field contains the following subfields:
      • Secured - indicates whether the current user has permission to view the setting in the Value field.
      • Value - contains an ArtifactTypeID, which is an identifier used to specify 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. The Value field also contains the Artifact ID of the object type.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object type is linked to the applications in this array. If the array is empty, then the object type isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
    • Name - the user-friendly name of the object type.
    • CopyInstancesOnCaseCreation - a Boolean value indicating whether instances of this object type are copied when you create a new workspace. For more information, see Fields for an object type.
    • CopyInstancesOnParentCopy - a Boolean value indicating whether the child objects are copied when the parent object is copied. For more information, see Fields for an object type.
    • EnableSnapshotAuditingOnDelete - a Boolean value indicating whether to capture audit information about the current field values for an object. For more information, see Fields for an object type.
    • PersistentListsEnabled - a Boolean value indicating whether users can save lists of these object instances.
    • PivotEnabled - a Boolean value indicating whether pivot functionality is available on objects of this type. Pivot provides the functionality to analyze and report trends or patterns by querying specific sets of data and summarizing the results. For more information, see Pivot on the Relativity Documentation site.
    • SamplingEnabled - a Boolean value indicating whether the sampling functionality is enabled on the object. You can use sampling to create a group of documents for quality control or other purposes. For more information, seeSampling on the Relativity Documentation site.
    • Keywords - optional words or phrases used to describe the object type.
    • Notes - an optional description or other information about the object type.
  • LastModifiedOn - the date and time when the object type was most recently modified. This field is only required if you want to restrict the update of an object type to the date that it was last modified. The value must match the LastModifiedOn date for the object type stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.
{
   "ObjectTypeRequest":{
      "ParentObjectType":{
         "Secured":false,
        "Value": {
            "Name": "System",
            "ArtifactTypeID": 1,
            "ArtifactID": 1016168,
            "Guids": []
        }
      },
      "RelativityApplications":[
         {
            "ArtifactID": 1045231
         }
      ],
      "Name":"My Object Type",
      "CopyInstancesOnCaseCreation":false,
      "CopyInstancesOnParentCopy":false,
      "EnableSnapshotAuditingOnDelete":true,
      "PersistentListsEnabled":false,
      "PivotEnabled":false,
      "SamplingEnabled":false,
      "Keywords":"updated",
      "Notes":"Renamed object type"
   },
   "LastModifiedOn":"2018-10-19T18:41:20.54"
}

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

Delete an object type

Before you delete an object type, you may want to call the dependencylist endpoint to retrieve a list of dependent objects. For more information, see Retrieve a list of dependent objects.

To remove an object type from Relativity, send a DELETE request to a URL with the following general format:

<host>/Relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceID}}/objectTypes/{{ToDelete}}

Set the {{WorkspaceID}} variable to the Artifact ID of the workspace containing the object type, or use -1 to indicate the admin-level context. Set the {{ToDelete}} variable to the Artifact ID of the object type that you want to delete.

The body of the request is empty. When the object type is successfully deleted, the response returns the status code of 200.

Retrieve a parent object types

Use the availableparentobjecttypes endpoint to retrieve a list of parent object types. You may want to call this endpoint before creating a new object type, because you must specify its parent object type. Fore more information, see Create an object type.

To call this endpoint, send a GET request to the URL with the following format:

<host>/relativity.rest/api/Relativity.objectTypes/workspace/{{WorkspaceID}}/objectTypes/availableparentobjecttypes

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

The response contains the following fields for each parent 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 the object type.
  • Guids - an array of GUIDs used to identify the object type.
[
    {
        "Name": "Analytics Categorization Result",
        "ArtifactTypeID": 1000017,
        "ArtifactID": 1036390,
        "Guids": []
    },
    {
        "Name": "Analytics Categorization Set",
        "ArtifactTypeID": 1000018,
        "ArtifactID": 1036399,
        "Guids": []
    },
    {
        "Name": "Analytics Categorization Set Build History",
        "ArtifactTypeID": 1000045,
        "ArtifactID": 1039799,
        "Guids": []
    },
    {
        "Name": "Analytics Category",
        "ArtifactTypeID": 1000019,
        "ArtifactID": 1036408,
        "Guids": []
    },
    {
        "Name": "Workspace",
        "ArtifactTypeID": 8,
        "ArtifactID": 1035229,
        "Guids": []
    }
]

Retrieve a list of dependent objects

You can use the dependencylist endpoint to retrieve information about objects dependent on the object type that you want to delete. This information includes the relationship between object type that you specified, and the dependent one.

To call the dependencylist endpoint, send a GET request to the URL with the following format:

<host>/relativity.rest/api/Relativity.objectTypes/workspace/{{WorkspaceID}}/objectTypes/{{ObjectTypeID}}/dependencylist

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

The response contains the following fields:

  • ObjectType - the type of the Relativity object dependent on the object selected for deletion.
    • Secured - indicates whether the current user has permissions to view the setting in the Value field.
    • Value - represents a securable value, which is the object type.
  • Action - indicates whether a dependent object is deleted or unlinked when a specific object is deleted.
  • Count - indicates the number of objects with a dependency on a specific object selected for deletion.
    • Secured - indicates whether the current user has permission to view the setting in the Value field.
    • Value - represents a securable value, which is the number of dependent objects.
  • Connection - indicates whether the object for deletion is a parent, or a field on a single or multiple object field.
    • Secured - indicates whether the current user has permission to view the setting in the Value field.
    • Value - represents a securable value, which is the type of relationship between the objects. For example, the value is Parent when the dependent object is a child, and Field: {field name} when the dependent object is a field on a single or multiple object field.
  • HierarchicLevel - indicates the degree of dependency between object types. For example, you might select an object type for deletion that has a child object type. The fields and views associated with the child object type have a dependency with a hierarchical level of 1.
[
    {
        "ObjectType": {
            "Secured": false,
            "Value": "Object Type (Level 1)"
        },
        "Action": "Delete",
        "Count": {
            "Secured": false,
            "Value": 1
        },
        "Connection": {
            "Secured": false,
            "Value": "Parent"
        },
        "HierarchicLevel": 0
    },
    {
        "ObjectType": {
            "Secured": false,
            "Value": "Layout"
        },
        "Action": "Delete",
        "Count": {
            "Secured": false,
            "Value": 1
        },
        "Connection": {
            "Secured": false,
            "Value": "Child of: Object Type (Level 1)"
        },
        "HierarchicLevel": 0
    },
    {
        "ObjectType": {
            "Secured": false,
            "Value": "View"
        },
        "Action": "Delete",
        "Count": {
            "Secured": false,
            "Value": 1
        },
        "Connection": {
            "Secured": false,
            "Value": "Child of: Object Type (Level 1)"
        },
        "HierarchicLevel": 0
    }
]

Event Handler service for object types

You can add custom behavior to an object type by attaching event handlers to it. For example, you might attach an event handler that performs a specific action when a user makes an update to an object and then attempts to save it. For more information, see Develop object type event handlers.

The Event Handler Manager service contains an endpoints for programmatically attaching event handlers to an object type, and for detaching them. It also provides helper endpoints that you can use for the following purposes:

  • To retrieve a list of event handlers in a workspace, which could be attached to a specific object type.
  • To retrieve a list of event handlers currently attached to an object type.

See the following subsections for more information:

Attach an event handler to an object type

To attach an event handler to an object type, send a POST request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceArtifactID}}/objectTypes/{{ObjectTypeArtifactID}}/eventhandlers/{{EventHandlerID}}

Set the variables in the URL as follows:

  • {{WorkspaceArtifactID}} - the Artifact ID of the workspace that contains the object type.
  • {{ObjectTypeArtifactID}} - the Artifact ID of the object type that you want to attach the event handler to.
  • {{EventHandlerID}} - the ID of the event handler.

    Note: The {{EventHandlerID}} is an identifier assigned by Relativity to the event handler. This identifier isn't the Artifact ID for the event handler. The endpoints for retrieving attached or available event handlers return a field that contains this ID. See Retrieve event handlers attached to an object type or Retrieve available event handlers for an object type.

The body of the request is empty. When the request is successful, the response returns the status code of 200.

Detach an event handler from an object type

To detach an event handler from an object type, send a DELETE request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceArtifactID}}/objectTypes/{{ObjectTypeArtifactID}}/eventhandlers/{{EventHandlerID}}

Set the variables in the URL as follows:

  • {{WorkspaceArtifactID}} - the Artifact ID of the workspace that contains the object type.
  • {{ObjectTypeArtifactID}} - the Artifact ID of the object type that you want to detach the event handler from.
  • {{EventHandlerID}} - the ID of the event handler.

    Note: The {{EventHandlerID}} is an identifier assigned by Relativity to the event handler. This identifier isn't the Artifact ID for the event handler. The endpoints for retrieving attached or available event handlers return a field that contains this ID. See Retrieve event handlers attached to an object type or Retrieve available event handlers for an object type.

The body of the request is empty. When the request is successful, the response returns the status code of 200.

Retrieve event handlers attached to an object type

To retrieve a list of event handlers attached to an object type, send a GET request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceArtifactID}}/objectTypes/{{ObjectTypeArtifactID}}/eventhandlers

Set the variables in the URL as follows:

  • {{WorkspaceArtifactID}} - the Artifact ID of the workspace that contains the object type.
  • {{ObjectTypeArtifactID}} - the Artifact ID of the object type that has attached event handlers to retrieve.

The body of the request is empty.

The response contains multiple fields, such as the Artifact ID of the event handler, name, and others. If no event handlers are available for the object type, this endpoint returns an empty array.

  • ID - the reference ID of the event handler assigned by Relativity.
  • ArtifactID - the artifact ID of the object type.
  • Execution - the type of event handler, such as Console, Post Save, and others. For more information, see the EventHandlerExecution enumeration in the Services API, and Develop object type event handlers.
  • Application - an application that contains the event handler. This field contains the following:
    • Name - the user-friendly name for the application.
    • ArtifactID - the Artifact ID of the application.
    • Guids - an array of GUIDs used to identify the application.
  • AssemblyName - the name of the .NET assembly containing the event handler code.
  • ClassName - the name of the class that defines the event handler.
  • CompanyName - the name of the company that implemented or provided the event handler.
  • Description - general information about the event handler.
[
    {
        "ID": 20565,
        "ArtifactID": 1042543,
        "Execution": "PreSave",
        "Application": {
            "Name": "Default",
            "ArtifactID": 0,
            "Guids": [
                "3e86b18f-8b55-45c4-9a57-9e0cbd7baf46"
            ]
        },
        "AssemblyName": "myassembly.dll",
        "ClassName": "myassembly.MyPreSave",
        "CompanyName": "",
        "Description": ""
    }
]

Retrieve available event handlers for an object type

To retrieve a list of event handlers available in a workspace to attach to a specific object type, send a GET request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectTypes/workspace/{{WorkspaceArtifactID}}/objectTypes/{{ObjectTypeArtifactID}}/availableeventhandlers

Set the variables in the URL as follows:

  • {{WorkspaceArtifactID}} - the Artifact ID of the workspace that contains the object type.
  • {{ObjectTypeArtifactID}} - the Artifact ID of the object type that you want to retrieve a list of available event handlers for.

The body of the request is empty.

The response contains multiple fields, such as the Artifact ID of the event handler, name, and others. If no event handlers are available for the object type, this endpoint returns an empty array.

  • ID - the reference ID of the event handler assigned by Relativity.
  • ArtifactID - the artifact ID of the object type.
  • Execution - the type of event handler, such as Console, Post Save, and others. For more information, see the EventHandlerExecution enumeration in the Services API, and Develop object type event handlers.
  • Application - an application that contains the event handler. This field contains the following:
    • Name - the user-friendly name for the application.
    • ArtifactID - the Artifact ID of the application.
    • Guids - an array of GUIDs used to identify the application.
  • AssemblyName - the name of the .NET assembly containing the event handler code.
  • ClassName - the name of the class that defines the event handler.
  • CompanyName - the name of the company that implemented or provided the event handler.
  • Description - general information about the event handler.
[
   {
      "ID":20564,
      "ArtifactID":0,
      "Execution":"PreSave",
      "Application":{
         "Name":"Default",
         "ArtifactID":0,
         "Guids":[
            "3e86b18f-8b55-45c4-9a57-9e0cbd7baf46"
         ]
      },
      "AssemblyName":"testEH.dll",
      "ClassName":"testEH.REHEPreSave",
      "CompanyName":"",
      "Description":""
   },
   {
      "ID":20566,
      "ArtifactID":0,
      "Execution":"PreSave",
      "Application":{
         "Name":"Default",
         "ArtifactID":0,
         "Guids":[
            "3e86b18f-8b55-45c4-9a57-9e0cbd7baf46"
         ]
      },
      "AssemblyName":"testEHg.dll",
      "ClassName":"testEHg.REHEPreSave",
      "CompanyName":"",
      "Description":""
   },
   {
      "ID":20565,
      "ArtifactID":0,
      "Execution":"PreSave",
      "Application":{
         "Name":"Default",
         "ArtifactID":0,
         "Guids":[
            "3e86b18f-8b55-45c4-9a57-9e0cbd7baf46"
         ]
      },
      "AssemblyName":"myassembly.dll",
      "ClassName":"myassembly.MyPreSave",
      "CompanyName":"",
      "Description":""
   }
]

Object Rule Manager service

You can use object rules to further customize the behavior of the object types that you create. The Object Rule Manager service simplifies this process by supporting CRUD operations on object rules. It also provides helper endpoints for retrieving information about associative objects, layouts, choices and choice fields used when creating or updating an object rule. For a complete list of object rules, see Guidelines for the Object Rule Manager service.

See the following subsections for more information:

Guidelines for the Object Rule Manager service

Review the following guidelines for the Object Rule Manager service:

  • Use the Object Rule Manager service to work with the same object rule types available through the Relativity UI. For general information about object rules, see Adding an object rule
    • Choice behavior - controls whether the users can add or delete choices for fields.
    • Custom single object add link visibility - controls the availability of the Add link button used to add RDO instances to existing custom single objects from a layout.
    • Default layout - determines whether the user sees the default or any layout for the object type.
    • Default layout on new - determines the layout displayed when a user creates a new custom object.
    • Global button visibility - controls the visibility of specific buttons or action options for an object type.
    • Mass action visibility - controls the visibility of buttons for the mass operations for an object type.
    • New button override - overrides the page displayed when the New button is clicked by specifying a custom button label and page URL.
    • Sub-list button visibility - controls the display of the buttons for child and associative object lists.
    • Override edit link URL - overrides the page displayed when the Edit link is clicked by specifying custom link text and a page URL.
    • Override view link URL - overrides the page displayed when the View link is clicked by specifying custom link text and a page URL.
  • Use helper endpoints to retrieve information that you need when creating or updating an object rule. See the following table for suggested uses.
    Create or update this object rule Use these helper endpointsCompares to this UI field

    Choice Behavior

    		availablechoicefieldsField

    Default Layout

    		availablelayoutsAction
    availablechoicefieldsField
    availablechoicesValue

    Default Layout on New

    		availablelayoutsAction

    Sub-List Button Visibility

    		availablechoicefieldsField
    availablechoicesValue
    availableassociatedobjectsAssociative/Child Object
  • If a call to a helper endpoint returns an empty array, you can't create that object rule on the object type.
  • To attach an object rule, the object type must be an RDO and non-system object, or a document object type.
  • Use -1 for the workspace ID when you want to indicate the admin-level context.
  • To retrieve the Artifact ID of an object rule, use the Object Manager Service. For more information, see Object Manager service.

Create an object rule

You can create object rules by sending a POST request to the appropriate URL for the rule type. For general information about these object rules, see Adding an object rule.

Click the following drop-down links to view URLs and sample requests for sub-list visibility, choices, and layouts rules. You can find the URLs and JSON request formats for other object type rules in the Postman file provided for this service. For more information, see Postman sample files.

For the URLs in these examples, set the {{WorkspaceID}} variable to the Artifact ID of the workspace containing the object type, or use -1 to indicate the admin-level context.

  • Choice behavior
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/choicebehaviorobjectrules
  • Custom single object add link visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/customsingleobjectaddlinkvisibilityobjectrules
  • Default layout 
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/defaultlayoutobjectrules
  • Default layout on new
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/defaultlayoutonnewobjectrules
  • Global button visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/globalbuttonvisibilityobjectrules
  • Mass action visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/massactionvisibilityobjectrules
  • New button override
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/newbuttonoverrideobjectrules
  • Sub-list button visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/sublistbuttonvisibilityobjectrules
  • Override edit link URL
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/overrideeditlinkobjectrules
  • Override view link URL
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/overrideeditlinkobjectrules

To create a sub-list visibility rule, send a POST request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/sublistbuttonvisibilityobjectrules

The body of the request must contain the following fields unless specifically identified as optional:

  • objectRuleRequest - request to create or update a rule. It contains the following fields:
    • Name - the user-friendly name of the rule.
    • ObjectType - contains the Artifact ID of the object type.
    • Field - contains a Value specifying the Artifact ID of the field, which affects the button visibility.
    • Choice - contains a Value specifying the Artifact ID of the choice, which affects the button visibility.
    • SubListObject - contains a Value specifying the Artifact ID of the associative object list controlled by the rule.
    • ShowNew - a Boolean value indicating whether to display the New button on the associative object list. The default value is true.
    • ShowLink - a Boolean value indicating whether to display the Link button on the associative object list. The default value is true.
    • ShowUnlink - a Boolean value indicating whether to display the Unlink button on the associative object list. The default value is true.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object rule is linked to the applications in this array. If the array is empty, then the object rule isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
{
    "objectRuleRequest":{
         "Name": "Sample rule for sublist button",
         "ObjectType": {
            "ArtifactID": 1042378
        },
        "Field": {
            "Value": {
                "ArtifactID": 1042566
            }
        },
        "Choice": {
            "Value": {
                "ArtifactID": 1042568
            }
        },
        "SubListObject": {
            "Value": {
                "ArtifactID": 1042586
            }
        },
        "ShowNew": true,
        "ShowLink": false,
        "ShowUnlink": false,
        "RelativityApplications": []
    }
}

To create a choice rule, send a POST request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/choicebehaviorobjectrules

The body of the request must contain the following fields unless specifically identified as optional:

  • objectRuleRequest - request to create or update a rule. It contains the following fields:
    • Name - the user-friendly name of the rule.
    • ObjectType - contains the Artifact ID of the object type.
    • AllowAdd - a Boolean value indicating whether the user can mass copy choices.
    • AllowDelete - a Boolean value indicating whether the user can mass delete choices.
    • AllowRename - a Boolean value indicating whether the user can rename a choice.
    • Field - contains a Value specifying the Artifact ID of the field, which affects the choice behavior.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object rule is linked to the applications in this array. If the array is empty, then the object rule isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
{
    "objectRuleRequest":{
        "Name": "Sample Rule One",
        "ObjectType": {
            "ArtifactID": 1042378
        },
        "AllowAdd": true,
        "AllowDelete": true,
        "AllowRename": true,
        "Field": {
            "Value": {
                "ArtifactID": 1042565
            }
        },
        "RelativityApplications": []
      }
}

To create a layout rule, send a POST request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/defaultlayoutobjectrules

The body of the request must contain the following fields unless specifically identified as optional:

  • objectRuleRequest - request to create or update a rule. It contains the following fields:
    • Name - the user-friendly name of the rule.
    • ObjectType - contains the Artifact ID of the object type.
    • Field - contains a Value specifying the Artifact ID of the field, which controls the layout behavior.
    • Layout - contains a Value specifying the Artifact ID of the layout.
    • Choice - contains a Value specifying the Artifact ID of the choice, which controls the layout behavior.
    • AllowLayoutChange - a Boolean value indicating whether the user can select another layout. The default value is false.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object rule is linked to the applications in this array. If the array is empty, then the object rule isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
{
    "objectRuleRequest":{
        "Name": "Sample rule for layout",
        "ObjectType": {
            "ArtifactID": 1042378
        },
        "Field": {
            "Value": {
                "ArtifactID": 1042566
            }
        },
        "Layout": {
            "Value": {
                "ArtifactID": 1042594
            }
        },
        "Choice": {
            "Value": {
                "ArtifactID": 1042569
            }
        },
        "AllowLayoutChange": false,
        "RelativityApplications": []
    }
}

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

Read an object rule

You can retrieve basic information about an object rule or extended information, which also includes operations that you have permissions to perform on the object rule.

  • Retrieve basic metadata for an object rule - send a GET request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/{{ObjectRuleId}}
  • Retrieve extended metadata for an object rule - send a GET request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/{{ObjectRuleId}}/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 {{ObjectRuleId}} variable to the Artifact ID of the object rule that you want to read, and leave the body of the request empty.

  • Behavior - indicates the type of object rule, such as sub-list visibility, or choice behavior. See Create an object rule or the ObjectRuleBehavior enumeration on the Relativity.Services.Interfaces.ObjectRules.Models namespace in the Services API.
  • Field - contains the following fields:
    • 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 field.
      • ArtifactID - the Artifact ID of the field.
      • Guids - an array of GUIDs used to identify the field.
  • Layout - contains the following fields:
    • 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 layout.
      • ArtifactID - the Artifact ID of the layout.
      • Guids - an array of GUIDs used to identify the layout.
  • Choice - contains the following fields:
    • 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 choice.
      • ArtifactID - the Artifact ID of the choice.
      • Guids - an array of GUIDs used to identify the choice.
  • SubListObject - contains the following fields:
    • 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 associated object.
      • 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 the associated object.
      • Guids - an array of GUIDs used to identify the associated object.
      • ListType - the type of associative objects that the list contains.

        The ListType field contains one of the following values:

        • ChildObject - indicates that the list contains associated child objects.
        • MultipleObjectField - indicates that the list contains associated multiple object field types.
        • SingleObjectField - indicates that the list contains associated single object field types.

          For more information, see the ListType Enumeration in the Relativity.Services.Interfaces.ObjectRules.Models namespace.

  • AllowAdd - a Boolean value indicating whether the user can mass copy choices.
  • AllowDelete - a Boolean value indicating whether the user can mass delete choices.
  • AllowRename - a Boolean value indicating whether the user can rename choices.
  • ShowDelete - a Boolean value indicating whether the Delete button is available for global or sub-list button visibility. For example, it controls whether the button displays for mass operations or on the detail view of an object.
  • ShowAddLink - a Boolean value indicating whether the Add link button is available for custom single object add link visibility. For example, it controls whether the Add link button can be used to add RDO instances to existing custom single objects from a layout.
  • AllowLayoutChange - a Boolean value indicating whether the user can select another layout. The default value is false.
  • ShowNew - a Boolean value indicating whether to display the New button on the associative object list. The default value is true.
  • ShowLink - a Boolean value indicating whether to display the Link button on the associative object list. The default value is true.
  • ShowUnlink - a Boolean value indicating whether to display the Unlink button on the associative object list. The default value is true.
  • ShowMassCopy - a Boolean value indicating whether to display the Copy option for mass operations on an object. The mass action visibility rule controls this behavior.
  • ShowMassEdit - a Boolean value indicating whether to display the Edit option for mass operations on an object. The mass action visibility rule controls this behavior.
  • ShowMassReplace - a Boolean value indicating whether to display the Replace option for mass operations on an object. The mass action visibility rule controls this behavior.
  • ShowMassTally - a Boolean value indicating whether to display the Tally/Sum/Average option for mass operations on an object. The mass action visibility rule controls this behavior.
  • RelativityApplications - contains the following fields:
    • HasSecuredItems - a Boolean value indicating whether the application contains items that the current user doesn't have permission to access.
    • ViewableItems - an array of identifier objects for items that are accessible to the current user. For example, an object in this array would contain the name, Artifact IDs, and GUIDs for an application. See DisplayableObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
  • ObjectType - represents the object type that the rule is assigned to. It contains the following fields:
    • Name - the user-friendly name for the object type.
    • ArtifactTypeID - an identifier used to specify an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
    • ArtifactID - the Artifact ID of the object type.
    • Guids - an array of GUIDs used to identify the object type.
  • Meta - provides additional information available as extended metadata. It includes the following fields:
    • Unsupported - an array of properties that indicate functionality not available on the current instance of this object rule.
    • ReadOnly - an array of object type properties that can't be modified, such as the type of rule.
  • Actions - an array of Action objects indicating operations that you have permissions to perform on this object rule. For example, you may not have permissions to modify an object rule. Each Action object contains the following fields that are available as extended metadata:
    • Name - name of an operation available through REST for the object rule, such as delete, update, and so on.
    • Href - the URL used to make an HTTP request for the operation.
    • Verb - the name of the HTTP method for the operation.
    • IsAvailable - a Boolean value indicating whether you have permissions to perform the operation on this object rule.
    • Reason - an explanation for the unavailability of an action.
  • LastModifiedOn - the date and time when the object rule was most recently modified.
  • LastModifiedBy - contains the Artifact ID and name of the user who recently updated the object rule. It also contains an array of GUIDs used to identify the user.
  • CreatedOn - the date and time when the object type was added to Relativity.
  • CreatedBy - contains the Artifact ID and name of the user who created the object type. It also contains an array of GUIDs used to identify the user.
  • Name - the user-friendly name for the object rule.
  • ArtifactID - the Artifact ID of the object rule.
  • Guids - an array of GUIDs used to identify the object rule.
{
    "Behavior": "SubListButtonVisibility",
    "Field": {
        "Secured": false,
        "Value": {
            "Name": "Custom Single Choice Field",
            "ArtifactID": 1042566,
            "Guids": []
        }
    },
    "Choice": {
        "Secured": false,
        "Value": {
            "Name": "Green",
            "ArtifactID": 1042568,
            "Guids": []
        }
    },
    "SubListObject": {
        "Secured": false,
        "Value": {
            "Name": "Associated object example",
            "ArtifactTypeID": 1000051,
            "ArtifactID": 1042586,
            "Guids": [],
            "ListType": "ChildObject"    
        }
    },
    "AllowAdd": false,
    "AllowDelete": false,
    "AllowRename": false,
    "ShowDelete": false,
    "ShowAddLink": false,
    "AllowLayoutChange": false,
    "ShowNew": true,
    "ShowLink": false,
    "ShowUnlink": false,
    "ShowMassCopy": false,
    "ShowMassEdit": false,
    "ShowMassReplace": false,
    "ShowMassTally": false,
    "RelativityApplications": {
        "HasSecuredItems": false,
        "ViewableItems": []
    },
    "ObjectType": {
        "Name": "Custom Object Type",
        "ArtifactTypeID": 1000048,
        "ArtifactID": 1042378,
        "Guids": []
    },
    "Actions": [],
    "LastModifiedOn": "2019-02-22T19:22:49.927",
    "LastModifiedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "CreatedOn": "2019-02-22T17:40:24.7",
    "CreatedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "Name": "Updated object rule",
    "ArtifactID": 1042590,
    "Guids": []
}
{
    "Behavior": "SubListButtonVisibility",
    "Field": {
        "Secured": false,
        "Value": {
            "Name": "Custom Single Choice Field",
            "ArtifactID": 1042566,
            "Guids": []
        }
    },
    "Layout": {
        "Secured": false,
        "Value": {
            "Name": "Custom Layout",
            "ArtifactID": 1042594,
            "Guids": []
        }
    },
    "Choice": {
        "Secured": false,
        "Value": {
            "Name": "Custom Choice",
            "ArtifactID": 1042569,
            "Guids": []
        }
    },
    "SubListObject": {
        "Secured": false,
        "Value": {
            "Name": "Associated object example",
            "ArtifactTypeID": 1000051,
            "ArtifactID": 1042586,
            "Guids": [],
            "ListType": "ChildObject"    
        }
    },
    "AllowAdd": false,
    "AllowDelete": false,
    "AllowRename": false,
    "ShowDelete": false,
    "ShowAddLink": false,
    "AllowLayoutChange": false,
    "ShowNew": false,
    "ShowLink": false,
    "ShowUnlink": false,
    "ShowMassCopy": false,
    "ShowMassEdit": false,
    "ShowMassReplace": false,
    "ShowMassTally": false,
    "RelativityApplications": {
        "HasSecuredItems": false,
        "ViewableItems": []
    },
    "ObjectType": {
        "Name": "Custom Object Type",
        "ArtifactTypeID": 1000048,
        "ArtifactID": 1042378,
        "Guids": []
    },
    "Meta": {
        "Unsupported": [],
        "ReadOnly": [
            "RuleType"
        ]
    },
    "Actions": [
        {
            "Name": "Delete",
            "Href": "Relativity.ObjectRules/workspace/2342954/objectrules/1042595",
            "Verb": "DELETE",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "Update",
            "Href": "Relativity.ObjectRules/workspace/2342954/DefaultLayoutobjectrules/1042595",
            "Verb": "PUT",
            "IsAvailable": true,
            "Reason": []
        }
    ],
    "LastModifiedOn": "2019-02-22T17:55:04.253",
    "LastModifiedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "CreatedOn": "2019-02-22T17:55:04.253",
    "CreatedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "Name": "Sample rule for layout",
    "ArtifactID": 1042595,
    "Guids": []
}

Update an object rule

You can update object rules by sending a PUT request to the appropriate URL for the rule type. For general information about object rules, see Adding an object rule.

Click the following drop-down links to view URLs and sample requests for sub-list visibility, choices, and layouts rules. You can find the URLs and JSON request formats for other object type rules in the Postman file provided for this service. For more information, see Postman sample files.

For the URLs in these examples, set the {{WorkspaceID}} variable to the Artifact ID of the workspace containing the object type, or use -1 to indicate the admin-level context. Set the {{ObjectRuleId}} variable to the Artifact ID of the object type.

  • Choice behavior
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/choicebehaviorobjectrules/{{ObjectRuleId}}
  • Custom Single Object Add Link Visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/customsingleobjectaddlinkvisibilityobjectrules/{{ObjectRuleId}}
  • Default Layout
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/defaultLayoutobjectrules/{{ObjectRuleId}}
  • Default Layout on New
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/defaultlayoutonnewobjectrules/{{ObjectRuleId}}
  • Global Button Visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/globalbuttonvisibilityobjectrules
  • Mass Action Visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/massactionvisibilityobjectrules/{{ObjectRuleId}}
  • New Button Override
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/newbuttonoverrideobjectrules/{{ObjectRuleId}}
  • Sub-List Button Visibility
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/sublistbuttonvisibilityobjectrules/{{ObjectRuleId}}
  • Override edit link URL
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/overrideeditlinkobjectrules/{{ObjectRuleId}}
  • Override view link URL
    <host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/overrideviewlinkobjectrules/{{ObjectRuleId}}

To update a sub-list visibility rule, send a PUT request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/sublistbuttonvisibilityobjectrules/{{ObjectRuleId}}

The body of the request must contain the following fields unless specifically identified as optional:

  • objectRuleRequest - request to create or update a rule. It contains the following fields:
    • Name - the user-friendly name of the rule.
    • ObjectType - contains the Artifact ID of the object type.
    • Field - contains a Value specifying the Artifact ID of the field, which affects the button visibility.
    • Choice - contains a Value specifying the Artifact ID of the choice, which affects the button visibility.
    • SubListObject - contains a Value specifying the Artifact ID of the associative object list controlled by the rule.
    • ShowNew - a Boolean value indicating whether to display the New button on the associative object list. The default value is true.
    • ShowLink - a Boolean value indicating whether to display the Link button on the associative object list. The default value is true.
    • ShowUnlink - a Boolean value indicating whether to display the Unlink button on the associative object list. The default value is true.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object rule is linked to the applications in this array. If the array is empty, then the object rule isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
  • LastModifiedOn - the date and time when the object rule was most recently modified. This field is only required if you want to restrict the update of an object rule to the date that it was last modified. The value must match the LastModifiedOn date for the object rule stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.
{
    "objectRuleRequest":{
         "Name": "Updated object rule",
         "ObjectType": {
            "ArtifactID": 1042378
        },
        "Field": {
            "Value": {
                "ArtifactID": 1042566
            }
        },
        "Choice": {
            "Value": {
                "ArtifactID": 1042568
            }
        },
        "SubListObject": {
            "Value": {
                "ArtifactID": 1042586
            }
        },
        "ShowNew": true,
        "ShowLink": false,
        "ShowUnlink": false,
        "RelativityApplications": []
    },
        "LastModifiedOn": "2019-02-22T19:33:57.89"
}

To update a choice rule, send a PUT request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/choicebehaviorobjectrules/{{ObjectRuleId}}

The body of the request must contain the following fields unless specifically identified as optional:

  • objectRuleRequest - request to create or update a rule. It contains the following fields:
    • Name - the user-friendly name of the rule.
    • ObjectType - contains the Artifact ID of the object type.
    • AllowAdd - a Boolean value indicating whether the user can mass copy choices.
    • AllowDelete - a Boolean value indicating whether the user can mass delete choices.
    • AllowRename - a Boolean value indicating whether the user can rename a choice.
    • Field - contains a Value specifying the Artifact ID of the field, which affects the choice behavior.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object rule is linked to the applications in this array. If the array is empty, then the object rule isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
  • LastModifiedOn - the date and time when the object rule was most recently modified. This field is only required if you want to restrict the update of an object rule to the date that it was last modified. The value must match the LastModifiedOn date for the object rule stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.
{
    "objectRuleRequest":{
        "Name": "Update choice behavior",
        "ObjectType": {
            "ArtifactID": 1042378
        },
        "AllowAdd": true,
        "AllowDelete": false,
        "AllowRename": true,
        "Field": {
            "Value": {
                "ArtifactID": 1042565
            }
        },
        "RelativityApplications": []
      },
        "LastModifiedOn": "2019-02-22T19:33:57.89"
}

To update a layout rule, send a PUT request to a URL with the following format:

<host>/relativity.rest/api/relativity.objectrules/workspace/{{WorkspaceArtifactId}}/defaultLayoutobjectrules/{{ObjectRuleId}}

The body of the request must contain the following fields unless specifically identified as optional:

  • objectRuleRequest - request to create or update a rule. It contains the following fields:
    • Name - the user-friendly name of the rule.
    • ObjectType - contains the Artifact ID of the object type.
    • Field - contains a Value specifying the Artifact ID of the field, which controls the layout behavior.
    • Layout - contains a Value specifying the Artifact ID of the layout.
    • Choice - contains a Value specifying the Artifact ID of the choice, which controls the layout behavior.
    • AllowLayoutChange - a Boolean value indicating whether the user can select another layout. The default value is false.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The object rule is linked to the applications in this array. If the array is empty, then the object rule isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
  • LastModifiedOn - the date and time when the object rule was most recently modified. This field is only required if you want to restrict the update of an object rule to the date that it was last modified. The value must match the LastModifiedOn date for the object rule stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.
{
    "objectRuleRequest":{
        "Name": "Updated rule for default layout",
        "ObjectType": {
            "ArtifactID":1042378
        },
        "Field": {
            "Value": {
                "ArtifactID": 1042566
            }
        },
        "Layout": {
            "Value": {
                "ArtifactID": 1042594
            }
        },
        "Choice": {
            "Value": {
                "ArtifactID": 1042569
            }
        },
        "AllowLayoutChange": false,
        "RelativityApplications": []
    },
        "LastModifiedOn": "2019-02-22T19:33:57.89"
}

When an update request is successful, the response returns the status code of 200.

Delete an object rule

To remove an object rule, send a DELETE request to a URL with the following general format:

<host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/{{ObjectRuleId}}

The body of the request is empty. When the object rule is successfully deleted, the response returns the status code of 200.

Delete multiple object rules

You can remove multiple object rules on the same object type and across different object types by making a single call to the mass-delete endpoint. Send a POST request to a URL with the following general format:

<host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/mass-delete

The body of the request must contains an array of object rules with the following fields:

  • ArtifactID - the Artifact ID of the object rule.
  • GUID - an array of GUIDs used to identify the object rule. This array can be empty.
{
   "ObjectRules":[
      {
         "ArtifactID":1039509,
         "GUID":[

         ]
      },
      {
         "ArtifactID":1039525,
         "GUID":[

         ]
      },
      {
         "ArtifactID":1039630,
         "GUID":[

         ]
      }
   ]
}

When the object rules are successfully deleted, the response returns the status code of 200.

Retrieve choices, choice fields, layouts, or associated objects

When you create or update an object rule, you must provide the Artifact ID of any associative objects, layouts, choices and choice fields that it references. The Object Rule Manager service provides several helper endpoints that you can use to retrieve the Artifact ID, name, and other information about these objects. For most objects, it includes endpoints for the following types of requests:

  • GET request - use the endpoint for this request if you have the Artifact ID for an object type.
  • POST request - use the endpoint for this request if you have the user-friendly name of the object type, but not its Artifact ID.

For more information, see Guidelines for the Object Rule Manager service.

Use the following endpoints to retrieve associated objects for a specific object type:

  • Retrieve with Artifact ID - send a GET request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availableassociatedobjects/{{ObjectTypeArtifactId}}
  • Retrieve with Artifact ID or name - send a POST request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availableassociatedobjects

    The body of the request contains the following fields:

    • ObjectTypeID - represents identification information for an object. It contains the following fields:
      • ArtifactID - the Artifact ID of the object type. If you specify a name, this field is optional.
      • Name - the user-friendly name of the associated object. If you specify an Artifact ID, this field is optional.
    {
    "ObjectTypeID" : {
       "ArtifactID": 1036417,
       "Name": "Analytics Example"
    }
}

The response for both the GET and POST request contains the following fields:

  • Name - the user-friendly name of the associated object.
  • ArtifactTypeID - an identifier used to specify an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10.
  • ArtifactID - the Artifact ID of the object type.
  • Guids - an array of GUIDs used to identify the object type.
  • ListType - the type of associative objects that the list contains. This field contains one of the following values:
    • ChildObject - indicates that the list contains associated child objects.
    • MultipleObjectField - indicates that the list contains associated multiple object field types.
    • SingleObjectField - indicates that the list contains associated single object field types.

    For more information, see the ListType Enumeration in the Relativity.Services.Interfaces.ObjectRules.Models namespace.

If no associated objects are available for the object type, this endpoint returns an empty array.

[
    {
        "Name": "Category Example",
        "ArtifactTypeID": 1000017,
        "ArtifactID": 1036424,
        "Guids": [
            "f611b0e4-6d92-4ff6-a247-46e87685bfc9"
        ],
        ListType: "ChildObject"    
    }
]

Use the following endpoints to retrieve single choice fields for a specific object type:

  • Retrieve with Artifact ID - send a GET request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availablesinglechoicefields/{{ObjectTypeArtifactId}}

  • Retrieve with Artifact ID or name - send a POST request to a URL with the following general format:

    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availablesinglechoicefields

    The body of the request contains the following fields:

    • ObjectTypeID - represents identification information for an object. It contains the following fields:
      • ArtifactID - the Artifact ID of the object type. If you specify a name, this field is optional.
      • Name - the user-friendly name of the associated object. If you specify an Artifact ID, this field is optional.
    {
    "ObjectTypeID" : {
       "ArtifactID": 1042378,
       "Name": "Custom Object Type"
    }
}

The response for both the GET and POST request contains the following fields:

  • Name - the user-friendly name of the associated object.
  • ArtifactID - the Artifact ID of the object type.
  • Guids - an array of GUIDs used to identify the object type.

If no associated single choice fields are available for the object type, this endpoint returns an empty array.

[
    {
        "Name": "Custom Single Choice Field",
        "ArtifactID": 1042566,
        "Guids": []
    },
    {
        "Name": "Single Choice Field",
        "ArtifactID": 1042564,
        "Guids": []
    }
]

Use the following endpoints to retrieve single and multiple choice fields for a specific object type:

  • Retrieve with Artifact ID - send a GET request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availablechoicefields/{{ObjectTypeArtifactId}}

  • Retrieve with Artifact ID or name - send a POST request to a URL with the following general format:

    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availablechoicefields/

    The body of the request contains the following fields:

    • ObjectTypeID - represents identification information for an object. It contains the following fields:
      • ArtifactID - the Artifact ID of the object type. If you specify a name, this field is optional.
      • Name - the user-friendly name of the associated object. If you specify an Artifact ID, this field is optional.
    {
    "ObjectTypeID" : {
       "ArtifactID": 1042378,       
       "Name": "Custom Object Type"
    }
}

The response for both the GET and POST request contains the following fields:

  • Name - the user-friendly name of the associated object.
  • ArtifactID - the Artifact ID of the object type.
  • Guids - an array of GUIDs used to identify the object type.

If no choice fields are available for the object type, this endpoint returns an empty array.

[
    {
        "Name": "Custom Single Choice Field",
        "ArtifactID": 1042566,
        "Guids": []
    },
    {
        "Name": "Multiple Choice Field",
        "ArtifactID": 1042565,
        "Guids": []
    },
    {
        "Name": "Single Choice Field",
        "ArtifactID": 1042564,
        "Guids": []
    }
]

To retrieve a list of choices for an object type, send a GET request to a URL with the following general format:

<host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availablechoices/{{FieldId}}

The response contains the following fields:

  • Name - the user-friendly name of the associated object.
  • ArtifactID - the Artifact ID of the object type.
  • Guids - an array of GUIDs used to identify the object type.

If no choice are available for the object type, this endpoint returns an empty array.

[
    {
        "Name": "Blue",
        "ArtifactID": 1042569,
        "Guids": []
    },
    {
        "Name": "Green",
        "ArtifactID": 1042568,
        "Guids": []
    },
    {
        "Name": "Orange",
        "ArtifactID": 1042570,
        "Guids": []
    }
]

Use the following endpoints to retrieve layouts for a specific object type:

  • Retrieve with Artifact ID - send a GET request to a URL with the following general format:
    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availablelayouts/{{ObjectTypeArtifactId}}

  • Retrieve with Artifact ID or name - send a POST request to a URL with the following general format:

    <host>/Relativity.rest/api/relativity.objectRules/workspace/{{WorkspaceArtifactId}}/objectrules/availablelayouts

    The body of the request contains the following fields:

    • ObjectTypeID - represents identification information for an object. It contains the following fields:
      • ArtifactID - the Artifact ID of the object type. If you specify a name, this field is optional.
      • Name - the user-friendly name of the associated object. If you specify an Artifact ID, this field is optional.
    {
    "ObjectTypeID" : {
        "ArtifactID": 1042378,
        "Name" : "Custom Object Type"
    }
}

The response for both the GET and POST request contains the following fields:

  • Name - the user-friendly name of the associated object.
  • ArtifactID - the Artifact ID of the object type.
  • Guids - an array of GUIDs used to identify the object type.

If no layouts are available for the object type, this endpoint returns an empty array.

[
    {
        "Name": "Custom Object Type Layout",
        "ArtifactID": 1042377,
        "Guids": []
    }
]

Mass Operation Manager service

You can add mass operations to object types to further customize their behavior. When a user interacts with a mass operation, you can display a custom page or execute an event handler with specialized functionality. For general information about mass operations, see Adding a custom mass operation.

The Mass Operation Manager service includes endpoints for creating, reading, updating, and deleting mass operations. It also includes helper endpoints for retrieving information about object types that be associated with a mass operation, and available event handlers and layouts for use with mass operations.

Review the following guidelines for working with this service:

  • Make sure that you set the appropriate field values for the type of mass operation that you want to create. See Create an object type and Update an object type.
  • Use the helper endpoints to retrieve object types, event handlers, and layouts available for associating with mass operation.
  • Mass operations aren't available in the admin-level context, so you must specify a workspace ID.

See the following subsections for more information:

Create a mass operation

You can a create a mass operation that displays a custom page or that executes a custom event handler when a user interacts with it. For general information about mass operations, see Adding a custom mass operation.

Click the following drop-down links to view URLs and sample requests for mass operations that use a custom page or an event handler. For the URLs in these examples, set the {{WorkspaceID}} variable to the Artifact ID of a workspace.

To create a mass operations that displays a custom page for a user, send a POST request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/custompagemassoperations

The body of the request must contain the following fields unless specifically identified as optional:

  • MassOperationRequest - represents a request to create a mass operation. It contains the following fields:
    • Name - the user-friendly name of the mass operation.
    • ObjectType - contains information about the object type to associate with this mass operation. It contains the following fields, but only the Artifact ID of the object type is required:
      • ArtifactID - the Artifact ID 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.
      • Guids - an array of GUIDs used to identify the object type. This array can be empty.
      • Name - the user-friendly name of the object type.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The mass operation is linked to the applications in this array. If the array is empty, then the mass operation isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
    • Url - the URL for the custom page that you want displayed as a pop-up window for the mass operation.
    • PopupHeight - the height of the pop-up window displayed for this mass operation in pixels. This value must be greater than 0.
    • PopupWidth - the width of the pop-up window displayed for this mass operation in pixels. This value must be greater than 0.
{
   "MassOperationRequest":{
      "Name":"Custom page mass operation",
      "ObjectType":{
         "ArtifactID":1042378,
         "ArtifactTypeID":1000048,
         "Guids":[],
         "Name":"Custom Object Type"
      },
      "RelativityApplications": [
           {
               "ArtifactID":1042630,
               "Guids":[]
           }
       ],
      "Url":"https://www.mydomain.corp/MySite/Content/MyCustomPage.htm",
      "PopupHeight":500,
      "PopupWidth":500
   }
}

To create a mass operation that executes an event handler, send a POST request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/eventhandlermassoperations

The body of the request must contain the following fields unless specifically identified as optional:

  • MassOperationRequest - represents a request to create a mass operation. It contains the following fields:
    • Name - the user-friendly name of the mass operation.
    • ObjectType - contains information about the object type to associate with this mass operation. It contains the following fields, but only the Artifact ID of the object type is required:
      • ArtifactID - the Artifact ID 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.
      • Guids - an array of GUIDs used to identify the object type. This array can be empty.
      • Name - the user-friendly name of the object type.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The mass operation is linked to the applications in this array. If the array is empty, then the mass operation isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
    • EventHandlerID - an identifier assigned by Relativity to the event handler. This identifier isn't the Artifact ID for the event handler. The endpoint for retrieving available event handlers for a mass operation returns a field that contains this ID. See Retrieve a parent object types.
    • Layout - represents identification information for a layout. It contains the following field:
      • Value - contains the Artifact ID and GUIDs used to identify a specific layout for the mass operation. The array containing GUIDs can be empty.
{
    "MassOperationRequest": {
        "Name": "Event handler mass operation",
        "ObjectType": {
            "ArtifactID": 1042378,
            "ArtifactTypeID" : 1000048,
            "Guids": [],
            "Name": "Custom Object Type"
        },
        "RelativityApplications": [
           {
               "ArtifactID":1042630,
               "Guids":[]
           }
         ],
        "EventHandlerID": "3717",
        "Layout": {
            "Value": {
                "ArtifactID": 1042377,
                "Guids": []
            }
        }
    }
}

When a custom page or event handler mass operation is successfully created, the response contains the Artifact ID of the mass operation, such as 1042616. It also returns a status code of 200.

Read a mass operation

You can retrieve basic information about a mass operation or extended information, which also includes operations that you have permissions to perform on the mass operation.

  • Retrieve basic metadata for a mass operation - send a GET request to a URL with the following general format:
    <host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/massoperations/{{massOperationId}}
  • Retrieve extended metadata for a mass operation - send a GET request to a URL with the following general format:
    <host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/massoperations/{{massOperationId}}/true/true

For both requests, set the {{WorkspaceID}} variable to the Artifact ID of a workspace. Set the {{massOperationId}} variable to the Artifact ID of the mass operation that you want to read, and leave the body of the request empty.

The response contains the following fields:

  • Type - indicates whether the mass operation uses a custom page or event handler when it executes. See Create an object type or the MassOperationType enumeration on the Relativity.Services.Interfaces.MassOperation.Models namespace in the Services API.
  • Name - the user-friendly name of the mass operation.
  • ObjectType - represents identification information for the object type associated with the mass operation. It contains the following fields, but only the Artifact ID of the object type is required:
    • ArtifactID - the Artifact ID of the object type.
    • Guids - an array of GUIDs used to identify the object type.
  • RelativityApplications - contains the following fields:
    • HasSecuredItems - a Boolean value indicating whether the application contains items that the current user doesn't have permission to access.
    • ViewableItems - an array of identifier objects for items that are accessible to the current user. For example, an object in this array would contain the name, Artifact IDs, and GUIDs for an application. See DisplayableObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
  • Url - the URL for the custom page that displays as a pop-up window for the mass operation.
  • PopupHeight - the height of the pop-up window displayed for this mass operation in pixels.
  • PopupWidth - the width of the pop-up window displayed for this mass operation in pixels.
  • EventHandlerID - an identifier assigned by Relativity to the event handler. This identifier isn't the Artifact ID for the event handler. The endpoint for retrieving available event handlers for a mass operation return a field that contains this ID. See Retrieve a parent object types.
  • ClassName - the name of the class that defines the event handler.
  • ApplicationName - the name of the Relativity application containing the event handler.
  • Layout - represents identification information for a layout. It contains the following field:
    • Secured - indicates whether the current user has permission to view the settings in the Value field.
    • Value - contains the Name, Artifact ID, and GUIDs used to identify a specific layout for the mass operation.
  • CreatedOn - the date and time when the mass operation was added to Relativity.
  • CreatedBy - contains the Artifact ID and name of the user who created the mass operation. It also contains an array of GUIDs used to identify the user.
  • LastModifiedBy - contains the Artifact ID and name of the user who recently updated the mass operation. It also contains an array of GUIDs used to identify the user.
  • LastModifiedOn - the date and time when the mass operation was most recently modified.

  • Meta - provides additional information available as extended metadata. It includes the following fields:

    • Unsupported - an array of properties that indicate functionality not available on the current instance of this object type.
    • ReadOnly - an array of object type properties that can't be modified.
  • Actions - an array of Action objects indicating operations that you have permissions to perform on this object type. For example, you may not have permissions to modify an mass operation that is part of a locked application. Each Action object contains the following fields that are available as extended metadata:
    • Name - name of an operation available through REST for the object type, such as delete, update, and so on.
    • Href - the URL used to make an HTTP request for the operation.
    • Verb - the name of the HTTP method for the operation.
    • IsAvailable - a Boolean value indicating whether you have permissions to perform the operation on this object type.
    • Reason - an explanation for the unavailability of an action.
  • ArtifactID - the Artifact ID of the mass operation.
  • Guids - an array of GUIDs used to identify the mass operation.
{
    "Type": "EventHandlerMassOperation",
    "Name": "Event handler mass operation",
    "ObjectType": {
        "ArtifactID": 1042378,
        "Guids": []
    },
    "RelativityApplications": {
        "HasSecuredItems": false,
        "ViewableItems": [
            {
                "Name": "MySampleApplication",
                "ArtifactID": 1042630,
                "Guids": [
                    "555556e4-0f70-4b3a-85cc-bb8572b600f1"
                ]
            }
         ]
    },
    "PopupHeight": 0,
    "PopupWidth": 0,
    "EventHandlerID": 3717,
    "ClassName": "Test.Relativity.EventHandlers.MassOperations.GenerateExcelTextHandler",
    "ApplicationName": "TEST",
    "Layout": {
        "Secured": false,
        "Value": {
            "Name": "Custom Object Type Layout",
            "ArtifactID": 1042377,
            "Guids": []
        }
    },
    "CreatedOn": "2019-03-06T19:53:06.413",
    "CreatedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "LastModifiedOn": "2019-03-06T19:53:06.413",
    "Actions": [],
    "ArtifactID": 1042616,
    "Guids": []
}
{
    "Type": "CustomPageMassOperation",
    "Name": "Custom page mass operation",
    "ObjectType": {
        "ArtifactID": 1042378,
        "Guids": []
    },
    "RelativityApplications": {
        "HasSecuredItems": false,
        "ViewableItems": [
            {
                "Name": "MySampleApplication",
                "ArtifactID": 1042630,
                "Guids": [
                    "555556e4-0f70-4b3a-85cc-bb8572b600f1"
                ]
            }
        ]
    },
    "Url": "https://www.mydomain.corp/MySite/Content/MyCustomPage.htm",
    "PopupHeight": 500,
    "PopupWidth": 500,
    "EventHandlerID": 0,
    "CreatedOn": "2019-03-06T18:56:10.047",
    "CreatedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "LastModifiedOn": "2019-03-06T18:56:10.047",
    "Meta": {
        "Unsupported": [],
        "ReadOnly": []
    },
    "Actions": [
        {
            "Name": "Delete",
            "Href": "Relativity.MassOperations/workspace/2342954/massoperations/1042615",
            "Verb": "DELETE",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "Update",
            "Href": "Relativity.MassOperations/workspace/2342954/custompagemassoperations/1042615",
            "Verb": "PUT",
            "IsAvailable": true,
            "Reason": []
        }
    ],
    "ArtifactID": 1042615,
    "Guids": []
}
{
    "Type": "EventHandlerMassOperation",
    "Name": "Event handler mass operation",
    "ObjectType": {
        "ArtifactID": 1042378,
        "Guids": []
    },
    "RelativityApplications": {
        "HasSecuredItems": false,
        "ViewableItems": [
            {
                "Name": "MySampleApplication",
                "ArtifactID": 1042630,
                "Guids": [
                    "555556e4-0f70-4b3a-85cc-bb8572b600f1"
                ]
            }
        ]
    },
    "PopupHeight": 0,
    "PopupWidth": 0,
    "EventHandlerID": 3717,
    "ClassName": "Test.Relativity.EventHandlers.MassOperations.GenerateExcelTextHandler",
    "ApplicationName": "TEST",
    "Layout": {
        "Secured": false,
        "Value": {
            "Name": "Custom Object Type Layout",
            "ArtifactID": 1042377,
            "Guids": []
        }
    },
    "CreatedOn": "2019-03-06T19:53:06.413",
    "CreatedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "Doe, Jane",
        "ArtifactID": 1023652,
        "Guids": []
    },
    "LastModifiedOn": "2019-03-06T19:53:06.413",
    "Meta": {
        "Unsupported": [],
        "ReadOnly": []
    },
    "Actions": [
        {
            "Name": "Delete",
            "Href": "Relativity.MassOperations/workspace/2342954/massoperations/1042616",
            "Verb": "DELETE",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "Update",
            "Href": "Relativity.MassOperations/workspace/2342954/eventhandlermassoperations/1042616",
            "Verb": "PUT",
            "IsAvailable": true,
            "Reason": []
        }
    ],
    "ArtifactID": 1042616,
    "Guids": []
}

Update a mass operation

You can update a mass operation by sending a PUT request to the endpoint for a custom page or event handler mass operation.

Click the following drop-down links to view URLs and sample requests for custom page and event handler mass operations.

For the URLs in these examples, set the {{WorkspaceID}} variable to the Artifact ID of a workspace. Set the {{massOperationId}} variable to the Artifact ID of the mass operation.

To update a custom page mass operation, send a PUT request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/custompagemassoperations/{{massOperationId}}

The body of the request must contain the following fields unless specifically identified as optional:

  • MassOperationRequest - represents a request to update a mass operation. It contains the following fields:
    • Name - the user-friendly name of the mass operation.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The mass operation is linked to the applications in this array. If the array is empty, then the mass operation isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
    • PopupHeight - the height of the pop-up window displayed for this mass operation in pixels. This value must be greater than 0.
    • PopupWidth - the width of the pop-up window displayed for this mass operation in pixels. This value must be greater than 0.
    • LastModifiedOn - the date and time when the object rule was most recently modified. This field is only required if you want to restrict the update of a mass operation to the date that it was last modified. The value must match the LastModifiedOn date for the mass operation stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.
{
    "MassOperationRequest": {
        "Name": "Updated custom page mass operation",
        "RelativityApplications": [
           {
               "ArtifactID":1042630,
               "Guids":[]
           }
         ],
        "Url": "https://www.mydomain.corp/MySite/Content/MyCustomPage.htm",
        "PopupHeight": 500,
        "PopupWidth": 500,
        "LastModifiedOn": "2019-03-11T19:00:53.317"
    }
}

To update an event handler mass operation, send a PUT request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/eventhandlermassoperations/{{massOperationId}}

The body of the request must contain the following fields unless specifically identified as optional:

  • MassOperationRequest - represents a request to update a mass operation. It contains the following fields:
    • Name - the user- friendly name of the mass operation.
    • RelativityApplications - an array of Relativity applications represented by ObjectIdentifier objects, which contain the Artifact ID and GUIDs for an application. The mass operation is linked to the applications in this array. If the array is empty, then the mass operation isn't linked to any application. See ObjectIdentifier class in the Relativity.Services.Interfaces.Shared.Models namespace of the Services API.
    • EventHandlerID - an identifier assigned by Relativity to the event handler. This identifier isn't the artifact ID for the event handler. The endpoint for retrieving available event handlers for a mass operation return a field that contains this ID. See Retrieve a parent object types.
    • Layout - represents identification information for a layout. It contains the following field:
      • Value - contains the Artifact ID and GUIDs used to identify a specific layout for the mass operation.
    • LastModifiedOn - the date and time when the object rule was most recently modified. This field is only required if you want to restrict the update of a mass operation to the date that it was last modified. The value must match the LastModifiedOn date for the mass operation stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.
{
   "MassOperationRequest":{
      "Name":"Updated event handler mass operation",
      "RelativityApplications":[

      ],
      "EventHandlerID":"3717",
      "Layout":{
         "Value":{
            "ArtifactID":1042377,
            "Guids":[

            ]
         }
      },
      "LastModifiedOn":"2019-03-14T19:30:52.35"
   }
}

When a mass operation is successfully updated, the response returns a status code of 200.

Delete a mass operation

To remove a mass operation, send a DELETE request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/massoperations/{{massOperationId}}

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

The body of the request is empty. When the mass operation is successfully deleted, the response is a status code of 200.

Retrieve available object types for a mass operation

You can customize your object types with additional functionality by creating mass operations for them.

To retrieve a list of object types available in a workspace, send a POST request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/massoperations/availableobjecttypes

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

The body of the request is empty.

  • 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 the object type.
  • Guids - an array of GUIDs used to identify the object type.
[
   {
      "Name":"Document",
      "ArtifactTypeID":10,
      "ArtifactID":1035231,
      "Guids":[

      ]
   },
   {
      "Name":"Transform Set",
      "ArtifactTypeID":1000004,
      "ArtifactID":1035285,
      "Guids":[

      ]
   },
   {
      "Name":"Transform",
      "ArtifactTypeID":1000005,
      "ArtifactID":1035296,
      "Guids":[

      ]
   },
   {
      "Name":"Search Terms Report",
      "ArtifactTypeID":1000006,
      "ArtifactID":1035313,
      "Guids":[

      ]
   }
]

Retrieve available event handlers for a mass operation

You can add an event handler for a mass operation to an object type. This event handler executes when the user executes the mass operation through the Relativity UI. You can retrieve a list of event handlers available for the object type by calling the availableeventhandlers endpoint. For general information about event handlers, see Create an object type.

To retrieve a list of available event handlers, send a POST request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/eventhandlermassoperations/availableeventhandlers

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

The body of the request is empty.

The response contains the following fields:

  • Application - an application that contains the event handler. This field contains the following:
    • Name - the user-friendly name for the application.
    • ArtifactID - the Artifact ID of the application.
    • Guids - an array of GUIDs used to identify the application.
  • EventHandlerID - the reference ID of the event handler assigned by Relativity.
  • AssemblyName - the name of the .NET assembly containing the event handler code.
  • ClassName - the name of the class that defines the event handler.
  • CompanyName - the name of the company that implemented or provided the event handler.
  • Description - general information about the event handler.
[
   {
      "Application":{
         "Name":"Custom Test Application",
         "ArtifactID":0,
         "Guids":[
            "5a4d89fc-7ec9-4a37-99ca-2a4d94ba4f02"
         ]
      },
      "EventHandlerID":3717,
      "AssemblyName":"Test.Package.dll",
      "ClassName":"Test.Relativity.EventHandlers.MassOperations.GenerateExcelTextHandler",
      "CompanyName":"TEST",
      "Description":""
   },
   {
      "Application":{
         "Name":"Case Dynamics",
         "ArtifactID":0,
         "Guids":[
            "5975ec2c-ef13-4358-a062-aff4891b2343"
         ]
      },
      "EventHandlerID":16685,
      "AssemblyName":"kCura.CaseDynamics.EventHandlers.dll",
      "ClassName":"kCura.CaseDynamics.EventHandlers.PrintingProfile.PrintingProfile_MassDelete",
      "CompanyName":"Relativity ODA LLC",
      "Description":"Printing Profile Mass Delete Custom"
   },
   {
      "Application":{
         "Name":"Document Utilities",
         "ArtifactID":0,
         "Guids":[
            "6894df96-b204-4157-9318-4073d8a7476d"
         ]
      },
      "EventHandlerID":16276,
      "AssemblyName":"MoveDocumentsToFolder_EH.dll",
      "ClassName":"MoveDocumentsToFolder_EH.MassOperation",
      "CompanyName":"Relativity ODA LLC",
      "Description":"Mass operation to move documents to a folder path specified in a text field."
   }
]

Retrieve available layouts for a mass operation

When you add a mass operation that uses an event handler to an object type, you must select a layout that displays after the user initiates the operation in the Relativity UI. You can retrieve a list of layouts available for the object type by calling the availablelayouts endpoint. For general information about layouts, see Create an object type.

To retrieve a list of available layouts, send a POST request to the following URL:

<host>/Relativity.REST/api/Relativity.MassOperations/workspace/{{workspaceId}}/eventhandlermassoperations/availablelayouts

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

The body of the request contains the following fields:

  • ObjectType - represents identification information for an object. It contains the following fields, but only the Artifact ID of the object type is required:
    • ArtifactID - the Artifact ID 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.
    • Guids - an array of GUIDs used to identify the object type. This array can be empty.
    • Name - the user-friendly name of the object type.

Note: You can specify a value for only one of these fields: Name, ArtifactID, or ArtifactTypeID. The other fields are then optional.

{
   "ObjectType":{
      "ArtifactID":1042378,
      "ArtifactTypeID":1000048,
      "Guids":[
      ],
      "Name":"Custom Object Type"
   }
}

The response contains the following fields:

  • ObjectTypeName - the object type associated with the layout.
  • Name - the user-friendly name of the layout.
  • ArtifactID - the Artifact ID of the layout.
  • Guids - an array of GUIDs used to identify the layout.
[
   {
      "ObjectTypeName":"Custom Object Type",
      "Name":"Custom Object Type Layout",
      "ArtifactID":1042377,
      "Guids":[

      ]
   },
   {
      "ObjectTypeName":"Custom Object Type",
      "Name":"Custom Layout",
      "ArtifactID":1042594,
      "Guids":[

      ]
   },
   {
      "ObjectTypeName":"Custom Object Type Two",
      "Name":"Custom Object Type Two Layout",
      "ArtifactID":1042579,
      "Guids":[

      ]
   },
   {
      "ObjectTypeName":"Custom Page",
      "Name":"Custom Page Layout",
      "ArtifactID":1036937,
      "Guids":[

      ]
   },
   {
      "ObjectTypeName":"Data Grid Audit",
      "Name":"Data Grid Audit Layout",
      "ArtifactID":1038060,
      "Guids":[

      ]
   },
   {
      "ObjectTypeName":"Data Grid Audit Field Mapping",
      "Name":"Data Grid Audit Field Mapping Layout",
      "ArtifactID":1038061,
      "Guids":[

      ]
   }
]