​

Smartsheet

Manage your spreadsheets and data with Smartsheet’s collaborative work management platform for project management, task tracking, and team collaboration.

​

Overview

The Smartsheet skill provides functionality for:

• Reading and managing spreadsheet data
• Accessing sheet information and metadata
• Working with rows, columns, and cells
• Handling sheet relationships and hierarchies
• Integrating with Smartsheet’s collaborative features

​

Connection Requirements

This skill requires a Smartsheet connection configured through:

• Connection ID: custom.smartsheet
• Integration: Uses Paragon custom integration for Smartsheet API access

​

Basic Usage

// Get list of all sheets
const integrationId = config.paragonIntegrations.smartsheet;
const url = PROXY_URL + "custom/" + integrationId + "/2.0/sheets";

// Read data from a specific sheet
const sheetUrl = PROXY_URL + "custom/" + integrationId + "/2.0/sheets/[SheetId]";

​

Key Features

​

Sheet Management

• List Sheets: Get all sheets accessible to your account
• Read Sheet Data: Access complete sheet contents including rows, columns, and cells
• Sheet Metadata: Retrieve sheet properties and configuration
• Sheet Relationships: Handle parent-child relationships between sheets

​

Data Access

• Column Information: Access column definitions and properties
• Row Data: Read row contents and cell values
• Cell Values: Extract individual cell data and formatting
• Sheet Structure: Understand sheet organization and hierarchy

​

Common Operations

​

List All Sheets

GET: custom/{integrationId}/2.0/sheets

​

Read Sheet Data

GET: custom/{integrationId}/2.0/sheets/{sheetId}

​

Access Specific Sheet Information

// Get sheet with specific options
GET: custom/{integrationId}/2.0/sheets/{sheetId}?include=attachments,discussions,format

​

Understanding Sheet Response Structure

​

Sheet Object Hierarchy

{
  "id": 123456789,
  "name": "Project Tracker",
  "columns": [
    {
      "id": 987654321,
      "index": 0,
      "title": "Task Name",
      "type": "TEXT_NUMBER",
      "primary": true
    }
  ],
  "rows": [
    {
      "id": 111222333,
      "rowNumber": 1,
      "cells": [
        {
          "columnId": 987654321,
          "value": "Project Setup",
          "displayValue": "Project Setup"
        }
      ]
    }
  ]
}

​

Key Relationships

• Sheets contain Columns and Rows
• Rows contain Cells that reference Column IDs
• Column IDs are used to map cell values to column headers
• Row IDs are used to identify and update specific rows

​

Data Processing Pattern

​

Reading Sheet Data

// 1. Get sheet structure
const sheet = await fetchSheet(sheetId);

// 2. Map column IDs to column names
const columnMap = {};
sheet.columns.forEach(col => {
  columnMap[col.id] = col.title;
});

// 3. Process rows and cells
sheet.rows.forEach(row => {
  const rowData = {};
  row.cells.forEach(cell => {
    const columnName = columnMap[cell.columnId];
    rowData[columnName] = cell.value;
  });
  // Process rowData...
});

​

Column Types

​

Available Column Types

• TEXT_NUMBER: Text and numeric values
• DATE: Date values
• DATETIME: Date and time values
• CONTACT_LIST: Contact information
• DROPDOWN: Predefined dropdown options
• CHECKBOX: Boolean checkbox values
• SYMBOL: Symbol indicators (stars, flags, etc.)
• PICKLIST: Single or multi-select lists

​

API Endpoint Structure

​

Base URL Pattern

const baseUrl = PROXY_URL + "custom/" + integrationId + "/2.0/";

​

Common Endpoints

• Sheets: sheets - List all sheets
• Sheet Details: sheets/{sheetId} - Get specific sheet
• Rows: sheets/{sheetId}/rows - Sheet rows
• Columns: sheets/{sheetId}/columns - Sheet columns
• Cells: sheets/{sheetId}/rows/{rowId}/cells - Specific cells

​

Query Parameters

​

Common Parameters

• include: Include additional data (attachments, discussions, format)
• exclude: Exclude specific data types
• columnIds: Specify which columns to include
• rowIds: Specify which rows to include
• pageSize: Number of items per page
• page: Page number for pagination

​

Important Notes

• Column ID Mapping: Always map column IDs to column titles for readable data processing
• Row Processing: Loop through columns first, then rows and cells for efficient data access
• API Version: Always include /2.0/ in the API URL path
• Integration ID: Use the correct Paragon integration ID for your Smartsheet connection
• Rate Limits: Respect Smartsheet API rate limits for large data operations
• Data Types: Handle different column types appropriately when processing cell values

​

Best Practices

1. Efficient Data Access: Map column IDs to names once, then reuse the mapping
2. Error Handling: Check for missing columns or cells before processing
3. Batch Operations: Use include parameters to get all needed data in one request
4. Data Validation: Validate cell values against expected column types
5. Performance: Use pagination for large sheets to avoid timeouts
6. Caching: Cache sheet structure if making multiple requests to the same sheet
7. Type Safety: Handle null or undefined cell values gracefully