Analytics Search Manager (REST)

The Relativity REST API supports operations with analytics saved searches though the Analytics Search Manager Service. The operations available through the Analytics Search Manager Service are equivalent to the methods for interacting with the Analytics Search DTO in the Relativity Services API. For more information, see AnalyticsSearch in the Services API documentation.

Note: You can only use the POST method when interacting with the service.

You can programmatically execute analytics searches created with the Analytics Search Manager Service by using the SavedSearchCondition class of the Relativity Services API or a saved search query in the REST API.

This page contains the following information:

Client code sample

The following is an example of .NET REST client for creating an analytics saved search. The code can be used for all Analytics Search Manager Service operations with different endpoint URLs and input JSON values.

//Set up the client.
            
HttpClient httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("http://localhost/");

//Set the required headers.
            
httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
httpClient.DefaultRequestHeaders.Add("Authorization", "Basic c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

//Call Create for a SavedSearch.
            
string url = "Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/CreateSingleAsync";
StringContent content = new StringContent(CreateInputJSON, Encoding.UTF8, "application/json");
HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
string result = response.Content.ReadAsStringAsync().Result;
bool success = HttpStatusCode.Created == response.StatusCode;

//Parse the result with Json.NET.
            
JObject resultObject = JObject.Parse(result);        

Create

Use this Analytics Search Manager Service URL to create an analytics search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/CreateSingleAsync

The request must include a workspace ID and valid JSON representation of an AnalyticsSearch DTO.

Note: Required AnalyticsSearch DTO properties include ArtifactTypeID, Name, SearchIndex, and Fields.

The response is an Artifact ID of the created search.

Read

Use this Analytics Search Manager Service URL to read an analytics search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/ReadSingleAsync   

The request must include the workspace ID and the analytics saved search Artifact ID.

{
  "workspaceArtifactID": 1030160,
  "searchArtifactID": 1038760
}  

The response returns a JSON representation of an AnalyticsSearch DTO.

Update

Use this Analytics Search Manager Service URL to update an analytics search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/UpdateSingleAsync

The request must include a workspace ID and a valid JSON representation of an AnalyticsSearch DTO.

Note: You must include all DTO field information in the update. You cannot update individual fields because fields left empty will be cleared on the update. All DTO fields are required except for system/user created by/created on.

The following JSON sample illustrates how to change fields and sort order of the analytics search created in a previous example.

{
  "workspaceArtifactID": 1030160,
  "searchDTO": {
    "ArtifactID": 1038760,
    "ArtifactTypeID": 10,
    "Name": "Oil vs Gas Analytics Search",
    "SearchIndex": {
      "ArtifactID": 1038684,
    },
    "RequiresManualRun": true,
    "SearchCriteria": {
      "Conditions": [
      {
        "Condition": {
          "Operator": "Is",
          "FieldIdentifier": {
            "Name": "Email From"
          },
          "Value": "JonSmith@mycompany.com",
          "ConditionType": "Criteria"
        },
        "BooleanOperator": "And"
      },
      {
        "Condition": {
          "Operator": "AnyOfThese",
          "FieldIdentifier": {
            "Name": "Designation"
          },
          "Value": [
          1035850
          ],
          "ConditionType": "Criteria"
        },
        "BooleanOperator": "And"
      },
      {
        "Condition": {
          "Operator": "IsBefore",
          "FieldIdentifier": {
             "Name": "Date Created"
          },
          "Value": "2014-10-09T00:00:00",
          "ConditionType": "CriteriaDate"
        },
        "BooleanOperator": "None"
      }
      ],
      "BooleanOperator": "None"
    },

    "Fields": [
      {
        "Name": "Doc ID Beg"
      },
      {
        "Name": "Author"
      },
      {
        "Name": "Extracted Text"
      }
    ],
    "Sorts": [
      {
        "FieldIdentifier": {
          "Name": "Doc ID Beg"
        },
        "Order": 0,
        "Direction": 1
      }
    ],
    "SortByRank": true,
    "ConceptsText": "She sells sanctuary",
    "MinimumConceptRank": ".6",
  }
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Delete

Use this Analytics Search Manager Service URL to update an analytics search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/DeleteSingleAsync

The request must include the workspace ID and the analytics saved search Artifact ID.

{
  "workspaceArtifactID": 1030160,
  "searchArtifactID": 1038661
}  

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Query

The Analytics Search Manager Service URL for querying analytics searches:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/QueryAsync

The request must include the workspace ID and the query. You can also specify the number of results to return as the optional length property.

{
  "workspaceArtifactID": 1030160,
  "query": {
    "Condition": "'Name' STARTSWITH 'My'",
    "Sorts": [
      {
        "FieldIdentifier": {
          "ArtifactID": 0,
          "ViewFieldID": 0,
          "Guids": [],
          "Name": "ArtifactID"
        },
        "Order": 0,
        "Direction": 1
      }
    ]
  },
  "length": 5
}

If more results are available than initially specified in the length property, the query returns a token value that is not null. The results can subsequently be retrieved by a call to the QuerySubsetAsync operation.

/relativity.rest/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/QuerySubsetAsync

Note that the QuerySubsetAsync request can specify the starting index of the result subset and the number of results to be returned.

{
  "workspaceArtifactID": 1030160,
  "queryToken": "d0aff8bf-321d-4600-8240-dba2f0173b1d",
  "start": 6,
  "length": 5
}

To return all analytics saved searches in a workspace, specify an empty Condition as shown in the JSON example below. When the length parameter is not specified, its value defaults to 0, and the number of returned results defaults to the Instance setting table value of PDVDefaultQueryCacheSize of 10000. For more information, see Search Relativity.

{
  "workspaceArtifactID": 1030160,
  "query": {}
}

The response returns a collection of analytics search objects as an AnalyticsSearchQueryResultSet object.

Move

You can move an analytics saved search to a different folder. Send a request to this Analytics Search Manager service URL:

/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/MoveAsync

The request must contain the following fields:

  • workspaceArtifactID – the Artifact ID for the workspace where the saved search resides.
  • artifactID – the Artifact ID of the search.
  • destinationContainerID – the Artifact ID of the target saved search folder.

Note: You must have delete permission for saved search and search folder on the source search folder and add permissions for saved search and search folder on destination folder. If any of those is not met then a validation error is returned.

{
   "workspaceArtifactID":1015024,
   "artifactID":1039180,
   "destinationContainerID":1039178
}

The response returns the following fields:

  • ProcessState - a message that indicates the current operation executing on the search being moved. The values can include:
    • Moving saved searches.
    • Error
    • Completed
  • TotalOperations - equals the sum of the number of moved objects.
  • OperationsCompleted - indicates the number of operations that have been executed.
{
   "TotalOperations": 1,
   "ProcessState": "Completed",
   "OperationsCompleted": 1
}

Note: Unlike the Services API, the Analytics Search Manager Service doesn’t support use of progress indicators or cancellation tokens.

Copy

You can create a copy of an existing analytics saved search in the same saved search folder. Send a request to this Analytics Search Manager service URL:

/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/CopySingleAsync

The request must contain the following fields:

  • workspaceArtifactID – the Artifact ID for the workspace where the saved search resides.
  • artifactID – the Artifact ID of the search
{
   "workspaceArtifactID": 1015024,
   "searchArtifactID": 1036361
}

This creates a copy of an existing search in the same location. The name of the copy is based on the name of the original with an incremented number in brackets, for example Jones Case Documents (1).

The response returns the saved search reference object the with following fields:

  • ArtifactID - the Artifact ID of the copy.
  • Name - the name of the copy.
{
    "ArtifactID": 1041178,
    "Name": "Jones Case Documents (1)"
}

Helper operations

The Analytics Search Manager Service provides the following helper operations for retrieving search properties:

GetEmailToLinkUrlAsync

The Analytics Search Manager Service URL for retrieving an email link to analytics search results:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetEmailToLinkUrlAsync

The request must include the workspace ID and the search artifact ID.

{
  "workspaceArtifactID": 1030160,
  "searchArtifactID": 1039106
}

The response is the string value of the email link.

"mailto:?subject=Relativity%20Review%20-%20Integration%20Tests%20-%20My%20New%20Analytics%20Search%20With%20Two%20Conditions&body=http%3a%2f%2fmyhost%2frelativity%2fsearchlink.aspx%3fSelectedSearchArtifactID%3d1039106%26AppID%3d1275015"

GetFieldsForCriteriaConditionAsync

The Analytics Search Manager Service URL for retrieving all workspace fields available to the user that can be included in a saved search conditions criteria:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetFieldsForCriteriaConditionAsync

The request must include the workspace ID and the search artifact type ID.

{
  "workspaceArtifactID": 1275015,
  "artifactTypeID": 10
}

Note: Currently only Document can be specified as the artifact type.

The response is a collection of Field objects.

GetFieldsForObjectCriteriaCollectionAsync

The Analytics Search Manager Service URL for retrieving all workspace fields available to the user that can be specified as a subcondition for a given field in batch and multi-object field conditions.

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetFieldsForObjectCriteriaCollectionAsync

The request must include the workspace ID, a multi-object Field, and the search artifact type ID.

{
  "workspaceArtifactID": 1275015,
   "field":{"Name": "Batch"},
  "artifactTypeID": 10
}

The response is a collection of Field objects.

[
  {
    "ArtifactID": 1035250,
    "ViewFieldID": 1000422,
    "Guids": [
      "d7a9d9fd-68fc-4c85-ad44-ba524a0ca872"
    ],
    "Name": "Batch"
  },
  {
    "ArtifactID": 1035251,
    "ViewFieldID": 1000423,
    "Guids": [
      "8c3ea95d-6c72-4463-8696-1b6859c0e00e"
    ],
    "Name": "Batch::Batch Set"
  },
  {
    "ArtifactID": 1035252,
    "ViewFieldID": 1000424,
    "Guids": [
      "3e62303c-b955-4a93-b82a-894ce40b5563"
    ],
    "Name": "Batch::Assigned To"
  },
  {
    "ArtifactID": 1035253,
    "ViewFieldID": 1000425,
    "Guids": [
      "70e1751f-4f6b-4c1d-abd7-8a6328750175"
    ],
    "Name": "Batch::Status"
  }
]

GetFieldsForSearchResultViewAsync

The Analytics Search Manager Service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetFieldsForSearchResultViewAsync

If the request includes the workspace ID and the artifact type ID, the service returns all workspace fields available to the user as a collection of Field objects in the FieldsNotIncluded property.

{
  "workspaceArtifactID": 1030160,
  "artifactTypeID": 10
}

If the request includes the workspace ID, the artifact type ID, and the Artifact ID of an analytics saved search, the service returns the fields included in the specified search as a collection of Field objects in the FieldsIncluded property. Workspace fields available to be included in the search are returned in the FieldsNotIncluded property.

{
  "workspaceArtifactID": 1030160,
  "artifactTypeID": 10,
  "searchArtifactID": 1039076
}

GetSearchIncludesAsync

To return all relational fields available to the user in the workspace, use this Analytics Search Manager Service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetSearchIncludesAsync

The request must include a workspace ID.

{
  "workspaceArtifactID": 1030160
}

The response includes a collection of Field objects.

[
  {
    "ArtifactID": 0,
    "ViewFieldID": 0,
    "Guids": [],
    "Name": ""
  },
  {
    "ArtifactID": 1035456,
    "ViewFieldID": 1000643,
    "Guids": [
      "14ffb8be-42d1-419e-b72c-645484a78a83"
    ],
    "Name": "Include Conversation Family"
  },
  {
    "ArtifactID": 1003669,
    "ViewFieldID": 1000188,
    "Guids": [
      "a426bc5e-3420-47b4-a293-4c4848a237d7"
    ],
    "Name": "Include Duplicates"
  },
  {
    "ArtifactID": 1036396,
    "ViewFieldID": 1000671,
    "Guids": [
      "c0aa4323-45d5-4db3-bf00-71094792901b"
    ],
    "Name": "Include Emailset"
  },
  {
    "ArtifactID": 1036394,
    "ViewFieldID": 1000670,
    "Guids": [
      "ff4e3c74-d1e0-4c0c-bb58-b50dd7ee8dfa"
    ],
    "Name": "Include EquiSet"
  },
  {
    "ArtifactID": 1003671,
    "ViewFieldID": 1000190,
    "Guids": [
      "1f036749-a691-4aa8-8cf7-5eeb80c36caf"
    ],
    "Name": "Include Family"
  }
]

GetSearchIndexesAsync

To return all analytics indexes available to the user for a given workspace, use this Analytics Search Manager Service URL:

/Relativity.REST/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetSearchIndexesAsync

The request must include a workspace ID.

{
  "workspaceArtifactID": 1030160
}

The response includes a collection of index objects.

[
  {
    "ArtifactID": 1038684,
    "Name": "Salt vs Pepper case index"
  },
  {
    "ArtifactID": 1039332,
    "Name": "Oil and gas correspondence index"
  }
]

GetSearchOwnersAsync

To return all users in the workspace with permissions to view saved searches, use this Analytics Search Manager Service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetSearchIncludesAsync

The request must include a workspace ID.

{
  "workspaceArtifactID": 1030160
}

The response includes a collection of User objects.

[
  {
    "ArtifactID": 0,
    "Name": "Public, Joe"
  },
  {
    "ArtifactID": 9,
    "Name": "Admin, Relativity"
  },
  {
    "ArtifactID": 1000000392,
    "Name": "Admin, Relativity"
  },
  {
    "ArtifactID": 1271248,
    "Name": "Doe, Jane"
  }
]

GetAccessStatusAsync

The GetAccessStatusAsync endpoint returns the information about the user‘s ability to access the saved search.

To return the access status, use this Analytics Search Manager Service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Analytics%20Search%20Manager/GetAccessStatusAsync

The request must include these fields:

  • workspaceArtifactID – the Artifact ID for the workspace where the search resides.
  • artifactID – the Artifact ID of the search.
  • ancestorArtifactIDs – a collection of Artifact IDs representing the folder path where the search resides.
{
    "workspaceArtifactID": 1015024,
    "artifactID": 1038050,
    "ancestorArtifactIDs":[1036361, 1035243]        
}

The response returns an access status object with the following fields:

  • Exists – indicates whether the search exists relative to the specified folder path.
  • CanView – indicates whether the user has view permissions to the search.
  • CanAccessSearchProvider – indicates whether the user has view permissions to the search provider used in the search.
  • CanViewCriteriaFields – indicates whether the user has view permissions to all of the fields used in the search.
{
    "Exists": true,
    "CanView": true,
    "CanAccessSearchProvider": false,
    "CanViewCriteriaFields": false
}

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.