Authentication Quickstart

To use the SDK, you will require an Access Token. As shown in the example below, you can obtain a new Access Token by using your email and password if you do not have SSO enabled for your team. You can then save that token for future use. For SSO and other options, see the Authentication section.

using Catalytic.Sdk.Entities;

namespace Catalytic.Sdk.Examples
{
    class Program
    {
        static void Main(string[] args)
        {
            var catalytic = new Catalytic.Sdk.CatalyticClient();

            // Create or load your Access Token

            // You can directly set the serialized Access Token string on the constructed CatalyticClient.
            // The serialized Access Token string is accessible upon creation of a new Access Token via the Catalytic WebApp
            catalytic.AccessToken = "YOUR_SERIALIZED_ACCESS_TOKEN_STRING";

            if (AccessToken.HasDefault)
            {
                // This will load the Access Token from the CATALYTIC_TOKEN env var 
                // if set, or ~/.catalytic/tokens/default otherwise
                catalytic.AccessToken = AccessToken.Default;

                // Or you can pass your Access Token into the constructor:
                catalytic = new Catalytic.Sdk.Client(AccessToken.Default);
            }
            else
            {
                // otherwise you can log in with your email and password to create a new Access Token
                var accessToken = catalytic.AccessTokens.Create(
                    "your-team", 
                    "your-email", 
                    "your-password");

                accessToken.SaveToFile("default");
                catalytic.AccessToken = accessToken;

              
            }
            // you are now authenticated and ready to use the Catalytic SDK
        }
    }
}

Quickstart Examples

The following examples all assume that you have configured your default Access Token. Details on other ways to create and load Access Tokens are in the Getting Started & Installation section.

Example 1: Start a Workflow

Here is a simple example of finding and and starting a Workflow with a couple inputs. The first time you run it it will import an Sdk Example Workflow into your team.

To use this example:

Create a new C# console application in Visual Studio
Follow the instructions in Authentication to add the Catalytic.SDK NuGet package to your project and set up your default Access Token.
Replace Program.cs with the following

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

namespace Catalytic.Sdk.Examples
{
    class Program
    {
        static void Main(string[] args)
        {
            // create and initialize the Catalytic SDK Client
            var catalytic = new CatalyticClient(AccessToken.Default);

            // find workflows matching "Sdk Example Pushbot"
            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);

            var instanceUrl = $"https://{catalytic.AccessToken.Domain}/runs/{instance.Id}";
            Console.WriteLine(
              "Workflow started successfully." +
              $"View your Workflow at ${instanceUrl}");
        }
    }
}

Example 2: Complete a Step with Data Tables and Files

Here is a more advanced example showing how you can upload and download files from an Instance, complete a task in an Instance, and upload and download data tables. The Workflow used in this example will email you the results when then example completes.

To use this example:

Create a new C# console application in Visual Studio
Follow the instructions above to add the Catalytic.SDK NuGet package to your project and set up your default Access Token.
Replace Program.cs with the following

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(AccessToken.Default);

            // find workflows matching "Sdk Example Pushbot"
            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);

            // get the step we want to complete
            var steps = catalytic.Instances.GetSteps(instance.InstanceId).Steps;
            var uploadStep = steps.Where(
                s => s.Name == "Upload Updated Spreadsheet and Set Email").First();

            // download the Data Table from the "Table" field as a CSV 
            var tableId = instance.Fields["Table"].GetValue<Guid>();
            var csvFile = catalytic.DataTables.DownloadFile(tableId, DataTableExportFormat.CSV);

            // Do our "business logic" to transform the csv data
            // As a simple example, we replace "Foo" with "Bar"
            var updatedCsvContent = csvFile.OpenText().ReadToEnd().Replace("Foo", "Bar");

            // create the output csv file locally
            var updatedCsvFile = new FileInfo(Path.GetTempFileName());
            File.WriteAllText(updatedCsvFile.FullName, updatedCsvContent);

            // To complete the step, we will set both a text and a file field
            var stepRequest = uploadStep 
              .SetInput("Updated CSV", updatedCsvFile)
              .SetInput("Email Address", YourEmail);
            catalytic.Instances.CompleteStep(stepRequest);

            Console.WriteLine(
              $"You should have an email waiting for you at {YourEmail} now " + 
              "with the updated CSV converted to an Excel attachment");
        }
    }
}