Workflow UI Knowledge Base

Introduction

The Workflow UI (also called "Custom UI") is a powerful feature of Sheet Workflows that allows you to transform cell notes into an interactive, step-by-step guided interface. This enables end users to interact with complex spreadsheet operations without needing to understand the underlying formulas, APIs, or automation.

This knowledge base article provides comprehensive information on creating, configuring, and optimizing custom UIs for your spreadsheets.

Table of Contents

1. What is Custom UI?
2. Getting Started
3. Creating a Custom UI
4. Cell Note Format
5. Step Types and Operations
6. UI Navigation and Flow
7. API Configuration
8. Row Selection Operations
9. Best Practices
10. Internationalization
11. Splash Pages
12. Troubleshooting
13. Advanced Techniques

What is Custom UI?

The Custom UI is a sidebar-based interface that guides users through a sequence of operations in Google Sheets. It translates specially formatted cell notes into interactive steps with instructions and action buttons.

Key characteristics:

• Step-by-step wizard interface
• Instructions and action buttons for each step
• Support for operations on cells, rows, files, and API configurations
• Automatic handling of cell navigation and selection
• Rate limiting for batch operations
• Support for multiple languages and Right-to-Left layouts

Getting Started

Accessing the Custom UI

To access the Custom UI feature:

1. Open your Google Sheet
2. Click Extensions > Sheet Workflows > Workflow UI in the menu
3. The sidebar will appear with all configured steps

Basic Workflow

A typical Custom UI workflow consists of:

1. Adding specially formatted notes to cells in your spreadsheet using the sticky note icon
2. Accessing the Workflow UI from the menu
3. Users following the sequential steps in the sidebar
4. Each step can navigate to specific cells, run operations, or configure settings

Creating a Custom UI

Basic Structure

The Custom UI is built from cell notes placed strategically in your spreadsheet. The system scans the active sheet for specially formatted notes and converts them into interactive steps.

Each step typically consists of:

• Instructional text
• An optional action button
• Automatic navigation to the relevant cell

Planning Your UI

Before adding notes, plan your workflow:

1. Determine the steps: List all operations users need to perform
2. Choose cell locations: Decide where each step should be anchored
3. Organize sequentially: Arrange steps in a logical order
4. Define operations: Determine what each step should do (navigate, run tasks, etc.)

Creating Cell Notes

To create the custom UI steps:

1. Select the cell where you want to add a step
2. Click the sticky note icon (📝) in the Sheet Workflows sidebar
3. A dialog will appear allowing you to add or edit the cell note
4. Enter your formatted note with the appropriate keys (Info, Button, Type, etc.)
5. Click "Save Note"

Simple Example

Let's say you want to create a two-step workflow:

1. Navigate to cell A2 and enter a value
2. Run a task in column B using that value

You would:

1. Select cell A2 → Click the sticky note icon → Add Info: Enter your input data here → Save Note
2. Select cell B1 → Click the sticky note icon → Add:
   

      Info: Click to process your data
      Button: Run Processing
      Type: tasks

   
   → Save Note

Cell Note Format

Cell notes are written in a simple Key: Value format, with each key-value pair on a new line.

Recognized Keys

Note Placement

The position of the note in the spreadsheet determines its behavior:

• Row 1 cells: Notes in the first row are treated as column operations
• Other cells: Notes elsewhere specify exact cell operations

Example Cell Notes

Info: Enter your API key
Button: Save Configuration
Type: api_config

Info: Run the analysis on selected rows
Button: Process Data
Type: tasks
RPM: 5

Info: Download the results
Button: Download File
Type: download

Step Types and Operations

The Type parameter determines what operation a step performs when its button is clicked.

tasks

The most common type, tasks runs Sheet Workflows operations on cells or rows.

Info: Generate summaries for selected rows
Button: Generate Summaries
Type: tasks
RPM: 10

• With Column: Runs the operation on selected rows in that column
• With Cell: Runs the operation on a specific cell
• With RPM: Limits execution rate to prevent API throttling

files

Allows inserting files from Google Drive into the current cell.

Info: Insert reference files here
Button: Choose Files
Type: files

When clicked, opens the Google Picker dialog to select files from Drive.

download

Creates a download link for a Google Drive file referenced in the cell.

Info: Get the latest report
Button: Download Report
Type: download

The cell should contain a hyperlink to a Google Drive file.

api_config

Creates a configuration form for API settings.

Info: Configure OpenAI API
Type: api_config

This type is typically managed through the Share APIs feature in the Sheet Workflows sidebar rather than direct cell notes.

Default (no type specified)

If no type is specified, the step simply navigates to the cell location.

Info: Enter your data here

UI Navigation and Flow

Navigation Controls

The Custom UI provides navigation buttons at the bottom of the sidebar:

• Previous step (left arrow)
• Next step (right arrow)

Step Execution

When a user clicks an action button on a step:

1. The button shows a loading state
2. The operation executes (tasks run, files opened, etc.)
3. The UI automatically advances to the next step if appropriate

Sequential Operations

Steps can be chained together to run in sequence:

1. If a step has a button, clicking it executes that step's operation
2. If the next step doesn't have a button (info-only), it's automatically included in the sequence
3. This continues until reaching a step that does have a button

This enables creating multi-step operations that execute with a single click.

API Configuration

The Custom UI can be used to collect and save API configurations through the UI. This allows you to create guided workflows that prompt users to enter their API credentials without them having to manually edit configuration files.

Setting Up Shared API Configurations

To set up shared API configurations for your workflow:

1. In the Sheet Workflows sidebar, click on the gear icon (⚙️) to open the "Manage APIs" interface

2. From the dropdown menu, select an API that you want to share with your workflow users

3. Click the Share button (with the share icon 🔗)

4. In the dialog that appears:

   • Enter the Info Text that will be displayed to users in the workflow UI
   • Optionally provide a Link to where users can obtain their API key
   • Click "Save"

The system automatically handles the creation of all necessary backend structures. You don't need to manually create any hidden sheets or set up columns - this is all done for you behind the scenes.

Configuration Form Display in Workflow UI

When a user runs your workflow with a shared API configuration:

1. The Workflow UI automatically detects if any API configurations are missing

2. It presents the user with a configuration form containing:

   • The info text you provided when sharing the API
   • Input fields for all required API credentials (with appropriate security for sensitive fields)
   • A link to where they can get their API key (if you provided one)
   • A "Save" button

3. After the user enters their API information and clicks Save:

   • The configuration is securely stored in their user properties
   • A success message appears
   • The step is automatically removed from the workflow
   • The workflow continues to the next step

This seamless experience allows workflow creators to incorporate API-powered functionality without requiring users to understand the technical details of API configuration.

Row Selection Operations

A powerful feature of the Custom UI is the ability to run operations on selected rows within a column.

Setting Up a Row Operation

1. Select a cell in row 1 of your target column
2. Click the sticky note icon in the Sheet Workflows sidebar
3. Enter a note with the following format:
   

      Info: Process selected customers
      Button: Generate Reports
      Type: tasks
      RPM: 5

4. Click "Save Note"

When users click the button in the Workflow UI:

• If rows are selected: The operation runs on just those rows
• If no rows are selected: The UI prompts users to select rows first

Row Selection Management

The UI helps users track which rows are selected:

• Displays the selection range (e.g., "12,21:22")
• Provides a refresh button to update the selection count
• Shows a note explaining that the operation will run on selected rows

Best Practices

Designing an Effective UI

1. Clear Instructions: Write concise, action-oriented step information
2. Logical Flow: Arrange steps in a natural sequence
3. Consistent Terminology: Use the same terms throughout your UI
4. Visual Organization: Group related steps in the same column
5. Feedback: Include steps that confirm successful operations

Performance Considerations

1. Use RPM Limits: For operations that call external APIs, set appropriate rate limits
2. Split Large Operations: Break down large tasks into smaller chunks
3. Pre-validate Data: Include steps that check data quality before processing

User Experience

1. Onboarding Step: Start with an introduction step explaining the workflow
2. Clear Success States: Include confirmation steps after complex operations
3. Error Handling: Add steps for common error scenarios
4. Progress Indicators: Use step numbering to show progress

Internationalization

The Custom UI supports multiple languages and right-to-left (RTL) layouts.

Supported Languages

The UI automatically displays in the user's selected language. Currently supported:

• English (en)
• Hebrew (he - RTL)
• Spanish (es)
• French (fr)
• German (de)

RTL Support

For RTL languages like Hebrew:

• The UI automatically adjusts layout direction
• Navigation buttons are reversed
• Content alignment is adjusted

Splash Pages

For easy distribution of your workflows, you can create a splash page with installation instructions.

Creating a Splash Page

To create a splash page:

1. In the Sheet Workflows sidebar, click on the cloud download icon (☁️⬇️)
2. This automatically creates a new sheet named "START HERE" at the beginning of your spreadsheet
3. The splash page includes:
   • A link to copy the spreadsheet
   • Instructions to install Sheet Workflows
   • Guidance on accessing the Workflow UI

This is particularly useful when sharing workflows with new users, as it provides clear instructions for getting started.

Troubleshooting

Common Issues

1. Steps not appearing:

   • Check that cell notes follow the exact Key: Value format
   • Verify you're on the correct sheet
   • Try refreshing the UI using the refresh button

2. Buttons not working:

   • Check if the operation type is correct
   • Verify that referenced cells or columns exist
   • Check for permissions issues (for files/downloads)

3. Row operations not running:

   • Ensure rows are properly selected
   • Verify the column letter is correct
   • Check if the RPM setting is too restrictive

Debug Tools

Use these techniques to troubleshoot Custom UI issues:

1. Browser console logs provide details about step processing
2. Test individual operations separately before combining in the UI
3. If using shared APIs, check the API configuration in the Manage APIs interface

Advanced Techniques

Combining with Other Sheet Workflows Features

The Custom UI can trigger various Sheet Workflows operations:

• Language model completions (LM function)
• Formula generation
• Sheet formatting
• API calls
• File operations

Dynamic Step Generation

For advanced scenarios, you can use the Sheet Workflows sidebar to add multiple notes in a pattern:

1. Design your workflow steps in a spreadsheet
2. Use the sticky note icon to add each note systematically
3. Test the complete workflow before sharing

Custom API Integration

The Custom UI can be extended to support custom API integrations:

1. Use the Manage APIs interface to define API configurations
2. Share the APIs with users via the Share API option
3. Create workflow steps that use these APIs

By leveraging the Custom UI / Workflow UI feature, you can transform complex spreadsheet operations into guided, user-friendly experiences that require no technical knowledge to use. This empowers teams to implement sophisticated data workflows while maintaining accessibility for all users.