The Field Entity

Field

Catalytic.SDK.Entities.Field

Fields hold the data in your Workflows and can be used to configure which steps your Workflow Instance takes and which are skipped.

Fields can hold simple data like text, dates or numbers. Fields can also hold files or references to other Catalytic entities like Workflows or Tables.

πŸ“˜

More About Fields

For more information on Fields and Field Types in the Catalytic platform, see the platform help docs.

Field Types

When you get the Fields on an Instance, each field will be a concrete subtype of Field. Calling SetValue<T> or GetValue<T> will throw an InvalidFieldTypeException if the field's type does not support conversion from or to type T. For example, an IntegerField is a subclass of Field<int?>. It supports conversion to and from string and object as well as all primitive numeric types. Be careful when converting between numeric types as decimal values may be truncated. Field types and their associated class are listed in the following table. Also note that all struct fields are nullable. They support conversion to non-nullable values, but will throw

FieldTypeValue TypeNotes
TextstringContains arbitrary UTF-8 text. Many use-cases support markdown.
Integerint?
DecimalDecimal?
DateDateTime?Contains only the date, without a time component
DateTimeDateTimeOffset?A date and time, represented in UTC
JsonstringValidated JSON, encoded as a string
SingleChoicestringOne of an enumerated set of text values
MultipleChoiceHashSet<string>One or more of an enumerated set of text values
WorkflowGuidReference to a Workflow
InstanceGuidReference to an Instance
InstructionsstringRead-only field for passing instructions to users
FileGuidReference to a File
FilesList<Guid>Reference to multiple Files
TableGuidReference to a DataTable
UserGuidReference to a User

Summary of Properties and Methods

Instance Properties

NameTypeDescription
IdGuidThe unique ID of the Field
NamestringThe descriptive name of the Field
DescriptionstringA description of the Field, or instructions for filling out the Field in a form
FieldTypeFieldTypeAn enum representing the type of data held in the field.
TypeTypeThe dotnet runtime Type of the data held in the field.
HasValueboolIndicates whether the field has a value.
RestrictionsFieldRestrictionsMay include a set of string Choices for
SingleChoice and MultipleChoice fields.

Instance Methods

These are the most commonly used methods of aField.

NameReturn TypeDescription
GetValue<T>TGet the value stored in the field as a specific type
SetValue<T>voidSet she value stored in the field as a specific type
ClearValuevoidRemoves the value stored in the Field

The GetValue Method

Gets the field's value as a specific type, or as an object.

🚧

Nullable Struct-typed fields

If you are getting the value of a struct-type (non-nullable) field, be sure to either get the value as a Nullable<T> or check Field.HasValue to see if it is null. Otherwise you may get a default value for the type when the Field actually had no value at all. For example, if you have an Integer field named age, with a value of 42, both age.GetValue<int>() and age.getValue<int?>() will both return 42. However if age has no value, age.GetValue<int>() will return 0 while age.getValue<int?>() will return null.

Method Signature

T GetValue<T>()
object GetValue()
ParameterTypeDescription
returnsTThe field value, if any

Example

/*
 * This example demonstrates getting field values from and Instance
 */

using Catalytic.Sdk;
using Catalytic.Sdk.Entities;
using System;
using System.IO;

namespace Catalytic.Sdk.Examples
{
    class Program
    {
        // update this to your email before running this sample
        public const string YourEmail = "[email protected]";
      
        static void Main(string[] args)
        {
            // create and initialize the Catalytic SDK Client
            var catalytic = new CatalyticClient(Credentials.Default);
            var instance = catalytic.Instances.Get("e6df431b-1041-4326-89e5-1e14caa6a08f");
          
            // Get field values from the instance
            Guid tableId = instance.Fields["Table"].GetValue<Guid>();
          
            // If the field might be null, it's safer to get as a nullable type
            Guid? maybeTableId = instance.Fields["Table"].GetValue<Guid?>();
          
            // you can also get any field type as a string
            string tableIdText = instance.Fields["Table"].GetValue<string>();
          
            // however, getting the value as an incompatible type will
            // throw an exception, for example:
            try
            {
                instance.Fields["Table"].GetValue<int>();
            }
            catch (Errors.InvalidFieldTypeException ex)
            {
                Console.WriteLine($"Caught the expected exception: {ex.Message}");
            }
        }
    }
}

The SetValue Method

Sets the value of the field

Method Signature

void SetValue<T>(T value)
ParameterTypeDescription
valueTThe field value to set

The ClearValue Method

Removes the value from the field, setting it to null.

Method Signature

void ClearValue<T>()