# Roadmap: Usage Documentation for MCP Functions

## Overview

This roadmap outlines the creation of comprehensive usage documentation for creating and modifying ABAP objects through MCP function calls, covering both low-level and high-level handlers.

## Goals

1. ✅ Create structured documentation for object creation and modification workflows
2. ✅ Document CRUD operations for simple objects
3. ⏳ Document complex RAP BO creation scenarios with related objects
4. ✅ Emphasize best practices: code checking before update, deferred group activation

## Documentation Structure

```
doc/user-guide/
├── usage/                          # ✅ Created
│   ├── README.md                   # ✅ Created
│   ├── simple-objects/             # ✅ Created
│   │   ├── README.md               # ✅ Created
│   │   ├── classes-high.md         # ✅ Created
│   │   ├── classes-low.md          # ✅ Created
│   │   ├── interfaces-high.md      # ✅ Created
│   │   ├── interfaces-low.md       # ✅ Created
│   │   ├── programs-high.md         # ✅ Created
│   │   ├── programs-low.md          # ✅ Created
│   │   ├── function-groups-high.md  # ✅ Created
│   │   ├── function-groups-low.md   # ✅ Created
│   │   ├── function-modules-high.md # ✅ Created
│   │   ├── function-modules-low.md  # ✅ Created
│   │   ├── tables-high.md          # ✅ Created
│   │   ├── tables-low.md           # ✅ Created
│   │   ├── structures-high.md      # ✅ Created
│   │   ├── structures-low.md       # ✅ Created
│   │   ├── views-high.md           # ✅ Created
│   │   ├── views-low.md            # ✅ Created
│   │   ├── domains-high.md         # ✅ Created
│   │   ├── domains-low.md          # ✅ Created
│   │   ├── data-elements-high.md  # ✅ Created
│   │   ├── data-elements-low.md    # ✅ Created
│   │   ├── service-definitions-high.md # ✅ Created
│   │   └── service-definitions-low.md  # ✅ Created
│   └── rap-business-objects/       # ⏳ Pending
│       ├── README.md               # ⏳ Pending
│       ├── creating-rap-bo.md      # ⏳ Pending
│       └── deferred-activation.md  # ⏳ Pending
```

## Phase 1: Simple Objects CRUD Documentation ✅ COMPLETED

### Scope
Document CRUD operations for standalone objects that don't have complex dependencies.

### Objects Documented ✅
1. ✅ **Classes** (`CLAS/OC`) - `classes-high.md` / `classes-low.md`
2. ✅ **Interfaces** (`INTF/OI`) - `interfaces-high.md` / `interfaces-low.md`
3. ✅ **Programs** (`PROG/P`) - `programs-high.md` / `programs-low.md`
4. ✅ **Function Groups** (`FUGR`) - `function-groups-high.md` / `function-groups-low.md`
5. ✅ **Function Modules** (`FUGR/FF`) - `function-modules-high.md` / `function-modules-low.md`
6. ✅ **Tables** (`TABL/DT`) - `tables-high.md` / `tables-low.md`
7. ✅ **Structures** (`STRU/DS`) - `structures-high.md` / `structures-low.md`
8. ✅ **CDS Views** (`DDLS/DF`) - `views-high.md` / `views-low.md`
9. ✅ **Domains** (`DOMA/DD`) - `domains-high.md` / `domains-low.md`
10. ✅ **Data Elements** (`DTEL/DE`) - `data-elements-high.md` / `data-elements-low.md`
11. ✅ **Service Definitions** (`SRVD/SRVD`) - `service-definitions-high.md` / `service-definitions-low.md`

### Documentation Format ✅

Each object has **two separate files**:
- **`<object>-high.md`**: High-level handler usage (single function call)
- **`<object>-low.md`**: Low-level handler usage (step-by-step workflow)

**Format:**
- Compact, laconic style
- Only exact MCP function calls with parameters
- No unnecessary descriptions
- Clear, no confusion

**Low-Level Workflow (Standard Pattern):**
1. `GetSession` - Obtain session
2. `Validate<Object>Low` - Validate object name
3. `Create<Object>Low` - Create object
4. `Lock<Object>Low` - Lock for modification
5. `Check<Object>Low` - **Check code BEFORE update** (CRITICAL)
6. `Update<Object>Low` - Update object (only if check passed)
7. `Unlock<Object>Low` - Release lock
8. `Check<Object>Low` - Check inactive version after unlock
9. `Activate<Object>Low` or `ActivateObjectLow` - Activate

## Phase 2: RAP Business Objects Documentation ⏳ PENDING

### Scope
Document creation of complete RAP Business Objects with all related objects and dependencies.

### RAP BO Components to Document

1. **Domains** (`DOMA/DD`)
   - Base data types
   - Value ranges
   - Documentation

2. **Data Elements** (`DTEL/DE`)
   - Based on domains
   - Field labels
   - Documentation

3. **Tables** (`TABL/DT`)
   - Root entity table
   - Field definitions using data elements
   - Primary keys
   - Foreign keys

4. **Draft Tables** (`TABL/DT`)
   - Draft-enabled tables
   - Relationship to root table

5. **CDS Views** (`DDLS/DF`)
   - Interface view (projection)
   - Consumption view
   - Composite structures
   - Associations

6. **Behavior Definitions** (`BDEF/BD`)
   - Behavior definition
   - Draft enabled
   - Actions, validations, determinations

7. **Behavior Implementations** (`BDEF/BDO`)
   - Implementation classes
   - Save, modify, delete handlers

8. **Metadata Extensions** (`DDLX/EX`)
   - UI annotations
   - Field labels
   - Field visibility

9. **Service Definitions** (`SRVD/SRVD`)
   - Service binding
   - Service version

### Documentation Structure

#### 1. Overview Section
- What is a RAP BO
- Component relationships
- Creation order and dependencies
- Deferred activation concept

#### 2. Complete RAP BO Creation Workflow

**Step-by-step process:**

1. **Create Domains**
   - Create all required domains
   - **Do NOT activate yet** (deferred activation)

2. **Create Data Elements**
   - Create data elements based on domains
   - **Do NOT activate yet** (deferred activation)

3. **Create Root Table**
   - Create table with fields using data elements
   - Define primary key
   - **Do NOT activate yet** (deferred activation)

4. **Create Draft Table**
   - Create draft table
   - Link to root table
   - **Do NOT activate yet** (deferred activation)

5. **Create CDS Interface View**
   - Create interface CDS view
   - Reference root table
   - Define associations
   - **Do NOT activate yet** (deferred activation)

6. **Create CDS Consumption View**
   - Create consumption view
   - Use composite structure if needed
   - **Do NOT activate yet** (deferred activation)

7. **Create Behavior Definition**
   - Define behavior
   - Enable draft
   - **Do NOT activate yet** (deferred activation)

8. **Create Behavior Implementation**
   - Implement behavior handlers
   - **Do NOT activate yet** (deferred activation)

9. **Create Metadata Extension**
   - Add UI annotations
   - **Do NOT activate yet** (deferred activation)

10. **Deferred Group Activation**
    - Activate all related objects together
    - Use `ActivateObjectLow` with multiple objects
    - Handle activation errors

11. **Create Service Definition**
    - Create service definition
    - Bind to CDS view
    - Activate service definition

#### 3. Low-Level vs High-Level Approach

**Using Low-Level Handlers:**
- Full control over each step
- Explicit session management
- **Must check code before each update**
- Manual deferred activation

**Using High-Level Handlers:**
- Simpler workflow
- Automatic session management
- Built-in code checking
- **Still need deferred activation for related objects**

#### 4. Deferred Group Activation Guide

**Why Deferred Activation?**
- Related objects have dependencies
- Activating individually can cause errors
- Group activation ensures consistency
- Better error handling

**How to Use:**
- Create all objects without activation
- Collect all object references
- Use `ActivateObjectLow` with array of objects
- Handle activation errors and warnings

**Example:**
```json
{
  "objects": [
    { "name": "ZDOMAIN_001", "type": "DOMA/DD" },
    { "name": "ZDTEL_001", "type": "DTEL/DE" },
    { "name": "ZTABL_001", "type": "TABL/DT" },
    { "name": "ZCDS_001", "type": "DDLS/DF" }
  ],
  "preaudit": true
}
```

## Phase 3: Critical Best Practices Documentation ✅ INTEGRATED

### Code Checking Before Update ✅

**Why it's critical:**
- Prevents syntax errors from being saved
- Catches errors early in the workflow
- Required when using low-level handlers

**Workflow (documented in all low-level files):**
1. Lock object
2. **Check new code** (with `sourceCode`/`ddlCode` and `version='inactive'` or `version='new'`)
3. **Only update if check passes**
4. Unlock object
5. Check inactive version (after unlock, without sourceCode)
6. Activate (if needed)

### Deferred Group Activation for Related Objects ✅

**When to use:**
- Objects with dependencies (domains → data elements → tables)
- Composite structures
- RAP BO components
- Any related objects created together

**Pattern (documented in all low-level files):**
1. Create all objects without activation
2. Collect object references
3. Activate as a group using `ActivateObjectLow`
4. Handle activation results

## Implementation Tasks

### Task 1: Create Folder Structure ✅
- [x] Create `doc/user-guide/usage/` folder
- [x] Create `doc/user-guide/usage/simple-objects/` folder
- [x] Create `doc/user-guide/usage/rap-business-objects/` folder

### Task 2: Create README Files ✅
- [x] Create `usage/README.md` with overview
- [x] Create `usage/simple-objects/README.md`
- [ ] Create `usage/rap-business-objects/README.md`

### Task 3: Document Simple Objects (11 objects) ✅
- [x] classes-high.md / classes-low.md
- [x] interfaces-high.md / interfaces-low.md
- [x] programs-high.md / programs-low.md
- [x] function-groups-high.md / function-groups-low.md
- [x] function-modules-high.md / function-modules-low.md
- [x] tables-high.md / tables-low.md
- [x] structures-high.md / structures-low.md
- [x] views-high.md / views-low.md
- [x] domains-high.md / domains-low.md
- [x] data-elements-high.md / data-elements-low.md
- [x] service-definitions-high.md / service-definitions-low.md

**Total: 22 files created (11 objects × 2 files each)**

### Task 4: Document RAP BO Creation ⏳
- [ ] creating-rap-bo.md (complete workflow)
- [ ] deferred-activation.md (detailed guide)

### Task 5: Update Main Documentation ⏳
- [ ] Update `doc/user-guide/README.md` to reference new usage folder
- [ ] Update `doc/user-guide/scenarios/README.md` to distinguish from usage docs

## Documentation Standards ✅

### Code Examples ✅
- ✅ Include both high-level and low-level examples (separate files)
- ✅ Show complete request/response JSON (compact format)
- ✅ Use realistic object names (following SAP conventions)
- ✅ Compact, laconic style - only exact MCP calls

### Structure ✅
- ✅ Clear separation: high-level vs low-level
- ✅ Step-by-step workflows in low-level files
- ✅ No unnecessary descriptions
- ✅ Maximum clarity, no confusion

### Language ✅
- ✅ All documentation in English
- ✅ Clear, concise format
- ✅ Technical accuracy
- ✅ Practical examples

## Progress Summary

### ✅ Completed
- **Phase 1**: All 11 simple objects documented (22 files total)
- **Phase 3**: Best practices integrated into all documentation
- Folder structure created
- README files created

### ⏳ Pending
- **Phase 2**: RAP BO documentation
  - creating-rap-bo.md
  - deferred-activation.md
  - rap-business-objects/README.md
- Main documentation updates

## Notes

- All examples use compact JSON format (single line)
- Each object has separate high/low files for maximum clarity
- Code checking before update is emphasized in all low-level files
- Group activation examples included in all low-level files
- Documentation follows "exact MCP calls only" principle