From f7e6b835303921c06089c46b670540da590bced7 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:55:05 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + SKILL.md | 331 ++++++++++++++ plugin.lock.json | 109 +++++ references/adapters.md | 429 ++++++++++++++++++ references/api-management.md | 474 ++++++++++++++++++++ references/cloud-integration.md | 431 ++++++++++++++++++ references/content-transport.md | 388 ++++++++++++++++ references/data-space-integration.md | 413 +++++++++++++++++ references/edge-integration-cell.md | 332 ++++++++++++++ references/event-mesh.md | 385 ++++++++++++++++ references/graph-odata.md | 375 ++++++++++++++++ references/integration-advisor-tpm.md | 389 ++++++++++++++++ references/migration-assessment.md | 396 +++++++++++++++++ references/operations-monitoring.md | 456 +++++++++++++++++++ references/scripting.md | 562 ++++++++++++++++++++++++ references/security.md | 427 ++++++++++++++++++ references/troubleshooting.md | 437 ++++++++++++++++++ templates/api-policy-template.xml | 381 ++++++++++++++++ templates/groovy-script-template.groovy | 249 +++++++++++ 20 files changed, 6979 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 plugin.lock.json create mode 100644 references/adapters.md create mode 100644 references/api-management.md create mode 100644 references/cloud-integration.md create mode 100644 references/content-transport.md create mode 100644 references/data-space-integration.md create mode 100644 references/edge-integration-cell.md create mode 100644 references/event-mesh.md create mode 100644 references/graph-odata.md create mode 100644 references/integration-advisor-tpm.md create mode 100644 references/migration-assessment.md create mode 100644 references/operations-monitoring.md create mode 100644 references/scripting.md create mode 100644 references/security.md create mode 100644 references/troubleshooting.md create mode 100644 templates/api-policy-template.xml create mode 100644 templates/groovy-script-template.groovy diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..6e544ee --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "sap-btp-integration-suite", + "description": "Enterprise integration with SAP Integration Suite. Covers Cloud Integration iFlows, API Management, Event Mesh, Trading Partner Management, and integration adapters.", + "version": "1.0.0", + "author": { + "name": "Zhongwei Li", + "email": "zhongweili@tubi.tv" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d16d07 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# sap-btp-integration-suite + +Enterprise integration with SAP Integration Suite. Covers Cloud Integration iFlows, API Management, Event Mesh, Trading Partner Management, and integration adapters. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..c05d78c --- /dev/null +++ b/SKILL.md @@ -0,0 +1,331 @@ +--- +name: sap-btp-integration-suite +description: | + Develops and operates enterprise integration solutions using SAP Integration Suite on Business Technology Platform. + Covers Cloud Integration (iFlows), API Management, Event Mesh, Edge Integration Cell, Integration Advisor, + Trading Partner Management, Graph, OData Provisioning, Integration Assessment, and Migration Assessment. + + Use this skill when: + - Building integration flows (iFlows) to connect applications + - Creating, managing, or debugging API proxies and policies + - Implementing event-driven architectures with Event Mesh + - Setting up B2B/EDI integrations with Trading Partner Management + - Deploying hybrid integrations with Edge Integration Cell + - Migrating from SAP Process Orchestration (PO/PI) + - Configuring adapters (SFTP, HTTP, OData, RFC, AMQP, Kafka, etc.) + - Writing Groovy/JavaScript scripts for message processing + - Troubleshooting integration errors and monitoring message flows + + Keywords: sap integration suite, cloud integration, cpi, scpi, sap cpi, iflow, integration flow, + api management, apim, api proxy, api policy, developer hub, developer portal, event mesh, + edge integration cell, integration advisor, trading partner management, tpm, b2b integration, + edi integration, migration assessment, integration assessment, isa-m, graph, odata provisioning, + sap btp integration, cloud platform integration, message mapping, groovy script, adapter configuration, + content modifier, splitter, aggregator, router, sftp adapter, http adapter, odata adapter, rfc adapter, + amqp adapter, kafka adapter, jms queue, data store, idempotent processing, exactly once + +license: GPL-3.0 +metadata: + version: 1.1.0 + last_verified: 2025-11-27 + documentation_source: [https://github.com/SAP-docs/sap-btp-integration-suite](https://github.com/SAP-docs/sap-btp-integration-suite) + sap_help_portal: [https://help.sap.com/docs/integration-suite](https://help.sap.com/docs/integration-suite) + status: production + token_savings: ~65-80% + +allowed-tools: + - Read + - Bash + - Glob + - Grep + - WebFetch + - WebSearch +--- + +# SAP BTP Integration Suite Development + +## Quick Reference + +| Capability | Purpose | Key Artifact | +|------------|---------|--------------| +| Cloud Integration | A2A/B2B/B2G integration | Integration Flow (iFlow) | +| API Management | API lifecycle & governance | API Proxy | +| Event Mesh | Event-driven architecture | Topics & Queues | +| Edge Integration Cell | Hybrid deployment | Kubernetes runtime | +| Integration Advisor | B2B mapping automation | MIG/MAG | +| Trading Partner Management | Partner onboarding | Agreements | +| Graph | Unified data API | Business Data Graph | +| Integration Assessment | Technology selection | ISA-M | +| Migration Assessment | PO migration planning | Extraction & Analysis | + +--- + +## Capability Overview + +### Cloud Integration +Build and run integration flows across cloud, on-premise, and hybrid landscapes for A2A, B2B, and B2G scenarios. Supports 80+ adapters and real-time message processing. + +**Core Components**: +- Integration Flows (iFlows) - Visual message processing pipelines +- Adapters - Protocol/application connectors (SFTP, HTTP, OData, RFC, AMQP, Kafka, etc.) +- Message Mapping - Graphical/XSLT/Groovy transformations +- Data Stores & Variables - Persistence for stateful processing +- Security Material - Keystores, credentials, PGP keys + +### API Management +Complete API lifecycle management with security, traffic control, and developer engagement. + +**Core Components**: +- API Proxies - Facade layer for backend services +- Policies (34 types) - Security, traffic, mediation rules +- Developer Hub - API portal for developers +- Products - API bundles with access control +- Analytics - Usage metrics and insights + +### Event Mesh +Publish and consume business events across your enterprise ecosystem for event-driven architectures. + +### Edge Integration Cell +Hybrid runtime for processing data within private landscapes while designing in the cloud. Deploy on Kubernetes (EKS, AKS, GKE, OpenShift, RKE2). + +### Integration Advisor +AI-powered B2B content development supporting UN/EDIFACT, SAP IDoc, ASC X12. Creates Message Implementation Guidelines (MIGs) and Mapping Guidelines (MAGs). + +### Trading Partner Management +Streamline B2B relationships with partner profiles, agreement templates, and automated runtime artifact generation. Supports AS2, SFTP, FTP protocols. + +--- + +## Cloud Integration Development + +### Integration Flow Structure + +``` +Sender → [Adapter] → Integration Process → [Adapter] → Receiver + ↓ + ┌────────────┴────────────┐ + │ Message Processing │ + │ - Content Modifier │ + │ - Router/Filter │ + │ - Mapping │ + │ - Splitter/Aggregator │ + │ - Script │ + │ - External Call │ + └─────────────────────────┘ +``` + +### Common Flow Steps + +| Category | Steps | +|----------|-------| +| Routing | Router, Filter, Multicast, Recipient List | +| Transformation | Content Modifier, Mapping, Converter, Script | +| Splitting | General Splitter, Iterating Splitter, EDI Splitter | +| Persistence | Data Store, Write Variable, JMS Send | +| External | Request Reply, Send, Poll Enrich, Content Enricher | +| Security | Encryptor, Decryptor, Signer, Verifier | +| Error Handling | Exception Subprocess, Escalation Event | + +### Adapter Categories + +**Protocol Adapters**: HTTP, HTTPS, SFTP, FTP, AMQP, JMS, Kafka, AS2, AS4, SOAP, OData +**Application Adapters**: SuccessFactors, Ariba, Salesforce, ServiceNow, Workday +**Database Adapters**: JDBC (Oracle, SQL Server, PostgreSQL, HANA, DB2) +**Cloud Adapters**: AWS (S3, SQS, SNS), Azure (Service Bus, Storage), Google Cloud + +### Scripting Guidelines + +**Prefer standard steps over scripts**. When scripting is necessary: + +```groovy +// Access message body +def body = message.getBody(String.class) + +// Access headers +def header = message.getHeader("HeaderName", String.class) + +// Access properties +def prop = message.getProperty("PropertyName") + +// Modify body +message.setBody(newBody) + +// Add header +message.setHeader("NewHeader", "value") + +// Logging (use SLF4J) +def log = org.slf4j.LoggerFactory.getLogger("script") +log.info("Processing message") +``` + +**Best Practices**: +- Use `XmlSlurper.parse(Object)` instead of `parseText(String)` for large payloads +- Use `StringBuilder` for string concatenation +- Never use `TimeZone.setDefault()` (VM-wide impact) +- Never write credentials to headers (tracing exposes them) + +--- + +## API Management Development + +### API Proxy Structure + +``` +Client → Proxy Endpoint → [Policies] → Target Endpoint → Backend + ↓ ↓ + PreFlow PreFlow + Conditional Flows Conditional Flows + PostFlow PostFlow + ↓ ↓ + Fault Rules Fault Rules +``` + +### Policy Categories + +| Category | Policies | +|----------|----------| +| Security | OAuth 2.0, Verify API Key, Basic Auth, SAML, Access Control | +| Traffic | Quota, Spike Arrest, Concurrent Rate Limit, Response Cache | +| Mediation | Assign Message, Extract Variables, JSON/XML Transform, XSL Transform | +| Extension | JavaScript, Python Script, Service Callout | +| Threat Protection | JSON/XML Threat Protection, Regular Expression Protection | +| Logging | Message Logging, Statistics Collector | + +### Common Policy Attributes + +```xml + + + +``` + +--- + +## Message Quality of Service + +### Exactly-Once Processing + +Use when duplicates must be prevented: + +1. **JMS Queues** - Transactional message storage +2. **Idempotent Process Call** - Duplicate detection via ID mapping +3. **Data Store** - Persistent message tracking + +### Idempotent Pattern + +``` +Sender → [ID Mapping] → Check Duplicate → Process → [ID Mapping Complete] + ↓ (duplicate) + Return Cached Response +``` + +--- + +## Edge Integration Cell + +### Deployment Requirements + +- Kubernetes cluster (EKS, AKS, GKE, OpenShift, RKE2) +- Minimum: 4 worker nodes, 4 vCPU, 16GB RAM each +- Storage: 100GB+ persistent volume +- Network: Ingress controller, DNS configuration + +### Workflow + +1. Activate Edge Integration Cell in Integration Suite +2. Prepare Kubernetes cluster (platform-specific) +3. Deploy Edge Lifecycle Management Bridge +4. Deploy Edge Integration Cell solution +5. Configure keystore synchronization +6. Deploy integration content + +--- + +## Troubleshooting + +### Common Issues + +| Issue | Resolution | +|-------|------------| +| Adapter connection failed | Check credentials, firewall, Cloud Connector | +| Message mapping error | Validate source/target structures, check XPath | +| Timeout | Increase adapter timeout, optimize mapping | +| Memory issues | Stream large payloads, reduce logging | +| Duplicate messages | Implement idempotent processing | +| Keystore sync failed | Verify certificate validity, check permissions | + +### Monitoring Hierarchy + +``` +Integration Suite → Monitor → Integrations and APIs + ├── Message Processing → All Integration Flows + ├── Manage Integration Content → Deployed Artifacts + ├── Manage Security → Keystores, Credentials + └── Manage Stores → Data Stores, Variables, Queues +``` + +--- + +## Limits Reference + +| Resource | Limit | +|----------|-------| +| Integration flows per tenant | Varies by plan | +| JMS queues | 30 per tenant (standard) | +| Data stores | 100MB total storage | +| Message processing log retention | 30 days | +| Attachment size | 40MB | +| API proxies (APIM) | Based on service plan | +| Business data graphs | 500/account, 50/subaccount | + +--- + +## Bundled Resources + +### Reference Documentation +Detailed guides available in `references/` directory: + +**Core Development**: +- `cloud-integration.md` - iFlow development, steps, patterns, best practices +- `adapters.md` - All 80+ adapter configurations (HTTP, SFTP, OData, RFC, etc.) +- `scripting.md` - Groovy/JavaScript patterns, APIs, and templates +- `api-management.md` - API proxy development, 34 policies, Developer Hub +- `security.md` - Authentication, keystores, certificates, credentials + +**Capabilities**: +- `edge-integration-cell.md` - Hybrid Kubernetes deployment guide +- `event-mesh.md` - Topics, queues, brokers, webhooks, EDA patterns +- `integration-advisor-tpm.md` - B2B integration, MIGs, MAGs, partner management +- `graph-odata.md` - Business Data Graph, OData provisioning +- `data-space-integration.md` - Catena-X, EDC, sovereign data exchange +- `migration-assessment.md` - PO migration, ISA-M, technology mapping + +**Operations**: +- `operations-monitoring.md` - Message monitoring, stores, connectivity tests +- `content-transport.md` - TMS, CTS+, MTAR, manual export/import +- `troubleshooting.md` - Error resolution, diagnostics, HTTP error catalog + +### Templates +Ready-to-use templates in `templates/` directory: +- `groovy-script-template.groovy` - Common script patterns +- `api-policy-template.xml` - Policy configuration template + +--- + +## Documentation Links + +### Official Sources +- **GitHub Repository**: [https://github.com/SAP-docs/sap-btp-integration-suite](https://github.com/SAP-docs/sap-btp-integration-suite) +- **SAP Help Portal**: [https://help.sap.com/docs/integration-suite](https://help.sap.com/docs/integration-suite) +- **SAP Community**: [https://community.sap.com/topics/cloud-platform-integration-suite](https://community.sap.com/topics/cloud-platform-integration-suite) +- **SAP Business Accelerator Hub**: [https://api.sap.com/](https://api.sap.com/) + +### Capability-Specific +- **Cloud Integration**: [https://help.sap.com/docs/cloud-integration](https://help.sap.com/docs/cloud-integration) +- **API Management**: [https://help.sap.com/docs/sap-api-management](https://help.sap.com/docs/sap-api-management) +- **Event Mesh**: [https://help.sap.com/docs/event-mesh](https://help.sap.com/docs/event-mesh) +- **Integration Advisor**: [https://help.sap.com/docs/integration-advisor](https://help.sap.com/docs/integration-advisor) + +### Release Notes +- **What's New**: Check `what-s-new-for-sap-integration-suite-79cd682.md` in documentation +- **Patch Releases**: Check `patch-release-notes-for-sap-integration-suite-58595b5.md` diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..563c38a --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,109 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:secondsky/sap-skills:skills/sap-btp-integration-suite", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "d32967239c085f6b35a73c21a467a0c0459c6688", + "treeHash": "57b19127f1f3bd6fd5c9974f38fb1d372b64a833d4562ed6e89e754dc21aa748", + "generatedAt": "2025-11-28T10:28:12.606172Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "sap-btp-integration-suite", + "description": "Enterprise integration with SAP Integration Suite. Covers Cloud Integration iFlows, API Management, Event Mesh, Trading Partner Management, and integration adapters.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "a42c5ff036c89ac69a24dea1c7b3d4b7cf7182a3513ecfc7893ebec14d29850a" + }, + { + "path": "SKILL.md", + "sha256": "0a246dad3db4985d971beb49656af775ba4f8363f255ff005ddc31960a9863fe" + }, + { + "path": "references/operations-monitoring.md", + "sha256": "68a45b557701092a796e03b7575a5230708803e166031ef9f03b294387d7631a" + }, + { + "path": "references/content-transport.md", + "sha256": "1ef256e958d032b1fbbf4988fc6b3d1956a749646dc10bd9420f531b5e17daf7" + }, + { + "path": "references/integration-advisor-tpm.md", + "sha256": "ddede9e36a6aac99fadf78a66f1dbd49079597a820d4982c093e9f26b6cfb5b9" + }, + { + "path": "references/troubleshooting.md", + "sha256": "0acd7b862ba8c2a62f3d2f77b06b763caea99006f55c87cd54460db45dc7ae2c" + }, + { + "path": "references/edge-integration-cell.md", + "sha256": "6c7180762ef20e9e51d70174a9f5f8fd347ac0b02c89dd521e936eb8b79294b9" + }, + { + "path": "references/data-space-integration.md", + "sha256": "b072f6c096ab8e8575fc2501a2f1d678f6a1c8517ea7d0c2bf5cf17d3be1b600" + }, + { + "path": "references/adapters.md", + "sha256": "d0f833ec003f9737b4d8960b8b34e1045e7d95733f268138a25add07ba7ced87" + }, + { + "path": "references/migration-assessment.md", + "sha256": "2e8b9e421bbaab3dfef5741dfca86cbe45314fcbc3bc42a766e9d68d54042e65" + }, + { + "path": "references/api-management.md", + "sha256": "73ae1a04a9a2ef1fb97391e1a83d3385a772bec35d9ee1f6e614500af8dbd8a4" + }, + { + "path": "references/event-mesh.md", + "sha256": "d6e2605a1f05ecb15e899a0eb6d59c2abd42e31bd73219aa929fbfbd16bb251f" + }, + { + "path": "references/cloud-integration.md", + "sha256": "b47a7dd7fc61d61e2023a885f53c0c453d5d5daa444afa786aa26e6f48c5044f" + }, + { + "path": "references/graph-odata.md", + "sha256": "9d82365403138f2ecf57cacf1ac7d289717d5c841cd9ad08866ec08d36581dd9" + }, + { + "path": "references/scripting.md", + "sha256": "3030d01cd197e36c62768b75d31b37c723adb0ca7b57e88840e5634a370b2130" + }, + { + "path": "references/security.md", + "sha256": "7d6f3252cf78842da36d80fb5ce5bb17e9cb600b715c3a4297baa61359042a42" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "8d60ac679b8a9e58e76456ec8283088d6559a6ece1e94fbcd86c949eb61bc156" + }, + { + "path": "templates/groovy-script-template.groovy", + "sha256": "9e73f3879ea4a907187fff170414c85212fef3be398b9b18a0c65ae334a1b997" + }, + { + "path": "templates/api-policy-template.xml", + "sha256": "82b807c4102832782d8ad4eb140e84bb4a344c4ec4367be4afa05e194edbe251" + } + ], + "dirSha256": "57b19127f1f3bd6fd5c9974f38fb1d372b64a833d4562ed6e89e754dc21aa748" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/references/adapters.md b/references/adapters.md new file mode 100644 index 0000000..b72f015 --- /dev/null +++ b/references/adapters.md @@ -0,0 +1,429 @@ +# Adapters - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Protocol Adapters](#protocol-adapters) +3. [Application Adapters](#application-adapters) +4. [Database Adapters](#database-adapters) +5. [Cloud Platform Adapters](#cloud-platform-adapters) +6. [B2B Adapters](#b2b-adapters) +7. [Adapter Development Kit](#adapter-development-kit) + +--- + +## Overview + +SAP Integration Suite provides 80+ adapters for connectivity: +- **Protocol Adapters**: Technical protocol support +- **Application Adapters**: SAP and non-SAP applications +- **Database Adapters**: Direct database connectivity +- **Cloud Platform Adapters**: Cloud services (AWS, Azure, GCP) +- **B2B Adapters**: EDI/B2B communication standards + +Additionally, 170+ **Open Connectors** provide API-based access to SaaS applications. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/connectivity-options-93d82e8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/connectivity-options-93d82e8.md) + +--- + +## Protocol Adapters + +### HTTP/HTTPS Adapter + +**Sender (HTTPS)**: +| Parameter | Description | +|-----------|-------------| +| Address | Endpoint path (e.g., `/myflow`) | +| Authorization | Basic, Client Certificate, OAuth | +| CSRF Protection | Enable/disable CSRF token validation | + +**Receiver (HTTP)**: +| Parameter | Description | +|-----------|-------------| +| Address | Target URL | +| Proxy Type | Internet, On-Premise (Cloud Connector) | +| Method | GET, POST, PUT, DELETE, PATCH | +| Authentication | Basic, OAuth, Client Certificate | +| Timeout | Connection timeout in ms | + +**Documentation**: +- Sender: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/https-sender-adapter-0ae4a78.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/https-sender-adapter-0ae4a78.md) +- Receiver: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/http-receiver-adapter-2da452e.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/http-receiver-adapter-2da452e.md) + +### SFTP Adapter + +**Sender**: +| Parameter | Description | +|-----------|-------------| +| Host | SFTP server hostname | +| Port | Default: 22 | +| Directory | Source directory path | +| File Name | Pattern (e.g., `*.xml`) | +| Authentication | User/Password, Public Key | +| Post-Processing | Delete, Move, Archive | +| Scheduler | Poll interval | + +**Receiver**: +| Parameter | Description | +|-----------|-------------| +| Host | SFTP server hostname | +| Directory | Target directory path | +| File Name | Output filename (supports headers) | +| Authentication | User/Password, Public Key | +| Handling | Append, Overwrite, Fail | + +**Documentation**: +- Sender: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-sftp-sender-adapter-2de9ee5.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-sftp-sender-adapter-2de9ee5.md) +- Receiver: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-sftp-receiver-adapter-4ef52cf.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-sftp-receiver-adapter-4ef52cf.md) + +### FTP Adapter + +Similar to SFTP but for non-secure FTP connections. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/ftp-adapter-4464f89.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/ftp-adapter-4464f89.md) + +### SOAP Adapter + +**Variants**: +- SOAP 1.x (standard SOAP) +- SOAP SAP RM (reliable messaging) + +**Key Settings**: +| Parameter | Description | +|-----------|-------------| +| Address | WSDL URL or endpoint | +| Service | Service name from WSDL | +| Endpoint | Port/binding selection | +| Authentication | Basic, Certificate, OAuth | +| WS-Security | Signing, encryption options | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-soap-soap-1-x-receiver-adapter-57f7b34.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-soap-soap-1-x-receiver-adapter-57f7b34.md) + +### OData Adapter + +**Sender (OData V2)**: +| Parameter | Description | +|-----------|-------------| +| Address | OData service root URL | +| Operations | GET, POST, PUT, DELETE | +| Query Options | $filter, $select, $expand | +| Pagination | Handle large result sets | + +**Receiver (OData V2/V4)**: +| Parameter | Description | +|-----------|-------------| +| Address | OData service URL | +| Resource Path | Entity set path | +| Operation | Query, Create, Update, Delete | +| Authentication | Basic, OAuth, Certificate | + +**Documentation**: +- V2: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-odata-v2-receiver-adapter-c5c2e38.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-odata-v2-receiver-adapter-c5c2e38.md) +- V4: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-odata-v4-receiver-adapter-cd66a12.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-odata-v4-receiver-adapter-cd66a12.md) + +### RFC Adapter + +Connect to SAP ABAP systems via RFC. + +| Parameter | Description | +|-----------|-------------| +| Destination | RFC destination name | +| Function Module | BAPI/FM name | +| Connection | Via Cloud Connector | +| Authentication | User/Password | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/rfc-receiver-adapter-5c76048.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/rfc-receiver-adapter-5c76048.md) + +### IDoc Adapter + +Send/receive SAP IDocs. + +**Sender**: +- Receives IDocs from SAP systems +- Supports IDoc packaging + +**Receiver**: +- Sends IDocs to SAP systems +- Supports exactly-once delivery + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/idoc-adapter-6042250.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/idoc-adapter-6042250.md) + +### Mail Adapter + +**Sender** (IMAP/POP3): +| Parameter | Description | +|-----------|-------------| +| Host | Mail server | +| Protocol | IMAP, POP3 | +| Folder | Inbox or specific folder | +| Authentication | User/Password, OAuth | +| Post-Processing | Delete, Mark as Read, Move | + +**Receiver** (SMTP): +| Parameter | Description | +|-----------|-------------| +| Host | SMTP server | +| From/To | Email addresses | +| Subject | Email subject | +| Body | Message content | +| Attachments | Include attachments | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/mail-adapter-f1145cc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/mail-adapter-f1145cc.md) + +--- + +## Messaging Adapters + +### JMS Adapter + +Internal message queuing. + +| Parameter | Description | +|-----------|-------------| +| Queue Name | Target queue (30 max) | +| Retry | Enable automatic retry | +| Transaction | Enable transactional handling | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/jms-adapter-0993f2a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/jms-adapter-0993f2a.md) + +### AMQP Adapter + +Connect to AMQP 1.0 brokers. + +**Supported Brokers**: +- SAP Event Mesh +- Apache ActiveMQ +- RabbitMQ (with plugin) +- Microsoft Azure Service Bus +- IBM MQ +- Solace PubSub+ + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/amqp-adapter-5cc1a71.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/amqp-adapter-5cc1a71.md) + +### Kafka Adapter + +Connect to Apache Kafka. + +| Parameter | Description | +|-----------|-------------| +| Host | Kafka broker addresses | +| Topic | Kafka topic name | +| Consumer Group | For sender adapter | +| Authentication | SASL, SSL | +| Serialization | Avro, JSON, String | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/kafka-adapter-3e7b995.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/kafka-adapter-3e7b995.md) + +### ProcessDirect Adapter + +Internal iFlow-to-iFlow communication (synchronous, same tenant). + +| Parameter | Description | +|-----------|-------------| +| Address | Internal endpoint path | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/processdirect-adapter-7445718.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/processdirect-adapter-7445718.md) + +--- + +## Application Adapters + +### SAP SuccessFactors Adapter + +**Types**: +- SuccessFactors OData V2 +- SuccessFactors SOAP +- SuccessFactors REST + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-successfactors-odata-v2-receiver-adapter-d16dd12.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/configure-the-successfactors-odata-v2-receiver-adapter-d16dd12.md) + +### SAP Ariba Adapter + +Connect to Ariba Network. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/ariba-adapter-98da76c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/ariba-adapter-98da76c.md) + +### Salesforce Adapter + +**Operations**: +- Query (SOQL) +- Create/Update/Delete +- Bulk operations +- Streaming API + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/salesforce-receiver-adapter-a548be9.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/salesforce-receiver-adapter-a548be9.md) + +### Microsoft Dynamics CRM Adapter + +Connect to Dynamics 365/CRM. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/microsoft-dynamics-crm-receiver-adapter-ee724c8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/microsoft-dynamics-crm-receiver-adapter-ee724c8.md) + +### Open Connectors + +Access 170+ SaaS applications via unified API. + +**Examples**: Slack, HubSpot, Zendesk, Shopify, ServiceNow, Workday + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/openconnectors-receiver-adapter-1a27cee.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/openconnectors-receiver-adapter-1a27cee.md) + +--- + +## Database Adapters + +### JDBC Adapter + +Direct database connectivity. + +**Supported Databases**: +| Database | Cloud | On-Premise | +|----------|-------|------------| +| SAP HANA | Yes | Yes | +| Oracle | Yes | Yes | +| Microsoft SQL Server | Yes | Yes | +| PostgreSQL | Yes | Yes | +| IBM DB2 | - | Yes | +| SAP ASE | Yes | Yes | + +**Operations**: +- Select (query) +- Insert +- Update +- Delete +- Stored procedures + +**Configuration**: +| Parameter | Description | +|-----------|-------------| +| JDBC URL | Database connection string | +| Credential | User credentials artifact | +| SQL Statement | Query or DML statement | +| Batch Mode | Enable batch operations | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/jdbc-receiver-adapter-88be644.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/jdbc-receiver-adapter-88be644.md) + +--- + +## Cloud Platform Adapters + +### Amazon Web Services + +**Supported Services**: +- S3 (object storage) +- SQS (message queuing) +- SNS (notifications) +- SWF (workflow) +- DynamoDB (NoSQL) +- EventBridge (events) + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/amazonwebservices-receiver-adapter-bc7d1aa.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/amazonwebservices-receiver-adapter-bc7d1aa.md) + +### Microsoft Azure + +**Supported Services**: +- Azure Service Bus +- Azure Storage (Blob, Queue, Table) +- Azure CosmosDB + +### Google Cloud Platform + +**Supported Services**: +- Cloud Storage +- Pub/Sub +- BigQuery + +--- + +## B2B Adapters + +### AS2 Adapter + +Applicability Statement 2 for EDI over HTTP. + +**Features**: +- Signed/encrypted messages +- MDN (receipt) handling +- Certificate-based authentication + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/as2-adapter-d3af635.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/as2-adapter-d3af635.md) + +### AS4 Adapter + +OASIS ebMS 3.0/AS4 standard. + +**Features**: +- ebMS3 messaging +- Push/Pull modes +- Receipt handling + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/as4-receiver-adapter-3a2fde8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/as4-receiver-adapter-3a2fde8.md) + +### ELSTER Adapter + +German tax authority integration. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/elster-receiver-adapter-e374ef7.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/elster-receiver-adapter-e374ef7.md) + +--- + +## Adapter Development Kit + +Create custom adapters using the ADK. + +**Prerequisites**: +- Java development skills +- OSGi bundle knowledge +- Cloud Integration SDK + +**Process**: +1. Create adapter project +2. Implement adapter logic +3. Define metadata +4. Package as OSGi bundle +5. Deploy to tenant + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/develop-adapters-f798db6.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/develop-adapters-f798db6.md) + +--- + +## Common Configuration Patterns + +### Authentication Types + +| Type | Use Case | +|------|----------| +| Basic | Username/password | +| Client Certificate | mTLS authentication | +| OAuth 2.0 Client Credentials | Machine-to-machine | +| OAuth 2.0 Authorization Code | User-delegated access | +| SAML Bearer Assertion | SAP-to-SAP scenarios | +| Principal Propagation | Pass-through user context | + +### Proxy Types + +| Type | Description | +|------|-------------| +| Internet | Direct internet access | +| On-Premise | Via SAP Cloud Connector | + +### Timeout Settings + +Always configure appropriate timeouts: +- Connection timeout +- Response timeout +- Read timeout + +--- + +## Related Documentation + +- **Connectivity Options**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/connectivity-options-93d82e8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/connectivity-options-93d82e8.md) +- **Cloud Connector**: [https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/cloud-connector) +- **Destination Configuration**: [https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/http-destinations](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/http-destinations) diff --git a/references/api-management.md b/references/api-management.md new file mode 100644 index 0000000..284ff28 --- /dev/null +++ b/references/api-management.md @@ -0,0 +1,474 @@ +# API Management - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/apim/API-Management](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/apim/API-Management) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [API Proxy Structure](#api-proxy-structure) +3. [Creating API Proxies](#creating-api-proxies) +4. [Policies Reference](#policies-reference) +5. [Developer Hub](#developer-hub) +6. [Analytics](#analytics) +7. [Best Practices](#best-practices) + +--- + +## Overview + +API Management provides complete API lifecycle management including: +- API design and creation +- Security and access control +- Traffic management +- Analytics and monitoring +- Developer engagement + +**Core Components**: +| Component | Purpose | +|-----------|---------| +| API Proxy | Facade for backend services | +| Policies | Runtime behavior rules | +| Products | API bundles for subscription | +| Developer Hub | Developer portal | +| Analytics | Usage insights | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/what-is-api-management-0aef763.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/what-is-api-management-0aef763.md) + +--- + +## API Proxy Structure + +### Flow Architecture + +``` + API Proxy +┌─────────────────────────────────────────────────────────────┐ +│ │ +│ Client Request │ +│ ↓ │ +│ ┌─────────────────────┐ ┌─────────────────────┐ │ +│ │ Proxy Endpoint │ │ Target Endpoint │ │ +│ ├─────────────────────┤ ├─────────────────────┤ │ +│ │ PreFlow │ │ PreFlow │ │ +│ │ ↓ │ │ ↓ │ │ +│ │ Conditional Flows │ →→ │ Conditional Flows │ →→ Backend +│ │ ↓ │ │ ↓ │ │ +│ │ PostFlow │ │ PostFlow │ │ +│ │ ↓ │ │ ↓ │ │ +│ │ FaultRules │ │ FaultRules │ │ +│ └─────────────────────┘ └─────────────────────┘ │ +│ │ +│ Backend Response │ +│ ↓ │ +│ (Flows execute in reverse for response) │ +│ ↓ │ +│ Client Response │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Proxy Endpoint +Handles incoming client requests. + +**Configuration**: +- Virtual host and base path +- Route rules +- Request/response policies +- Fault handling + +### Target Endpoint +Connects to backend services. + +**Configuration**: +- Backend URL +- Load balancing +- Health monitoring +- Connection settings + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-proxy-structure-4dfd54a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-proxy-structure-4dfd54a.md) + +--- + +## Creating API Proxies + +### Methods + +1. **From API Provider** + - Connect to SAP or non-SAP systems + - Import API definitions automatically + +2. **From URL** + - Direct target endpoint URL + - Manual configuration + +3. **From API Designer** + - Design OpenAPI specification + - Generate proxy from design + +4. **From Existing Proxy** + - Copy and modify existing proxy + - Clone for similar use cases + +5. **From Cloud Integration** + - Expose iFlow endpoints as APIs + - Apply API policies to integration flows + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/different-methods-of-creating-an-api-proxy-4ac0431.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/different-methods-of-creating-an-api-proxy-4ac0431.md) + +### API Versioning + +**Strategies**: +- URI versioning: `/v1/resource` +- Header versioning: `X-API-Version: 1` +- Query parameter: `?version=1` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-versioning-b3cda3b.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-versioning-b3cda3b.md) + +### API Revisions + +Create non-destructive updates: +- Draft revisions for testing +- Deploy specific revisions +- Rollback to previous versions + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-revisions-58097ac.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-revisions-58097ac.md) + +--- + +## Policies Reference + +### Common Attributes + +All policies support: +```xml + + + +``` + +| Attribute | Description | +|-----------|-------------| +| `enabled` | Policy active (true/false) | +| `continueOnError` | Continue on failure | +| `async` | Execute asynchronously | + +### Security Policies + +#### Verify API Key +```xml + + + +``` + +#### OAuth 2.0 +Supports grant types: +- Client Credentials +- Authorization Code +- Password +- Implicit + +```xml + + VerifyAccessToken + +``` + +#### Basic Authentication +```xml + + Decode + + + +``` + +#### SAML Assertion +Validate SAML tokens for SSO scenarios. + +#### Access Control +IP-based access restrictions. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/verify-api-key-4d15a04.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/verify-api-key-4d15a04.md) + +### Traffic Management Policies + +#### Quota +Limit API calls over time periods. +```xml + + 1 + month + + +``` + +**Types**: +- Default: Fixed allocation +- FlexQuota: Dynamic allocation +- Calendar: Time-based periods + +#### Spike Arrest +Prevent traffic spikes. +```xml + + 30pm + +``` + +**Rate formats**: `Xpm` (per minute), `Xps` (per second) + +#### Concurrent Rate Limit +Limit simultaneous connections. + +#### Response Cache +Cache backend responses. +```xml + + + + + + 3600 + + +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/quota-1f742c1.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/quota-1f742c1.md) + +### Mediation Policies + +#### Assign Message +Modify request/response. +```xml + + + +
value
+ + + request + +``` + +#### Extract Variables +Extract data from messages. +```xml + + + + $.user.id + + + +``` + +#### JSON to XML / XML to JSON +Format conversion. + +#### XSL Transform +Apply XSLT transformations. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/assign-message-523efe6.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/assign-message-523efe6.md) + +### Extension Policies + +#### JavaScript +Custom logic with JavaScript. +```xml + + jsc://script.js + +``` + +#### Python Script +Custom logic with Python. + +#### Service Callout +Call external services. +```xml + + + [https://service.example.com](https://service.example.com) + + +``` + +### Threat Protection Policies + +#### JSON Threat Protection +```xml + + 20 + 10 + 15 + 500 + +``` + +#### XML Threat Protection +Prevent XML bombs and malformed XML. + +#### Regular Expression Protection +Block injection attacks. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/json-threat-protection-952cbd7.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/json-threat-protection-952cbd7.md) + +### Fault Handling + +#### Raise Fault +Generate custom errors. +```xml + + + + 400 + Bad Request + + {"error": "Invalid input"} + + + + +``` + +### Logging Policies + +#### Message Logging +Log to external systems. + +#### Statistics Collector +Collect custom metrics. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/policy-types-c918e28.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/policy-types-c918e28.md) + +--- + +## Developer Hub + +### Overview +Self-service portal for API discovery and subscription. + +**Features**: +- API documentation +- Interactive testing +- Application registration +- Subscription management +- Analytics dashboard + +### Products +Bundle APIs for subscription. + +**Configuration**: +- Included APIs +- Rate plans +- Access control +- Custom attributes + +### Applications +Developer registrations for API access. + +**Workflow**: +1. Developer registers on portal +2. Creates application +3. Subscribes to products +4. Receives API key/credentials +5. Accesses APIs + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/developer-hub-41f7c45.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/developer-hub-41f7c45.md) + +--- + +## Analytics + +### Dashboard Views +- API usage trends +- Response times +- Error rates +- Developer activity +- Geographic distribution + +### Custom Reports +Create custom analytics with: +- Dimensions (what to measure) +- Measures (how to aggregate) +- Filters (what to include) + +### Statistics Collector Policy +Capture custom metrics in API flows. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-analytics-6766dc3.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-analytics-6766dc3.md) + +--- + +## Best Practices + +### Security +1. Always use API keys or OAuth +2. Apply threat protection policies +3. Validate input data +4. Use HTTPS only +5. Implement rate limiting + +### Performance +1. Cache responses where appropriate +2. Use compression +3. Minimize policy chain length +4. Stream large payloads + +### Design +1. Use consistent naming conventions +2. Version APIs properly +3. Document all endpoints +4. Use policy templates for reuse +5. Test with API debugger + +### Operations +1. Monitor analytics regularly +2. Set up alerts for errors +3. Review quota usage +4. Keep certificates updated + +--- + +## Variables Reference + +### Request Variables +``` +request.header.{name} +request.queryparam.{name} +request.path +request.uri +request.verb +``` + +### Response Variables +``` +response.header.{name} +response.status.code +response.content +``` + +### Flow Variables +``` +proxy.basepath +proxy.pathsuffix +target.url +error.message +error.status.code +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/variable-references-4f8993f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/variable-references-4f8993f.md) + +--- + +## Related Documentation + +- **Policies Guide**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/policies-7e4f3e5.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/policies-7e4f3e5.md) +- **Policy Types**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/policy-types-c918e28.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/policy-types-c918e28.md) +- **API Proxy**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-proxy-8962643.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/apim/API-Management/api-proxy-8962643.md) +- **Developer Hub**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/developer-hub-41f7c45.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/developer-hub-41f7c45.md) diff --git a/references/cloud-integration.md b/references/cloud-integration.md new file mode 100644 index 0000000..e69a06e --- /dev/null +++ b/references/cloud-integration.md @@ -0,0 +1,431 @@ +# Cloud Integration - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Integration Flow Structure](#integration-flow-structure) +3. [Flow Steps Reference](#flow-steps-reference) +4. [Message Processing](#message-processing) +5. [Data Persistence](#data-persistence) +6. [Error Handling](#error-handling) +7. [Quality of Service](#quality-of-service) +8. [Best Practices](#best-practices) + +--- + +## Overview + +Cloud Integration enables building and running integration flows across cloud, on-premise, and hybrid landscapes for: +- **A2A** (Application-to-Application) +- **B2B** (Business-to-Business) +- **B2G** (Business-to-Government) + +**Key Concepts**: +- Integration flows define message processing pipelines +- Adapters connect to sender/receiver systems +- Steps transform, route, and process messages +- Security material protects sensitive data + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development) + +--- + +## Integration Flow Structure + +### Core Components + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Integration Flow │ +├─────────────────────────────────────────────────────────────────┤ +│ Sender ──► [Sender Adapter] ──► Integration Process │ +│ │ │ +│ ┌─────────┴─────────┐ │ +│ │ Processing Steps │ │ +│ │ - Transformations │ │ +│ │ - Routing │ │ +│ │ - External Calls │ │ +│ │ - Persistence │ │ +│ └─────────┬─────────┘ │ +│ │ │ +│ ──► [Receiver Adapter] ──► Receiver │ +├─────────────────────────────────────────────────────────────────┤ +│ Exception Subprocess (for error handling) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Component Types + +| Component | Purpose | +|-----------|---------| +| **Sender/Receiver** | External systems connected to the flow | +| **Sender Channel** | Inbound adapter configuration | +| **Receiver Channel** | Outbound adapter configuration | +| **Integration Process** | Main message processing container | +| **Local Integration Process** | Reusable subprocess | +| **Exception Subprocess** | Error handling container | + +--- + +## Flow Steps Reference + +### Message Transformation Steps + +#### Content Modifier +Enriches messages by modifying headers, properties, or body. + +**Tabs**: +- **Message Header**: Headers sent to receiver systems +- **Exchange Property**: Internal flow properties (not transmitted) +- **Message Body**: Payload content + +**Source Types**: +| Type | Description | +|------|-------------| +| Constant | Static value | +| Header | Reference Camel header | +| Property | Reference exchange property | +| XPath | Extract from XML using XPath | +| Expression | Camel Simple Expression | +| External Parameter | Externalized configuration | +| Local Variable | Flow-specific variable | +| Global Variable | Tenant-level variable | +| Number Range | Unique identifier | + +**Example Expressions**: +``` +${property.propertyName} +${header.headerName} +${in.body} +${exchangeId} +${camelId} +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-content-modifier-8f04a70.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-content-modifier-8f04a70.md) + +#### Message Mapping +Graphical transformation between source and target structures. + +**Types**: +- **Flow Step Mapping**: Defined within the flow +- **Mapping Artifact**: Reusable standalone artifact + +**Functions**: +- Standard functions (string, arithmetic, date, boolean) +- Conversion functions +- Custom Groovy functions + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/message-mapping-459ccdf.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/message-mapping-459ccdf.md) + +#### XSLT Mapping +XML transformation using XSLT stylesheets. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/create-xslt-mapping-5ce1f15.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/create-xslt-mapping-5ce1f15.md) + +#### Converters +| Converter | Function | +|-----------|----------| +| JSON to XML | Convert JSON payload to XML | +| XML to JSON | Convert XML payload to JSON | +| CSV to XML | Convert CSV data to XML | +| XML to CSV | Convert XML data to CSV | +| EDI to XML | Convert EDI formats to XML | +| XML to EDI | Convert XML to EDI formats | + +### Routing Steps + +#### Router +Routes messages based on conditions. + +**Condition Types**: +- **XML**: XPath expressions +- **Non-XML**: Header/property conditions + +**Operators (Non-XML)**: +``` +=, !=, >, >=, <, <= +and, or +contains, not contains +in, not in +regex, not regex +``` + +**Best Practice**: Use same condition type (XML or Non-XML) for all branches. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-router-d7fddbd.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-router-d7fddbd.md) + +#### Filter +Removes messages not matching specified conditions. + +#### Multicast +Sends message copies to multiple branches simultaneously. + +#### Recipient List +Dynamically determines recipients at runtime. + +### Splitting Steps + +| Splitter Type | Use Case | +|---------------|----------| +| General Splitter | Split by XPath expression | +| Iterating Splitter | Process items one-by-one | +| IDoc Splitter | Split IDoc messages | +| EDI Splitter | Split EDI documents | +| Zip Splitter | Extract from ZIP archives | +| Tar Splitter | Extract from TAR archives | +| PKCS#7/CMS Splitter | Split encrypted messages | + +**Difference**: General Splitter preserves envelope; Iterating Splitter strips envelope elements. + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-splitter-dabea9d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-splitter-dabea9d.md) + +### Aggregator +Combines split messages back together. + +**Correlation**: Uses correlation expression to group related messages. +**Completion**: Timeout or condition-based. + +### External Call Steps + +| Step | Purpose | +|------|---------| +| Request Reply | Synchronous call with response | +| Send | Asynchronous fire-and-forget | +| Poll Enrich | Fetch data to enrich message | +| Content Enricher | Merge external data into message | +| Process Call | Call local integration process | +| Looping Process Call | Iterate with local process | + +### Security Steps + +| Step | Purpose | +|------|---------| +| Encryptor | PGP/PKCS#7 encryption | +| Decryptor | PGP/PKCS#7 decryption | +| Signer | XML/PKCS#7 signature | +| Verifier | Signature verification | +| Message Digest | Hash calculation | + +--- + +## Message Processing + +### Message Components + +``` +┌───────────────────────────────────────┐ +│ Camel Message │ +├───────────────────────────────────────┤ +│ Headers │ +│ ├─ CamelHttpMethod │ +│ ├─ CamelHttpUri │ +│ ├─ Content-Type │ +│ └─ Custom headers... │ +├───────────────────────────────────────┤ +│ Body │ +│ └─ Message payload │ +├───────────────────────────────────────┤ +│ Attachments │ +│ └─ Binary attachments │ +└───────────────────────────────────────┘ + +┌───────────────────────────────────────┐ +│ Exchange Properties │ +│ ├─ SAP_MessageProcessingLogID │ +│ ├─ SAP_Receiver │ +│ ├─ CamelSplitIndex │ +│ └─ Custom properties... │ +└───────────────────────────────────────┘ +``` + +### Accessing in Scripts + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message + +def Message processData(Message message) { + // Get body + def body = message.getBody(String.class) + + // Get header + def contentType = message.getHeader("Content-Type", String.class) + + // Get property + def logId = message.getProperty("SAP_MessageProcessingLogID") + + // Process and transform body + def transformedBody = body.toUpperCase() + + // Set body (use the transformed result) + message.setBody(transformedBody) + + // Set header + message.setHeader("CustomHeader", "value") + + // Set property + message.setProperty("CustomProperty", "value") + + return message +} +``` + +--- + +## Data Persistence + +### Data Stores +Persistent storage for messages/data. + +**Operations**: +| Operation | Description | +|-----------|-------------| +| Write | Store entry with ID | +| Get | Retrieve by ID | +| Select | Query multiple entries | +| Delete | Remove entry | + +**Scope**: Global (cross-flow) or Local (single flow) + +**Use Cases**: +- Decouple sender and processing +- Store intermediate results +- Implement idempotent processing + +### Variables +Store values during runtime. + +**Types**: +- **Local Variable**: Single flow scope +- **Global Variable**: Tenant-wide scope + +### JMS Queues +Transactional message storage. + +**Benefits**: +- Guaranteed delivery +- Transaction support +- Decoupling +- Retry handling + +**Limits**: 30 queues per tenant (standard plan) + +--- + +## Error Handling + +### Exception Subprocess + +**Required Structure**: +``` +Error Start Event → [Processing Steps] → End Event +``` + +**End Event Types**: +- **End Message**: Return fault message to sender +- **Error End**: Throw to default handler +- **Escalation**: Trigger escalation handling + +**Accessing Errors**: +``` +${exception.message} +${exception.stacktrace} +``` + +**Limitations**: +- Cannot catch Data Store duplicate key errors (transaction rollback) +- Local process exceptions not caught by main process +- Processing terminates after handling + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-exception-subprocess-690e078.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/define-exception-subprocess-690e078.md) + +### Error Configuration + +Configure adapter-level error handling: +- **Retry**: Automatic retry with intervals +- **Dead Letter**: Route failed messages +- **Alerting**: Trigger notifications + +--- + +## Quality of Service + +### Exactly-Once Delivery + +Prevent duplicate processing: + +1. **Idempotent Process Call** + - Check for duplicate message IDs + - Skip or return cached response + +2. **ID Mapping** + - Map source ID to target ID + - Track processed messages + +3. **JMS + Transaction** + - Transactional message processing + - Rollback on failure + +### Idempotent Pattern + +``` +Sender → ID Mapping (Get) → Exists? + ├─ Yes → Return cached response + └─ No → Process → ID Mapping (Store) → Response +``` + +--- + +## Best Practices + +### Design Guidelines + +1. **Keep flows readable** + - Use meaningful names + - Add comments + - Keep processes focused + +2. **Apply security standards** + - Use credential artifacts (not hardcoded) + - Encrypt sensitive data + - Validate input + +3. **Handle errors gracefully** + - Use exception subprocesses + - Log meaningful information + - Implement retry logic + +4. **Optimize performance** + - Stream large payloads + - Minimize transformations + - Use appropriate adapters + +### Scripting Guidelines + +**Do**: +- Use SLF4J for logging +- Use `XmlSlurper.parse(Object)` for large XML +- Use `StringBuilder` for string operations +- Include comments + +**Don't**: +- Write credentials to headers +- Use `TimeZone.setDefault()` +- Use `Eval()` class +- Bind variables unnecessarily + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md) + +--- + +## Related Documentation + +- **Development Guide**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development) +- **Operations Guide**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Operations](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Operations) +- **Security Guide**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/SecurityCF](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/SecurityCF) +- **Design Guidelines**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/integration-flow-design-guidelines-6803389.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/integration-flow-design-guidelines-6803389.md) diff --git a/references/content-transport.md b/references/content-transport.md new file mode 100644 index 0000000..9917802 --- /dev/null +++ b/references/content-transport.md @@ -0,0 +1,388 @@ +# Content Transport - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Transport Options](#transport-options) +3. [Cloud Transport Management](#cloud-transport-management) +4. [CTS+ Transport](#cts-transport) +5. [MTAR Download](#mtar-download) +6. [Manual Export/Import](#manual-exportimport) +7. [Best Practices](#best-practices) + +--- + +## Overview + +Content transport enables reuse of integration content across multiple tenants by exporting from source and importing to target. + +### Use Cases + +- **Development → Test → Production** promotion +- **Tenant-to-tenant** content sharing +- **Backup and restore** scenarios +- **Multi-region** deployment + +### Key Constraints + +| Constraint | Description | +|------------|-------------| +| Environment | Cannot transport between Neo and CF | +| Draft status | Cannot transport draft artifacts | +| Access policies | Protected artifacts restricted | +| Externalized parameters | Values unchanged during transport | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-e3c79d6.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-e3c79d6.md) + +--- + +## Transport Options + +### Option Comparison + +| Option | Automation | Setup | Use Case | +|--------|------------|-------|----------| +| Cloud Transport Management | High | Complex | Enterprise DevOps | +| CTS+ | High | Complex | SAP landscape | +| MTAR Download | Medium | Moderate | Flexible deployment | +| Manual Export/Import | Low | Simple | Ad-hoc, small scale | + +### Decision Flow + +``` +Need automated DevOps pipeline? +├── Yes → Cloud Transport Management +└── No + ├── Have CTS+ infrastructure? + │ ├── Yes → CTS+ + │ └── No → MTAR Download or Manual + └── Small scale / ad-hoc? + ├── Yes → Manual Export/Import + └── No → MTAR Download +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/decision-help-for-choosing-the-right-content-transport-option-19e0e73.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/decision-help-for-choosing-the-right-content-transport-option-19e0e73.md) + +--- + +## Cloud Transport Management + +SAP Cloud Transport Management Service provides automated transport across landscapes. + +### Architecture + +``` +┌──────────────────────────────────────────────────┐ +│ Cloud Transport Management │ +├──────────────────────────────────────────────────┤ +│ Source Node → Transport Route → Destination Node │ +│ (DEV) (PRD) │ +└──────────────────────────────────────────────────┘ +``` + +### Setup Steps + +1. **Subscribe** to Cloud Transport Management Service +2. **Create service instance** in BTP cockpit +3. **Configure source node** (source tenant) +4. **Configure destination node** (target tenant) +5. **Create transport route** connecting nodes +6. **Enable transport** in Integration Suite + +### Configuration + +**Source Node**: +- Integration Suite tenant +- Export permissions +- Content Agent service + +**Destination Node**: +- Target Integration Suite tenant +- Import permissions +- Deployment credentials + +**Transport Route**: +- Source → Destination mapping +- Route name +- Description + +### Transport Process + +1. **Select content** in Integration Suite +2. **Export to transport** queue +3. **Approve transport** in TMS +4. **Import** to destination +5. **Verify** deployment + +### Node Configuration (JSON) + +```json +{ + "name": "DEV_Integration", + "description": "Development tenant", + "type": "SAP_CPI", + "url": "[https://dev-tenant.it-cpitrial.cfapps.eu10.hana.ondemand.com",](https://dev-tenant.it-cpitrial.cfapps.eu10.hana.ondemand.com",) + "credentials": { + "type": "OAuth", + "clientId": "...", + "clientSecret": "..." + } +} +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-cloud-transport-management-d458b17.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-cloud-transport-management-d458b17.md) + +--- + +## CTS+ Transport + +SAP Change and Transport System extended for cloud content. + +### Prerequisites + +- CTS+ system configured +- Transport domain setup +- RFC connectivity to cloud + +### Setup + +1. **Configure CTS+** transport domain +2. **Create transport routes** to cloud targets +3. **Set up destination** in SAP Solution Manager +4. **Enable CTS+ transport** in Integration Suite + +### Transport Process + +1. **Create transport request** in CTS+ +2. **Export content** from Integration Suite +3. **Release transport** request +4. **Import** at target via CTS+ + +### Use Cases + +- Organizations with existing CTS+ infrastructure +- Integrated with SAP Change Management +- Enterprise transport governance + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-cts-3cdfb51.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-cts-3cdfb51.md) + +--- + +## MTAR Download + +Download content as Multi-Target Application Archive for flexible deployment. + +### Process + +1. **Select content** to export +2. **Download MTAR** file +3. **Upload to** CTS+ or Cloud Transport Management +4. **Deploy** to target tenant + +### MTAR Structure + +``` +my-content.mtar +├── META-INF/ +│ ├── MANIFEST.MF +│ └── mtad.yaml +├── package1/ +│ ├── integration-flow1.iflw +│ └── mapping1.mmap +└── package2/ + └── integration-flow2.iflw +``` + +### Deployment Options + +| Option | Description | +|--------|-------------| +| CTS+ | Upload to transport request | +| TMS | Upload to transport node | +| CF Deploy | Direct CF deployment | + +### Neo Environment + +MTAR can be deployed directly to target tenant via SAP Cloud Platform Solutions: +1. Navigate to Solutions +2. Upload MTAR +3. Deploy to tenant + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-mtar-download-c111710.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-mtar-download-c111710.md) + +--- + +## Manual Export/Import + +Direct export and import without transport infrastructure. + +### Export Process + +1. **Navigate** to Design workspace +2. **Select package** to export +3. **Click Export** +4. **Download** .zip file + +### Import Process + +1. **Navigate** to Design workspace +2. **Click Import** +3. **Select** .zip file +4. **Choose** import options +5. **Import** content + +### Import Options + +| Option | Description | +|--------|-------------| +| Create new | Create as new package | +| Overwrite | Replace existing | +| Skip existing | Keep existing, add new | + +### Exported Content + +| Content Type | Included | +|--------------|----------| +| Integration Flows | Yes | +| Value Mappings | Yes | +| Script Collections | Yes | +| Message Mappings | Yes | +| OData APIs | Yes | +| REST APIs | Yes | + +### Not Exported + +| Content Type | Reason | +|--------------|--------| +| Security Material | Security risk | +| Deployed state | Runtime-specific | +| Monitoring data | Tenant-specific | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-manual-export-and-import-fd23e14.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-manual-export-and-import-fd23e14.md) + +--- + +## API Management Transport + +### Transportable Content + +| Content Type | Method | +|--------------|--------| +| API Proxies | TMS / Manual | +| Products | TMS / Manual | +| API Providers | TMS / Manual | +| Key Value Maps | TMS / Manual | +| Certificates | Special handling | + +### Transport via TMS + +1. **Configure** API Management for TMS +2. **Export** API artifacts +3. **Transport** via TMS route +4. **Import** to target + +### Certificate Transport + +Certificates require special handling: +1. Export certificate references (not keys) +2. Import references to target +3. Upload actual certificates separately + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/transport-api-management-artifacts-via-sap-cloud-transport-management-service-2e4bc72.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/transport-api-management-artifacts-via-sap-cloud-transport-management-service-2e4bc72.md) + +--- + +## Selective Transport + +### Individual Artifact Transport + +Transport specific artifacts instead of entire packages: + +1. **Select artifact** in package +2. **Export** individual item +3. **Transport** or download +4. **Import** to target + +### Restrictions + +| Condition | Transport Allowed | +|-----------|-------------------| +| Draft status | No | +| Access policy protected | No | +| Referenced artifacts | Must include dependencies | + +### Handling Dependencies + +When transporting artifacts with dependencies: +1. **Include** all referenced artifacts +2. **Verify** references exist in target +3. **Transport** in correct order + +--- + +## Best Practices + +### Transport Strategy + +1. **Define landscape** (DEV → QA → PRD) +2. **Choose transport method** based on scale +3. **Automate** where possible +4. **Document** transport procedures + +### Content Management + +1. **Use packages** to group related content +2. **Version** artifacts meaningfully +3. **Test** in lower environment first +4. **Validate** after transport + +### Externalized Parameters + +Externalized parameters retain source values: +1. **Document** parameter differences +2. **Update** after transport if needed +3. **Use environment-specific** configuration + +### Pre-Shipped Content + +Standard SAP content is not updated during transport: +1. **Update separately** from SAP +2. **Track versions** independently +3. **Test compatibility** after updates + +--- + +## Troubleshooting + +### Common Issues + +| Issue | Resolution | +|-------|------------| +| Transport fails | Check permissions, connectivity | +| Content missing | Verify export includes all dependencies | +| Deployment error | Check target tenant configuration | +| Version conflict | Resolve conflicts manually | + +### Error Resolution + +1. **Check transport logs** in TMS +2. **Verify credentials** for source/target +3. **Confirm connectivity** between systems +4. **Review artifact** compatibility + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-transporting-content-bbfb41a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-transporting-content-bbfb41a.md) + +--- + +## Related Documentation + +- **Content Transport Overview**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-e3c79d6.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-e3c79d6.md) +- **Decision Help**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/decision-help-for-choosing-the-right-content-transport-option-19e0e73.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/decision-help-for-choosing-the-right-content-transport-option-19e0e73.md) +- **TMS Transport**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-cloud-transport-management-d458b17.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/content-transport-using-cloud-transport-management-d458b17.md) +- **Best Practices**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/guidelines-and-best-practices-for-content-transport-8a8aa38.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/guidelines-and-best-practices-for-content-transport-8a8aa38.md) diff --git a/references/data-space-integration.md b/references/data-space-integration.md new file mode 100644 index 0000000..af1e061 --- /dev/null +++ b/references/data-space-integration.md @@ -0,0 +1,413 @@ +# Data Space Integration - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Core Concepts](#core-concepts) +3. [Eclipse Dataspace Connector](#eclipse-dataspace-connector) +4. [Contract Negotiation](#contract-negotiation) +5. [Asset Management](#asset-management) +6. [Data Transfer](#data-transfer) +7. [Supported Data Spaces](#supported-data-spaces) + +--- + +## Overview + +Data Space Integration enables secure, sovereign data exchange between data space participants in a reliable and controlled manner. + +### Key Features + +- **Sovereign data exchange** between participants +- **Policy enforcement** for data access control +- **Standardized protocols** (IDS standard) +- **SAP and non-SAP** application support +- **Harmonized monitoring** and configuration + +### Benefits + +| Benefit | Description | +|---------|-------------| +| Data Sovereignty | Control over data sharing policies | +| Interoperability | Standard-based exchange | +| Security | Encrypted, authenticated transfer | +| Compliance | Policy-enforced access | +| Auditability | Full transaction logging | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-data-space-integration-4edeee5.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-data-space-integration-4edeee5.md) + +--- + +## Core Concepts + +### International Data Spaces (IDS) + +IDS represents "a uniform standard for data sharing that can be applied in any professional and private areas" based on European Privacy Policy principles. + +### Data Space + +A data space is "a virtual place that enables sovereign data governance, based on interoperable standardized components, among involved persons and companies." + +Data spaces typically organize around: +- Industries (automotive, manufacturing) +- Topics (sustainability, supply chain) +- Regions (European data spaces) + +### Participants + +| Role | Description | +|------|-------------| +| Provider | Offers data assets | +| Consumer | Requests data assets | +| Broker | Facilitates discovery (optional) | +| Clearing House | Logs transactions (optional) | + +### Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Data Space │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ Provider │ ←── Contract ───→ │ Consumer │ │ +│ │ (SAP IS) │ Negotiation │ (SAP IS) │ │ +│ │ │ │ │ │ +│ │ ┌───────┐ │ │ ┌───────┐ │ │ +│ │ │ Asset │ │ ════ Transfer ════▶ │ │ Asset │ │ │ +│ │ └───────┘ │ │ └───────┘ │ │ +│ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/concepts-in-data-space-integration-fcf96b2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/concepts-in-data-space-integration-fcf96b2.md) + +--- + +## Eclipse Dataspace Connector + +Data Space Integration is built on Eclipse Dataspace Connector (EDC), an open-source framework. + +### EDC Capabilities + +| Capability | Description | +|------------|-------------| +| Data Querying | Discover available assets | +| Data Exchange | Transfer data between participants | +| Policy Enforcement | Apply access policies | +| Monitoring | Track transfers and usage | +| Auditing | Log all transactions | + +### EDC Components + +``` +┌─────────────────────────────────────┐ +│ Eclipse Dataspace Connector │ +├─────────────────────────────────────┤ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ Identity │ │ Catalog │ │ +│ │ Service │ │ Service │ │ +│ └─────────────┘ └─────────────┘ │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ Transfer │ │ Policy │ │ +│ │ Service │ │ Engine │ │ +│ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────────┘ +``` + +--- + +## Contract Negotiation + +### Negotiation Process + +``` +1. Provider creates Asset + Policy → Contract Definition + ↓ +2. Contract Offers generated from definitions + ↓ +3. Consumer discovers offers in catalog + ↓ +4. Consumer initiates negotiation + ↓ +5. Negotiation iterations (accept/counter/reject) + ↓ +6. Agreement finalized → Contract established +``` + +### Contract Components + +| Component | Description | +|-----------|-------------| +| Asset | Data being shared | +| Policy | Access rules and constraints | +| Offer | Provider's terms | +| Agreement | Final accepted terms | + +### Policy Types + +| Policy | Description | +|--------|-------------| +| Access Policy | Who can access | +| Usage Policy | How data can be used | +| Contract Policy | Terms of agreement | + +### Policy Examples + +```json +{ + "policy": { + "permissions": [ + { + "action": "USE", + "constraints": [ + { + "leftOperand": "PURPOSE", + "operator": "EQ", + "rightOperand": "ANALYTICS" + } + ] + } + ] + } +} +``` + +--- + +## Asset Management + +### Asset Types + +| Type | Description | +|------|-------------| +| HTTP | REST API endpoints | +| S3 | AWS S3 storage | +| Azure | Azure Blob storage | +| File | File-based transfer | + +### Creating Assets + +1. **Define asset** metadata +2. **Configure** data source +3. **Set** access policies +4. **Publish** to catalog + +### Asset Structure + +```json +{ + "asset": { + "id": "asset-001", + "properties": { + "name": "Product Catalog", + "description": "Product master data", + "contentType": "application/json" + } + }, + "dataAddress": { + "type": "HttpData", + "baseUrl": "[https://api.example.com/products"](https://api.example.com/products") + } +} +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-data-space-assets-5c0cdb8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-data-space-assets-5c0cdb8.md) + +--- + +## Data Transfer + +### Transfer Types + +| Type | Description | +|------|-------------| +| HTTP | REST-based transfer | +| S3 | Object storage transfer | +| Azure Blob | Azure storage transfer | + +### Transfer Process + +1. **Initiate** transfer request +2. **Authenticate** with data space +3. **Apply** contract policies +4. **Execute** data transfer +5. **Confirm** completion + +### HTTP Asset Transfer + +``` +Consumer Provider + │ │ + │──── Transfer Request ──▶│ + │ │ + │◀─── EDR (Endpoint) ─────│ + │ │ + │──── GET /data ─────────▶│ + │ (with EDR token) │ + │ │ + │◀─── Data Response ──────│ + │ │ +``` + +### EDR Management + +Endpoint Data Reference (EDR) provides secure access to assets: +- Time-limited tokens +- Policy-enforced access +- Automatic refresh + +**Documentation**: +- HTTP Assets: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-http-assets-735300c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-http-assets-735300c.md) +- S3/Azure Assets: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-s3-and-azure-assets-4afdf5c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-s3-and-azure-assets-4afdf5c.md) + +--- + +## Supported Data Spaces + +### Currently Supported + +| Data Space | Industry | Description | +|------------|----------|-------------| +| Catena-X | Automotive | Automotive supply chain | + +### Catena-X Overview + +Catena-X is the automotive industry data space for: +- Supply chain visibility +- Quality management +- Sustainability tracking +- Circular economy + +### Catena-X Integration + +``` +┌──────────────────────────────────────┐ +│ Catena-X Network │ +│ ┌────────────────────────────────┐ │ +│ │ SAP Integration Suite │ │ +│ │ ┌──────────────────────────┐ │ │ +│ │ │ Data Space Integration │ │ │ +│ │ │ - Asset Management │ │ │ +│ │ │ - Contract Negotiation │ │ │ +│ │ │ - Data Transfer │ │ │ +│ │ └──────────────────────────┘ │ │ +│ └────────────────────────────────┘ │ +└──────────────────────────────────────┘ +``` + +--- + +## API Access + +### EDR Management APIs + +Programmatic access to Data Space Integration: + +| Operation | Description | +|-----------|-------------| +| List offers | Browse available assets | +| Negotiate | Initiate contract negotiation | +| Get EDR | Obtain data reference | +| Transfer | Execute data transfer | + +### API Example + +```bash +# Get contract offers +GET /api/v1/catalog/offers + +# Initiate negotiation +POST /api/v1/negotiations +{ + "offerId": "offer-123", + "policy": {...} +} + +# Get EDR for transfer +GET /api/v1/edr/{agreementId} +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/using-apis-to-work-with-data-space-integration-411fd1e.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/using-apis-to-work-with-data-space-integration-411fd1e.md) + +--- + +## Configuration + +### Prerequisites + +| Requirement | Description | +|-------------|-------------| +| BTP Subaccount | Cloud Foundry enabled | +| Data Space membership | Registered participant | +| Integration Suite | With Data Space entitlement | + +### Setup Steps + +1. **Enable** Data Space Integration capability +2. **Configure** data space connection +3. **Register** as participant +4. **Set up** identity provider +5. **Create** assets and policies + +### Monitoring + +Track data space activities: +- Contract negotiations +- Active agreements +- Data transfers +- Policy violations + +--- + +## Best Practices + +### Policy Design + +1. **Be specific** about permitted uses +2. **Set time limits** on agreements +3. **Require purpose** declarations +4. **Log all access** for audit + +### Asset Management + +1. **Document** asset metadata thoroughly +2. **Version** assets appropriately +3. **Test** access before publishing +4. **Monitor** consumption patterns + +### Security + +1. **Use strong authentication** +2. **Encrypt** data in transit +3. **Audit** all transactions +4. **Review** policies regularly + +--- + +## Troubleshooting + +### Common Issues + +| Issue | Resolution | +|-------|------------| +| Negotiation failed | Check policy compatibility | +| Transfer timeout | Verify network connectivity | +| Access denied | Review contract terms | +| Invalid EDR | Request new EDR token | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-data-space-integration-166fa88.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-data-space-integration-166fa88.md) + +--- + +## Related Documentation + +- **Overview**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-data-space-integration-4edeee5.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-data-space-integration-4edeee5.md) +- **Concepts**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/concepts-in-data-space-integration-fcf96b2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/concepts-in-data-space-integration-fcf96b2.md) +- **Consuming Assets**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-data-space-assets-5c0cdb8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/consuming-data-space-assets-5c0cdb8.md) +- **APIs**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/using-apis-to-work-with-data-space-integration-411fd1e.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/using-apis-to-work-with-data-space-integration-411fd1e.md) +- **Troubleshooting**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-data-space-integration-166fa88.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-data-space-integration-166fa88.md) diff --git a/references/edge-integration-cell.md b/references/edge-integration-cell.md new file mode 100644 index 0000000..daf348f --- /dev/null +++ b/references/edge-integration-cell.md @@ -0,0 +1,332 @@ +# Edge Integration Cell - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Architecture](#architecture) +3. [Prerequisites](#prerequisites) +4. [Deployment Guide](#deployment-guide) +5. [Operations](#operations) +6. [Troubleshooting](#troubleshooting) + +--- + +## Overview + +Edge Integration Cell is an optional hybrid integration runtime that enables: +- **Design in cloud**: Use Integration Suite web UI +- **Deploy on-premise**: Run in private Kubernetes cluster +- **Data sovereignty**: Data stays within private landscape + +### Use Cases + +1. **Security/Compliance Requirements** + - Sensitive data must stay behind firewall + - Regulatory data residency requirements + - No data transit over internet + +2. **SAP Process Orchestration Migration** + - Modernize to Integration Suite + - Keep existing network topology + - Gradual migration path + +3. **Hybrid Architecture** + - Mix cloud and edge deployment + - Centralized design and monitoring + - Distributed execution + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-edge-integration-cell-aee74bb.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-edge-integration-cell-aee74bb.md) + +--- + +## Architecture + +### Component Overview + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SAP BTP Cloud │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ SAP Integration Suite │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ +│ │ │ Design │ │ Monitor │ │ Security Material │ │ │ +│ │ │ Studio │ │ (Logs) │ │ (Keystore Sync) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +└────────────────────────────┬────────────────────────────────────┘ + │ HTTPS (Outbound only) + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Customer Private Landscape │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Kubernetes Cluster │ │ +│ │ ┌─────────────────────────────────────────────────────┐ │ │ +│ │ │ Edge Integration Cell │ │ │ +│ │ │ ┌─────────────┐ ┌─────────────┐ ┌───────────────┐ │ │ │ +│ │ │ │ Runtime │ │ Worker │ │ Security │ │ │ │ +│ │ │ │ Engine │ │ Pods │ │ Manager │ │ │ │ +│ │ │ └─────────────┘ └─────────────┘ └───────────────┘ │ │ │ +│ │ └─────────────────────────────────────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────┴──────────────┐ │ +│ ▼ ▼ │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ Sender │ │ Receiver │ │ +│ │ System │ │ System │ │ +│ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Supported Kubernetes Platforms + +| Platform | Documentation | +|----------|---------------| +| Amazon EKS | [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-amazon-elastic-kubernetes-service-eks-6f95afa.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-amazon-elastic-kubernetes-service-eks-6f95afa.md) | +| Azure AKS | [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-azure-kubernetes-service-aks-a3c3a9c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-azure-kubernetes-service-aks-a3c3a9c.md) | +| Google GKE | [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-google-kubernetes-engine-gke-24a1e56.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-google-kubernetes-engine-gke-24a1e56.md) | +| Red Hat OpenShift | [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-red-hat-openshift-ocp-21ae0fd.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-red-hat-openshift-ocp-21ae0fd.md) | +| SUSE Rancher RKE2 | [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-suse-rancher-kubernetes-engine-rke2-0359e5c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/prepare-for-deployment-on-suse-rancher-kubernetes-engine-rke2-0359e5c.md) | + +--- + +## Prerequisites + +### Kubernetes Cluster Requirements + +| Requirement | Specification | +|-------------|---------------| +| Kubernetes Version | 1.23+ | +| Worker Nodes | Minimum 4 | +| CPU per Node | 4 vCPU minimum | +| Memory per Node | 16 GB minimum | +| Storage | 100 GB+ persistent volume | +| Ingress Controller | Required (NGINX, etc.) | + +### Network Requirements + +| Requirement | Description | +|-------------|-------------| +| Outbound HTTPS | To SAP BTP (*.hana.ondemand.com) | +| DNS | Resolvable cluster DNS | +| Load Balancer | For ingress traffic | +| Firewall Rules | Allow outbound 443 to SAP | + +### SAP BTP Requirements + +| Requirement | Description | +|-------------|-------------| +| Integration Suite License | With Edge Integration Cell entitlement | +| BTP Subaccount | Cloud Foundry enabled | +| Role Collections | Edge Integration Cell Administrator | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/plan-your-setup-of-edge-integration-cell-217fed1.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/plan-your-setup-of-edge-integration-cell-217fed1.md) + +--- + +## Deployment Guide + +### Step 1: Prepare Kubernetes Cluster + +Platform-specific preparation: + +```bash +# Example: Create namespace +kubectl create namespace sap-integration + +# Verify cluster resources +kubectl get nodes -o wide +kubectl top nodes +``` + +### Step 2: Activate Edge Integration Cell + +1. Navigate to Integration Suite +2. Go to Settings → Integrations +3. Enable Edge Integration Cell +4. Note the activation token + +### Step 3: Deploy Edge Lifecycle Management Bridge + +```bash +# Download and deploy the bridge +# Follow SAP-provided instructions for your platform +``` + +### Step 4: Add Edge Node + +1. In Integration Suite, go to Settings → Edge Nodes +2. Click "Add Edge Node" +3. Provide: + - Name + - Kubernetes context + - Namespace + +### Step 5: Deploy Edge Integration Cell Solution + +1. Select the edge node +2. Click "Deploy Solution" +3. Configure: + - Resource allocation + - Ingress settings + - Storage class + +### Step 6: Configure Keystore Synchronization + +1. Navigate to Security Material +2. Configure which keystores to sync +3. Verify synchronization status + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/deploy-the-edge-integration-cell-solution-ab81b84.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/deploy-the-edge-integration-cell-solution-ab81b84.md) + +--- + +## Operations + +### Deploy Integration Content + +1. Design integration flow in cloud +2. Navigate to Manage Integration Content +3. Select target: Edge Integration Cell +4. Click Deploy + +### Monitor + +**From Cloud**: +- Message processing logs (centralized) +- Runtime status +- Certificate expiration + +**On Cluster**: +```bash +# Check pod status +kubectl get pods -n sap-integration + +# View logs +kubectl logs -n sap-integration + +# Check resources +kubectl top pods -n sap-integration +``` + +### Keystore Management + +**Synchronization**: +- Cloud keystores sync to edge +- Automatic sync at intervals +- Manual sync trigger available + +**Local Keystores**: +- Edge-specific certificates +- Not synced to cloud +- Managed via API/CLI + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/manage-keystore-for-edge-integration-cell-39eb101.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/manage-keystore-for-edge-integration-cell-39eb101.md) + +### Upgrade + +1. Check for available updates in Integration Suite +2. Review release notes +3. Initiate upgrade from cloud UI +4. Monitor rollout progress + +```bash +# Monitor upgrade +kubectl get pods -n sap-integration -w +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/upgrade-edge-integration-cell-27c3926.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/upgrade-edge-integration-cell-27c3926.md) + +### Backup and Restore + +**Backup**: +- Export integration content +- Backup keystore entries +- Document configuration + +**Restore**: +- Redeploy solution if needed +- Restore keystores +- Redeploy integration content + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/backup-and-restore-edge-integration-cell-61cf37b.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/backup-and-restore-edge-integration-cell-61cf37b.md) + +--- + +## Troubleshooting + +### Common Issues + +| Issue | Resolution | +|-------|------------| +| Pods not starting | Check resources, image pull | +| Keystore sync failed | Verify connectivity, permissions | +| Deployment failed | Check logs, storage availability | +| Connection timeout | Verify firewall, DNS resolution | + +### Diagnostic Commands + +```bash +# Check pod status +kubectl get pods -n sap-integration -o wide + +# Describe failing pod +kubectl describe pod -n sap-integration + +# View pod logs +kubectl logs -n sap-integration --tail=100 + +# Check events +kubectl get events -n sap-integration --sort-by='.lastTimestamp' + +# Check persistent volumes +kubectl get pv,pvc -n sap-integration +``` + +### Log Locations + +| Log Type | Access | +|----------|--------| +| Runtime Logs | Kubernetes pod logs | +| Message Logs | Integration Suite Monitor | +| System Logs | Cloud Foundry logs | + +### Connectivity Test + +```bash +# Test outbound connectivity +kubectl run -it --rm test --image=curlimages/curl \ + --restart=Never -n sap-integration -- \ + curl -v [https://your-btp-url.hana.ondemand.com](https://your-btp-url.hana.ondemand.com) +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-edge-integration-cell-816d9e4.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-edge-integration-cell-816d9e4.md) + +--- + +## Runtime Scope + +### Supported Features +Most Cloud Integration features supported with some exceptions. + +### Not Supported +- Neo environment features +- Some deprecated adapters +- Certain legacy configurations + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/edge-integration-cell-runtime-scope-144c64a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/edge-integration-cell-runtime-scope-144c64a.md) + +--- + +## Related Documentation + +- **Overview**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-edge-integration-cell-aee74bb.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-edge-integration-cell-aee74bb.md) +- **Planning**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/plan-your-setup-of-edge-integration-cell-217fed1.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/plan-your-setup-of-edge-integration-cell-217fed1.md) +- **Operations**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/operating-edge-integration-cell-2af17b8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/operating-edge-integration-cell-2af17b8.md) +- **Troubleshooting**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-edge-integration-cell-816d9e4.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-edge-integration-cell-816d9e4.md) diff --git a/references/event-mesh.md b/references/event-mesh.md new file mode 100644 index 0000000..a848227 --- /dev/null +++ b/references/event-mesh.md @@ -0,0 +1,385 @@ +# Event Mesh - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Core Concepts](#core-concepts) +3. [Topics](#topics) +4. [Queues](#queues) +5. [Event Brokers](#event-brokers) +6. [Message Clients](#message-clients) +7. [Webhook Subscriptions](#webhook-subscriptions) +8. [Best Practices](#best-practices) + +--- + +## Overview + +Event Mesh is a capability within SAP Integration Suite that enables event-driven architecture (EDA) for publishing and consuming business events across your enterprise ecosystem. + +**Key Benefits**: +- Decouple producers from consumers +- Enable real-time event processing +- Scale independently +- Support async communication patterns + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/event-mesh-3129673.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/event-mesh-3129673.md) + +--- + +## Core Concepts + +### What is an Event? + +An event represents "a change in the state of data" - something that happens in a system that other systems may need to know about. + +**Examples**: +- Order created in e-commerce system +- Temperature sensor reading changed +- Customer record updated in CRM +- Payment processed + +### Event-Driven Architecture (EDA) + +EDA helps enterprises "act on new data in near-real time" by: +- Publishing events when state changes occur +- Subscribing to events of interest +- Processing events asynchronously +- Decoupling system dependencies + +### Event Messages + +Events generate messages to communicate event data between systems. Messages contain: +- Event type/topic +- Payload (event data) +- Metadata (timestamp, source, etc.) + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-events-9a5bf90.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-events-9a5bf90.md) + +--- + +## Topics + +Topics classify event messages using a hierarchical structure. + +### Topic Structure + +Format: `level1/level2/level3/.../levelN` + +**Example**: +``` +sales/orders/created +sales/orders/updated +sales/orders/cancelled +inventory/stock/updated +inventory/stock/depleted +``` + +### Topic Naming Rules + +| Rule | Requirement | +|------|-------------| +| Length | Maximum 150 characters | +| Characters | Alphanumeric, underscore, period, hyphen | +| Segments | Minimum 2, maximum 20 | +| Separator | Forward slash (/) only | +| Start/End | Cannot start or end with / | +| Empty segments | Not allowed | + +### Topic Wildcards + +**Asterisk (*)**: Matches entire subtree, must be at end +``` +sales/* → matches sales/orders, sales/returns, etc. +sales/orders/* → matches sales/orders/created, sales/orders/updated +``` + +**Plus (+)**: Matches single segment +``` +sales/+/created → matches sales/orders/created, sales/returns/created ++/orders/+ → matches sales/orders/created, purchases/orders/updated +``` + +### Topic Subscriptions + +Queues subscribe to topics to receive matching events: + +``` +Subscription: sales/*/created +Matches: + ✓ sales/orders/created + ✓ sales/returns/created + ✓ sales/quotes/created + ✗ sales/orders/updated +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-topics-and-topic-subscriptions-1712c0d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-topics-and-topic-subscriptions-1712c0d.md) + +--- + +## Queues + +Queues are endpoints that persist messages for consumers. + +### Queue Definition + +"A queue is an endpoint configured with topic subscriptions that can publish messages to and consume messages from." + +### Queue Types + +| Type | Description | Use Case | +|------|-------------|----------| +| **EXCLUSIVE** | Only one consumer can access at a time | Serial processing, single consumer | +| **NON-EXCLUSIVE** | Multiple consumers can access | Parallel processing, load balancing | + +### Queue Workflow + +``` +1. Producer → publishes message → Event Mesh +2. Event Mesh → matches topic → stores in queue +3. Queue → retains message → until consumed +4. Consumer → connects → receives message +5. Consumer → acknowledges → message removed +``` + +### Queue Features + +- Subscribe to multiple topics +- Persist messages until consumed +- Support guaranteed delivery +- Enable message acknowledgment +- Allow dead-letter handling + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/queues-99b7501.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/queues-99b7501.md) + +--- + +## Event Brokers + +### Definition + +An event broker is "middleware that mediates the communication of event messages between producers and consumers using the various message exchange patterns." + +### Broker Functions + +1. **Receive** events from producers +2. **Route** based on topics/subscriptions +3. **Store** for persistence +4. **Deliver** to subscribers +5. **Acknowledge** successful delivery + +### Deployment Options + +| Type | Description | +|------|-------------| +| Hardware appliance | Physical messaging hardware | +| Software | On-premise software installation | +| Cloud SaaS | SAP Event Mesh service | + +### Message Exchange Patterns + +| Pattern | Description | +|---------|-------------| +| Publish/Subscribe | One-to-many distribution | +| Point-to-Point | One-to-one delivery | +| Request/Reply | Synchronous with response | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-event-brokers-f72428f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-event-brokers-f72428f.md) + +--- + +## Message Clients + +Message clients connect applications to Event Mesh. + +### Creating a Message Client + +**Via BTP Cockpit**: +1. Navigate to Event Mesh service +2. Create message client instance +3. Configure queue subscriptions +4. Generate credentials + +**Via CF CLI**: +```bash +cf create-service enterprise-messaging default my-event-mesh \ + -c '{"emname": "my-client", "options": {"management": true, "messaging": true}}' +``` + +### Client Configuration + +```json +{ + "emname": "my-message-client", + "namespace": "company/department/app", + "rules": { + "topicRules": { + "publishFilter": ["${namespace}/*"], + "subscribeFilter": ["${namespace}/*", "shared/*"] + }, + "queueRules": { + "publishFilter": ["${namespace}/*"], + "subscribeFilter": ["${namespace}/*"] + } + } +} +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/configure-a-message-client-867c517.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/configure-a-message-client-867c517.md) + +--- + +## Webhook Subscriptions + +Enable HTTP-based event delivery without persistent connections. + +### How Webhooks Work + +``` +1. Event published → Event Mesh +2. Event Mesh → matches subscription +3. Event Mesh → HTTP POST → Webhook URL +4. Webhook endpoint → processes event +5. Endpoint → returns 2xx → acknowledged +``` + +### Webhook Configuration + +| Parameter | Description | +|-----------|-------------| +| URL | Target endpoint for events | +| Topic subscription | Topics to receive | +| Authentication | Basic, OAuth, Certificate | +| Retry policy | Retry on failure | + +### Webhook vs Queue Consumption + +| Aspect | Webhook | Queue | +|--------|---------|-------| +| Connection | HTTP push | Protocol connection | +| Persistence | Limited | Full | +| Ordering | Not guaranteed | Guaranteed | +| Throughput | Lower | Higher | +| Simplicity | Higher | Lower | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/webhook-subscriptions-58e3729.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/webhook-subscriptions-58e3729.md) + +--- + +## Integration with Cloud Integration + +### AMQP Adapter + +Connect iFlows to Event Mesh using AMQP adapter. + +**Sender Adapter** (consume events): +``` +Adapter Type: AMQP +Transport Protocol: WebSocket +Host: messaging-service-host +Queue Name: queue:my-queue +Authentication: OAuth2 Client Credentials +``` + +**Receiver Adapter** (publish events): +``` +Adapter Type: AMQP +Transport Protocol: WebSocket +Host: messaging-service-host +Topic: topic/my/event +Authentication: OAuth2 Client Credentials +``` + +### Event-Driven iFlow Pattern + +``` +┌──────────────┐ ┌────────────────┐ ┌──────────────┐ +│ Event Mesh │ → │ iFlow (AMQP) │ → │ Backend │ +│ Queue │ │ Processing │ │ System │ +└──────────────┘ └────────────────┘ └──────────────┘ +``` + +--- + +## Best Practices + +### Topic Design + +1. **Use hierarchical structure** + ``` + organization/domain/entity/action + acme/sales/order/created + ``` + +2. **Be specific but not too granular** + - Good: `sales/orders/created` + - Too broad: `sales/event` + - Too specific: `sales/orders/created/usa/region1/store5` + +3. **Use consistent naming conventions** + - lowercase + - no spaces + - descriptive names + +### Queue Design + +1. **One queue per consumer type** + - Order processing queue + - Analytics queue + - Audit queue + +2. **Use dead-letter queues** + - Handle failed messages + - Enable retry analysis + +3. **Set appropriate TTL** + - Time-to-live for messages + - Prevent queue overflow + +### Error Handling + +1. **Acknowledge after processing** + - Don't acknowledge before work is done + - Use transactions when needed + +2. **Implement retry logic** + - Exponential backoff + - Maximum retry count + +3. **Use dead-letter handling** + - Route failed messages + - Enable investigation + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Event** | Change in system state | +| **Topic** | Hierarchical event classification | +| **Queue** | Persistent message endpoint | +| **Subscription** | Topic pattern for queue | +| **Producer** | Application publishing events | +| **Consumer** | Application receiving events | +| **Broker** | Middleware routing events | +| **Webhook** | HTTP-based event delivery | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-event-mesh-501ba2d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-event-mesh-501ba2d.md) + +--- + +## Related Documentation + +- **Event Mesh Overview**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/event-mesh-3129673.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/event-mesh-3129673.md) +- **Events**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-events-9a5bf90.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-events-9a5bf90.md) +- **Event Brokers**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-event-brokers-f72428f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-event-brokers-f72428f.md) +- **Topics**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-topics-and-topic-subscriptions-1712c0d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-are-topics-and-topic-subscriptions-1712c0d.md) +- **Queues**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/queues-99b7501.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/queues-99b7501.md) +- **Topic Syntax**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/topic-naming-syntax-62460b8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/topic-naming-syntax-62460b8.md) diff --git a/references/graph-odata.md b/references/graph-odata.md new file mode 100644 index 0000000..992859d --- /dev/null +++ b/references/graph-odata.md @@ -0,0 +1,375 @@ +# Graph & OData Provisioning - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Graph Overview](#graph-overview) +2. [Business Data Graph](#business-data-graph) +3. [Entity Types](#entity-types) +4. [Querying Graph](#querying-graph) +5. [Extensibility](#extensibility) +6. [OData Provisioning Overview](#odata-provisioning-overview) +7. [OData Service Registration](#odata-service-registration) +8. [Limits and Quotas](#limits-and-quotas) + +--- + +## Graph Overview + +Graph is a capability that provides a unified API to access business data across SAP systems as a semantically connected data graph. + +### Key Benefits + +- **Single API** for multiple SAP systems +- **Unified data model** across S/4HANA, Sales Cloud, SuccessFactors +- **Query languages** OData V4 and GraphQL +- **No data caching** - queries route to source systems +- **Scalable multitenant** architecture + +### How It Works + +``` +┌─────────────────┐ +│ Applications │ +│ (OData/GraphQL)│ +└────────┬────────┘ + │ +┌────────▼────────┐ +│ Graph │ +│ Business Data │ +│ Graph │ +└────────┬────────┘ + │ +┌────────┴────────────────────────────┐ +│ │ +▼ ▼ ▼ +┌──────────┐ ┌──────────┐ ┌──────────────┐ +│ S/4HANA │ │ Sales │ │SuccessFactors│ +│ Cloud │ │ Cloud │ │ │ +└──────────┘ └──────────┘ └──────────────┘ +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-graph-ad1c48d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-graph-ad1c48d.md) + +--- + +## Business Data Graph + +The Business Data Graph consolidates data entities from SAP systems into one curated, semantically connected data model. + +### SAP-Managed Graph + +SAP provides a baseline data graph with: +- Pre-defined entity relationships +- Standard data models +- Cross-system navigation + +### Supported Data Sources + +| System | Entity Examples | +|--------|-----------------| +| S/4HANA Cloud | BusinessPartner, SalesOrder, Product | +| Sales Cloud | Account, Opportunity, Lead | +| SuccessFactors | Employee, Position, Department | + +### Graph Navigator + +Visual tool for exploring the data graph: +- Browse entities and relationships +- View entity properties +- Test queries +- Explore navigation paths + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/graph-e03300f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/graph-e03300f.md) + +--- + +## Entity Types + +### Unified Entities + +Entities that aggregate data from multiple systems into a single view. + +**Example**: Customer entity combining: +- S/4HANA BusinessPartner +- Sales Cloud Account +- SuccessFactors Employee (as contact) + +### Mirrored Entities + +Direct representation of source system entities without transformation. + +### Custom Entities + +User-defined entities that extend the standard graph: +- Custom data sources +- Custom properties +- Custom relationships + +### Entity Properties + +| Property Type | Description | +|---------------|-------------| +| Primitive | String, Number, Boolean, Date | +| Navigation | Links to other entities | +| Complex | Structured nested types | + +**Documentation**: +- Unified: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/unified-entities-9bcd2ec.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/unified-entities-9bcd2ec.md) +- Mirrored: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/mirrored-entities-07fdc7a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/mirrored-entities-07fdc7a.md) +- Custom: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/custom-entities-af8dcd6.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/custom-entities-af8dcd6.md) + +--- + +## Querying Graph + +### OData V4 Queries + +Standard OData query syntax: + +``` +GET /graph/api/v1/sap.graph/Customer +GET /graph/api/v1/sap.graph/Customer('1001') +GET /graph/api/v1/sap.graph/Customer?$filter=country eq 'US' +GET /graph/api/v1/sap.graph/Customer?$select=name,email +GET /graph/api/v1/sap.graph/Customer?$expand=orders +``` + +### Query Options + +| Option | Description | +|--------|-------------| +| `$filter` | Filter results | +| `$select` | Select properties | +| `$expand` | Include related entities | +| `$orderby` | Sort results | +| `$top` | Limit results | +| `$skip` | Pagination offset | + +### GraphQL Queries + +```graphql +query { + Customer(id: "1001") { + name + email + orders { + orderNumber + totalAmount + } + } +} +``` + +### Navigation + +Traverse entity relationships: + +``` +# OData - Get customer's orders +GET /graph/api/v1/sap.graph/Customer('1001')/orders + +# OData - Get order's line items +GET /graph/api/v1/sap.graph/SalesOrder('ORDER001')/items +``` + +--- + +## Extensibility + +### Custom Data Sources + +Add non-SAP data to the graph: + +1. **Register data source** connection +2. **Define entity mappings** +3. **Configure authentication** +4. **Test connectivity** + +### Projections + +Customize existing entities: +- Add/remove properties +- Rename entities +- Filter data +- Define transformations + +### Compositions + +Create new entities from existing ones: +- Combine entities +- Define relationships +- Create computed properties + +### Projection Definition (JSON) + +```json +{ + "projections": [ + { + "name": "MyCustomer", + "source": "sap.graph.Customer", + "properties": { + "include": ["id", "name", "email"], + "exclude": ["internalNotes"] + }, + "filter": "status eq 'ACTIVE'" + } + ] +} +``` + +--- + +## OData Provisioning Overview + +OData Provisioning exposes SAP Business Suite data as OData services on BTP without requiring an on-premise SAP Gateway hub. + +### Key Features + +- **Expose business data** as OData services +- **No Gateway hub** installation required +- **Reduced TCO** with cloud-managed service +- **Multi-device access** through standard protocol + +### Architecture + +``` +┌─────────────────┐ +│ Application │ +│ (OData V2/V4) │ +└────────┬────────┘ + │ +┌────────▼────────┐ +│ OData │ +│ Provisioning │ +│ (BTP) │ +└────────┬────────┘ + │ Cloud Connector +┌────────▼────────┐ +│ SAP Business │ +│ Suite (ECC) │ +│ (On-Premise) │ +└─────────────────┘ +``` + +### Prerequisites + +| Requirement | Description | +|-------------|-------------| +| Cloud Connector | Connect to on-premise | +| Backend components | IW_BEP 200 or SAP_GWFND | +| Service plan | Appropriate IS service plan | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/odata-provisioning-d257fc3.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/odata-provisioning-d257fc3.md) + +--- + +## OData Service Registration + +### Register Service + +1. **Navigate** to OData Provisioning in Integration Suite +2. **Add system** connection via Cloud Connector +3. **Select services** to expose +4. **Configure** service settings +5. **Activate** service + +### Service Settings + +| Setting | Description | +|---------|-------------| +| Service Name | External service identifier | +| Backend System | Source system connection | +| Authentication | User propagation, technical user | +| Cache Settings | Response caching options | + +### Runtime Access + +Configure user access: +1. **Create role collection** for OData access +2. **Assign users** or user groups +3. **Map roles** to service operations + +### Service URL Pattern + +``` +[https://.integrationsuite.cfapps..hana.ondemand.com](https://.integrationsuite.cfapps..hana.ondemand.com) + /odata/v4// +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/runtime-access-and-role-assignment-for-odata-provisioning-b46816c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/runtime-access-and-role-assignment-for-odata-provisioning-b46816c.md) + +--- + +## Limits and Quotas + +### Graph Limits + +| Limit | Value | Scope | +|-------|-------|-------| +| Business data graphs | 500 | Per global account | +| Business data graphs | 50 | Per subaccount | +| Services per graph | 5,000 | Per graph | +| Service metadata size | 50 MB | Per service | +| Extensions | 100 | Per subaccount | +| Projection definitions | 100 | Per extension | +| Projection file size | 1 MB | Per file | + +### OData Provisioning Limits + +| Limit | Value | +|-------|-------| +| Services | Based on service plan | +| Connections | Based on service plan | +| Request size | 50 MB | +| Response size | 50 MB | + +### Error Handling + +When limits are exceeded: +- Graph returns error response +- Check quota usage in cockpit +- Request quota increase if needed + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/limits-a61f1ce.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/limits-a61f1ce.md) + +--- + +## Best Practices + +### Graph Usage + +1. **Use projections** to limit data exposure +2. **Select specific properties** to reduce payload +3. **Implement pagination** for large result sets +4. **Cache** where appropriate in applications + +### OData Provisioning + +1. **Secure services** with proper authentication +2. **Monitor usage** through BTP cockpit +3. **Optimize queries** to reduce backend load +4. **Use filters** to limit data transfer + +### Performance + +1. **Avoid deep navigation** (>3 levels) +2. **Batch requests** when possible +3. **Use $select** to limit properties +4. **Implement client-side caching** + +--- + +## Related Documentation + +- **Graph Overview**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-graph-ad1c48d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-graph-ad1c48d.md) +- **Business Data Graph**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/business-data-graph-894e28c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/business-data-graph-894e28c.md) +- **OData Provisioning**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/odata-provisioning-d257fc3.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/odata-provisioning-d257fc3.md) +- **Graph Troubleshooting**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-graph-2cfb06c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-graph-2cfb06c.md) +- **Limits**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/limits-a61f1ce.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/limits-a61f1ce.md) diff --git a/references/integration-advisor-tpm.md b/references/integration-advisor-tpm.md new file mode 100644 index 0000000..6421336 --- /dev/null +++ b/references/integration-advisor-tpm.md @@ -0,0 +1,389 @@ +# Integration Advisor & Trading Partner Management - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Integration Advisor Overview](#integration-advisor-overview) +2. [Type Systems](#type-systems) +3. [Message Implementation Guidelines (MIGs)](#message-implementation-guidelines-migs) +4. [Mapping Guidelines (MAGs)](#mapping-guidelines-mags) +5. [Trading Partner Management Overview](#trading-partner-management-overview) +6. [Partner Profiles](#partner-profiles) +7. [Agreements](#agreements) +8. [Runtime Artifacts](#runtime-artifacts) + +--- + +## Integration Advisor Overview + +SAP Integration Advisor is a cloud application that simplifies B2B/A2A and B2G integration by using machine learning to accelerate content development. + +### Key Benefits + +- **60% faster** content creation to deployment +- **Reduced manual work** managing multiple standards +- **Content sharing** with other users +- **AI-powered** mapping suggestions + +### Supported Standards + +| Standard | Description | +|----------|-------------| +| UN/EDIFACT | International EDI standard | +| ASC X12 | North American EDI standard | +| SAP IDoc | SAP Intermediate Document | +| cXML | Commerce XML | +| TRADACOMS | UK retail EDI | +| VDA | German automotive | +| Odette | European automotive | + +### Core Components + +``` +Type Systems → MIGs → MAGs → Runtime Artifacts + ↓ ↓ ↓ ↓ + Standards Custom Trans- Deploy to + Library Messages forms CI/PO +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/overview-of-sap-integration-advisor-f99fdaf.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/overview-of-sap-integration-advisor-f99fdaf.md) + +--- + +## Type Systems + +Type systems are pre-built message templates maintained by standards agencies. + +### SAP-Provided Type Systems + +| Type System | Use Case | +|-------------|----------| +| UN/EDIFACT | International B2B | +| ASC X12 | North American B2B | +| SAP IDoc | SAP-to-SAP integration | +| ISO 20022 | Financial messaging | +| GS1 | Supply chain standards | + +### Custom Type Systems + +Organizations can upload proprietary message structures: + +1. **Define structure** using XSD or codelists +2. **Upload** to Integration Advisor +3. **Use** in MIG/MAG creation + +### Type System Components + +| Component | Description | +|-----------|-------------| +| Message types | Document definitions | +| Segments | Reusable data groups | +| Data elements | Individual fields | +| Codelists | Enumerated values | +| Qualifiers | Context specifiers | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md) + +--- + +## Message Implementation Guidelines (MIGs) + +MIGs are customized message interfaces that define specific message requirements. + +### MIG Purpose + +- Define **which fields** are used +- Specify **cardinality** (required/optional) +- Document **business meaning** +- Ensure **partner alignment** + +### Creating a MIG + +1. **Select type system** (e.g., EDIFACT D.96A) +2. **Choose message type** (e.g., ORDERS) +3. **Customize structure**: + - Mark required/optional segments + - Set field constraints + - Add documentation +4. **Activate** for use + +### MIG Structure + +``` +MIG: ORDERS_CustomerA +├── UNH (Mandatory) +│ ├── 0062 Message Reference (M) +│ └── S009 Message Identifier (M) +├── BGM (Mandatory) +│ ├── C002 Document Name (M) +│ └── C106 Document Identification (M) +├── DTM (Optional, Max 35) +│ ├── C507 Date/Time/Period (M) +│ └── 2005 Qualifier (M) +└── ... +``` + +### MIG Best Practices + +1. **Start from standards** - Use SAP type systems +2. **Document everything** - Add business context +3. **Be specific** - Define exact requirements +4. **Version control** - Track changes + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md) + +--- + +## Mapping Guidelines (MAGs) + +MAGs define transformations between source and target messages. + +### MAG Purpose + +- Define **field mappings** between standards +- Specify **transformations** (concatenation, lookup, etc.) +- Generate **runtime artifacts** for deployment + +### Creating a MAG + +1. **Select source MIG** (e.g., IDoc ORDERS05) +2. **Select target MIG** (e.g., EDIFACT ORDERS) +3. **Map fields**: + - Direct mappings + - Transformations + - Conditions + - Constants +4. **Generate artifacts** + +### MAG Mapping Types + +| Type | Description | +|------|-------------| +| Direct | 1:1 field mapping | +| Concatenate | Combine multiple fields | +| Split | Divide field into parts | +| Lookup | Value mapping table | +| Constant | Fixed value | +| Conditional | If/then logic | +| Function | Custom transformation | + +### AI-Powered Mapping + +Integration Advisor uses machine learning to: +- **Suggest mappings** based on field names/types +- **Learn from approvals** to improve suggestions +- **Identify patterns** across similar mappings + +### Generated Artifacts + +| Artifact | Target Platform | +|----------|-----------------| +| XSLT mapping | Cloud Integration | +| Message mapping | Cloud Integration | +| Operation mapping | Process Orchestration | +| XSD schemas | Both platforms | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md) + +--- + +## Trading Partner Management Overview + +SAP Trading Partner Management (TPM) streamlines B2B relationship management and governance. + +### Key Capabilities + +- **Partner profiles** with B2B requirements +- **Agreement templates** for common scenarios +- **Automated artifact generation** +- **Protocol support** (AS2, SFTP, FTP) + +### Supported Protocols + +| Protocol | Description | +|----------|-------------| +| AS2 | Applicability Statement 2 (HTTPS) | +| SFTP | Secure File Transfer Protocol | +| FTP | File Transfer Protocol | +| HTTPS | HTTP with TLS | + +### Supported Standards + +| Standard | Description | +|----------|-------------| +| EDI | Electronic Data Interchange | +| XML | Custom XML formats | +| JSON | JSON messages | +| IDoc | SAP IDocs | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/trading-partner-management-28fe3dc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/trading-partner-management-28fe3dc.md) + +--- + +## Partner Profiles + +Partner profiles store B2B partner information and requirements. + +### Profile Components + +| Component | Description | +|-----------|-------------| +| General Info | Company name, contact details | +| Identifiers | DUNS, GLN, VAT numbers | +| Communication | AS2, SFTP parameters | +| Certificates | Public keys, certificates | +| Agreements | Active trading agreements | + +### Creating a Partner Profile + +1. **Add partner** in TPM +2. **Configure identifiers**: + - Business identifier types + - Identifier values +3. **Set communication parameters**: + - Protocol (AS2/SFTP) + - Endpoints + - Authentication +4. **Upload certificates** + +### AS2 Configuration + +| Parameter | Description | +|-----------|-------------| +| AS2 ID | Partner's AS2 identifier | +| Partner URL | MDN return URL | +| Encryption | Encryption algorithm | +| Signing | Signature algorithm | +| Certificate | Partner's public certificate | + +### SFTP Configuration + +| Parameter | Description | +|-----------|-------------| +| Host | SFTP server hostname | +| Port | Server port (default: 22) | +| Directory | File drop location | +| Authentication | Password or SSH key | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/trading-partner-management-28fe3dc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/trading-partner-management-28fe3dc.md) + +--- + +## Agreements + +Agreements define B2B transaction requirements between partners. + +### Agreement Components + +| Component | Description | +|-----------|-------------| +| Parties | Company and partner | +| Transactions | Supported message types | +| Communication | Protocol settings | +| Processing | MIG/MAG references | +| Validity | Effective dates | + +### Agreement Templates + +Reusable templates for common B2B scenarios: + +1. **Create template** with standard settings +2. **Include transactions** (e.g., ORDERS, INVOIC) +3. **Define mappings** (MIG/MAG references) +4. **Apply to partners** to create agreements + +### Transaction Types + +| Direction | Description | +|-----------|-------------| +| Inbound | Partner sends to company | +| Outbound | Company sends to partner | + +### Agreement Workflow + +``` +1. Create Agreement Template + ↓ +2. Select Partner Profile + ↓ +3. Generate Agreement + ↓ +4. Configure Partner-Specific Settings + ↓ +5. Activate Agreement + ↓ +6. Generate Runtime Artifacts +``` + +--- + +## Runtime Artifacts + +TPM generates artifacts for Cloud Integration deployment. + +### Generated Artifacts + +| Artifact | Purpose | +|----------|---------| +| Partner Directory entries | Partner parameters | +| Integration flows | Message processing | +| Value mappings | ID translations | +| Agreements | Runtime configuration | + +### Partner Directory + +Central repository for partner parameters accessed at runtime: + +```groovy +// Access partner info in iFlow +def pd = ITApiFactory.getService(PartnerDirectoryService.class, null) +def partner = pd.getPartner("PartnerID") +def as2Id = partner.getParameter("AS2_ID") +``` + +### Deployment Process + +1. **Activate agreement** in TPM +2. **Push artifacts** to Partner Directory +3. **Deploy iFlows** to Cloud Integration +4. **Test** end-to-end + +### Monitoring + +Track B2B messages in Integration Suite Monitor: +- Partner identification +- Agreement reference +- Processing status +- Error details + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **Type System** | Standard message library | +| **MIG** | Message Implementation Guideline | +| **MAG** | Mapping Guideline | +| **TPM** | Trading Partner Management | +| **Partner Profile** | B2B partner configuration | +| **Agreement** | Transaction contract | +| **AS2** | Secure HTTP EDI protocol | +| **EDI** | Electronic Data Interchange | +| **Partner Directory** | Runtime parameter store | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-sap-trading-partner-management-81860a4.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-sap-trading-partner-management-81860a4.md) + +--- + +## Related Documentation + +- **Integration Advisor**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/integration-advisor-3309fe0.md) +- **TPM Overview**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/trading-partner-management-28fe3dc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/trading-partner-management-28fe3dc.md) +- **Glossary (IA)**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/terminology-glossary-for-sap-integration-advisor-9c221b4.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/terminology-glossary-for-sap-integration-advisor-9c221b4.md) +- **Glossary (TPM)**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-sap-trading-partner-management-81860a4.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-sap-trading-partner-management-81860a4.md) diff --git a/references/migration-assessment.md b/references/migration-assessment.md new file mode 100644 index 0000000..71798f4 --- /dev/null +++ b/references/migration-assessment.md @@ -0,0 +1,396 @@ +# Migration & Integration Assessment - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Migration Assessment Overview](#migration-assessment-overview) +2. [Migration Tooling](#migration-tooling) +3. [Supported Components](#supported-components) +4. [Migration Patterns](#migration-patterns) +5. [Integration Assessment Overview](#integration-assessment-overview) +6. [ISA-M Methodology](#isa-m-methodology) +7. [Questionnaires](#questionnaires) +8. [Technology Mapping](#technology-mapping) + +--- + +## Migration Assessment Overview + +Migration Assessment evaluates the complexity and effort required to migrate integration scenarios from SAP Process Orchestration to SAP Integration Suite. + +### Key Capabilities + +1. **Data Extraction** - Extract from SAP PO/PI systems +2. **Data Evaluation** - Analyze integration scenarios +3. **Effort Estimation** - Estimate migration effort + +### Supported PO/PI Versions + +| Version | Minimum SP | +|---------|------------| +| 7.31 | SP28+ | +| 7.40 | SP23+ | +| 7.50 | SP06+ | + +### Assessment Status Levels + +| Status | Description | +|--------|-------------| +| Ready to migrate | Direct migration possible | +| Adjustment required | Manual modifications needed | +| Evaluation required | Complex assessment needed | + +### Assessment Workflow + +``` +1. Connect PO System + ↓ +2. Create Extraction Request + ↓ +3. Extract Data + ↓ +4. Evaluate Scenarios + ↓ +5. Review Assessment Report + ↓ +6. Plan Migration +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-assessment-164b835.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-assessment-164b835.md) + +--- + +## Migration Tooling + +Migration Tooling is a pattern-based feature that converts PO/PI integration objects to Cloud Integration flows. + +### How It Works + +1. **Analyze** - Examine migratable object +2. **Match** - Map to integration pattern +3. **Generate** - Create Cloud Integration flow +4. **Deploy** - Deploy to tenant + +### Supported Object Types + +| Object Type | Description | +|-------------|-------------| +| ICO | Integrated Configuration Objects | +| Receiver Determination | Message routing config | + +### Migration Approaches + +| Approach | Description | Use Case | +|----------|-------------|----------| +| Standard | Direct pattern-based migration | Simple scenarios | +| Pipeline | Step-by-step migration | Complex scenarios | +| Modular | Component-based migration | Large interfaces | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-tooling-1a3bfbc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-tooling-1a3bfbc.md) + +--- + +## Supported Components + +### Communication Channels + +| Adapter Type | Direction | Support | +|--------------|-----------|---------| +| HTTP | Sender/Receiver | Full | +| SOAP | Sender/Receiver | Full | +| SFTP | Sender/Receiver | Full | +| IDoc | Sender/Receiver | Full | +| RFC | Receiver | Full | +| File | Sender/Receiver | Partial | +| JMS | Sender/Receiver | Partial | +| Mail | Sender/Receiver | Full | + +### Flow Steps + +| Step Type | Support | +|-----------|---------| +| Message Mapping | Full | +| XSLT Mapping | Full | +| Content Modifier | Full | +| Router | Full | +| Splitter | Full | +| Exception Handling | Partial | + +### Known Limitations + +- Some adapter-specific features may differ +- Custom Java mappings require manual migration +- Certain PI-specific features not available +- BPM processes require redesign + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/supported-components-46b27d1.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/supported-components-46b27d1.md) + +--- + +## Migration Patterns + +### Standard Patterns + +Supported integration patterns with direct migration: + +| Pattern | Description | +|---------|-------------| +| Point-to-Point | Simple A→B integration | +| Content-Based Routing | Conditional routing | +| Message Mapping | Transformation | +| Message Split | Divide messages | +| Request-Reply | Synchronous call | + +### Pipeline Approach + +For complex scenarios: + +``` +┌───────────────┐ +│ PO Scenario │ +└───────┬───────┘ + │ +┌───────▼───────┐ +│ Stage 1: │ +│ Extract Data │ +└───────┬───────┘ + │ +┌───────▼───────┐ +│ Stage 2: │ +│ Transform │ +└───────┬───────┘ + │ +┌───────▼───────┐ +│ Stage 3: │ +│ Validate │ +└───────┬───────┘ + │ +┌───────▼───────┐ +│ CI iFlow │ +└───────────────┘ +``` + +### Modular Approach + +Break down large interfaces: + +1. **Identify components** in PO +2. **Map to CI artifacts** +3. **Migrate incrementally** +4. **Test each module** +5. **Integrate modules** + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/migration-patterns-40c080f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/migration-patterns-40c080f.md) + +--- + +## Integration Assessment Overview + +Integration Assessment helps assess your integration strategy and determine suitable integration technologies. + +### Key Capabilities + +- Capture ISA-M technology mappings +- Guide interface request workflows +- Apply policies during technology selection +- Provide intelligent recommendations + +### Assessment Workflow + +``` +1. Define Integration Domains + ↓ +2. Specify Integration Styles + ↓ +3. Create Questionnaires + ↓ +4. Evaluate Scenarios + ↓ +5. Receive Recommendations +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-integration-assessment-eeee253.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-integration-assessment-eeee253.md) + +--- + +## ISA-M Methodology + +SAP Integration Solution Advisory Methodology (ISA-M) provides a structured approach to integration architecture. + +### ISA-M Components + +| Component | Description | +|-----------|-------------| +| Integration Domains | Business areas (e.g., Finance, HR) | +| Integration Styles | Technical patterns (P2P, Process, Data) | +| Use Case Patterns | Specific scenarios | +| Technology Mapping | Platform recommendations | + +### Integration Domains + +Organize by business area: + +| Domain | Examples | +|--------|----------| +| Finance | AP, AR, GL | +| HR | Payroll, Benefits | +| Supply Chain | Procurement, Logistics | +| Customer | Sales, Service | +| Manufacturing | Production, Quality | + +### Integration Styles + +| Style | Description | Technology | +|-------|-------------|------------| +| Process Integration | Orchestrated flows | Cloud Integration | +| Data Integration | Bulk data movement | Data Intelligence | +| Analytics Integration | BI/reporting | SAC | +| User Integration | UI composition | Build Apps | +| Thing Integration | IoT devices | IoT Services | + +### Use Case Patterns + +| Pattern | Description | +|---------|-------------| +| A2A | Application to Application | +| B2B | Business to Business | +| B2G | Business to Government | +| Cloud2Cloud | Cloud to Cloud | +| Cloud2OnPrem | Cloud to On-Premise | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/sap-integration-solution-advisory-methodology-a2e17f3.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/sap-integration-solution-advisory-methodology-a2e17f3.md) + +--- + +## Questionnaires + +Questionnaires guide technology selection decisions. + +### Creating Questionnaires + +1. **Define questions** for your scenarios +2. **Set answer options** with weights +3. **Map to technologies** +4. **Assign to domains** + +### Question Types + +| Type | Description | +|------|-------------| +| Single choice | One answer | +| Multiple choice | Multiple answers | +| Free text | Open response | +| Rating scale | Numeric rating | + +### Sample Questions + +- Is this integration synchronous or asynchronous? +- Does this require guaranteed delivery? +- What is the expected message volume? +- Are there regulatory compliance requirements? +- Does this involve B2B partners? + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/questionnaires-da3f7d8.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/questionnaires-da3f7d8.md) + +--- + +## Technology Mapping + +Map integration requirements to technologies. + +### Mapping Process + +1. **Collect requirements** via questionnaire +2. **Evaluate responses** against criteria +3. **Score technologies** based on fit +4. **Generate recommendation** + +### Technology Options + +| Technology | Use Case | +|------------|----------| +| Cloud Integration | A2A/B2B messaging | +| API Management | API lifecycle | +| Event Mesh | Event-driven | +| Data Intelligence | Data pipelines | +| Open Connectors | SaaS connectivity | + +### Recommendation Output + +``` +Interface: Order Processing +Domain: Sales +Style: Process Integration + +Recommended: SAP Cloud Integration +Score: 95% + +Rationale: +- Supports async messaging ✓ +- B2B capability ✓ +- Transformation features ✓ +- Monitoring included ✓ +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/technology-mapping-a50d8d6.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/technology-mapping-a50d8d6.md) + +--- + +## Best Practices + +### Migration Planning + +1. **Inventory** all PO scenarios +2. **Prioritize** by business criticality +3. **Assess** migration complexity +4. **Plan** phased approach +5. **Test** thoroughly + +### Migration Execution + +1. **Extract** configuration from PO +2. **Review** assessment report +3. **Migrate** using tooling +4. **Validate** functionality +5. **Test** end-to-end +6. **Switch** traffic +7. **Decommission** PO scenario + +### Integration Assessment + +1. **Define** clear domains +2. **Standardize** questionnaires +3. **Document** decisions +4. **Review** periodically +5. **Update** mappings + +--- + +## Glossary + +| Term | Definition | +|------|------------| +| **ICO** | Integrated Configuration Object | +| **ISA-M** | Integration Solution Advisory Methodology | +| **PO** | Process Orchestration | +| **PI** | Process Integration | +| **MIG** | Message Implementation Guideline | +| **MAG** | Mapping Guideline | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-integration-assessment-5c29e9b.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/glossary-for-integration-assessment-5c29e9b.md) + +--- + +## Related Documentation + +- **Migration Assessment**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-assessment-164b835.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-assessment-164b835.md) +- **Migration Tooling**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-tooling-1a3bfbc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-migration-tooling-1a3bfbc.md) +- **Integration Assessment**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-integration-assessment-eeee253.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/what-is-integration-assessment-eeee253.md) +- **ISA-M**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/sap-integration-solution-advisory-methodology-a2e17f3.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/sap-integration-solution-advisory-methodology-a2e17f3.md) +- **Supported Components**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/supported-components-46b27d1.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/supported-components-46b27d1.md) +- **Migration Patterns**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/migration-patterns-40c080f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/migration-patterns-40c080f.md) diff --git a/references/operations-monitoring.md b/references/operations-monitoring.md new file mode 100644 index 0000000..4c21c4e --- /dev/null +++ b/references/operations-monitoring.md @@ -0,0 +1,456 @@ +# Operations & Monitoring - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Operations](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Operations) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Monitoring Overview](#monitoring-overview) +2. [Message Monitoring](#message-monitoring) +3. [Integration Content Management](#integration-content-management) +4. [Store Management](#store-management) +5. [Security Material Operations](#security-material-operations) +6. [Connectivity Testing](#connectivity-testing) +7. [Logging and Tracing](#logging-and-tracing) +8. [Alerting](#alerting) + +--- + +## Monitoring Overview + +The Integration Suite Monitor provides visibility into message processing, deployed content, and system health. + +### Monitor Areas + +``` +Monitor → Integrations and APIs + ├── Monitor Message Processing + │ ├── All Integration Flows + │ ├── All Artifacts + │ └── Failed Messages + ├── Manage Integration Content + │ └── Deployed artifacts + ├── Manage Security + │ ├── Keystore + │ ├── User Credentials + │ ├── OAuth Credentials + │ └── Known Hosts + └── Manage Stores + ├── Data Stores + ├── Variables + ├── Message Queues + └── Number Ranges +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/operating-and-monitoring-cloud-integration-c401afc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/operating-and-monitoring-cloud-integration-c401afc.md) + +--- + +## Message Monitoring + +### Filtering Messages + +| Filter | Options | +|--------|---------| +| Time | Past Minute, Hour, 24h, Week, Month, Custom | +| Status | Failed, Retry, Completed, Processing, Escalated, Cancelled, Discarded | +| Artifact | Integration Flow, OData API, SOAP API, REST API | +| ID | Message ID, Correlation ID | + +### Message Status Types + +| Status | Description | Action | +|--------|-------------|--------| +| **Completed** | Successfully processed | None needed | +| **Failed** | Processing error | Investigate error | +| **Retry** | Retry scheduled | Monitor retry | +| **Escalated** | Max retries exceeded | Manual intervention | +| **Processing** | Currently running | Wait for completion | +| **Cancelled** | Manually cancelled | Review if needed | +| **Discarded** | Intentionally dropped | Review discard reason | +| **Abandoned** | System cleanup | Review timeout settings | + +### Message Details + +| Section | Information | +|---------|-------------| +| Status | Processing time, error messages | +| Properties | Message ID, Correlation ID, Sender, Receiver | +| Custom Headers | User-defined properties | +| Logs | Log entries with levels | +| Attachments | MPL attachments (text, XML, etc.) | +| Artifact | Flow name, ID, package link | + +### Error Analysis + +1. **Open failed message** in monitor +2. **Review error message** in Status section +3. **Check logs** for detailed trace +4. **View attachments** for payload at failure +5. **Navigate to artifact** to review configuration + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/monitor-message-processing-314df3f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/monitor-message-processing-314df3f.md) + +--- + +## Integration Content Management + +### Deployed Artifacts View + +| Information | Description | +|-------------|-------------| +| Artifact Name | Integration flow name | +| Status | Started, Error, Starting | +| Deployed On | Deployment timestamp | +| Deployed By | User who deployed | +| Version | Artifact version | + +### Artifact Status Types + +| Status | Description | +|--------|-------------| +| Started | Running successfully | +| Starting | Deployment in progress | +| Error | Deployment failed | +| Stopping | Being undeployed | + +### Artifact Operations + +| Operation | Description | +|-----------|-------------| +| Undeploy | Remove from runtime | +| Restart | Stop and start | +| Download | Get deployed artifact | +| Navigate | Go to design view | + +### Endpoints + +View endpoints for deployed artifacts: +- Sender endpoints (inbound URLs) +- Configured protocols +- Authentication requirements + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-integration-content-09a7223.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-integration-content-09a7223.md) + +--- + +## Store Management + +### Data Stores + +Persistent storage for messages and variables. + +**Operations**: +| Action | Description | +|--------|-------------| +| View entries | Browse stored data | +| Delete entry | Remove specific entry | +| Delete all | Clear entire store | +| Download | Export entry content | + +**Monitoring Metrics**: +- Entry count +- Storage usage +- Overdue entries +- Last modified + +### Variables + +Runtime variables across integration flows. + +**Types**: +| Type | Scope | +|------|-------| +| Local Variable | Single flow | +| Global Variable | Entire tenant | + +**Operations**: +- View current values +- Download values +- Delete variables + +### Message Queues + +JMS queue management. + +**Monitoring**: +- Queue depth (message count) +- Consumer count +- Dead letter messages + +**Operations**: +| Action | Description | +|--------|-------------| +| Retry messages | Reprocess dead letters | +| Delete messages | Remove from queue | +| Move messages | Transfer between queues | + +### Number Ranges + +Unique identifier generation. + +**Management**: +- View current values +- Reset counters +- Delete ranges + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-stores-59f8e3a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-stores-59f8e3a.md) + +--- + +## Security Material Operations + +### Keystore Management + +**View Operations**: +- List all entries +- View certificate details +- Check expiration dates + +**Management Operations**: +| Operation | Description | +|-----------|-------------| +| Add Certificate | Import public certificate | +| Add Key Pair | Import private key + certificate | +| Rename Alias | Change entry name | +| Delete Entry | Remove from keystore | +| Download | Export certificate/keystore | + +**Backup Operations**: +- Backup individual entries +- Restore from backup +- View backup history + +### User Credentials + +**Management**: +- Deploy new credentials +- Update existing credentials +- Delete credentials +- View deployment status + +### OAuth Credentials + +**Types Supported**: +- Client Credentials +- Authorization Code +- SAML Bearer Assertion + +**Management**: +- Deploy OAuth configurations +- Update token settings +- Monitor token refresh + +### Known Hosts (SSH) + +**For SFTP connections**: +- Add known hosts +- Update host keys +- Remove hosts + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-security-6e7c44c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-security-6e7c44c.md) + +--- + +## Connectivity Testing + +### Test Types + +| Test | Purpose | +|------|---------| +| TLS | Test HTTPS connectivity | +| SSH | Test SFTP connectivity | +| AMQP | Test message broker | +| Kafka | Test Kafka connectivity | +| Cloud Connector | Test on-premise access | +| FTP | Test FTP connectivity | +| IMAP | Test mail (receive) | +| POP3 | Test mail (receive) | +| SMTP | Test mail (send) | + +### Running Connectivity Tests + +1. **Navigate** to Monitor → Connectivity Tests +2. **Select** test type +3. **Enter** connection parameters +4. **Execute** test +5. **Review** results + +### Test Parameters + +| Parameter | Description | +|-----------|-------------| +| Host | Target hostname | +| Port | Target port | +| Authentication | Credentials type | +| Timeout | Connection timeout | + +### Interpreting Results + +| Result | Meaning | +|--------|---------| +| Success | Connection established | +| Authentication Failed | Wrong credentials | +| Connection Refused | Firewall/service down | +| Timeout | Network/routing issue | +| Certificate Error | TLS/SSL problem | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/performing-connectivity-tests-d5b2fae.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/performing-connectivity-tests-d5b2fae.md) + +--- + +## Logging and Tracing + +### Log Levels + +| Level | Information | Use Case | +|-------|-------------|----------| +| None | No logging | Production (minimal) | +| Error | Errors only | Production (standard) | +| Info | Key operations | Development | +| Debug | Detailed info | Troubleshooting | +| Trace | Full payload | Deep debugging | + +### Setting Log Levels + +**Per Artifact**: +1. Navigate to deployed artifact +2. Select Log Configuration +3. Set desired level +4. Apply changes + +**Considerations**: +- Trace captures sensitive data +- Higher levels impact performance +- Revert after debugging + +### Tracing Integration Flows + +1. **Enable trace** on artifact +2. **Send test message** +3. **Open message** in monitor +4. **View trace details**: + - Step-by-step execution + - Payload at each step + - Header values + - Property values + +### System Logs + +**Access Methods**: +- Cloud Foundry logs via CLI +- Kibana (if configured) +- External logging services + +**CF CLI Commands**: +```bash +cf logs --recent +cf logs # streaming +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/setting-log-levels-4e6d3fc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/setting-log-levels-4e6d3fc.md) + +--- + +## Alerting + +### Alert Types + +| Alert | Description | +|-------|-------------| +| Message Failed | Processing error | +| Certificate Expiring | Certificate near expiry | +| Queue Full | JMS queue at capacity | +| Deployment Failed | Artifact deployment error | + +### Alert Configuration + +**SAP Alert Notification Service**: +1. Subscribe to Alert Notification +2. Configure alert channels (email, webhook) +3. Set up alert rules +4. Define recipients + +### External Monitoring Integration + +**SAP Cloud ALM**: +- Central monitoring dashboard +- Cross-system visibility +- SLA monitoring + +**Third-Party Tools**: +- Splunk (via external logging) +- Datadog +- New Relic + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/alerting-fe8c67d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/alerting-fe8c67d.md) + +--- + +## Resource Inspection + +### Inspect Views + +| View | Information | +|------|-------------| +| Data Store Usage | Storage consumption | +| Database Connections | Connection pool usage | +| Transaction Duration | Long-running transactions | +| Message Processing Logs | Log storage usage | + +### Identifying Issues + +**High Data Store Usage**: +- Review retention policies +- Clean up old entries +- Optimize store usage + +**Connection Pool Exhaustion**: +- Identify leaking flows +- Optimize connection handling +- Increase pool if needed + +**Long Transactions**: +- Review flow design +- Optimize database operations +- Consider async processing + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/inspect-a4d5e49.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/inspect-a4d5e49.md) + +--- + +## Best Practices + +### Monitoring + +1. **Set up alerts** for failed messages +2. **Review daily** message processing stats +3. **Monitor certificate** expiration (30-day warning) +4. **Track resource** utilization trends + +### Operations + +1. **Schedule maintenance** windows +2. **Document procedures** for common tasks +3. **Automate** routine operations via APIs +4. **Test connectivity** after network changes + +### Troubleshooting + +1. **Start with logs** - check message processing log +2. **Enable trace** temporarily for debugging +3. **Test connectivity** to isolate issues +4. **Review recent changes** for root cause + +--- + +## Related Documentation + +- **Operating CI**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/operating-and-monitoring-cloud-integration-c401afc.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/operating-and-monitoring-cloud-integration-c401afc.md) +- **Message Monitoring**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/monitor-message-processing-314df3f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/monitor-message-processing-314df3f.md) +- **Manage Security**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-security-6e7c44c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-security-6e7c44c.md) +- **Manage Stores**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-stores-59f8e3a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/manage-stores-59f8e3a.md) +- **Connectivity Tests**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/performing-connectivity-tests-d5b2fae.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/performing-connectivity-tests-d5b2fae.md) diff --git a/references/scripting.md b/references/scripting.md new file mode 100644 index 0000000..c7429ef --- /dev/null +++ b/references/scripting.md @@ -0,0 +1,562 @@ +# Scripting - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci/Development) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Groovy Scripting](#groovy-scripting) +3. [JavaScript Scripting](#javascript-scripting) +4. [Script Collections](#script-collections) +5. [Common Use Cases](#common-use-cases) +6. [Best Practices](#best-practices) +7. [API Reference](#api-reference) + +--- + +## Overview + +SAP Cloud Integration supports two scripting languages: +- **Groovy** (primary, full API support) +- **JavaScript** (limited API support) + +**When to Use Scripts**: +- Custom transformations not possible with standard steps +- Complex business logic +- Access to external libraries (Groovy) +- Dynamic routing decisions + +**When NOT to Use Scripts**: +- Standard transformations (use Content Modifier, Mapping) +- Simple XML/JSON manipulation (use XPath, JSONPath) +- Standard encoding/decoding (use Encoder/Decoder steps) + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md) + +--- + +## Groovy Scripting + +### Basic Structure + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message + +def Message processData(Message message) { + // Your code here + return message +} +``` + +### Accessing Message Components + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message + +def Message processData(Message message) { + // Get message body as String + def body = message.getBody(String.class) + + // Get message body as InputStream (for large payloads) + def bodyStream = message.getBody(java.io.InputStream.class) + + // Get specific header + def contentType = message.getHeader("Content-Type", String.class) + + // Get all headers as Map + def headers = message.getHeaders() + + // Get exchange property + def prop = message.getProperty("PropertyName") + + // Get all properties + def props = message.getProperties() + + return message +} +``` + +### Modifying Message Components + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message + +def Message processData(Message message) { + // Set body + message.setBody("New body content") + + // Set body from object + def data = [name: "John", age: 30] + message.setBody(groovy.json.JsonOutput.toJson(data)) + + // Set header + message.setHeader("X-Custom-Header", "value") + + // Set property + message.setProperty("CustomProperty", "value") + + return message +} +``` + +### XML Processing + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import groovy.xml.XmlSlurper +import groovy.xml.MarkupBuilder + +def Message processData(Message message) { + // Parse XML body (use parse for streams, not parseText) + def body = message.getBody(java.io.InputStream.class) + def xml = new XmlSlurper().parse(body) + + // Access elements + def name = xml.customer.name.text() + def id = xml.customer.@id.text() // attribute + + // Iterate over elements + xml.items.item.each { item -> + println "Item: ${item.name.text()}" + } + + // Create new XML + def writer = new StringWriter() + def builder = new MarkupBuilder(writer) + builder.response { + status("success") + data(name) + } + message.setBody(writer.toString()) + + return message +} +``` + +### JSON Processing + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import groovy.json.JsonSlurper +import groovy.json.JsonOutput + +def Message processData(Message message) { + // Parse JSON body + def body = message.getBody(String.class) + def json = new JsonSlurper().parseText(body) + + // Access properties + def name = json.customer.name + def items = json.items + + // Modify JSON + json.customer.processed = true + json.timestamp = new Date().format("yyyy-MM-dd'T'HH:mm:ss") + + // Convert back to JSON string + message.setBody(JsonOutput.toJson(json)) + + // Pretty print (avoid in production - performance impact) + // message.setBody(JsonOutput.prettyPrint(JsonOutput.toJson(json))) + + return message +} +``` + +### Logging + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import org.slf4j.LoggerFactory + +def Message processData(Message message) { + def log = LoggerFactory.getLogger("script.processing") + + log.info("Processing started") + log.debug("Body: ${message.getBody(String.class)}") + log.warn("Warning message") + log.error("Error occurred", new Exception("Details")) + + return message +} +``` + +### Secure Parameters + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import com.sap.it.api.ITApiFactory +import com.sap.it.api.securestore.SecureStoreService + +def Message processData(Message message) { + def secureStore = ITApiFactory.getService(SecureStoreService.class, null) + def credential = secureStore.getUserCredential("CredentialName") + + def username = credential.getUsername() + def password = new String(credential.getPassword()) + + return message +} +``` + +### Value Mappings + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import com.sap.it.api.ITApiFactory +import com.sap.it.api.mapping.ValueMappingApi + +def Message processData(Message message) { + def vmApi = ITApiFactory.getService(ValueMappingApi.class, null) + + def targetValue = vmApi.getMappedValue( + "SourceAgency", // source agency + "SourceIdentifier", // source identifier + "SourceValue", // source value + "TargetAgency", // target agency + "TargetIdentifier" // target identifier + ) + + return message +} +``` + +### Attachments + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import javax.activation.DataHandler + +def Message processData(Message message) { + // Get all attachments + def attachments = message.getAttachments() + + // Get specific attachment + def attachment = message.getAttachment("filename.pdf") + if (attachment) { + def content = attachment.getContent() + } + + // Add attachment + def data = "Attachment content".getBytes() + def dataSource = new javax.mail.util.ByteArrayDataSource(data, "text/plain") + message.addAttachmentObject("newfile.txt", new DataHandler(dataSource)) + + return message +} +``` + +--- + +## JavaScript Scripting + +### Basic Structure + +```javascript +function processData(message) { + // Your code here + return message; +} +``` + +### Accessing Message + +```javascript +function processData(message) { + // Get body + var body = message.getBody(java.lang.String); + + // Get header + var header = message.getHeader("Content-Type", java.lang.String); + + // Get property + var prop = message.getProperty("PropertyName"); + + // Set body + message.setBody("New content"); + + // Set header + message.setHeader("X-Custom", "value"); + + return message; +} +``` + +### JSON Processing + +```javascript +function processData(message) { + var body = message.getBody(java.lang.String); + var json = JSON.parse(body); + + // Modify + json.processed = true; + + message.setBody(JSON.stringify(json)); + return message; +} +``` + +**Note**: JavaScript has limited API support compared to Groovy. + +--- + +## Script Collections + +Reusable script libraries deployed as artifacts. + +### Creating Script Collection + +1. Create Script Collection artifact +2. Add script files (.groovy or .gsh) +3. Deploy to tenant + +### Structure + +``` +ScriptCollection/ +├── META-INF/ +│ └── MANIFEST.MF +└── script/ + ├── Utils.groovy + ├── Validators.groovy + └── Transformers.groovy +``` + +### Using in Integration Flow + +1. Add Script Collection reference in Resources +2. Import and use in Script step: + +```groovy +import com.company.Utils + +def Message processData(Message message) { + def result = Utils.processData(message.getBody(String.class)) + message.setBody(result) + return message +} +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/creating-a-script-collection-824bff0.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/creating-a-script-collection-824bff0.md) + +--- + +## Common Use Cases + +### Dynamic Routing + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message + +def Message processData(Message message) { + def body = message.getBody(String.class) + def json = new groovy.json.JsonSlurper().parseText(body) + + def endpoint + switch(json.region) { + case "US": + endpoint = "[https://us-api.example.com"](https://us-api.example.com") + break + case "EU": + endpoint = "[https://eu-api.example.com"](https://eu-api.example.com") + break + default: + endpoint = "[https://default-api.example.com"](https://default-api.example.com") + } + + message.setProperty("TargetEndpoint", endpoint) + return message +} +``` + +### Add Timestamp + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import java.time.Instant + +def Message processData(Message message) { + message.setHeader("X-Timestamp", Instant.now().toString()) + message.setProperty("ProcessingTime", new Date()) + return message +} +``` + +### UUID Generation + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message + +def Message processData(Message message) { + def uuid = java.util.UUID.randomUUID().toString() + message.setHeader("X-Correlation-ID", uuid) + return message +} +``` + +### Base64 Encoding/Decoding + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message + +def Message processData(Message message) { + def body = message.getBody(String.class) + + // Encode + def encoded = body.bytes.encodeBase64().toString() + + // Decode + def decoded = new String(encoded.decodeBase64()) + + message.setBody(encoded) + return message +} +``` + +### Exception Handling + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import org.slf4j.LoggerFactory + +def Message processData(Message message) { + def log = LoggerFactory.getLogger("script") + + try { + def body = message.getBody(String.class) + def json = new groovy.json.JsonSlurper().parseText(body) + // Process... + } catch (Exception e) { + log.error("Processing failed: ${e.message}", e) + message.setProperty("ErrorMessage", e.message) + throw e // Re-throw to trigger error handling + } + + return message +} +``` + +--- + +## Best Practices + +### Do + +1. **Use SLF4J for logging** + ```groovy + def log = LoggerFactory.getLogger("script") + log.info("Message") + ``` + +2. **Use streams for large payloads** + ```groovy + def body = message.getBody(java.io.InputStream.class) + def xml = new XmlSlurper().parse(body) + ``` + +3. **Use StringBuilder for string concatenation** + ```groovy + def sb = new StringBuilder() + items.each { sb.append(it) } + ``` + +4. **Include comments** + ```groovy + // Transform customer data to target format + // Input: JSON with customer array + // Output: XML with customer elements + ``` + +5. **Use credential artifacts** + ```groovy + def secureStore = ITApiFactory.getService(SecureStoreService.class, null) + def cred = secureStore.getUserCredential("MyCredential") + ``` + +### Don't + +1. **Don't use parseText() for large XML** + ```groovy + // BAD: Loads entire string into memory + def xml = new XmlSlurper().parseText(bodyString) + + // GOOD: Stream-based parsing + def xml = new XmlSlurper().parse(bodyStream) + ``` + +2. **Don't write credentials to headers** + ```groovy + // BAD: Exposed in traces + message.setHeader("Authorization", "Bearer " + token) + + // GOOD: Use adapter authentication + ``` + +3. **Don't use TimeZone.setDefault()** + - Affects entire JVM + - Not thread-safe + - Use explicit timezone in formatting + +4. **Don't use Eval class** + - Never unloaded from memory + - Performance and security issues + +5. **Don't bind variables unnecessarily** + - Persists in memory + - Not thread-safe + - Causes memory leaks + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md) + +--- + +## API Reference + +### Message API + +| Method | Description | +|--------|-------------| +| `getBody(Class)` | Get body as specified type | +| `setBody(Object)` | Set message body | +| `getHeader(name, Class)` | Get specific header | +| `getHeaders()` | Get all headers as Map | +| `setHeader(name, value)` | Set header | +| `getProperty(name)` | Get property | +| `getProperties()` | Get all properties | +| `setProperty(name, value)` | Set property | +| `getAttachments()` | Get all attachments | +| `getAttachment(name)` | Get specific attachment | +| `addAttachmentObject(name, DataHandler)` | Add attachment | + +### Available Services + +| Service | Purpose | +|---------|---------| +| `SecureStoreService` | Access credentials | +| `ValueMappingApi` | Value mapping lookups | +| `PartnerDirectoryService` | Partner directory access | +| `DataStoreService` | Data store operations | + +### Import Package + +```groovy +import com.sap.gateway.ip.core.customdev.util.Message +import com.sap.it.api.ITApiFactory +import com.sap.it.api.securestore.SecureStoreService +import com.sap.it.api.mapping.ValueMappingApi +import org.slf4j.LoggerFactory +``` + +--- + +## Related Documentation + +- **Scripting Guidelines**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md) +- **Script Collections**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/creating-a-script-collection-824bff0.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/creating-a-script-collection-824bff0.md) +- **Script Use Cases**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/script-use-cases-148851b.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/script-use-cases-148851b.md) +- **Access Headers/Properties**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/access-headers-and-properties-in-scripts-6bc5ed1.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/access-headers-and-properties-in-scripts-6bc5ed1.md) diff --git a/references/security.md b/references/security.md new file mode 100644 index 0000000..d7fa952 --- /dev/null +++ b/references/security.md @@ -0,0 +1,427 @@ +# Security - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ci) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Security Overview](#security-overview) +2. [Authentication Methods](#authentication-methods) +3. [Keystore Management](#keystore-management) +4. [Credential Artifacts](#credential-artifacts) +5. [Message-Level Security](#message-level-security) +6. [Certificate Management](#certificate-management) +7. [Security Best Practices](#security-best-practices) + +--- + +## Security Overview + +### Security Layers + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Security Layers │ +├─────────────────────────────────────────────────────────────┤ +│ Transport Layer (TLS/SSL) │ +│ ├─ Server certificates │ +│ ├─ Client certificates (mTLS) │ +│ └─ Cipher suites │ +├─────────────────────────────────────────────────────────────┤ +│ Authentication Layer │ +│ ├─ Basic authentication │ +│ ├─ OAuth 2.0 │ +│ ├─ Client certificate │ +│ ├─ SAML assertion │ +│ └─ Principal propagation │ +├─────────────────────────────────────────────────────────────┤ +│ Message Layer │ +│ ├─ Encryption (PGP, PKCS#7) │ +│ ├─ Digital signatures │ +│ └─ Message digest │ +├─────────────────────────────────────────────────────────────┤ +│ Access Control │ +│ ├─ Role collections │ +│ ├─ Access policies │ +│ └─ Endpoint protection │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Security Material Types + +| Type | Purpose | Storage | +|------|---------|---------| +| Keystore | Certificates and keys | Keystore artifact | +| User Credentials | Username/password | Credential artifact | +| Secure Parameters | Sensitive config values | Secure store | +| OAuth Credentials | OAuth tokens | Credential artifact | +| PGP Keys | Encryption/signing keys | Keyring artifact | +| SSH Keys | SFTP authentication | Keystore artifact | + +--- + +## Authentication Methods + +### Inbound Authentication (Senders calling Integration Suite) + +#### Basic Authentication +Username/password in HTTP header. + +**Configuration**: +1. Create service instance for process integration +2. Assign `ESBMessaging.send` role +3. Use service key credentials + +#### Client Certificate Authentication +X.509 certificate verification. + +**Configuration**: +1. Import client CA certificate to keystore +2. Configure sender adapter for client certificate +3. Map certificate to user (Neo) or use role-based auth (CF) + +#### OAuth 2.0 +Token-based authentication. + +**Grant Types**: +- Client Credentials (machine-to-machine) +- Authorization Code (user-delegated) +- SAML Bearer Assertion (SSO scenarios) + +### Outbound Authentication (Integration Suite calling receivers) + +#### Basic Authentication +``` +Adapter → Authentication: Basic + → Credential Name: [UserCredential artifact] +``` + +#### Client Certificate +``` +Adapter → Authentication: Client Certificate + → Private Key Alias: [Keystore alias] +``` + +#### OAuth 2.0 Client Credentials +``` +Adapter → Authentication: OAuth2 Client Credentials + → Token Service URL: [https://oauth.example.com/token](https://oauth.example.com/token) + → Client ID: [from credential] + → Client Secret: [from credential] +``` + +#### Principal Propagation +Forward user identity to backend systems. + +**Scenarios**: +- SAP to SAP Cloud Identity +- Cloud Foundry to on-premise +- Subaccount to subaccount + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/basic-authentication-outbound-f26152c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/basic-authentication-outbound-f26152c.md) + +--- + +## Keystore Management + +### Keystore Structure + +``` +Tenant Keystore +├── SAP Keys (managed by SAP) +│ ├── sap_cloudintegrationcertificate (client cert) +│ └── sap_cloudintegrationca (CA cert) +├── Customer Keys +│ ├── my_client_key (private key + cert) +│ ├── partner_ca_cert (CA certificate) +│ └── backend_server_cert (server certificate) +└── Key History + └── Rotated keys for reference +``` + +### Key Types + +| Type | Content | Use Case | +|------|---------|----------| +| Key Pair | Private key + certificate | Client authentication, signing | +| Certificate | Public certificate only | Server validation, CA trust | +| SSH Key | SSH private/public key | SFTP authentication | + +### Keystore Operations + +**Upload Certificate**: +1. Navigate to Monitor → Manage Security → Keystore +2. Click Add → Certificate +3. Upload .cer/.crt/.pem file +4. Assign alias + +**Upload Key Pair**: +1. Navigate to Keystore +2. Click Add → Key Pair +3. Upload .p12/.pfx file with password +4. Assign alias + +**Renew Certificate**: +1. Upload new certificate with new alias +2. Update adapter configurations +3. Test connectivity +4. Delete old certificate after validation + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-keystore-entries-2dc8942.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-keystore-entries-2dc8942.md) + +--- + +## Credential Artifacts + +### User Credentials + +Store username/password combinations. + +**Deployment**: +1. Navigate to Monitor → Manage Security → Security Material +2. Click Add → User Credentials +3. Enter name, user, password +4. Deploy + +**Usage in Adapter**: +``` +Authentication: Basic +Credential Name: MyCredential +``` + +### OAuth2 Credentials + +Store OAuth client credentials. + +**Types**: +- Client Credentials Grant +- Authorization Code Grant +- SAML Bearer Assertion + +**Configuration**: +- Token Service URL +- Client ID +- Client Secret +- Scope (optional) +- Token refresh settings + +### Secure Parameters + +Store sensitive configuration values. + +**Deployment**: +1. Navigate to Security Material +2. Click Add → Secure Parameter +3. Enter name and value +4. Deploy + +**Access in Script**: +```groovy +def secureStore = ITApiFactory.getService(SecureStoreService.class, null) +def value = secureStore.getSecureParameter("ParameterName") +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-security-material-b8ccb53.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-security-material-b8ccb53.md) + +--- + +## Message-Level Security + +### Encryption + +#### PGP Encryption +Encrypt payload using OpenPGP standard. + +**Encryptor Step**: +| Parameter | Description | +|-----------|-------------| +| Public Key Alias | Recipient's public key | +| Algorithm | AES-256, etc. | +| Armor | ASCII armor output | + +**Decryptor Step**: +| Parameter | Description | +|-----------|-------------| +| Private Key Alias | Your private key | +| Signatures Required | Verify sender signature | + +#### PKCS#7/CMS Encryption +Enterprise encryption standard. + +**Supported Algorithms**: +- AES (128, 192, 256 bit) +- 3DES +- DES (legacy, not recommended) + +### Digital Signatures + +#### XML Digital Signature +Sign/verify XML documents. + +**Algorithms**: +- RSA-SHA256 (recommended) +- RSA-SHA1 (legacy) +- ECDSA + +**Elements**: +- Enveloped signature +- Enveloping signature +- Detached signature + +#### PKCS#7/CMS Signature +Sign binary/text content. + +### Message Digest + +Calculate hash of message content. + +**Algorithms**: +- SHA-256 (recommended) +- SHA-1 (legacy) +- MD5 (not recommended) + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/apply-message-level-security-9036c0c.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/apply-message-level-security-9036c0c.md) + +--- + +## Certificate Management + +### Certificate Types + +| Certificate | Purpose | +|-------------|---------| +| Server Certificate | Identify server to clients | +| Client Certificate | Identify client to servers | +| CA Certificate | Trust anchor for validation | +| Signing Certificate | Digital signature creation | +| Encryption Certificate | Message encryption | + +### Certificate Lifecycle + +``` +┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ +│ Request │ → │ Issue │ → │ Active │ → │ Renew │ +│ CSR │ │ Cert │ │ Usage │ │ Before │ +│ │ │ │ │ │ │ Expiry │ +└─────────┘ └─────────┘ └─────────┘ └─────────┘ + │ + ▼ + ┌─────────┐ + │ Replace │ + │ & Test │ + └─────────┘ +``` + +### Certificate Renewal Best Practices + +1. **Monitor Expiration** + - Set alerts for 30-day warning + - Track all certificates in inventory + +2. **Prepare New Certificate** + - Generate or request before expiry + - Use same key type and size + +3. **Staged Rollout** + - Import with new alias + - Update configurations + - Test in lower environments + +4. **Validate** + - Verify connectivity + - Check signature validation + - Confirm encryption/decryption + +5. **Cleanup** + - Remove old certificate after validation + - Update documentation + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/security-artifact-renewal-083fc8d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/security-artifact-renewal-083fc8d.md) + +--- + +## Security Best Practices + +### General + +1. **Use HTTPS everywhere** + - No unencrypted HTTP + - TLS 1.2+ only + +2. **Rotate credentials regularly** + - Passwords: 90 days + - Certificates: Before expiry + - API keys: As needed + +3. **Principle of least privilege** + - Minimal role assignments + - Specific permissions only + +4. **Audit and monitor** + - Enable audit logging + - Monitor security events + - Review access regularly + +### Integration Flow Security + +1. **Never hardcode credentials** + ```groovy + // BAD + def password = "mypassword" + + // GOOD + def cred = secureStore.getUserCredential("MyCredential") + ``` + +2. **Don't log sensitive data** + ```groovy + // BAD + log.info("Password: ${password}") + + // GOOD + log.info("Authentication configured") + ``` + +3. **Validate input data** + - Check payload structure + - Validate against schema + - Sanitize user input + +4. **Use secure credential artifacts** + - User Credentials for passwords + - Secure Parameters for config + - OAuth artifacts for tokens + +### API Management Security + +1. **Always authenticate APIs** + - API keys at minimum + - OAuth 2.0 preferred + +2. **Apply threat protection** + - JSON/XML threat policies + - Regular expression validation + - Input validation + +3. **Implement rate limiting** + - Quota policies + - Spike arrest + - Concurrent limits + +4. **Use CORS carefully** + - Restrict origins + - Limit methods + - Validate headers + +--- + +## Related Documentation + +- **Security Guidelines**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/apply-the-highest-security-standards-201fd43.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/apply-the-highest-security-standards-201fd43.md) +- **Keystore Management**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-keystore-entries-2dc8942.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-keystore-entries-2dc8942.md) +- **Certificate Renewal**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/security-artifact-renewal-083fc8d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/security-artifact-renewal-083fc8d.md) +- **PGP Keys**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-pgp-keys-cd478a7.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/managing-pgp-keys-cd478a7.md) +- **OAuth Configuration**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/deploying-an-oauth2-client-credentials-artifact-801b106.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/deploying-an-oauth2-client-credentials-artifact-801b106.md) diff --git a/references/troubleshooting.md b/references/troubleshooting.md new file mode 100644 index 0000000..4a24bc7 --- /dev/null +++ b/references/troubleshooting.md @@ -0,0 +1,437 @@ +# Troubleshooting - Comprehensive Reference + +**Source**: SAP BTP Integration Suite Documentation +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite](https://github.com/SAP-docs/sap-btp-integration-suite/tree/main/docs/ISuite) +**Last Updated**: 2025-11-22 + +--- + +## Table of Contents + +1. [Monitoring Overview](#monitoring-overview) +2. [Message Processing Errors](#message-processing-errors) +3. [Adapter Issues](#adapter-issues) +4. [Mapping Errors](#mapping-errors) +5. [Security Issues](#security-issues) +6. [Deployment Issues](#deployment-issues) +7. [Performance Issues](#performance-issues) +8. [API Management Issues](#api-management-issues) +9. [HTTP Error Catalog](#http-error-catalog) + +--- + +## Monitoring Overview + +### Accessing Monitoring + +``` +Integration Suite → Monitor → Integrations and APIs + ├── Monitor Message Processing + │ ├── All Integration Flows + │ ├── All Artifacts + │ └── By specific criteria + ├── Manage Integration Content + │ └── Deployed artifacts status + ├── Manage Security + │ ├── Keystore + │ ├── User Credentials + │ └── Security Material + └── Manage Stores + ├── Data Stores + ├── Variables + ├── Message Queues + └── Number Ranges +``` + +### Message Status Types + +| Status | Meaning | +|--------|---------| +| **Completed** | Successfully processed | +| **Failed** | Processing failed with error | +| **Retry** | Failed, retry scheduled | +| **Escalated** | Exceeded retry limit | +| **Processing** | Currently processing | +| **Discarded** | Intentionally discarded | + +### Log Levels + +| Level | Information Captured | +|-------|---------------------| +| **None** | No logging | +| **Error** | Errors only | +| **Info** | Standard operations | +| **Debug** | Detailed debugging | +| **Trace** | Full message content (use sparingly) | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/monitor-message-processing-314df3f.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/monitor-message-processing-314df3f.md) + +--- + +## Message Processing Errors + +### Common Error Types + +#### 1. Connection Refused +**Symptom**: Cannot connect to target system +**Causes**: +- Target system down +- Firewall blocking +- Wrong hostname/port +- Cloud Connector not running + +**Resolution**: +1. Verify target URL is correct +2. Check firewall rules +3. Verify Cloud Connector status +4. Test connectivity manually + +#### 2. Connection Timeout +**Symptom**: Request times out waiting for response +**Causes**: +- Slow backend response +- Network latency +- Timeout too short +- Large payload processing + +**Resolution**: +1. Increase adapter timeout +2. Optimize backend processing +3. Check network path +4. Consider async processing + +#### 3. Authentication Failed +**Symptom**: 401/403 errors +**Causes**: +- Wrong credentials +- Expired tokens +- Missing permissions +- Certificate issues + +**Resolution**: +1. Verify credential artifact +2. Check token expiration +3. Verify user permissions +4. Update certificates + +#### 4. Certificate Errors +**Symptom**: SSL/TLS handshake failures +**Causes**: +- Expired certificate +- Untrusted CA +- Hostname mismatch +- Wrong certificate chain + +**Resolution**: +1. Check certificate expiration +2. Import CA certificate to keystore +3. Verify hostname in certificate +4. Ensure complete certificate chain + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-cloud-integration-37743c2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-cloud-integration-37743c2.md) + +--- + +## Adapter Issues + +### SFTP/FTP Adapter + +| Issue | Cause | Resolution | +|-------|-------|------------| +| Connection refused | Firewall, wrong port | Check connectivity, verify port | +| Authentication failed | Wrong credentials/key | Update credential artifact | +| File not found | Wrong path, permissions | Verify path, check permissions | +| Permission denied | User lacks access | Grant necessary permissions | +| Timeout | Slow network, large files | Increase timeout, check network | + +### HTTP/HTTPS Adapter + +| Issue | Cause | Resolution | +|-------|-------|------------| +| 400 Bad Request | Malformed request | Validate payload format | +| 401 Unauthorized | Invalid credentials | Check authentication config | +| 403 Forbidden | Missing permissions | Verify user/role access | +| 404 Not Found | Wrong URL | Verify endpoint URL | +| 500 Server Error | Backend issue | Check backend logs | +| 502 Bad Gateway | Proxy/LB issue | Check proxy configuration | +| 503 Service Unavailable | Backend overloaded | Retry later, check backend | +| Connection refused | Firewall, service down | Check connectivity | + +### OData Adapter + +| Issue | Cause | Resolution | +|-------|-------|------------| +| Metadata error | Wrong URL, version | Verify service URL/version | +| Entity not found | Wrong entity name | Check entity set name | +| Filter error | Invalid OData filter | Validate filter syntax | +| Pagination issues | Large result sets | Enable pagination | + +### JMS Adapter + +| Issue | Cause | Resolution | +|-------|-------|------------| +| Queue full | Too many messages | Check consumers, increase capacity | +| Message lost | Transaction rollback | Check error handling | +| Connection error | Broker issue | Check JMS broker status | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-adapters-b7a3906.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-adapters-b7a3906.md) + +--- + +## Mapping Errors + +### Common Mapping Issues + +#### Structure Mismatch +**Symptom**: Mapping execution fails +**Resolution**: +1. Verify source/target structures match schema +2. Check for missing mandatory fields +3. Validate namespace declarations + +#### XPath Errors +**Symptom**: XPath expression returns empty/wrong result +**Resolution**: +1. Test XPath in isolation +2. Verify namespace prefixes +3. Check element names for typos +4. Use absolute paths for clarity + +#### Null Pointer Exception +**Symptom**: NPE in mapping +**Resolution**: +1. Check for missing optional elements +2. Add null checks in functions +3. Provide default values + +#### XSLT Errors +**Symptom**: XSLT transformation fails +**Resolution**: +1. Validate XSLT syntax +2. Check namespace handling +3. Verify template matching +4. Test with sample data + +### Debugging Mappings + +1. Enable trace logging +2. Add Content Modifier before mapping +3. Log intermediate values +4. Use local testing with sample data + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-message-mapping-cb5311a.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-message-mapping-cb5311a.md) + +--- + +## Security Issues + +### Keystore Problems + +| Issue | Resolution | +|-------|------------| +| Certificate not found | Import certificate to keystore | +| Certificate expired | Update with valid certificate | +| Private key missing | Import key pair, not just certificate | +| Wrong alias | Verify alias name in adapter config | +| Keystore sync failed | Check Edge Integration Cell connectivity | + +### Credential Issues + +| Issue | Resolution | +|-------|------------| +| Credential not found | Deploy credential artifact | +| Wrong password | Update credential artifact | +| OAuth token expired | Refresh token, check token URL | +| Certificate-based auth failed | Verify client certificate | + +### Security Artifact Renewal + +**Process**: +1. Prepare new certificate/key +2. Import to keystore (new alias) +3. Update adapter configuration +4. Test with new credentials +5. Remove old certificate (after validation) + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/security-artifact-renewal-083fc8d.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/security-artifact-renewal-083fc8d.md) + +--- + +## Deployment Issues + +### Integration Flow Deployment + +| Issue | Cause | Resolution | +|-------|-------|------------| +| Deployment failed | Syntax error | Check flow configuration | +| Resource not found | Missing artifact reference | Deploy referenced artifacts | +| Configuration error | Invalid parameters | Validate externalized parameters | +| Timeout | Complex flow | Simplify or split flow | +| Already exists | Duplicate ID | Use unique artifact ID | + +### Debugging Deployment + +1. Check deployment status in Monitor +2. Review deployment logs +3. Verify all referenced artifacts exist +4. Check runtime configuration +5. Validate adapter configurations + +### Common Resolution Steps + +1. **Undeploy** existing version +2. **Fix** the identified issue +3. **Save** the changes +4. **Deploy** again +5. **Verify** in monitoring + +--- + +## Performance Issues + +### Symptoms and Causes + +| Symptom | Possible Causes | +|---------|-----------------| +| Slow processing | Large payloads, complex mappings | +| High memory usage | XmlSlurper.parseText, string concat | +| Timeouts | Backend latency, insufficient timeout | +| Queue backup | Consumer too slow, too many messages | + +### Performance Optimization + +1. **Streaming** + - Use stream-based processing + - Avoid loading entire payload into memory + +2. **Mapping Optimization** + - Reduce transformation complexity + - Use XSLT for complex XML transforms + - Cache repeated lookups + +3. **Adapter Configuration** + - Set appropriate timeouts + - Use connection pooling + - Enable compression where supported + +4. **Flow Design** + - Split large flows into smaller units + - Use async processing where appropriate + - Implement parallel processing + +### Resource Monitoring + +``` +Monitor → Manage Stores → Inspect +├── Data Store Usage +├── Database Connection Usage +├── Transaction Usage +└── Monitoring Storage Usage +``` + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/inspect-a4d5e49.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Operations/inspect-a4d5e49.md) + +--- + +## API Management Issues + +### API Proxy Errors + +| Error | Cause | Resolution | +|-------|-------|------------| +| 401 Invalid API Key | Wrong/expired key | Verify API key | +| 403 Access Denied | Policy restriction | Check access control policies | +| 429 Too Many Requests | Rate limit exceeded | Check quota/spike arrest | +| 500 Internal Error | Proxy misconfiguration | Debug proxy, check policies | +| 502 Bad Gateway | Backend unreachable | Verify target endpoint | +| 504 Gateway Timeout | Backend too slow | Increase timeout | + +### Policy Debugging + +1. Use **Debug** feature in API proxy +2. Check policy execution order +3. Verify policy conditions +4. Check variable values +5. Review fault rules + +### Common Policy Issues + +| Policy | Issue | Resolution | +|--------|-------|------------| +| Quota | Wrong counter | Check quota type and key | +| OAuth | Token validation failed | Verify token, check scope | +| Cache | Stale data | Check cache key, TTL | +| Transform | Format error | Validate input/output | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-api-management-e765066.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-api-management-e765066.md) + +--- + +## HTTP Error Catalog + +### 4xx Client Errors + +| Code | Meaning | Common Causes | +|------|---------|---------------| +| 400 | Bad Request | Malformed payload, invalid syntax | +| 401 | Unauthorized | Missing/invalid credentials | +| 403 | Forbidden | Insufficient permissions | +| 404 | Not Found | Wrong URL, resource doesn't exist | +| 405 | Method Not Allowed | Wrong HTTP method | +| 408 | Request Timeout | Client too slow | +| 409 | Conflict | Resource state conflict | +| 413 | Payload Too Large | Message exceeds limit | +| 415 | Unsupported Media Type | Wrong Content-Type | +| 429 | Too Many Requests | Rate limit exceeded | + +### 5xx Server Errors + +| Code | Meaning | Common Causes | +|------|---------|---------------| +| 500 | Internal Server Error | Processing failure | +| 502 | Bad Gateway | Backend unreachable | +| 503 | Service Unavailable | Service overloaded | +| 504 | Gateway Timeout | Backend too slow | + +**Documentation**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-http-error-catalog-069b461.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-http-error-catalog-069b461.md) + +--- + +## Diagnostic Checklist + +### Before Escalating + +1. **Check Message Processing Log** + - Error details + - Stack trace + - Payload at failure point + +2. **Verify Configuration** + - Adapter settings + - Credentials + - Certificates + +3. **Test Connectivity** + - Use connectivity test feature + - Test endpoints independently + - Check Cloud Connector + +4. **Review Recent Changes** + - Deployment history + - Configuration changes + - Certificate updates + +5. **Check Resource Limits** + - JMS queue capacity + - Data store storage + - Message size limits + +--- + +## Related Documentation + +- **Cloud Integration Troubleshooting**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-cloud-integration-37743c2.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-cloud-integration-37743c2.md) +- **API Management Troubleshooting**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-api-management-e765066.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-api-management-e765066.md) +- **Adapter Troubleshooting**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-adapters-b7a3906.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-adapters-b7a3906.md) +- **Edge Integration Cell Troubleshooting**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-edge-integration-cell-816d9e4.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-for-edge-integration-cell-816d9e4.md) +- **HTTP Error Catalog**: [https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-http-error-catalog-069b461.md](https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ISuite/troubleshooting-http-error-catalog-069b461.md) diff --git a/templates/api-policy-template.xml b/templates/api-policy-template.xml new file mode 100644 index 0000000..da82c74 --- /dev/null +++ b/templates/api-policy-template.xml @@ -0,0 +1,381 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $.user.id + + + $.orders.length() + + + + + + http://example.com/ns + + + /ns:Order/ns:OrderId + + + +
+ application/{format} +
+ + {entityId} + + +--> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/templates/groovy-script-template.groovy b/templates/groovy-script-template.groovy new file mode 100644 index 0000000..de12704 --- /dev/null +++ b/templates/groovy-script-template.groovy @@ -0,0 +1,249 @@ +/** + * SAP Cloud Integration - Groovy Script Template + * + * Usage: Replace placeholders and customize for your use case + * + * Placeholders: + * - {{SCRIPT_NAME}}: Name/description of script purpose + * - {{AUTHOR}}: Script author + * - {{DATE}}: Creation date + * + * Documentation: + * - Scripting Guidelines: https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/general-scripting-guidelines-fcbf0f2.md + * - Script API: https://github.com/SAP-docs/sap-btp-integration-suite/blob/main/docs/ci/Development/access-headers-and-properties-in-scripts-6bc5ed1.md + */ + +import com.sap.gateway.ip.core.customdev.util.Message +import org.slf4j.LoggerFactory + +/** + * {{SCRIPT_NAME}} + * + * @author {{AUTHOR}} + * @date {{DATE}} + * + * Input: + * - Body: Description of expected input format + * - Headers: List of required headers + * - Properties: List of required properties + * + * Output: + * - Body: Description of output format + * - Headers: List of headers set + * - Properties: List of properties set + */ +def Message processData(Message message) { + // Initialize logger + def log = LoggerFactory.getLogger("script.{{SCRIPT_NAME}}") + + try { + // =========================================== + // 1. GET MESSAGE COMPONENTS + // =========================================== + + // Get message body (use InputStream for large payloads) + def body = message.getBody(String.class) + // def bodyStream = message.getBody(java.io.InputStream.class) + + // Get headers + def contentType = message.getHeader("Content-Type", String.class) + def customHeader = message.getHeader("X-Custom-Header", String.class) + + // Get properties + def property1 = message.getProperty("PropertyName") + + // =========================================== + // 2. PROCESS DATA + // =========================================== + + log.info("Processing started") + + // Example: Parse JSON + // def json = new groovy.json.JsonSlurper().parseText(body) + // def value = json.fieldName + + // Example: Parse XML (use parse() for streams, not parseText()) + // def xml = new groovy.xml.XmlSlurper().parse(message.getBody(java.io.InputStream.class)) + // def value = xml.element.text() + + // Example: Process data + def result = body.toUpperCase() + + // =========================================== + // 3. SET OUTPUT + // =========================================== + + // Set body + message.setBody(result) + + // Set headers + message.setHeader("X-Processed", "true") + message.setHeader("X-Timestamp", java.time.Instant.now().toString()) + + // Set properties + message.setProperty("ProcessingStatus", "completed") + + log.info("Processing completed successfully") + + } catch (Exception e) { + log.error("Processing failed: ${e.message}", e) + message.setProperty("ErrorMessage", e.message) + // Use StringWriter for readable stack trace + def sw = new StringWriter() + e.printStackTrace(new PrintWriter(sw)) + message.setProperty("ErrorStackTrace", sw.toString()) + throw e // Re-throw to trigger exception handling + } + + return message +} + + +// =========================================== +// ADDITIONAL SCRIPT PATTERNS +// =========================================== + +/** + * Pattern: JSON Transformation + */ +/* +def Message transformJson(Message message) { + def log = LoggerFactory.getLogger("script.transformJson") + + def body = message.getBody(String.class) + def input = new groovy.json.JsonSlurper().parseText(body) + + // Transform (use explicit UTC timezone for ISO 8601 format) + def output = [ + id: input.customerId, + name: input.customerName, + timestamp: new Date().format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone("UTC")) + ] + + message.setBody(groovy.json.JsonOutput.toJson(output)) + return message +} +*/ + +/** + * Pattern: XML Transformation + */ +/* +def Message transformXml(Message message) { + def log = LoggerFactory.getLogger("script.transformXml") + + // Use parse() with InputStream for better memory handling + def bodyStream = message.getBody(java.io.InputStream.class) + def xml = new groovy.xml.XmlSlurper().parse(bodyStream) + + // Access elements + def id = xml.customer.@id.text() + def name = xml.customer.name.text() + + // Build new XML + def writer = new StringWriter() + def builder = new groovy.xml.MarkupBuilder(writer) + builder.response { + customerId(id) + customerName(name) + processed(true) + } + + message.setBody(writer.toString()) + return message +} +*/ + +/** + * Pattern: Secure Parameter Access + */ +/* +def Message accessSecureParams(Message message) { + import com.sap.it.api.ITApiFactory + import com.sap.it.api.securestore.SecureStoreService + + def secureStore = ITApiFactory.getService(SecureStoreService.class, null) + def credential = secureStore.getUserCredential("CredentialName") + + def username = credential.getUsername() + def password = new String(credential.getPassword()) + + // Use credentials... + return message +} +*/ + +/** + * Pattern: Value Mapping Lookup + */ +/* +def Message lookupValueMapping(Message message) { + import com.sap.it.api.ITApiFactory + import com.sap.it.api.mapping.ValueMappingApi + + def vmApi = ITApiFactory.getService(ValueMappingApi.class, null) + + def targetValue = vmApi.getMappedValue( + "SourceAgency", + "SourceIdentifier", + "SourceValue", + "TargetAgency", + "TargetIdentifier" + ) + + message.setProperty("MappedValue", targetValue) + return message +} +*/ + +/** + * Pattern: Dynamic Routing + */ +/* +def Message dynamicRouting(Message message) { + def body = message.getBody(String.class) + def json = new groovy.json.JsonSlurper().parseText(body) + + def endpoint + switch(json.region?.toUpperCase()) { + case "US": + endpoint = "https://us-api.example.com/v1" + break + case "EU": + endpoint = "https://eu-api.example.com/v1" + break + default: + endpoint = "https://default-api.example.com/v1" + } + + message.setProperty("DynamicEndpoint", endpoint) + return message +} +*/ + +/** + * Pattern: Attachment Handling + */ +/* +def Message handleAttachments(Message message) { + import javax.activation.DataHandler + + // Get all attachments + def attachments = message.getAttachments() + + attachments.each { name, dataHandler -> + def content = dataHandler.getInputStream().text + // Process attachment... + } + + // Add new attachment + def newContent = "Attachment content" + def dataSource = new javax.mail.util.ByteArrayDataSource( + newContent.getBytes(), + "text/plain" + ) + message.addAttachmentObject("output.txt", new DataHandler(dataSource)) + + return message +} +*/