Script Steps

Script Steps let your users see what’s happening while your script runs—making complex operations easier to follow with clear, real-time visual subsections.

Instead of a blank screen, users get progress feedback through titled steps, icons, colors, and descriptions—bringing transparency, trust, and a polished experience.

Basic Step

Add a step with just a title:

script.step('Loading your data...');

Detailed Step

Enhance the step with optional visuals:

script.step({
  title: 'Getting Latest Data',
  description: 'Fetching records from your selected table',
  color: 'blue',
  icon: 'download'
});

Customization Options

Colors

Use colors to indicate the type of action:

Color	Use Case
`blue`	General info, loading data
`green`	Success, completed actions
`yellow`	Validation, warnings
`red`	Errors, critical issues
`purple`	Special or custom operations
`orange`	Updates or changes
`gray`	Background or neutral operations

Icons

Suggested icons for common use cases:

Icon	Meaning
`download`	Fetching or retrieving data
`upload`	Sending or submitting data
`database`	Interacting with tables
`sync`	Updating or syncing
`checkCircle`	Completion or success
`settings`	Configuration steps
`mail`	Email-related actions

Full Example

Here’s a complete example that guides the user through an import process:

// Step 1: Start import
script.step({
  title: 'Starting Import',
  description: 'Preparing to import customer data',
  color: 'blue',
  icon: 'database'
});

const sourceTable = await input.tableAsync('Which table has your customer data?');
const targetTable = await input.tableAsync('Which table should we import to?');

// Step 2: Validate data
script.step({
  title: 'Checking Your Data',
  description: 'Making sure the data will import correctly',
  color: 'yellow',
  icon: 'checkCircle'
});

const sourceRecords = await sourceTable.selectRecordsAsync();
if (sourceRecords.length === 0) {
  output.text('No records found to import!');
  return;
}

// Step 3: Import records
script.step({
  title: 'Importing Records',
  description: `Moving ${sourceRecords.length} customer records`,
  color: 'purple',
  icon: 'sync'
});

const newRecords = sourceRecords.map(record => ({
  'Customer Name': record.getCellValue('Name'),
  'Email': record.getCellValue('Email'),
  'Import Date': new Date()
}));

await targetTable.createRecordsAsync(newRecords);

// Step 4: Finish
script.step({
  title: 'Import Complete',
  description: `Successfully imported ${newRecords.length} customers`,
  color: 'green',
  icon: 'checkCircle'
});

script.clear();
output.text(`✅ Done! Imported ${newRecords.length} customer records.`);

Advanced Usage

Manually Clear a Step

Steps auto-clear when a new one starts, but you can also clear them explicitly:

script.step('Processing...');
await someAsyncTask();
script.clear();

Handling Errors Gracefully

Show errors in context to keep users informed:

script.step({
  title: 'Sending Emails',
  description: 'Notifying customers about their orders',
  color: 'blue',
  icon: 'mail'
});

try {
  await sendEmails();

  script.step({
    title: 'Emails Sent',
    description: 'All customers have been notified',
    color: 'green',
    icon: 'checkCircle'
  });
} catch (err) {
  script.step({
    title: 'Email Error',
    description: 'Could not send some emails – check your settings',
    color: 'red',
    icon: 'alert'
  });
}