Overview | Choice Fields

Choice fields restrict a field's values to a predefined list. ReadySuite supports two types: Choice (single value) and MultiChoice (multiple values). This topic covers creating choice fields, managing their value lists, and reading or writing choice data on documents.

Creating a Choice Field

Use CreateField() or GetOrCreateField() with a ChoiceFieldItemType:

C# Copy

script.CreateField("Status", ChoiceFieldItemType.Choice);
script.CreateField("Tags", ChoiceFieldItemType.MultiChoice);

GetOrCreateField() returns the existing field if it already exists:

C# Copy

var field = script.GetOrCreateField("Status", ChoiceFieldItemType.Choice);

The IChoiceFieldItem Interface

To work with a choice field's value list, convert it to IChoiceFieldItem using AsChoiceFieldItem():

C# Copy

var field = script.GetField("Status");
var choiceField = field.AsChoiceFieldItem();

AsChoiceFieldItem() returns null if the field is not a choice field.

Adding Values

Add allowed values individually or in bulk:

C# Copy

choiceField.AddValue("Open", "Closed", "Pending");

You can also add values from a delimited string:

C# Copy

choiceField.AddValue("Open;Closed;Pending", ';');

Checking and Retrieving Values

C# Copy

if (choiceField.HasValues())
{
    var values = choiceField.GetValues();  // Returns the list of allowed values
}

Removing Values

Remove a single value or clear all values:

C# Copy

choiceField.DeleteValue("Pending");
choiceField.ClearValues();

Setting Choice Data on Documents

For single-choice fields, set a value with SetFieldData():

C# Copy

document.SetFieldData(options.StatusField, "Open");
script.UpdateDocument(document);

For multi-choice fields, pass a collection of values:

C# Copy

var tags = new List<string> { "Responsive", "Privileged" };
document.SetFieldData(choiceField, tags, addIfMissingValue: true);
script.UpdateDocument(document);

You can also set multi-choice values from a delimited string:

C# Copy

document.SetFieldData(choiceField, "Responsive;Privileged", ';', addIfMissingValue: true);
script.UpdateDocument(document);

When addIfMissingValue is true, any value not already in the choice list is added automatically. When false, values not in the list are ignored.

Reading Choice Data

Reading choice data works the same as any other field:

C# Copy

var value = document.GetFieldData(options.StatusField);

For multi-choice fields, the returned string contains the selected values in their stored format.

Full Example

This example creates a single-choice "ReviewStatus" field, populates its value list, and assigns a value to each document:

C# Copy

public override void Run(IScriptContext script)
{
    base.Run(script);

    var field = script.GetOrCreateField("ReviewStatus", ChoiceFieldItemType.Choice);
    var choiceField = field.AsChoiceFieldItem();
    choiceField.AddValue("Not Started", "In Progress", "Complete");

    while (script.ReadDocument())
    {
        var document = script.Document;
        var current = document.GetFieldData(field);

        if (string.IsNullOrEmpty(current))
        {
            document.SetFieldData(field, "Not Started");
            script.UpdateDocument(document);
        }
    }
}