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

🚧

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.

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
TableGuidReference to a DataTable
UserGuidReference to a User

The Field Class

Common Properties

These are the most commonly used properties of aField.

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.
/*
 * 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 Client(Credentials.Default);
            // find workflows matching "Sdk Example Workflow"
            var matches = catalytic.Workflows.Find(
                Where.Text.Matches("Sdk Example Workflow"));
            // `matches` is a results page containing `Workflows` and 
            // a `NextPageToken` you can use to page through results.
            // We only expect one match for this example so we can simply
            // get the first matching Workflow.
            var workflow = matches.Workflows.FirstOrDefault();
            if (workflow == null)
            {
              workflow = catalytic.Workflows.Import(
                  new Uri("https://push.bot/sdk-example"));
            }
            // Now that we've got our workflow, let's set the inputs it expects
            var request = workflow
              .SetInput("Age", 42)
              .SetInput("Name", "Alice")
              .SetName($"SDK Example - {DateTimeOffset.Now.ToString()}");
            // Start the workflow
            var instance = catalytic.Instances.Start(request);
            // now we can 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
            try
            {
                instance.Fields["Table"].GetValue<int>();
            }
            catch (Errors.InvalidFieldTypeException ex)
            {
                Console.WriteLine($"Caught the expected exception: {ex.Message}");
            }
        }
    }
}