Agent Manager service

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 API.

Note: To implement your own custom agents, use the Agents API. For more information, see Build agents.

This page contains the following information:

Postman sample file

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:

  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 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 API.

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

Retrieve a list of agent types

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:

Retrieve a list of agent servers

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:

Retrieve servers compatible with a specific agent type

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"
    }
]

Create an agent

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, or it contains a list of Artifacts for multiple agents. It also returns the status code of 200.

Retrieve metadata for an agent

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

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.

Update the properties of an agent

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.

Delete an agent

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.

Delete an agent

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.

Forcefully delete an agent

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.

Validate a create, update, or delete operation

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:

Validate a create operation

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.

Validate an update operation

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.

Validate a delete operation

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.

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:

For more information, see the AgentInstanceLimit enumeration in the Relativity.Services.Interfaces.Agent.Models namespace in the Relativity API 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