Project Online Import CLI

A TypeScript CLI tool for importing Project Online data to Smartsheet. This tool helps organizations migrate their Microsoft Project Online projects to Smartsheet workspaces while preserving project structure, tasks, resources, and relationships.

Installation

Option 1: Install from npm (Recommended)

npm install -g @smartsheet/project-online-import

Option 2: Install from GitHub

npm install -g git+https://github.com/smartsheet-platform/project-online-import.git

Option 3: Clone and Build Locally

git clone https://github.com/smartsheet-platform/project-online-import.git
cd project-online-import
npm install
npm run build
npm link  # Makes CLI globally available

Development

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0
• Access to both Microsoft Project Online and Smartsheet

Setup

1. Clone the repository:

   git clone https://github.com/smartsheet-platform/project-online-import.git
   cd project-online-import

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Available Scripts

• npm run dev - Run the CLI in development mode with ts-node
• npm run build - Compile TypeScript to JavaScript
• npm start - Run the compiled CLI
• npm test - Run unit tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report
• npm run lint - Check code for linting errors
• npm run lint:fix - Fix linting errors automatically
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting
• npm run typecheck - Run TypeScript type checking
• npm run clean - Remove build artifacts

Usage

Import Command

Import data from Project Online to Smartsheet:

npm run dev -- import --source <project-id> --destination <workspace-id>

Single Project Import

# Import a specific project
npm run dev -- import --source 12345678-1234-1234-1234-123456789abc --destination 987654321

# Dry run for a specific project
npm run dev -- import --source 12345678-1234-1234-1234-123456789abc --destination 987654321 --dry-run

Options

• -s, --source <project-id> - Project Online project ID (GUID) to import
• -d, --destination <workspace-id> - Smartsheet destination workspace ID
• --dry-run - Run without making changes (validation only)
• -v, --verbose - Enable verbose logging
• --config <path> - Path to custom .env configuration file

Bulk Import Command

Import all accessible Project Online projects (each gets its own workspace):

# Import all accessible projects (creates one workspace per project)
npm run dev -- bulk-import

# Dry run to discover what projects would be imported
npm run dev -- bulk-import --dry-run

# Verbose output
npm run dev -- bulk-import --verbose

Options

• --dry-run - Discover projects without making changes
• -v, --verbose - Enable verbose logging
• --config <path> - Path to custom .env configuration file

Output: After successful completion, displays a mapping of project names to workspace links:

🔗 Project → Workspace Links:
Project Alpha → https://app.smartsheet.com/b/workspace/123456789
Project Beta → https://app.smartsheet.com/b/workspace/987654321

Validate Command

Validate Project Online data before import:

npm run dev -- validate --source <project-id>

Example:

npm run dev -- validate --source 12345678-1234-1234-1234-123456789abc

Configuration Command

Validate and display current configuration:

npm run dev -- config

Automation Script

For automation and CI/CD pipelines, use the standalone bulk import script:

# Bulk import all projects (automation-friendly)
npx tsx scripts/bulk-import-all-projects.ts

# Dry run for automation testing
npx tsx scripts/bulk-import-all-projects.ts --dry-run

Testing

Run all tests:

npm test

Run tests with coverage:

npm run test:coverage

Run tests in watch mode:

npm run test:watch

Code Quality

This project uses:

• TypeScript for type safety
• ESLint for code linting
• Prettier for code formatting
• Jest for unit testing

Run all quality checks:

npm run typecheck
npm run lint
npm run format:check
npm test

Configuration

Solution Type

The tool supports multiple workspace creation strategies via the SOLUTION_TYPE configuration:

# In your .env file
SOLUTION_TYPE=StandaloneWorkspaces  # Default - creates independent workspaces
# SOLUTION_TYPE=Portfolio            # Future - creates portfolio-based workspaces

StandaloneWorkspaces (default):

• Creates independent PMO Standards workspace
• Creates individual project workspaces
• Current tested implementation

Portfolio (future):

• Creates workspaces within portfolio structure
• Not yet implemented - coming soon!

See Factory Pattern Design for technical details.

Other Configuration

See .env.sample for all available configuration options including:

• SMARTSHEET_API_TOKEN - Smartsheet API authentication
• PMO_STANDARDS_WORKSPACE_ID - Reuse existing PMO Standards workspace
• TEMPLATE_WORKSPACE_ID - Use template for project workspace creation
• Project Online authentication settings

Documentation

Choose Your Path

Documentation is organized into three sections based on your needs:

🎯 Migrating to Smartsheet

Start here if you're migrating from Project Online to Smartsheet

For: Project managers, administrators, end users

1. Migration Overview ⭐ START HERE - Business context, what the tool does, migration structure
2. Authentication Setup - Credential configuration
3. CLI Usage Guide - Complete command reference and examples
4. Troubleshooting - Common issues and solutions

🏗️ How it Works

Start here to understand the technical architecture and design

For: Technical leads, architects, evaluators

5. ETL System Design ⭐ START HERE - Component architecture and implementation
6. Data Transformation Guide - Data mappings and transformation specs
7. Factory Pattern Design - Workspace creation strategies
8. Template-Based Workspace Creation - Efficient workspace creation
9. Re-run Resiliency - Idempotent operations and multi-run support
10. Sheet References - Cross-sheet references and relationships

🛠️ Contributing

Start here if you're developing or extending the codebase

For: Developers, contributors, maintainers

11. Issue First Approach ⭐ START HERE - How to write effective issues for AI agents
12. Code Conventions - Naming, formatting, and style standards
13. Code Patterns - Recommended implementation patterns
14. Anti-Patterns - Common mistakes to avoid
15. API Services Catalog - External API integration reference
16. Test Suite Guide - Testing strategy and implementation

---

Navigation Tips

• Each document has Previous/Next links for sequential reading
• Each document has section badges showing which section you're in
• Quick Access: Jump directly to any section's starting point above

Project Structure

.
├── sdlc/                      # SDLC documentation and configuration
│   ├── docs/
│   │   ├── architecture/      # System architecture documentation
│   │   │   ├── Project-Online-Migration-Overview.md
│   │   │   ├── ETL-System-Design.md
│   │   │   ├── Data-Transformation-Guide.md
│   │   │   ├── claude-agent-system.md
│   │   │   └── ultra-dry-architecture.md
│   │   ├── project/           # Implementation guides
│   │   │   ├── Authentication-Setup.md
│   │   │   ├── CLI-Usage-Guide.md
│   │   │   ├── Re-run-Resiliency.md
│   │   │   ├── Sheet-References.md
│   │   │   └── Template-Based-Workspace-Creation.md
│   │   ├── code/              # Code standards and patterns
│   │   │   ├── Anti-Patterns.md
│   │   │   ├── Conventions.md
│   │   │   ├── Patterns.md
│   │   │   └── Troubleshooting-Playbook.md
│   │   ├── api-reference/     # API integration reference
│   │   │   └── API-Services-Catalog.md
│   │   └── specs/             # Technical specifications
│   │       ├── E2E-Integration-Tests.md
│   │       └── Project-Plan.md
│   ├── shared/                # Shared documentation for Roo/Claude
│   └── memory-bank/           # SDLC context and progress tracking
├── src/                       # Source code
│   ├── cli.ts                 # CLI entry point
│   ├── index.ts               # Main export file
│   ├── factories/             # Workspace creation strategies
│   │   ├── index.ts           # Factory exports
│   │   ├── WorkspaceFactory.ts  # Factory interface
│   │   ├── WorkspaceFactoryProvider.ts  # Factory selector
│   │   ├── StandaloneWorkspacesFactory.ts  # Default implementation
│   │   └── PortfolioFactory.ts  # Future portfolio implementation
│   ├── lib/                   # Core library code
│   │   ├── importer.ts        # ETL orchestration
│   │   ├── ProjectOnlineClient.ts  # Project Online API client
│   │   └── auth/
│   │       └── MSALAuthHandler.ts  # Microsoft authentication
│   ├── transformers/          # Data transformation layer
│   │   ├── AssignmentTransformer.ts
│   │   ├── PMOStandardsTransformer.ts
│   │   ├── ProjectTransformer.ts
│   │   ├── ResourceTransformer.ts
│   │   ├── TaskTransformer.ts
│   │   └── utils.ts
│   ├── types/                 # TypeScript type definitions
│   │   ├── ProjectOnline.ts
│   │   ├── Smartsheet.ts
│   │   └── SmartsheetClient.ts
│   └── util/                  # Utility classes
│       ├── ConfigManager.ts
│       ├── ErrorHandler.ts
│       ├── ExponentialBackoff.ts
│       ├── Logger.ts
│       ├── ProgressReporter.ts
│       └── SmartsheetHelpers.ts
├── test/                      # Test suite
│   ├── unit/                  # Unit tests with mocks
│   │   ├── builders/          # Test data builders
│   │   ├── transformers/      # Transformer unit tests
│   │   ├── MockODataClient.ts
│   │   └── MockSmartsheetClient.ts
│   ├── integration/           # Integration tests
│   │   ├── scenarios/         # Test scenario definitions
│   │   └── helpers/           # Test utilities
│   └── README.md              # Test suite documentation
├── memory-bank/               # Main app project context
├── scripts/                   # Utility scripts
├── dist/                      # Compiled output (generated)
├── coverage/                  # Test coverage reports (generated)
└── node_modules/              # Dependencies (generated)

Architecture Overview

This tool implements an Extract-Transform-Load (ETL) pattern:

1. Extract - Fetch data from Project Online oData API (future)
2. Transform - Convert Project Online entities to Smartsheet format
3. Load - Create Smartsheet workspaces, sheets, and populate data

Key Features

• Workspace per Project - Each Project Online project becomes a dedicated Smartsheet workspace
• Three Sheets per Project - Summary, Tasks, and Resources
• Hierarchical Tasks - Maintains task hierarchy from Project Online
• Resource Type Handling - Work resources use contact lists, Material/Cost use picklists
• PMO Standards - Centralized reference sheets for consistent picklist values
• Factory Pattern - Extensible workspace creation supporting multiple strategies
• Type Safety - Full TypeScript implementation with comprehensive type definitions

See Project Online Migration Overview and ETL System Design for complete details.

Contributing

This project follows an "Issue First" approach for all contributions. Before making code changes:

1. Create or find a GitHub Issue describing the change
2. Provide clear context and examples in the issue
3. Reference relevant documentation and APIs

This approach enables effective collaboration with AI coding agents (Claude Code and Roo Code) and ensures high-quality contributions. See the Issue First Approach Guide for detailed guidance.

Code Quality Standards

Please ensure all contributions meet these standards:

• All code passes npm run typecheck, npm run lint, and npm test
• New features include appropriate unit and integration tests
• Code follows the conventions in Code Conventions and Patterns
• Documentation is updated for significant changes

License

MIT