Class Workflow

config

// Access workflow configuration service
const workflowConfig = tisa.workflow.config;
// Export a workflow configuration
const exportedConfig = await workflowConfig.export("MyWorkflow");
Copy

instances

// Access workflow instances service
const workflowInstances = tisa.workflow.instances;
// Start a new workflow instance (use tisa.page.listId for the current list GUID)
const startResults = await workflowInstances.start({
  workflow: "MyWorkflow",
  items: [{ listId: tisa.page.listId, itemId: 1 }]
});
Copy

tasks

// Access workflow tasks service
const workflowTasks = tisa.workflow.tasks;
// Get tasks assigned to the current user
const myTasks = await workflowTasks.getMine();
Copy

start

• start(workflowName: string, parameters?: Record<string, any>): Promise<StartInstanceResult[]>

  Starts a workflow on the current item or selected items without displaying a dialog. The workflow will be initiated with any provided parameters directly.

  Parameters

  • workflowName: string

    The internal name of the workflow to start
  • Optionalparameters: Record<string, any>

    Optional parameters to pass to the workflow instance

  Returns Promise<StartInstanceResult[]>

  Promise resolving to an array of workflow start responses indicating success or failure for each item

  Remarks

  Current list identity matches tisa.page.listId (see Page in Common/CustomScript docs).

  Throws

  Error if no list context is available or if the workflow start operation fails

  Example

  // Start a simple workflow without parameters
  const results = await tisa.workflow.start("SimpleWorkflow");
  // Results: [{ status: "Ok", instanceId: "guid-123", itemId: 1, error: null }]
  Copy

  Example

  // Start a workflow with custom parameters
  const results = await tisa.workflow.start("ApprovalWorkflow", {
    approverEmail: "approver@contoso.com",
    priority: "High",
    dueDate: "2025-02-01"
  });
  // Results: [{ status: "Ok", instanceId: "guid-456", itemId: 1, error: null }]
  Copy

  Example

  // Handle errors
  try {
    const results = await tisa.workflow.start("MyWorkflow");
    results.forEach(result => {
      if (result.status !== "Ok") {
        console.error(`Failed for item ${result.itemId}: ${result.error?.message}`);
      }
    });
  } catch (error) {
    console.error("Workflow start failed:", error.message);
  }
  Copy

startOnItems

• startOnItems(
      workflowName: string,
      startOnItems: { itemId: number; listId: string }[],
      parameters?: Record<string, any>,
  ): Promise<StartInstanceResult[]>

  Starts a workflow on the specified items without displaying a dialog. The workflow will be initiated with any provided parameters directly.

  Parameters

  • workflowName: string

    The internal name of the workflow to start
  • startOnItems: { itemId: number; listId: string }[]

    Array of items (listId and itemId) on which to start the workflow
  • Optionalparameters: Record<string, any>

    Optional parameters to pass to the workflow instance

  Returns Promise<StartInstanceResult[]>

  Promise resolving to an array of workflow start responses indicating success or failure for each item

  Throws

  Error if no list context is available or if the workflow start operation fails

  Example

  // Start a simple workflow without parameters
  const results = await tisa.workflow.start("SimpleWorkflow", [{ listId: "<guid>", itemId: 456 }]);
  // Results: [{ status: "Ok", instanceId: "guid-123", itemId: 1, error: null }]
  Copy

  Example

  // Start a workflow with custom parameters
  const results = await tisa.workflow.start("ApprovalWorkflow", [{ listId: "<guid>", itemId: 456 }], {
    approverEmail: "approver@contoso.com",
    priority: "High",
    dueDate: "2025-02-01"
  });
  // Results: [{ status: "Ok", instanceId: "guid-456", itemId: 1, error: null }]
  Copy

  Example

  // Handle errors
  try {
    const results = await tisa.workflow.start("MyWorkflow", [{ listId: "<guid>", itemId: 456 }]);
    results.forEach(result => {
      if (result.status !== "Ok") {
        console.error(`Failed for item ${result.itemId}: ${result.error?.message}`);
      }
    });
  } catch (error) {
    console.error("Workflow start failed:", error.message);
  }
  Copy

startOnItemsWithForm

• startOnItemsWithForm(
      workflowName: string,
      startOnItems: { itemId: number; listId: string }[],
      parameters?: Record<string, any>,
      dialogConfig?: DialogConfig,
      onDialogButton?: OnDialogButtonClicked,
  ): Promise<StartInstanceResult[]>

  Starts a workflow on the specified items after collecting user input via a dialog form. The dialog is populated with workflow parameters defined in the workflow definition. User-provided form data is merged with optional additional parameters before workflow initiation.

  Parameters

  • workflowName: string

    The internal name of the workflow to start
  • startOnItems: { itemId: number; listId: string }[]

    Array of items (listId and itemId) on which to start the workflow
  • Optionalparameters: Record<string, any>

    Optional additional parameters to merge with form data (parameters takes precedence)
  • OptionaldialogConfig: DialogConfig

    Optional custom dialog configuration for appearance and field definitions If not provided, dialog is auto-generated from workflow parameters
  • OptionalonDialogButton: OnDialogButtonClicked

    Optional callback function invoked when dialog buttons are clicked, useful for data validation and transformation

  Returns Promise<StartInstanceResult[]>

  Promise resolving to an array of workflow start responses, or empty array if user cancels the dialog

  Throws

  Error if workflow definition cannot be retrieved or workflow start fails

  Example

  // Basic usage: start workflow with user-provided form data
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", [{ listId: "<guid>", itemId: 456 }]);
  // Opens dialog with default fields, user fills form, workflow starts
  Copy

  Example

  // With additional parameters
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", [{ listId: "<guid>", itemId: 456 }], {
    source: "automated",
    priority: "High"
  });
  // Form data is merged with these parameters before workflow starts
  Copy

  Example

  // With custom dialog configuration
  const customDialog: DialogConfig = {
    Title: "Custom Approval Form",
    Template: [
      { Title: "Approver Email", InternalName: "approverEmail", Type: "Text", Required: true },
      { Title: "Comments", InternalName: "comments", Type: "Note" }
    ]
  };
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", [{ listId: "<guid>", itemId: 456 }], undefined, customDialog);
  Copy

  Example

  // With form validation callback
  const onDialogButton: OnDialogButtonClicked = async (button, data) => {
    if (button === "submit" && !data.approverEmail) {
      // Validation failed, dialog stays open
      return false;
    }
    return true; // Allow dialog to close
  };
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", [{ listId: "<guid>", itemId: 456 }], undefined, undefined, onDialogButton);
  Copy

  Example

  // Handle dialog cancellation
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", [{ listId: "<guid>", itemId: 456 }]);
  if (results.length === 0) {
    console.log("User cancelled the workflow dialog");
  } else {
    console.log(`Workflow started on ${results.length} item(s)`);
  }
  Copy

startWithForm

• startWithForm(
      workflowName: string,
      parameters?: Record<string, any>,
      dialogConfig?: DialogConfig,
      onDialogButton?: OnDialogButtonClicked,
  ): Promise<StartInstanceResult[]>

  Starts a workflow on the current item or selected items after collecting user input via a dialog form. The dialog is populated with workflow parameters defined in the workflow definition. User-provided form data is merged with optional additional parameters before workflow initiation.

  Parameters

  • workflowName: string

    The internal name of the workflow to start
  • Optionalparameters: Record<string, any>

    Optional additional parameters to merge with form data (parameters takes precedence)
  • OptionaldialogConfig: DialogConfig

    Optional custom dialog configuration for appearance and field definitions If not provided, dialog is auto-generated from workflow parameters
  • OptionalonDialogButton: OnDialogButtonClicked

    Optional callback function invoked when dialog buttons are clicked, useful for data validation and transformation

  Returns Promise<StartInstanceResult[]>

  Promise resolving to an array of workflow start responses, or empty array if user cancels the dialog

  Throws

  Error if workflow definition cannot be retrieved or workflow start fails

  Example

  // Basic usage: start workflow with user-provided form data
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow");
  // Opens dialog with default fields, user fills form, workflow starts
  Copy

  Example

  // With additional parameters
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", {
    source: "automated",
    priority: "High"
  });
  // Form data is merged with these parameters before workflow starts
  Copy

  Example

  // With custom dialog configuration
  const customDialog: DialogConfig = {
    Title: "Custom Approval Form",
    Template: [
      { Title: "Approver Email", InternalName: "approverEmail", Type: "Text", Required: true },
      { Title: "Comments", InternalName: "comments", Type: "Note" }
    ]
  };
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", undefined, customDialog);
  Copy

  Example

  // With form validation callback
  const onDialogButton: OnDialogButtonClicked = async (button, data) => {
    if (button === "submit" && !data.approverEmail) {
      // Validation failed, dialog stays open
      return false;
    }
    return true; // Allow dialog to close
  };
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow", undefined, undefined, onDialogButton);
  Copy

  Example

  // Handle dialog cancellation
  const results = await tisa.workflow.startWithForm("ApprovalWorkflow");
  if (results.length === 0) {
    console.log("User cancelled the workflow dialog");
  } else {
    console.log(`Workflow started on ${results.length} item(s)`);
  }
  Copy

stop

• stop(workflowName: string): Promise<StopInstanceResult[]>

  Stops running instances of a workflow on the current item or selected items. Resolves running instances on the backend by workflow name + items and stops each one.

  Parameters

  • workflowName: string

    The internal name of the workflow whose running instances should be stopped

  Returns Promise<StopInstanceResult[]>

  Promise resolving to an array of stop responses indicating success or failure for each resolved instance

  Remarks

  Current list identity matches tisa.page.listId (see Page in Common/CustomScript docs).

  Throws

  Error if no list context is available or if the stop operation fails entirely

  Example

  // Stop running workflow instances on the current item or selected items
  const results = await tisa.workflow.stop("ApprovalWorkflow");
  results.forEach(r => {
    if (r.status !== "Ok") {
      console.error(`Failed for item ${r.itemId}: ${r.error?.message}`);
    }
  });
  Copy

stopOnItems

• stopOnItems(workflowName: string, stopOnItems: { itemId: number; listId: string }[]): Promise<StopInstanceResult[]>

  Stops running instances of a workflow on the specified items. Resolves running instances on the backend by workflow name + items and stops each one.

  Parameters

  • workflowName: string

    The internal name of the workflow whose running instances should be stopped
  • stopOnItems: { itemId: number; listId: string }[]

    Array of items (listId and itemId) whose running instances should be stopped

  Returns Promise<StopInstanceResult[]>

  Promise resolving to an array of stop responses indicating success or failure for each resolved instance

  Throws

  Error if no items are provided or if the stop operation fails entirely

  Example

  // Stop running workflow instances on specific items
  const results = await tisa.workflow.stopOnItems("ApprovalWorkflow", [
    { listId: "72b67e8c-b1c1-4d41-8eaa-69944b79a28c", itemId: 12 }
  ]);
  Copy