lotus-migration

What this skill does

Covers Forms, Views, Agents, Script Libraries, Formula Language, LotusScript, direct database writes, ODBC connections, and replacement architecture decision frameworks.
# Lotus Notes Migration Skill

## Table of Contents

**Quick Start** → [What Is This](#purpose) | [When to Use](#when-to-use) | [Simple Example](#examples)

**How to Implement** → [Step-by-Step](#instructions) | [Expected Outcomes](#quick-start)

**Reference** → [Requirements](#requirements) | [Related Skills](#see-also)

## Purpose

This skill helps architects, developers, and technical leads analyze Lotus Notes applications, understand their architecture and integration patterns, plan migration strategies, and design modern replacements. It provides frameworks for assessing complexity, identifying dependencies, translating legacy patterns to modern equivalents, and managing the organizational and technical challenges of large-scale Notes migrations.

## When to Use

Use this skill when you need to:

- **Understand Lotus Notes applications** - Analyze NSF structure, design elements, Forms, Views, Agents, and Script Libraries
- **Identify integration points** - Map all inbound/outbound integrations, ODBC connections, and data flows
- **Plan migration strategies** - Choose between API integration, message queues, file staging, or event sourcing
- **Translate Notes concepts** - Convert Formula Language, LotusScript, or Notes patterns to modern equivalents
- **Assess migration complexity** - Evaluate risks, dependencies, and effort required for migration
- **Design replacement architecture** - Create modern system designs that replace legacy Notes functionality
- **Manage stakeholder expectations** - Plan phased migrations with testing, rollback, and communication strategies

This skill provides comprehensive guidance for all aspects of Lotus Notes migration projects.

## Quick Start

Use this skill when you need to:

1. **Understand a Lotus Notes application** - Analyze NSF structure, design elements, and how they work
2. **Identify integrations** - Map all inbound/outbound integration points and data flows
3. **Choose a replacement strategy** - Evaluate API integration, message queues, file staging, event sourcing, or hybrid approaches
4. **Plan a migration** - Design phased approach with testing, rollback, and stakeholder management
5. **Translate Notes concepts** - Convert Formula Language, LotusScript, or Notes patterns to modern equivalents

**Example Use Cases:**
- "Analyze the Product Incidents Lotus Notes application to understand its database writes to B&O"
- "Identify all ODBC connections in the VRS configuration database and plan replacement"
- "Design an API specification to replace a direct database integration from Delivery Standards"
- "Extract rich text fields from reference database and plan data migration strategy"

## Instructions

### Step 1: Gather Application Details

Before planning any migration, establish baseline understanding:

1. **Identify the application**
   - Application name and primary purpose
   - Owner and technical maintainer
   - Users and usage volume
   - Strategic importance (critical path, legacy, sunset?)

2. **Document the NSF structure**
   - Database name and path
   - Design elements present:
     - Forms (data entry/display structures)
     - Views (how data is displayed/filtered)
     - Agents (scheduled or manual automation)
     - Script Libraries (reusable code)
     - Design resources (images, CSS, HTML)
   - Data volume and growth rate
   - User count and access patterns

3. **Review existing documentation**
   - Design documentation (if available)
   - Business process documentation
   - Known issues or workarounds
   - Technical debt areas

**Questions to Ask:**
- What business process does this application support?
- Who depends on this application?
- What data sensitivity/compliance requirements exist?
- When was the application last updated?
- Are there plans to replace or sunset it?

### Step 2: Map All Integration Points

Integration patterns are the primary concern in Notes migrations because they determine replacement complexity:

1. **Identify inbound integrations** (data flowing INTO the Notes app)
   - Direct database writes (from other apps)
   - File uploads (CSV, XML, Excel)
   - ODBC connections (reading external databases)
   - Email triggers
   - Web service calls
   - Message queue consumption
   - Replication from other Notes databases

2. **Identify outbound integrations** (data flowing OUT of Notes app)
   - Direct database writes (to other apps/databases)
   - File exports (Oracle Finance, PDP, data warehouses)
   - ODBC writes (to external databases)
   - Email notifications/reminders
   - API calls
   - Report generation
   - Replication to other Notes databases

3. **Document each integration**
   - **What:** What data is transferred?
   - **Where:** Source and destination systems
   - **How:** Technology/method used
   - **When:** Frequency, schedule, or trigger
   - **Volume:** Data volume, frequency, peak times
   - **Dependencies:** What breaks if this fails?
   - **Error Handling:** How are errors detected/resolved?

4. **Create integration map** using this format:
   ```
   | Integration | Direction | Type | Source/Dest | Frequency | Volume | Critical? |
   |-------------|-----------|------|------------|-----------|--------|-----------|
   | Direct DB Write | Inbound | Database | Product Incidents → B&O | On-demand | ~50/day | YES |
   | ODBC Lookup | Inbound | Query | VRS → Mainframe DB2 | Per transaction | ~1000/day | YES |
   | File Export | Outbound | File | B&O → Oracle Finance | Daily batch | ~2000 records | CRITICAL |
   ```

**See also:** Local documentation at `docs/B&O-Integrations-and-Touchpoints.md`

### Step 3: Analyze Data Structures and Fields

Lotus Notes' document-based, semi-structured approach is fundamentally different from relational databases:

1. **Document structure analysis**
   - What document types exist in the database?
   - What fields are mandatory vs. optional?
   - What is the actual data schema (may differ from design)?
   - Are there computed fields or formulas that generate data?
   - What validation formulas exist?

2. **Handle rich text fields**
   - Identify all rich text fields
   - Determine what they contain (formatted text, embedded objects, file attachments)
   - For migration, you'll likely need to:
     - Convert to HTML/Markdown for modern storage
     - Extract file attachments separately
     - Use tools like Genii AppsFidelity for complex conversions
     - Create test data with samples of rich text variations

3. **Address semi-structured data**
   - Document flexibility in schema is a feature, not a bug in Notes
   - For migration, you must decide:
     - Enforce stricter schema in target system?
     - Create flexible storage (JSONB columns, document stores)?
     - Map different document types to different tables?
   - Identify documents that don't fit the primary pattern

4. **Map to modern equivalents**
   - Notes Form → UI Form/API Input Schema
   - Notes View → SQL Query/GraphQL Resolver/API Endpoint
   - Rich Text → HTML + Attachments Storage
   - Formula Field → Computed Field/View/Trigger
   - Document → Database Record/Document in Document Store

### Step 4: Assess Integration Complexity

Not all integrations have equal migration complexity. Use this framework:

**Complexity Level 1: Simple (Low Risk)**
- Direct data consumption (read from file, API, ODBC)
- No write-back requirements
- Data is consistent and well-formed
- Few dependencies
- Example: Readonly reference data lookup

**Complexity Level 2: Moderate (Medium Risk)**
- Bidirectional sync with periodic reconciliation
- Some data transformation required
- Multiple data sources
- Example: VRS configuration sync with monitoring

**Complexity Level 3: Complex (High Risk)**
- Direct database writes (tight coupling)
- Real-time transaction flow
- Rich data transformations
- Multiple s