Quickstart Examples

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.

import org.catalytic.sdk.CatalyticClient;

public class Program {

    public static void main(String[] args) throws Exception {
      
        // This will load the Access Token from the CATALYTIC_TOKEN
        // env var if set, or ~/.catalytic/tokens/default otherwise
        CatalyticClient catalytic = new CatalyticClient();
      
      	// Or you can pass in the name of the file your Access Token is stored in
      	// the ~/.catalytic/tokens dir
        CatalyticClient catalytic = new CatalyticClient("uat");
      
      	// Or the full path to the file containing the Access Token
      	CatalyticClient catalytic = new CatalyticClient("/users/alice/catalytic_token");
      
        // Or you can pass your Access Token directly into the constructor.
        // Not recommended for production
        CatalyticClient catalytic = new CatalyticClient("bd0df999-3f09-46d3-be8d-d044e234f00c");
    }
}

The following examples all assume that you have configured your default Access Token. Details on other ways to create and load credentials are in the Authentication section.

Quickstart Examples

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 java file
Follow the instructions in Getting Started & Installation to add the Catalytic SDK package to your project either via Maven or Gradle and set up your default credentials.
Replace program.java with the following

import org.catalytic.sdk.CatalyticClient;
import org.catalytic.sdk.entities.Field;
import org.catalytic.sdk.entities.Instance;
import org.catalytic.sdk.entities.Workflow;
import org.catalytic.sdk.entities.WorkflowsPage;

public class Program {

    public static void main(String[] args) throws Exception {

        // Create and initialize the Catalytic SDK Client
        CatalyticClient catalytic = new CatalyticClient();

        // Find workflows matching "Sdk Example Workflow"
        List<Workflow> workflows = new ArrayList<>();
	
        // Find Workflows that are owned by Alice with the name SDK Example.		  
      	Where where = new Where().text().matches("Sdk Example Workflow");
				
        // `results` is a results page containing `workflows` and 
        // a `nextPageToken` you can use to page through results.
      	WorkflowsPage results = catalytic.workflows().find(where);
      
      
      	// Get the workflows from the `results`
        List<Workflow> workflows = results.getWorkflows();

        // If Workflows were found, get the first one
        Workflow workflow = null;
        if (workflows != null) {
            workflow = workflows.get(0); 		
        }
        // If no Workflows were found, let's import one
        else {
            workflow = catalytic.workflows().import(new File("https://push.bot/sdk-example"));
        }

        // Now that we've got our Workflow, let's start an Instance with inputs it expects
        List<Field> fields = new ArrayList<>();
        Field age = new Field('Age', 42);
        Field name = new Field 'Name', 'Alice');
        fields.add(age);
        fields.add(name);

        Instance instance = catalytic.instances().start(
            workflow.getId(),
            'SDK Example',
            'My first SDK example',
            fields
        );

        String instanceUrl = "https://" + catalytic.getAccessToken().getDomain() + "/runs/" + instance.getId()";
        System.out.println("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 java file
Follow the instructions in Getting Started & Installation to add the Catalytic SDK package either via Maven or Gradle to your project and set up your default credentials.
Replace program.java with the following

import org.catalytic.sdk.CatalyticClient;
import org.catalytic.sdk.entities.Field;
import org.catalytic.sdk.entities.Instance;
import org.catalytic.sdk.entities.InstanceStep;
import org.catalytic.sdk.entities.InstanceStepsPage;
import org.catalytic.sdk.entities.Workflow;
import org.catalytic.sdk.entities.WorkflowsPage;

public class Program {

    public static void main(String[] args) throws Exception {

        // Create and initialize the Catalytic SDK Client
        CatalyticClient catalytic = new CatalyticClient();

        // Find workflows matching "Sdk Example Workflow"
        List<Workflow> workflows = new ArrayList<>();
	
        // Find Workflows that are owned by Alice with the name SDK Example.		  
      	Where where = new Where().text().matches("Sdk Example Workflow");
				
        // `results` is a results page containing `workflows` and 
        // a `nextPageToken` you can use to page through results.
      	WorkflowsPage results = catalytic.workflows().find(where);
      
      
      	// Get the workflows from the `results`
        List<Workflow> workflows = results.getWorkflows();

        // If Workflows were found, get the first one
        Workflow workflow = null;
        if (workflows != null) {
            workflow = workflows.get(0); 		
        }
        // If no Workflows were found, let's import one
        else {
            workflow = catalytic.workflows().import(new File("https://push.bot/sdk-example"));
        }

        // Now that we've got our Workflow, let's start an Instance with inputs it expects
        List<Field> fields = new ArrayList<>();
        Field age = new Field('Age', 42);
        Field name = new Field 'Name', 'Alice');
        fields.add(age);
        fields.add(name);

        Instance instance = catalytic.instances().start(
            workflow.getId(),
            'SDK Example',
            'My first SDK example',
            fields
        );

        // Get the steps
        InstanceStepsPage steps = catalytic.instances().getSteps(instance.getId()).getSteps();

        // Get the step we want to complete
        InstanceStep uploadStep = steps.stream()
            .filter(step -> "Upload Updated Spreadsheet and Set Email".equals(step.getName()))
            .findAny()
            .orElse(null)
            
        // Download the Data Table from the "Table" field as a CSV 
        String tableId = instance.getFields().stream()
            .filter(field -> "Table".equals(field.getName()))
            .findAny()
            .orElse(null)

        File csvFile = catalytic.getDataTables().download(tableId, 'csv');

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

        // Create the output csv file locally
        List<String> lines = Arrays.asList(updatedCsvContent);
        Path file = Paths.get(Files.createTempDirectory());
        updatedCsvFile = Files.write(file, lines, StandardCharsets.UTF_8);

        // To complete the step, we will set both a text and a file field
        fields = new ArrayList<>();
        Field updatedCsv = new Field("Updated CSV", updatedCsvFile);
        Field email = new Field("Email Address", "[email protected]");
        fields.add(updatedCsv);
        fields.add(email);

        catalytic.instances().completeStep(instance.getId(), fields);

        System.out.println("You should have an email waiting for you now " +
		 "with the updated CSV converted to an Excel attachment");
    }
}