# CreateDomain Tool Documentation

## Overview

The `CreateDomain` tool creates a new ABAP domain in the SAP system through ADT (ABAP Development Tools) API. It executes the complete workflow: lock, create, syntax check, unlock, activate, and verify.

## Architecture Highlights

### Session Management
- **Session ID**: Generated once at the handler level using `crypto.randomUUID()`
- **Scope**: All ADT requests within a single MCP call share the same `sap-adt-connection-id`
- **Request ID**: Each individual ADT request gets a unique `sap-adt-request-id`

### Workflow Steps

```
1. Lock & Create  → PUT /sap/bc/adt/ddic/domains/{name}?lockHandle={handle}&corrNr={transport}
2. Check Syntax   → POST /sap/bc/adt/checkruns
3. Unlock         → POST /sap/bc/adt/ddic/domains/{name}?_action=UNLOCK&lockHandle={handle}
4. Activate       → POST /sap/bc/adt/activation?method=activate&preauditRequested=true
5. Verify         → GET /sap/bc/adt/ddic/domains/{name}?version=workingArea
```

## Input Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `domain_name` | string | ✅ | - | Domain name (e.g., `ZZ_TEST_0001`). Must follow SAP naming conventions |
| `description` | string | ❌ | domain_name | Domain description |
| `package_name` | string | ✅ | - | Package name (e.g., `ZOK_LOCAL`, `$TMP`) |
| `transport_request` | string | ✅ | - | Transport request number (e.g., `E19K905635`) |
| `datatype` | string | ❌ | `CHAR` | Data type: `CHAR`, `NUMC`, `DATS`, `TIMS`, `DEC`, `INT1`, `INT2`, `INT4`, `INT8`, `CURR`, `QUAN` |
| `length` | number | ❌ | 100 | Field length (max depends on datatype) |
| `decimals` | number | ❌ | 0 | Decimal places (for `DEC`, `CURR`, `QUAN` types) |
| `conversion_exit` | string | ❌ | - | Conversion exit routine name (without `CONVERSION_EXIT_` prefix) |
| `lowercase` | boolean | ❌ | false | Allow lowercase input |
| `sign_exists` | boolean | ❌ | false | Field has sign (+/-) |
| `value_table` | string | ❌ | - | Value table name for foreign key relationship |

## Example Usage

### Minimal Request
```json
{
  "domain_name": "ZZ_TEST_0001",
  "package_name": "ZOK_LOCAL",
  "transport_request": "E19K905635"
}
```

### Full Request
```json
{
  "domain_name": "ZZ_CUSTOMER_ID",
  "description": "Customer ID Domain",
  "package_name": "ZCUSTOMER",
  "transport_request": "E19K905635",
  "datatype": "CHAR",
  "length": 10,
  "decimals": 0,
  "conversion_exit": "ALPHA",
  "lowercase": false,
  "sign_exists": false,
  "value_table": "ZCUSTOMERS"
}
```

## Response Format

### Success Response
```json
{
  "success": true,
  "domain_name": "ZZ_TEST_0001",
  "package": "ZOK_LOCAL",
  "transport_request": "E19K905635",
  "status": "active",
  "session_id": "9887bcfa3a564460843569a9efc55981",
  "message": "Domain ZZ_TEST_0001 created and activated successfully",
  "domain_details": {
    "adtcore:name": "ZZ_TEST_0001",
    "adtcore:type": "DOMA/DD",
    "adtcore:version": "active",
    "adtcore:description": "ZZ_TEST_0001",
    "doma:content": {
      "doma:typeInformation": {
        "doma:datatype": "CHAR",
        "doma:length": "000100",
        "doma:decimals": "000000"
      }
    }
  }
}
```

### Error Response
```json
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error: Domain check failed: Syntax error in domain definition"
    }
  ]
}
```

## Error Handling

The tool implements automatic cleanup on errors:

1. **Lock Cleanup**: If any step fails after obtaining a lock, the tool attempts to unlock the domain
2. **Validation**: Required parameters are validated before ADT requests
3. **Syntax Check**: Domain definition is verified before activation
4. **Activation Verification**: Confirms successful activation before returning

## Technical Implementation

### Key Functions

#### `generateSessionId()`
Generates a UUID for the entire MCP call, removing hyphens to match SAP ADT format.

#### `buildDomainXml(args, username)`
Constructs the XML payload for domain creation according to SAP ADT schema `http://www.sap.com/dictionary/domain`.

#### `lockAndCreateDomain(args, sessionId, username)`
Sends PUT request with lock handle and transport request to create the domain.

#### `checkDomainSyntax(domainName, sessionId)`
Validates domain definition using ADT checkrun API.

#### `unlockDomain(domainName, lockHandle, sessionId)`
Releases the lock on the domain object.

#### `activateDomain(domainName, sessionId)`
Activates the domain and performs pre-audit checks.

#### `getDomainForVerification(domainName, sessionId)`
Retrieves the final domain definition to verify successful creation.

## Testing

Run the test script:
```bash
node tests/test-create-domain.js
```

Test parameters can be modified in the script to test different scenarios:
- Different datatypes (CHAR, NUMC, DATS)
- Various lengths and decimals
- Conversion exits
- Value table references

## Known Limitations

1. **Lock Handle**: Currently generates a UUID for lock handle. In production, this should be obtained from an initial GET request to the domain endpoint.
2. **Headers**: The `makeAdtRequestWithTimeout` function needs to be extended to accept custom headers for session/request IDs.
3. **Rollback**: Failed activations leave inactive objects in the system. Consider implementing full rollback (delete) on critical failures.

## Future Enhancements

- [ ] Extend `AbapConnection` to manage session-id automatically
- [ ] Add support for fixed values in domain definition
- [ ] Implement domain modification (update existing domains)
- [ ] Add domain deletion tool
- [ ] Support for append structures in domains
- [ ] Batch domain creation from JSON/CSV

## Related Tools

- `GetTable` - Retrieve table structure (uses domains)
- `GetStructure` - Retrieve structure definition
- `GetTypeInfo` - Get ABAP type information
- `SearchObject` - Find existing domains

## References

- ADT API Research: `doc/ADT_API_RESEARCH.md`
- Domain Creation Flow: `doc/mcp_domain_create.txt`
- SAP ADT Documentation: https://help.sap.com/docs/ABAP_PLATFORM_NEW/