Additional Configurations

The following sections outline the number of different ways to render your input fields in Tray's builder UI by adding JSdoc annotations to the properties in your input.ts.

Data types

• string: represents string values
• number: represents a number, e.g. 42. If you want to limit an input field to a whole number you can use the JSdoc annotation @TJS-type integer above the number.
• boolean: is for the two values true and false
• array: represented by [] , e.g. number[]
• object: represented by object that contains different fields

Here is an example use of the different data types:

export type ExampleOperationInput = {
  str: string;
  num: number;
  /**
   * @TJS-type integer
   */
  int: number;
  bool: boolean;
  obj: object;
  arr: object[];
};

Required/Optional fields

By default all input fields are mandatory, you can set any to optional with a ? in your TypeScript type. Mandatory fields get a red * in the Tray builder UI and will warn the user that they must be filled in before attempting to run a workflow.

export type ExampleOperationInput = {
  mandatoryField: string;
  optionalField?: string;
};

Enums (Static dropdown lists)

Enums are rendered in the Tray builder UI as dropdowns.

The user will see the enum display names and the enum values are what will be passed into the handler.

By default, user friendly enum display names are generated. e.g. an enum of value my-enum-value will be rendered in the UI with the display name My enum value.

export type ExampleOperationInput = {
	type: ActionType;
};

enum ActionType {
	first-option = 'first-option', // User will see an auto generated display name: First option
	second-option = 'second-option', // User will see an auto generated display name: Second option
	third-option = 'third-option', // User will see an auto generated display name: Third option
}

You may want to provide custom enum display names instead, to do so use the JSdoc annotation @enumLabels followed by a comma separated list of strings that matches the order you have defined your enums in.

export type ExampleOperationInput = {
	type: ActionType;
};

/**
 * @enumLabels The First Option, The Second Option, The Third Option
 */
enum ActionType {
	first-option = 'first-option',
	second-option = 'second-option',
	third-option = 'third-option',
}

DDL (Dynamic dropdown lists)

Sometimes you want to provide the user a dropdown list, but you don't know the items to display in the list because they come from another API.

For example you may want to display a list of user names in a dropdown and based on the selection send the user ID. DDL's solve this problem.

Once you have created an operation for your DDL (check Building a DDL operation page on how to do it) you can use this DDL in the input of other operations (check Using a DDL operation page on how to do it).

The JSdoc annotation @lookupOperation specifies what operation to invoke when the user expands the dropdown.

Here is an example input.ts for Slack's send_message operation that would use list_user_ddl to present a dropdown list of users to whom the message can be sent.

export type ExampleOperationInput = {
  /**
   * @title user
   * @lookupOperation list_users_ddl
   * @lookupInput {"includePrivateChannels": false,"workspaceId": "{{{workspaceId}}}"}
   * @lookupAuthRequired true
   */
  userId: string;
  message: string;
};

@lookupInput is used to describe the JSON payload to send to that DDL operation.

Any inputs defined in input.ts can be passed to the DDL operation using tripple braces. In this example we send the workspaceId field value by doing {{{workspaceId}}}.

If your DDL operation calls an authenticated endpoint you can pass along the token used in the current operation by setting @lookupAuthRequired true.

Reusing types across multiple operations

You can reuse types by importing them and reuse sections of a schema by using TypeScript intersections.

// input.ts
import { ReusableField } from "./ReusableField";
import { ReusableSchema } from "./ReusableSchema";

export type ExampleOperationInput = SpecificSchema & ReusableSchema;

type SpecificSchema = {
  specificField: string;
  reusableFields: ReusableField;
};

// ReusableField.ts
export type ReusableField = {
  reusableFieldA: number;
  reusableFieldB: string;
};

// ReusableSchema.ts
export type ReusableSchema = {
  reusableSchemaA: number;
  reusableSchemaB: string;
};

Once the imports and intersection are resolved the above example would look like this

export type Input = {
  specificField: string;
  reusableFields: {
    reusableFieldA: number;
    reusableFieldB: string;
  };
  reusableSchemaA: number;
  reusableSchemaB: string;
};

Union types (Supporting multiple types)

If you want to support two or more different object types in your schema you can achieve this using TypeScript unions.

In the example below our input accepts an array of elements.

Each element of this array can be either of type image or text.

When the user adds an item to the array they will see a dropdown where they can select if this element will be an image or text.

The JSdoc annotation @title on the image and text types will be displayed in the dropdown the user sees.

export type ExampleOperationInput = {
  elements: ImageOrText[];
};

type ImageOrText = Image | Text;

/**
 * @title Image
 */
type Image = {
  name: string;
  src: string;
};

/**
 * @title Text
 */
type Text = {
  text: string;
};

Formatting fields

By default properties on your input type render as simple input fields.

You can select a more user friendly way to render the field based on your needs by using the JSdoc annotation @format.

The format options available are:

• datetime - renders a date and time picker
• code - renders a button which on click opens a modal with a simple code editor
• text - for longer text inputs, expands when you enter new lines

export type ExampleOperationInput = {
  /**
   * @format datetime
   */
  timestamp: string;
  /**
   * @format code
   */
  html: string;
  /**
   * @format text
   */
  longNotes: string;
};

Default values

If you want to provide a default initial value for a field you can use the JSdoc annotation @default.

export type ExampleOperationInput = {
  /**
   * @default string default
   */
  str: string;
  /**
   * @default 0.1
   */
  num: number;
  /**
   * @TJS-type integer
   * @default 1
   */
  int: number;
  /**
   * @default true
   */
  bool: boolean;
  /**
   * @default { "default": true }
   */
  obj: object;
  /**
   * @default ["default"]
   */
  arr: object[];
};

Advanced fields (Hidden by default)

If you have optional fields that are for more advanced use cases you can obscure these into the Tray builder UI's advanced fields section.

This can provide a cleaner interface for your operation, but can still be accessed by the user by expanding the advanced fields section.

You can add fields here by using the JSdoc annotation @advanced true.

export type ExampleOperationInput = {
  normalField: string;
  /**
   * @advanced true
   */
  advancedField?: string;
};