Relativity Services API (RSAPI) DTOs have been deprecated and are no longer supported. For more information and alternative APIs, see RSAPI deprecation process.
Relativity uses fields to store object information, document metadata, and coding choices. For more information, see Fields on the Relativity Documentation site.
The Services API supports create, read, delete, and query operations on a Field DTO.
Note: You can also create, read, and delete fields using the single-artifact access methods common to all Relativity DTOs. For more information, see Single-artifact access.
This page contains the following information:
Create a Field
You can use the Create() on the Field repository to add a new field to Relativity. The ObjectType indicates the object associated with this Field, such as Document as illustrated in this sample code.
public static bool Create_Field_Using_Repository(IRSAPIClient proxy)
{
proxy.APIOptions.WorkspaceID = 1016204;
// STEP 1: Create a Field DTO and populate the Fields.
DTOs.Field dto = new DTOs.Field();
dto.Name = "This is a Single Choice field by GUID11";
dto.ObjectType = new DTOs.ObjectType() { DescriptorArtifactTypeID = (int)ArtifactType.Document };
// The ObjectType DTO can also be instantiated with the GUID of the
// ObjectType instead of setting the DescriptorArtifactTypeID.
// dto.ObjectType = new DTOs.ObjectType(new Guid("4D3BA67C-9F88-4D29-8E6C-6DECB6A682D1"));
dto.FieldTypeID = kCura.Relativity.Client.FieldType.SingleChoice;
dto.IsRequired = false;
dto.Unicode = false;
dto.AvailableInFieldTree = false;
dto.OpenToAssociations = false;
dto.Linked = false;
dto.AllowSortTally = true;
dto.Wrapping = true;
dto.AllowGroupBy = false;
dto.AllowPivot = false;
dto.IgnoreWarnings = true;
dto.Width = "";
// STEP 2: Call the Create method on the repository and pass the DTO.
WriteResultSet<DTOs.Field> resultSet;
try {
resultSet = proxy.Repositories.Field.Create(dto);
}
catch (Exception ex) {
Console.WriteLine("Error: " + ex.Message);
return false;
}
if (!resultSet.Success) {
Console.WriteLine("Error: " + resultSet.Message);
foreach (Result<DTOs.Field> result in resultSet.Results) {
Console.WriteLine("Result Error: " + result.Message);
}
return false;
}
Console.WriteLine("Overall status of creating a Field: " + resultSet.Success);
Console.WriteLine("New Artifact ID: " + resultSet.Results.FirstOrDefault().Artifact.ArtifactID);
return true;
}
Note: Field properties are set depending on the field type. For example, you can't set the Unicode and AvailableInFieldTree properties as shown in the example if you are creating a single-object field or multi-object field. For more information, see Field properties.
Create a Relational Field
In Relativity, a relational field is used to identify a group of related documents. You can upload your own icon for a relational field, which is displayed in the Related Items pane of the reviewer interface. For more information, see PaneIcon property.
This code sample illustrates how to create a relational Field and set its pane icon.
public void Create_RelationalField()
{
try
{
using (IRSAPIClient proxy =
new RSAPIClient(new Uri("net.pipe://localhost/Relativity.Services"), new IntegratedAuthCredentials()))
{
proxy.APIOptions.WorkspaceID = WORKSPACE_ID;
var fieldDTO = new kCura.Relativity.Client.DTOs.Field();
fieldDTO.Name = "Relational Field 1";
fieldDTO.FieldTypeID = (Int32)FieldType.FixedLengthText;
fieldDTO.ObjectType = new kCura.Relativity.Client.DTOs.ObjectType() { DescriptorArtifactTypeID = (Int32)ArtifactType.Document };
fieldDTO.Length = 100;
fieldDTO.IsRequired = false;
fieldDTO.IncludeInTextIndex = false;
fieldDTO.Unicode = false;
fieldDTO.AllowHTML = false;
fieldDTO.OpenToAssociations = false;
fieldDTO.Linked = false;
fieldDTO.AllowSortTally = false;
fieldDTO.Width = "100";
fieldDTO.Wrapping = false;
fieldDTO.AllowPivot = false;
fieldDTO.AllowGroupBy = false;
// Set IsRelational to true.
fieldDTO.IsRelational = true;
// After IsRelational is set to true, add other required fields.
fieldDTO.FriendlyName = "New Relational Field Friendly Name";
fieldDTO.Order = 100;
fieldDTO.ImportBehavior = ImportBehavior.LeaveBlankValuesUnchanged;
fieldDTO.RelationalView = null; //Null is the default "All Items" view.
// The field "PaneIcon" takes a RelationalFieldIcon object that contains a path and a byte array
// for the icon that represents the field at the bottom of the document review page.
string path = "c:\\icon.png";
System.IO.FileStream ifStream = System.IO.File.OpenRead(path);
Int32 len = (Int32)ifStream.Length;
System.IO.BinaryReader reader = new System.IO.BinaryReader(ifStream);
byte[] byteArr = new byte[len];
reader.Read(byteArr, 0, len);
fieldDTO.PaneIcon = new RelationalFieldIcon(path, byteArr);
WriteResultSet<kCura.Relativity.Client.DTOs.Field> writeResults =
proxy.Repositories.Field.Create(fieldDTO);
if (writeResults.Success)
{
Console.WriteLine(string.Format("Field with name {0} was created with Artifact ID {1}.", fieldDTO.Name, writeResults.Results[0].Artifact.ArtifactID));
}
else
{
Console.WriteLine(string.Format("An error occurred creating field: {0}", writeResults.Message));
for (Int32 i = 0; i <= writeResults.Results.Count - 1; i++)
{
if (!writeResults.Results[i].Success)
{
Console.WriteLine(String.Format("An error occurred in create request {0}: {1}", i, writeResults.Results[i].Message));
foreach (string warning in writeResults.Results[0].WarningMessages)
{
Console.WriteLine("Warning: {0}", warning);
}
}
}
}
}
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
}
}
Read a Field
To read values on a Field, you can use the Read() method on the Field repository as illustrated in this code sample.
public static bool Read_Field_Using_Repository(IRSAPIClient proxy)
{
proxy.APIOptions.WorkspaceID = 1016204;
// STEP 1: Call the Read() method on the Field repository, passing a Field DTO.
ResultSet<DTOs.Field> results;
try {
results = proxy.Repositories.Field.Read(new DTOs.Field(1035984) { Fields = FieldValue.AllFields });
}
catch (Exception ex) {
Console.WriteLine("Error: " + ex.Message);
return false;
}
if (!results.Success) {
Console.WriteLine("Error: " + results.Message);
foreach (Result<DTOs.Field> result in results.Results) {
Console.WriteLine("Result Error: " + result.Message);
}
return false;
}
// STEP 2: Get the Field artifact from the read results.
DTOs.Field fieldArtifact = results.Results.FirstOrDefault().Artifact;
Console.WriteLine("Field Name: " + fieldArtifact.Name);
Console.WriteLine("Field Type: " + fieldArtifact.FieldTypeID);
Console.WriteLine("Object Type: " + fieldArtifact.ObjectType.DescriptorArtifactTypeID);
foreach (DTOs.Choice choice in fieldArtifact.Choices)
Console.WriteLine("Valid Choice for Field = " + choice.Name + ":" + choice.ArtifactID );
return true;
}
Delete a Field
You can use the Delete() method on the Field repository to remove fields as illustrated in this code sample.
public static bool Delete_Field_Using_Repository(IRSAPIClient proxy)
{
proxy.APIOptions.WorkspaceID = 1016204;
// STEP 1: Define the Field to delete.
kCura.Relativity.Client.DTOs.Field dto = new kCura.Relativity.Client.DTOs.Field(1039140);
ResultSet<kCura.Relativity.Client.DTOs.Field> results;
// STEP 2: Delete the Field.
try
{
results = proxy.Repositories.Field.Delete(dto);
}
catch (Exception ex)
{
Console.WriteLine("Error: " + ex.Message);
return false;
}
if (!results.Success)
{
Console.WriteLine("Error: " + results.Message);
foreach (Result<kCura.Relativity.Client.DTOs.Field> result in results.Results)
{
Console.WriteLine("Result Error: " + result.Message);
}
return false;
}
return true;
}
Query for a Field
This code sample illustrates how to set query conditions, call the Query() method on the Field repository, and iterate through the result set. For more information, see Search Relativity.
public static bool Query_Field_Using_Repository(IRSAPIClient proxy)
{
proxy.APIOptions.WorkspaceID = 1016204;
// STEP 1: Define the query.
Query<kCura.Relativity.Client.DTOs.Field> query = new Query<kCura.Relativity.Client.DTOs.Field>();
query.Fields = FieldValue.AllFields;
query.Condition =
new WholeNumberCondition(ArtifactQueryFieldNames.ArtifactID, NumericConditionEnum.EqualTo, 1039140);
ResultSet<kCura.Relativity.Client.DTOs.Field> results;
// STEP 2: Query for the Field.
try
{
results = proxy.Repositories.Field.Query(query);
}
catch (Exception ex)
{
Console.WriteLine("Error: " + ex.Message);
return false;
}
if (!results.Success)
{
Console.WriteLine("Error: " + results.Message);
foreach (Result<kCura.Relativity.Client.DTOs.Field> result in results.Results)
{
Console.WriteLine("Result Error: " + result.Message);
}
return false;
}
// STEP 3: Get the Field artifact from the read results.
kCura.Relativity.Client.DTOs.Field fieldArtifact = results.Results.FirstOrDefault().Artifact;
Console.WriteLine("Field Name: " + fieldArtifact.Name);
Console.WriteLine("Field Type: " + fieldArtifact.FieldTypeID);
Console.WriteLine("Object Type: " + fieldArtifact.ObjectType.DescriptorArtifactTypeID);
foreach (kCura.Relativity.Client.DTOs.Choice choice in fieldArtifact.Choices)
Console.WriteLine("Valid Choice for Field = " + choice.Name + ":" + choice.ArtifactID);
return true;
}
