Clients in Relativity are associated with one or more matters. Matters are used to define the different cases, disputes, or advising that a firm may be involved with for a client. Within Relativity, a matter must be associated with an existing client. A matter can also be associated with one or more workspaces, but it's not required. For more information, see Matters on the Relativity Documentation site.
The Services API supports the create, read, update, delete, and query operations on Matter DTOs. You can perform the operations on Matter DTOs asynchronously. Note that asynchronous operations return a standard .NET System.Threading.Tasks.Task<TResult> object that can be used to monitor progress and interact with the process.
You can also interact with the Matter objects using the Relativity REST API.
Complete code samples of operations on the Matter objects are included in the APISamples.sln solution in the Relativity SDK.
kCura.Relativity.Client.SamplesLibrary.CS\ServiceHost\Matter.cs
For more information, see Relativity SDK samples.
This page contains the following information:
Create a Matter
You can create a Matter asynchronously using the CreateSingleAsync() method of the IMatterManager interface. Note the use of the ChoiceRef class to set the value of the Status property of the Matter.
public static async Task<bool> CreateMatterAsync(IMatterManager proxy, int clientID)
{
bool success = false;
//Create the Matter Object
Matter newMatter = new Matter();
newMatter.Name = "Matter Name";
newMatter.Number = "7654321";
//Find choice values for matter status
List<ChoiceRef> choiceRefs = await proxy.GetStatusChoicesForMatterAsync();
ChoiceRef activeChoice = choiceRefs.Find(x => x.Name == "Active");
ChoiceRef matterStatus = activeChoice;
newMatter.Status = matterStatus;
newMatter.Client = new ClientRef(clientID);
try
{
int successCreate = await proxy.CreateSingleAsync(newMatter);
if (successCreate != 0)
{
success = true;
Console.WriteLine("Created Matter: {0}", newMatter.Name);
}
else
{
Console.WriteLine("Failed to create matter!");
}
}
catch (Exception e)
{
Console.WriteLine(e);
}
return success;
}
Read a Matter
The following code sample illustrates how to read a Matter DTO using the ReadSingleAsync() method of the IMatterManager interface.
public static async Task<bool> ReadMatterAsync(IMatterManager proxy, int matterID)
{
bool success = false;
try
{
Console.WriteLine($"Reading for Matter: {matterID}...");
var readMatter = await proxy.ReadSingleAsync(matterID);
Console.WriteLine("Matter Client: {0} \r\nMatter Name: {1} \r\nMatter ID: {2} ", readMatter.Client.Name, readMatter.Name, readMatter.ArtifactID);
success = true;
}
catch (Exception e)
{
Console.WriteLine(e);
}
return success;
}
Update a Matter
The following code sample illustrates how to update a Matter using the UpdateSingleAsync() method of the IMatterManager interface.
public static async Task<bool> UpdateSingleMatterAsync(IMatterManager proxy, int matterID, int clientID)
{
bool success = false;
//Create a Matter object and assign it's properties
Matter newMatter = new Matter();
newMatter.ArtifactID = matterID;
newMatter.Name = "UPDATED NAME VALUE";
newMatter.Number = "UPDATED NUMBER VALUE";
//Find choice values for Matter status in your environment
List<ChoiceRef> choiceRefs = await proxy.GetStatusChoicesForMatterAsync();
ChoiceRef activeChoice = choiceRefs.Find(x => x.Name == "Inactive");
ChoiceRef matterStatus = activeChoice;
newMatter.Status = matterStatus;
//Create the Client object that is associated with the Matter
newMatter.Client = new ClientRef(clientID);
//Perform the Matter update
try
{
await proxy.UpdateSingleAsync(newMatter);
success = true;
Console.WriteLine("Successfully updated {0}", newMatter.Name);
}
catch (Exception e)
{
Console.WriteLine(e);
}
return success;
}
Delete a Matter
You can delete Matters asynchronously by using the DeleteSingleAsync() method of the IMatterManager interface. The following code sample illustrates how to delete a Matter.
public static async Task<bool> DeleteMatterAsync(IMatterManager proxy, int matterID)
{
bool success = false;
try
{
Console.WriteLine($"Deleting Matter: {matterID}...");
try
{
await proxy.DeleteSingleAsync(matterID);
Console.WriteLine("Successfully deleted MatterID: {0}", matterID);
success = true;
}
catch (Exception ex)
{
Console.WriteLine("Failed to delete {0} \r\n" + ex.Message, matterID);
}
}
catch (Exception e)
{
Console.WriteLine(e);
}
return success;
}
Query Matters
The following code sample illustrates how to query Matter DTOs using the QueryAsync() and QuerySubsetAsync() methods of the IMatterManager interface. The query condition checks if the matter name starts with the string "API". The results are sorted by ArtifactID in descending order. If the query returns a token value that is not null, more results are available than initially specified in the length property (5 in this example), and they are subsequently retrieved by using the QuerySubsetAsync() method. 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 PDVDefaultQueryCacheSize of 10000. For more information about query conditions and using query tokens, see Search Relativity.
public static async Task<bool> QueryMatterAsync(IMatterManager proxy)
{
bool success = false;
//Create the Query & Condition
WholeNumberCondition queryCondition = new WholeNumberCondition("ArtifactID", NumericConditionEnum.IsSet);
Relativity.Services.Query matterQuery = new Query();
matterQuery.Condition = queryCondition.ToQueryString();
try
{
Console.WriteLine("Querying Matters...");
try
{
MatterQueryResultSet queryResultSet = await proxy.QueryAsync(matterQuery);
foreach (Result<Matter> singleMatter in queryResultSet.Results)
{
var singleMatterArtifact = singleMatter.Artifact;
Console.WriteLine("Matter Name: {0} - {1} \r\nMatter Number: {2} \r\nMatter Client: {3} \r\nMatter Notes: {4}\r\n",
singleMatterArtifact.Name, singleMatterArtifact.ArtifactID, singleMatterArtifact.Number,
singleMatterArtifact.Client.Name, singleMatterArtifact.Notes);
}
success = true;
}
catch (Exception ex)
{
Console.WriteLine("Failed to query {0} \r\n", ex.Message);
}
}
catch (Exception e)
{
Console.WriteLine(e);
}
return success;
}
Helper methods
IMatterManager interface provides the GetClientsForMatterAsync() and GetStatusChoicesForMatterAsync() helper methods to easily populate the Client and Status properties.
GetClientsForMatterAsync()
The following code sample illustrates how to use GetClientsForMatterAsync() to return all clients available to the user:
public static async Task<bool> GetClientsForMatterAsync(IMatterManager proxy)
{
bool success = false;
List<ClientRef> clientRefs = await proxy.GetClientsForMatterAsync();
foreach (ClientRef client in clientRefs)
{
string message = string.Format("{0} - {1}", client.ArtifactID, client.Name);
Console.WriteLine(message);
}
success = true;
return success;
}
For additional code samples of using GetClientsForMatterAsync(), see Create a matter and Update a matter.
GetStatusChoicesForMatterAsync()
The following code sample illustrates how to use GetStatusChoicesForMatterAsync() to return all status choices for the Matter:
public static async Task<bool> GetStatusChoicesForMatterAsync(IMatterManager proxy)
{
bool success = false;
//This call will return all available status choices for matters
List<ChoiceRef> choices = await proxy.GetStatusChoicesForMatterAsync();
foreach (ChoiceRef choice in choices)
{
Console.WriteLine("{0} - {1}", choice.ArtifactID, choice.Name);
}
success = true;
return success;
}
For additional code samples of using GetStatusChoicesForClientAsync(), see Create a matter and Update a matter.
