/integration

Create an Integration note documenting how two systems exchange data, including pattern, protocol, frequency, SLA, and error handling.

Usage

/integration <source-system> <target-system>
/integration SAP DataPlatform
/integration DataPlatform Snowflake --pattern batch
/integration "System - SAP S/4HANA" "System - DataPlatform" --frequency hourly

Instructions

Creates comprehensive Integration notes linking System notes and documenting connection characteristics.

Phase 1: Parse Input & Validate Systems

1. Extract source and target system names
2. Search vault for both systems:

   node scripts/graph-query.js --type System --search "<source>"
   node scripts/graph-query.js --type System --search "<target>"
   

3. If systems not found:
   • "[[System - {{name}}]] not found. Create it first? (Y/n)"
   • Offer to create System notes before Integration
4. If system already integrates, show existing:
   • "Found: [[Integration - SAP to DataPlatform]]. Edit instead? (Y/n)"

Phase 2: Essential Information

Gather required fields:

Creating Integration: {{source}} → {{target}}

1️⃣ Integration Pattern:
   - api-sync (REST/GraphQL synchronous)
   - event-streaming (Kafka/Pub-Sub asynchronous)
   - batch-etl (scheduled bulk data transfer)
   - message-queue (queued messages with processing)
   - file-transfer (SFTP/S3 file exchange)
   - database-replication (direct DB sync)
   Default: api-sync
   User input: [selection]

2️⃣ Protocol:
   (Based on pattern selection, suggest defaults)
   - For api-sync: rest, graphql, soap, odata
   - For event-streaming: kafka, rabbitmq, pubsub
   - For batch-etl: s3, sftp, sql
   Default: [depends on pattern]
   User input: [selection]

3️⃣ Frequency:
   - real-time (< 1 second latency)
   - near-real-time (< 5 minutes)
   - hourly
   - daily
   - weekly
   - on-demand
   Default: daily
   User input: [selection]

4️⃣ Direction:
   - one-way (source → target only)
   - bidirectional (source ↔ target)
   Default: one-way
   User input: [selection]

5️⃣ Criticality:
   - critical (business stops if fails)
   - high (significant impact)
   - medium (moderate impact)
   - low (minimal impact)
   Default: medium
   User input: [selection]

Phase 3: SLA & Performance (Brief)

6️⃣ Availability SLA (%):
   Default: 99.5
   User input: [number 90-99.99]

7️⃣ Maximum acceptable latency:
   For real-time: < 100ms
   For batch: < 5 minutes
   For daily: no constraint
   Default: [based on frequency]
   User input: [optional override]

8️⃣ Data volume (records/second or volume/day):
   Default: null
   User input: [e.g., "500 rec/sec" or "2.5GB/day"]

Phase 4: Middleware & Infrastructure

9️⃣ Does this use middleware?
   (Search for integration platforms)
   - [[System - Kong]] (API Gateway)
   - [[System - Cloud Platform Integration Suite]]
   - [[System - Apache Kafka]]
   - None (direct connection)
   Default: None
   User input: [selection]

Phase 5: Error Handling (Optional)

Ask: "Add error handling details? (Y/n)"

If YES:

- Retry strategy: exponential-backoff | linear-backoff | none
- Max retries: 3
- Dead letter queue: enabled | disabled
- Idempotent: yes | no

Phase 6: Generate Frontmatter

type: Integration
title: "{{source}} → {{target}}"

integrationId: "INT-{{source|upper}}-{{target|upper}}-001"
status: active
version: "1.0.0"

sourceSystem: "[[System - {{source}}]]"
targetSystem: "[[System - {{target}}]]"

pattern: {{pattern}}
protocol: [{{protocol}}]
direction: {{direction}}
criticality: {{criticality}}
frequency: {{frequency}}
latency-sla: "{{latency}}"

middleware: {{middleware|null}}

retryPolicy: exponential-backoff
maxRetries: 3
deadLetterQueue: {{dlq|true}}
idempotency: {{idempotency|true}}

slo: "{{sla}}%"

confidence: medium
freshness: current
verified: false

created: 2026-01-14
modified: 2026-01-14
tags: [type/integration, pattern/{{pattern}}, {{source|lower}}-{{target|lower}}]

Phase 7: Generate Body Content

1. Overview: What data flows and why
2. Data Flow Sequence Diagram: Mermaid sequence showing flow
3. Integration Properties Table: Quick reference
4. Middleware Details: If applicable
5. Protocol & Connection Details: Endpoints, auth, encryption
6. Error Handling: Retry logic, DLQ, monitoring
7. Monitoring & SLA: Health checks, alerts, dashboards
8. Related Architecture: Link to ADRs and Architectures

Phase 8: Update Related Systems

Automatically update both System notes:

1. Add this Integration to source System's connectsTo
2. Add this Integration to target System's connectedFrom
3. Suggest: "Update {{source}} and {{target}} System notes? (Y/n)"

Phase 9: Create File

Filename: Integration - {{source}} to {{target}}.md

Location: Vault root

Output:

✅ Created: Integration - {{source}} to {{target}}.md

Links updated:
- [[System - {{source}}]] → connectsTo added
- [[System - {{target}}]] → connectedFrom added

Next steps:
1. Add data sources: /datasource <name>
2. Generate diagram: /dataflow-diagram [[Project - <name>]]
3. Add to architecture: /architecture --relate-integration <name>

Example Interaction

User: /integration SAP DataPlatform

Skill: Searching for systems...
Found: [[System - SAP S/4HANA]] and [[System - DataPlatform]]

Integration Pattern (default: api-sync):
1. api-sync (REST/GraphQL synchronous)
2. event-streaming (Kafka publish/subscribe)
3. batch-etl (scheduled bulk transfer)
4. message-queue (queued messages)
> 2

Protocol (default: kafka):
> kafka

Frequency (default: daily):
> real-time

Direction (default: one-way):
> one-way

Criticality (default: medium):
> high

Availability SLA (default: 99.5):
> 99.95

Latency (default: < 1 second for real-time):
> < 100ms

Data volume:
> 500 records/second

Middleware:
> None

✅ Created: Integration - SAP to DataPlatform.md

Updated:
- [[System - SAP S/4HANA]] added to connectsTo
- [[System - DataPlatform]] added to connectedFrom

Next: /datasource SAP Invoices