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.

Fields used by Field type, User, and Group

Field, User, and Group objects use special fields that aren't used by other system types.

This page contains the following information:

Fields used by the Field objects

The Field system type uses specialized properties including IgnoreWarnings and the PaneIcon. In addition, the Result object available when a Field is create contains the specialized properties WarningMessage and IsWarning.

WarningMessage and IsWarning properties

The Create function can return warning messages when a Field object is created. If there are warnings, these messages are set on the WarningMessage property of the Result object, and IsWarning property is set to True. Since the WarningMessage property has a List datatype, multiple warning messages can be returned if necessary.

IgnoreWarnings property

The Field DTO contains an IgnoreWarnings Boolean property, which you can use to control how warning messages are handled. When the IgnoreWarnings property is set to False and warnings are returned, the Create call will fail. When IgnoreWarnings property is set to True and warnings are returned, the Create call will succeed.

In most cases, the code calling the API handles messages returned when the IgnoreWarnings property is set to False, and a Create call returns warnings. Depending on the programming logic, the IgnoreWarnings property could be set to True, and the Create call could be repeated when the warnings should be ignored.

When Fields are created, the Message property of a Result object can return multiple errors. Each error will be prefixed with the string API_Field_Validation_Error. This functionality contrasts with other areas in the API, which return only a single error message.

PaneIcon property

When you create a Relational Field, you must set a property for the pane icon that is displayed in the Relativity viewer. This icon should be a PNG of 16 x 16 pixels. On DTOs, the pane icon uses the RelationalFieldIcon object, which contains the same Data and Path properties as the FileValue object. You must set the Path and Data properties on the PaneIcon when creating a Relational Field. The Field DTO has a property called PaneIcon that takes a RelationalFieldIcon object as its value. On query and read operations, only the Path value is returned.

This code sample illustrates how to create a Relational Field with a PaneIcon. It uses the RelationalFieldIcon.

var fieldDTO = new DTOs.Field();
string path = "c:\\path\\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);
 
/// Set additional fields on the Field DTO.
 
DTOs.WriteResultSet<DTOs.RDO> results = client.Repositories.Field.Create(fieldDTO);
        

This code sample illustrates how to read a PaneIcon field on a Field.

DTOs.Field dto = new DTOs.Field(1038285);
dto.Fields.Add(new DTOs.FieldValue(DTOs.FieldFieldNames.PaneIcon));
 
var readResults = proxy.Repositories.Field.Read(dto);
 
DTOs.RelationalFieldIcon paneIcon = 
     readResults.Results[0].Artifact[DTOs.FieldFieldNames.PaneIcon].ValueAsRelationalFieldIcon;
        

Fields used by Group and User objects

Groups and Users require several special fields that aren't used by other system types. These fields include Password, User, and Group.

Password fields

To create a User, the Password, User Must Change Password on Next Login, and Send New Password To fields are required password settings. Use these general guidelines when working with password fields:

  • When working with Users, query for the values needed and save their Choice IDs in variables or a cache as you would for other Single Choice fields. Single Choice fields accept Choice IDs rather than Choice names.
  • The general guidelines for creating a User also apply on update, except that the Password field can be set to the Choice called Use Current Password. In this case, no other password fields are required, except for User Must Change Password On Next Login. This setting indicates that the password shouldn't be altered.

Note: These Fields exist as properties on the User DTO.

Password

Password is a Single Choice field. Use the following guidelines when working with this field:

  • Set this Field to one of these Choice values: Auto-generate Password or Manually set password.
  • Retrieve the Choice IDs for this Field by calling the Query method and passing in a Query object with a TextCondition on the field named Choice Type with Password as the text.
  • When the Password field is set to Auto-generate Password, a valid password is automatically generated for the user.
  • When the Password field is set to Manually set password, a Field named New Password is required. This Field is used to provide the new password when a User is being created.
  • Make sure that the password meets the following requirements:
    • Limited to between 8 and 50 characters in length.
    • Contains at least one uppercase letter, one lower case letter, one numeral, and one special character.
    • Doesn't contain the special characters backslash (\), quotation mark ("), greater than (>), or less than (<).
    • Can't be one of the previous X passwords, where X is the value in the EDDS Instance setting table named MaxPasswordHistory.

User Must Change Password on Next Login

User Must Change Password on Next Login is a Yes/No field.

Send New Password To

Send New Password To field is a Single Choice Field. Use the following guidelines when working with this field:

  • Set the Send New Password To field to one of these Choice ID values:
    • Me (email) - Sends the password to the user logged in to the Services API.
    • This user (email) - Sends the password to the user being created or edited.
    • Return - Create or Update call returns the password in a field named Password in the MetaDataArtifact property of a Result object.
  • Retrieve the Choice IDs for the Send New Password To field by calling the Query() method and passing in a Query object with a TextCondition on the field named Choice Type with Send new password to as the text.
  • Configuration settings for sending email messages are stored in the EDDS Instance setting table.

Groups field

When creating or updating a User, you can include the Groups field to set or modify the groups that include the user as a member. A Groups property also exists on the Group DTO. Follow these guidelines when working with the Groups field:

  • On create, the value of the Groups field is a list of ArtifactIDs, which indicate the groups that will include the user as a member.
  • On create, don't include the Everyone group in the list of ArtifactIDs. The user is automatically added to the Everyone group.
  • If an error while adding a user to a group, the user will still be created.
  • On update, the value of the Groups field is a MultiUpdateValue object, which contains the Value and Behavior properties. The Value property is a list of ArtifactIDs, and Behavior property specifies how the Artifact IDs are applied to the user.

    Note: You can only use the MultiUpdateValue class as a parameter when you update User and Group objects. This class has a Behavior property, which is a MultiUpdateBehavior enum. This enumeration is available for use only with User and Group objects.

  • When using DTOs, the Groups property takes a FieldValueList containing a List of Group DTOs.
  • If the behavior is set to Update, you must include the Everyone group in the list of ArtifactIDs.

Users field

You can include the User field when you want to set or modify users assigned to the Group that you are updating or creating. Follow these guidelines when working with the Users field:

  • On create, the value of the Users field is a list of ArtifactIDs that indicate the users that you want included in a group.
  • On update, the value of the Users field is MultiUpdateValue object, which contains the Value and Behavior properties. The Value property is a list of ArtifactIDs, and Behavior property specifies how the ArtifactIDs should be applied to the user.

    Note: You can only use the MultiUpdateValue class as a parameter when you update User and Group objects. This class has a Behavior property, which is a MultiUpdateBehavior enum. This enumeration is available for use only with User and Group objects.

  • When using the DTOs, the Users property takes a MultiUserFieldValueList. When you have a .NET List of User DTOs (FieldValueList<DTOs.Choice>), the UpdateBehavior property indicates how the IDs in the FieldValueList are applied to the field (Replace, Add, or Remove). The default behavior is Replace, when no value is specified.

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.