Through the REST API, the Agent Manager service exposes multiple endpoints that you can use to programmatically manage agents in your Relativity environment. It includes the following features:
Sample use cases for the Agent Manager service include:
The Relativity Services API supports the same functionality for this service as available through the REST API. For more information, see Agent Manager (.NET).
Note: To implement your own custom agents, use the Agents API. For more information, see Agents (background processing).
This page contains the following information:
You can use the Postman sample file to become familiar with making calls to endpoints on the Agent Manager service. To download the sample file, click Agent Manager Postman file.
To get started with Postman, complete these steps:
To use the Agent 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.agents/workspace/-1/agents
Note: For the workspace identifier in the URL, use -1 to indicate the admin-level context. This value is required for all URLs in the Agent Manager service. For additional guidelines, see Agent Manager (.NET).
You can use the following .NET code as a sample client for creating an agent. This code illustrates how to perform the following tasks:
public async Task<int?> RetrieveArtifactViewFieldIdExample() { 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/"); var agentTypeId = 1015253; var agentServerId = 1016892; string inputJSON = $"{{\"AgentRequest\":{{ \"AgentType\": {{ \"Secured\": false, \"Value\": {{ \"ArtifactID\": \"{agentTypeId}\" }} }}, \"AgentServer\": {{ \"Secured\": false, \"Value\": {{ \"ArtifactID\": \"{agentServerId}\" }} }}, \"Enabled\": true, \"Interval\": 10, \"LoggingLevel\": 1, \"Keywords\": \"keywords\", \"Notes\": \"notes\" }} }}"; var url = "/Relativity.REST/API/Relativity.Agents/workspace/-1/agents/"; 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; }
Relativity supports a variety of agent types used for productions, OCR, Analytics, and other purposes. In addition, you can also implement custom agent types to meet the needs of your users. For more information, see Agents on the Relativity Documentation site.
To retrieve a list of agent types available in a Relativity instance, send a GET request to the following URL:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agenttypes/
The request body is empty.
The response contains the following fields for each agent type returned in the array:
[ { "ApplicationName": "Default", "CompanyName": "Relativity ODA LLC", "DefaultInterval": 3600, "DefaultLoggingLevel": 1, "ArtifactID": 1015242, "Name": "Case Manager" }, { "ApplicationName": "Default", "CompanyName": "Relativity ODA LLC", "DefaultInterval": 3600, "DefaultLoggingLevel": 1, "ArtifactID": 1015243, "Name": "File Deletion Manager" }, { "ApplicationName": "Default", "CompanyName": "Relativity ODA LLC", "DefaultInterval": 3600, "DefaultLoggingLevel": 1, "ArtifactID": 1015244, "Name": "Case Statistics Manager" }, ... ]
You can retrieve a list of all agent servers in a Relativity environment. However, if you want information about servers where you can add a specific agent type, see Retrieve servers compatible with a specific agent type.
To retrieve a list of agent servers, send a GET request to the following URL:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agentservers
The request body is empty.
The response contains the following fields for each server returned in the array:
[ { "Type": "Agent", "ProcessorCores": 4, "NumberOfAgents": 46, "ArtifactID": 1016922, "Name": "Agent Server One" }, { "Type": "Agent", "ProcessorCores": 4, "NumberOfAgents": 34, "ArtifactID": 1016923, "Name": "Agent Server Two" }, { "Type": "Agent", "ProcessorCores": 4, "NumberOfAgents": 37, "ArtifactID": 1016924, "Name": "Agent Server Three" }, { "Type": "Web Background Processing", "ProcessorCores": 8, "NumberOfAgents": 3, "ArtifactID": 1016925, "Name": "Web Background One" }, { "Type": "Web Background Processing", "ProcessorCores": 8, "NumberOfAgents": 3, "ArtifactID": 1016926, "Name": "Web Background Two" } ]
You can retrieve a list of servers compatible with a specific agent type that you want to add to Relativity. However, if you want a list of all agent servers in your environment, see Retrieve a list of agent servers.
To retrieve a list of agent servers compatible with an agent type, send a GET request to the following URL:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agenttypes/{{AgentTypeID}}/availableagentservers
Set the {{AgentTypeID}} variable to the Artifact ID of the agent type.
The body of the request is empty.
The response contains the following fields for each server returned in the array:
[ { "Type": "Agent", "ProcessorCores": 4, "NumberOfAgents": 46, "ArtifactID": 1016922, "Name": "Agent Server One" }, { "Type": "Agent", "ProcessorCores": 4, "NumberOfAgents": 34, "ArtifactID": 1016923, "Name": "Agent Server Two" }, { "Type": "Agent", "ProcessorCores": 4, "NumberOfAgents": 38, "ArtifactID": 1016924, "Name": "Agent Server Three" } ]
Before creating an agent, you need to identify the agent type and a compatible server, and perform a validation check. For more information, see Sample workflow for adding agents.
To add a new agent to a Relativity environment, send a POST request to this URL:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/
The body of the request must contain the following fields unless specifically identified as optional:
{ "AgentRequest":{ "AgentType":{ "Secured":false, "Value":{ "ArtifactID":"1015277" } }, "AgentServer":{ "Secured":false, "Value":{ "ArtifactID":"1016924" } }, "Enabled":true, "Interval":3600, "LoggingLevel":1, "Keywords":"", "Notes":"" }, "count":5 }
When the request is successful, the response contains the Artifact ID of the new agent, such as 2017104
You can retrieve basic information about an agent or extended information, which also includes operations that you have permissions to perform on the agent.
<host>/relativity.rest/api/relativity.agents/workspace/-1/agents/{{Agent ID}}
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/{{Agent ID}}/true/true
For both requests, set the {{Agent ID}} variable to the Artifact ID of the agent that you want to read, and leave the bodies of the requests empty.
{ "AgentType": { "Secured": false, "Value": { "ArtifactID": 1015277, "Name": "Application Installation Manager" } }, "AgentServer": { "Secured": false, "Value": { "ArtifactID": 1016924, "Name": "SS010AGT000001" } }, "Enabled": true, "Interval": 3600, "LastUpdate": "2018-09-14T21:52:32.753", "LoggingLevel": 1, "Message": "Completed.", "DetailMessage": "", "EventLevel": "Informational", "CreatedOn": "2018-09-14T21:28:11.947", "CreatedBy": { "ArtifactID": 1023652, "Name": "Doe, Jane" }, "LastModifiedBy": { "ArtifactID": 1023652, "Name": "Doe, Jane" }, "LastModifiedOn": "2018-09-14T21:28:11.947", "Keywords": "", "Notes": "", "Actions": [], "ArtifactID": 2017104, "Name": "Application Installation Manager (7)" }
{ "AgentType": { "Secured": false, "Value": { "ArtifactID": 1015277, "Name": "Application Installation Manager" } }, "AgentServer": { "Secured": false, "Value": { "ArtifactID": 1016924, "Name": "SS010AGT000001" } }, "Enabled": true, "Interval": 3600, "LastUpdate": "2018-09-14T21:59:04.42", "LoggingLevel": 1, "Message": "Completed.", "DetailMessage": "", "EventLevel": "Informational", "CreatedOn": "2018-09-14T21:28:11.947", "CreatedBy": { "ArtifactID": 1023652, "Name": "Doe, Jane" }, "LastModifiedBy": { "ArtifactID": 1023652, "Name": "Doe, Jane" }, "LastModifiedOn": "2018-09-14T21:28:11.947", "Keywords": "", "Notes": "", "Meta": { "Unsupported": [], "ReadOnly": [ "Name", "AgentType" ] }, "Actions": [ { "Name": "Delete", "Href": "Relativity.Agents/workspace/-1/agents/2017104", "Verb": "DELETE", "IsAvailable": true, "Reason": [] }, { "Name": "Update", "Href": "Relativity.Agents/workspace/-1/agents/2017104", "Verb": "PUT", "IsAvailable": true, "Reason": [] } ], "ArtifactID": 2017104, "Name": "Application Installation Manager (7)" }
You can modify the properties of an agent, such as its run intervals, enabled property, and others. Additionally, you can also restrict the update of an agent to the date that it was last modified by adding the LastModifiedOn field to the request.
To update the properties of an agent, send a PUT request to a URL with the following general format:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/{{Agent ID}}
Set the {{Agent ID}} variable to the Artifact ID of the agent that you want to update.
The request must contain the following fields unless specifically identified as optional:
{ "AgentRequest":{ "AgentType":{ "Secured":true, "Value":{ } }, "AgentServer":{ "Secured":true, "Value":{ } }, "Enabled":false, "Interval":3600, "LoggingLevel":1, "Keywords":"", "Notes":"" }, "LastModifiedOn":"2018-10-19T18:41:20.54" }
When the agent is successfully updated, the response returns the status code of 200.
You can programmatically remove an agent from Relativity after it has finished executing, or you can remove it immediately by forcefully deleting it. When you forcefully delete an agent, the system doesn't wait for it to finish executing. In general, use a force delete when an agent has become unresponsive.
To remove an agent from Relativity after it has finished executing, send a DELETE request to a URL with the following general format:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/{{ToDelete}}
Set the {{ToDelete}} variable to the Artifact ID of the agent that you want to delete.
The body of the request is empty. When the agent is successfully deleted, the response returns the status code of 200.
To remove an agent from Relativity immediately, send a DELETE request to a URL with the following general format:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/{{ToDelete}}
Set the {{ToDelete}} variable to the Artifact ID of the agent. In the body of the request, set the force field to true.
{ "force" : true }
When the agent is successfully deleted, the response returns the status code of 200.
Before you attempt to add, update, or delete an agent, you can perform a check to verify the success of the operation. For detailed information, see Validation and compatibility checks.
Review the following information about agent validation:
To verify that you can add an agent to a Relativity environment or server, send a POST request to the following URL:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/validateinstancelimits
The request must contain the following fields unless specifically identified as optional:
{ "AgentRequest" : { "AgentType": { "Secured": false, "Value": { "ArtifactID": "1015277" } }, "AgentServer": { "Secured": false, "Value": { "ArtifactID": "1016924" } }, "Enabled": true, "Interval": 3600, "LoggingLevel": 1, "Keywords": "", "Notes": "" }, "count" : 1 }
If you can successfully add the agent, the response returns the status code of 200. Also, see Failed validation responses.
To confirm that you can update the properties of an agent, send a POST request to a URL with the following general format:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/{{Agent ID}}/validateinstancelimits
Set the {{Agent ID}} variable to the Artifact ID of the agent.
The request must contain the following fields unless specifically identified as optional:
{ "AgentRequest" : { "AgentType": { "Secured": true, "Value": { } }, "AgentServer": { "Secured": true, "Value": { } }, "Enabled": false, "Interval": 3600, "LoggingLevel": 1, "Keywords": "", "Notes": "" } }
If you can successfully update the agent, the response returns the status code of 200. Also, see Failed validation responses.
To verify that you can delete an agent, send a DELETE request to a URL with the following general format:
<host>/Relativity.rest/api/relativity.agents/workspace/-1/agents/{{Agent ID}}/validateinstancelimits
Set the {{Agent ID}} variable to the Artifact ID of the agent.
The body of the request is empty. If you can successfully delete the agent, the response returns the status code of 200. Also, see Failed validation responses.
When a validation check fails, the response varies depending on the reason for the failure. The AgentInstanceLimit enumeration contains constants that identify the reason for a failed validation check:
The following examples illustrate possible JSON responses for validation checks:
{ "Limit":"MaxPerEnvironment" }
{ "Limit":"MinPerServer", "AgentServer":{ "Secured":false, "Value":{ "ArtifactID":"1016892", "Name":"Agent Server One" } } }
For more information, see the AgentInstanceLimit enumeration in the Relativity.Services.Interfaces.Agent.Models namespace in the Class library reference.
Community Updates |
|||
Aero Developer FAQ | Evolving the Platform | Most recent release notes | |
Learn more | Learn more | Learn more |
Additional Resources |
|||
![]() |
![]() |
||
Access Third-Party Tools with GitHub | Create .NET Apps Faster with NuGet | ||
Visit github | visit nuget |