This DTO has been deprecated as part of the Relativity Services API (RSAPI) Deprecation and is no longer supported. For more information and alternative APIs, see RSAPI deprecation process.

Field

Relativity uses Fields to store document and other metadata, as well as coding selections made by a reviewer. It provides multiple Field types to support this functionality, which are also available through the Services API.

This page contains the following information:

See these related pages:

System type fields

System type fields are properties on the base Artifact class. Each DTO type has the following consistent set of base properties returned on the Artifact:

  • ArtifactID
  • ArtifactTypeID
  • ArtifactTypeName
  • ArtifactTypeGuids
  • Guids
  • ParentArtifact
  • SystemCreatedBy
  • SystemCreatedOn
  • SystemLastModifiedBy
  • SystemLastModifiedOn

TextIdentifier property on DTOs

Except for the Error DTO, all other DTOs have a TextIdentifier property that displays the Identifier field of an object. For example, TextIdentifier equals the Name field on instances of Relativity Dynamic Objects RDOs. You can use it in place of the Name property on RDOs. If you set both the TextIdentifier and Name properties during object creation, their values must be equal or you receive an error message.

Use the constant kCura.Relativity.Client.Constants.RELATIVITY_TEXT_IDENTIFIER to reference the Relativity Text Identifier field.

Use of system type fields

Since system type Fields don't have IDs, you must request them by name. Certain Fields have both a display name used in the Relativity web UI, and an SQL column name used to reference the Field in the database. For example, Field has a property with the display name Created By that contains a username as a String, and an SQL column name of CreatedByName. Another property on Field has no display name, but an SQL column name of CreatedBy, which returns the user’s ID.

You can use either name when requesting Fields during a read or query operation. The Services API returns the Field using the name referenced in your request. If you don't specify any Fields in a request, the API returns all Fields using the display names when they exist and the SQL names when no display names are available.

You can also set the StrictMode to maintain consistency on the Fields returned by the Services API, and field directives to indicate when you want all or no Fields returned.

Field types

The Services API supports several Field types that you can use on DTOs, including fixed-length text, single and multiple choice, single and multiple object, and others.

FixedLengthText and LongText fields

The fixed-length text field type is a text field with a limited length.

  • The field size defaults to 255 characters.
  • Fixed-length text types allow for a maximum of 4,999 characters, but Unicode enabled fixed-length text fields cannot exceed 4,000 characters.
  • The sum of all fixed-length text fields for any individual object should be no larger than 8,060 bytes.

For DTOs, text fields are set and returned as Strings.

SingleChoice fields

In Relativity, a SingleChoice field has a predetermined set of values called choices. A user can only select one of these choices for coding or other purposes. Use these guidelines for SingleChoice fields:

  • Create or update SingleChoice fields on documents or RDOs. Set the FieldValue to a Choice DTO instantiated with the Artifact ID or Artifact GUID. You can't set the values on SingleChoice fields to a text representation of a Choice. For example, you can set the value of the Field Single Choice Field on a Document or RDO to a Choice using its ArtifactID (such as 100456) or its GUID.
  • Retrieve a list of valid Choices for a SingleChoice field as follows:
    • Perform a read operation using the Artifact ID or GUID for Single Choice Field and the ArtifactTypeName of Field (or ArtifactTypeID = 14).
    • Request that the Choices field is returned. A List of kCura.Relativity.Client.DTOs.Choice is returned as illustrated in the following code.
      Copy

      DTOs.Field choiceFieldToRead = new DTOs.Field(ArtifactID);
      choiceFieldToRead.Fields.Add(new DTOs.FieldValue(DTOs.FieldFieldNames.Choices));
       
      var readResults = proxy.Repositories.Field.Read(choiceFieldToRead);
      DTOs.MultiChoiceFieldValueList choices = readResults.Results[0].Artifact
           [DTOs.FieldFieldNames.Choices].ValueAsMultipleChoice;
  • Read operations on a SingleChoice field return the following data:
    • Type of the Value returned using the ValueAsSingleChoice is kCura.Relativity.Choice.DTOs
    • Text value of the Choice set on the Field is the Name property of the Choice object
    • ArtifactID property of the Choice object is the ArtifactID of the Choice definition within the Workspace.
    • ArtifactGuids property is a List of GUIDs assigned to Choice definition.

File fields

You use a File type field to upload a file for a non-document object. When you add a File field, Relativity automatically creates other fields containing file metadata, such as File Size, File Icon, and Text fields. For more information and code samples, see File field.

MultiChoice fields

In Relativity, a MultiChoice field has a predetermined set of values called choices. A user can select several choices for coding or other purposes. Use these guidelines for MultiChoice fields:

  • Create and update operations require you to set the values of a MultiChoice Field by defining a MultiChoiceFieldValueList, which is used to set and return MultiChoice Fields on DTOs. When you have a .NET List of Choice DTOs (FieldValueList<DTOs.Choice>), the UpdateBehavior property indicates how the IDs in the FieldValueList are applied to the field (Replace or Merge). The default behavior is Replace, when no value is specified.

    If necessary, you can modified this list directly and pass it back in an update operation. You can populate this list from a read operation, or manually set it using a constructor that takes a List<DTOs.Choice> or parameter array of DTOs.Choice.

  • Read or query operations return a MultiChoice value as a FieldValueList<DTOs.Choice> using the ValueAsMultipleChoice property.

SingleObject fields

In Relativity, a SingleObject field defines a one-to-many relationship between two objects. Use these guidelines for SingleObject fields:

  • Create and update operations on a SingleObject field require you to pass DTO with the ArtifactID property set.
  • On read and query operations, the ValueAsSingleObject property returns a SingleObject as a DTO with the type of the object that you specified in the operation. On these DTOs, only the ArtifactID on the base Artifact is populated, while the Fields collections is empty.

    Note: If the DTO layer doesn't support the requested object type, then Artifact is used as the return type.

Starting in January 2018, you can set the OpenToAssociation property for single-object fields

MultiObject fields

In Relativity, MultiObject fields define a many-to-many relationship between two objects. Use these guidelines for MultiObject fields:

  • Create and update operations on MultiObject fields require you to pass a FieldValueList containing DTO objects with their ArtifactID property set.
  • Read and query operations return a FieldValueList of the DTO for the object, using the GetValueAsMultipleObject<T>() method, where T is the type of Object. On these DTOs, only the ArtifactID on the base Artifact is populated, while the Fields collections is empty.

    Note: If the DTO layer doesn't support the requested object type, then Artifact is used as the return type.

User fields

In Relativity, a User field contains the rights that a user has to the current workspace. Use these guidelines for User fields:

  • Create and update operations require you to set the User field to a User DTO with the ArtifactID property populated.
  • On read and query operations, the ValueAsUser property returns the Value property of the User field as a type kCura.Relativity.Client.DTOs.User, which is populated with the ArtifactID and Name properties.
  • A user must have explicit access to a workspace in order to be assigned to a User field. For example, a system admin can access Workspace A through admin permissions but cannot be assigned to the User field of an object in Workspace A unless explicitly added to the workspace.

User fields on RDOs in migrated workspaces

In workspaces created by migration with DBMT (Database Management Tool), the user fields on RDOs contains the ArtifactID values that do not directly map to user ArtifactID in the eddsdbo.User table.

To establish the user mapping:

  1. Get the value of the User field on the RDO. This is the ArtifactID of the user in that workspace (corresponding to the value of CaseUserArtifactID in the edds.UserCaseUser table).
  2. Perform a query to return all users in the workspace and include the WorkspaceUserIDs property of the User DTO in the results.
  3. The WorkspaceUserIDs property contains a collection of WorkspaceUserID objects. This object contains the UserArtifactID and WorkspaceID properties. Filter the result set of User DTOs from step 2 by searching each WorkspaceUserID object for UserArtifactID and WorkspaceID that match the ArtifactID and workspace from Step 1.
  4. When you find a match in step 3, the Artifact ID on the User DTO will map to the value of ArtifactID in eddsdbo.User table.

WholeNumber fields

Relativity uses WholeNumber fields to store any natural numbers. Use these guidelines for WholeNumber fields

  • Create and update operations require you to set the WholeNumber field to a whole number value.
  • Read and query operations on a WholeNumber field return the Value property as an integer using the ValueAsWholeNumber property.

Decimal fields

In Relativity, Decimal fields store numeric values that may include decimals. Use these guidelines for Decimal fields:

  • Create and update operations require you to set the Decimal field to a decimal value.
  • Read and query operations on a Decimal field return the Value property of the field as a decimal using the ValueAsDecimal property.

Currency fields

Relativity uses Currency fields to store numeric values in a currency format. Use these guidelines for Currency fields:

  • Create and update operations require you to set the Currency field to a decimal value.
  • Read and query operations on a Currency field return the Value property of the field decimal using the ValueAsCurrency property.

Date fields

Relativity uses Date fields to store the date or date and time. Use these guidelines for Date fields:

  • Create and update operations require you to set the Date field to a .NET DateTime value.
  • Read and query operations on a Date field return the Value property of the field as a .NET DateTime using the ValueAsDate property.

Yes/No fields

In Relativity, a Yes/No field stores a Boolean value. Use these guidelines for Yes/No fields:

  • Create and update operations require you to set the Yes/No field to a .NET Boolean value.
  • Read and query operations on Yes/No field return the Value property of the field as a .NET Boolean using the ValueAsYesNo Property.

Supported operations for Field types

The following operations are supported for Field types on DTOs:

Operation Supported for Fields on DTOs
Create a Field on a DTO RDO and Document DTOs
Read Field metadata All DTOs
Delete a Field (except system Field) from a DTO All DTOs
Query on Field metadata All DTOs

Note: For information about updating DTOs, see RSAPI reference for .NET. When you update Documents and RDOs, the value of each Field on an object in the Fields collection is overwritten with a new value, except for MultiChoice fields. See MultiChoice fields.