sap-btp-master-data-integration

# SAP BTP Master Data Integration

## Table of Contents
- [Quick Reference](#quick-reference)
- [Core Concepts](#core-concepts)
- [Decision Trees](#decision-trees)
- [Setup Workflow](#setup-workflow)
- [System Limitations](#system-limitations)
- [Client Configuration](#client-configuration)
- [SOAP Endpoints](#soap-endpoints)
- [Common Integration Scenarios](#common-integration-scenarios)
- [Security Best Practices](#security-best-practices)
- [Troubleshooting](#troubleshooting)
- [Bundled Resources](#bundled-resources)

SAP Master Data Integration (MDI) is a central master data hub on SAP BTP that enables applications to synchronize local master data databases with a centralized repository.

## Quick Reference

### What MDI Does
- Replicates master data between connected applications
- Supports 34 master data types via SAP One Domain Model
- Provides filtering to control data distribution scope
- Enables extensibility with custom fields

### What MDI Does NOT Do
- Consolidation (use SAP Master Data Governance)
- Data quality control
- Central governance workflows
- Referential integrity validation

## Core Concepts

### Key Terms
| Term | Definition |
|------|------------|
| Tenant | Isolated MDI environment per subaccount with own database and configs |
| Client | Application that integrates with MDI (producing or consuming) |
| Producing Client | Sends change requests to MDI (upstream/writing client) |
| Consuming Client | Receives change events from MDI (downstream/reading client) |
| Distribution Model | Configuration controlling which data replicates where |
| Change Token | Unique identifier per change request (max 36 chars) |

### Integration Models (SAP One Domain Model)

**Business Partner** - v2.1.1, v3.3.0 (multiversion support restricted for address data)
**Finance** - Cost Center v3.1.0, Exchange Rate v4.0.0, Bank v3.0.0
**Workforce** - Person v5.0.0, Job Classification v4.0.0, Organizational Unit v4.0.0
**Procurement** - Purchasing Organization v4.0.0, Purchasing Group v6.0.0
**Assets** - Equipment v5.1.0, Functional Location v5.0.0
**Products** - Product v5.0.0, Product Group v5.0.0

For complete list see `references/integration-models.md`

## Decision Trees

### Which Service Plan?

```
Is application SAP-branded cloud?
├─ Yes → sap-integration plan (FREE)
└─ No → Is it SAP S/4HANA On-Premise?
         ├─ Yes → s4hana-onpremise plan (PAID - storage + bandwidth)
         └─ No → Use SAP Integration Suite with MDI Adapter
```

### Which Authentication Method?

```
Mutual-TLS with X.509 certificates available?
├─ Yes → Use mTLS (RECOMMENDED)
│        credential-type: x509
│        Configure validity: DAYS/MONTHS/YEARS
└─ No → Use Client Credentials Grant (DEFAULT)
         Uses client_id/client_secret pairs
```

### REST vs SOAP API?

```
Master data type is Business Partner?
├─ Yes → SOAP API available for:
│        - Business Partner replication
│        - BP Relationship replication
│        - Key Mapping replication
│        - Confirmations
└─ No → REST API (Events API, Requests API, KeyMapping API)
```

## Setup Workflow

### 1. Prerequisites
- SAP BTP global enterprise account (no trial/free tier)
- Subaccount in supported region: EU10, US10, AP10, AP11
- Cloud Foundry space within subaccount
- User with BusinessConfigurationAdmin role

### 2. Create Tenant
```
1. Create subaccount in available region
2. Subscribe to SAP Master Data Integration Tenant application
3. One tenant maximum per subaccount
4. Separate tenants for dev/test/prod recommended
```

### 3. Connect Application
```
1. Create service instance (one per application - MANDATORY)
2. Choose service plan (sap-integration or s4hana-onpremise)
3. Set 'application' attribute (e.g., "s4" for S/4HANA Cloud)
4. Create service binding for credentials
5. Configure writePermissions for entity types
```

### 4. Configure Distribution Model
```
1. Access Business Data Orchestration UI
2. Create distribution model (provider → consumer)
3. Set filters (object selection + data scope)
4. Activate model
```

## System Limitations

| Limit | Value |
|-------|-------|
| Change Request Size | 256 KB (512 KB for Business Partner) |
| Master Data Record Size | 512 KB |
| Change Token Length | 36 characters max |
| Delta Token Validity | 28 days |
| SOAP Payload Size | 10 MB |
| Change Token Characters | a-z, A-Z, 0-9, -, _ |

## Client Configuration Attributes

### businessSystemId
- Required for SOAP API integration
- Max 60 characters, unique per tenant
- Must match SenderBusinessSystemID in SOAP messages

### writePermissions
```json
"writePermissions": [
  { "entityType": "sap.odm.finance.costobject.CostCenter" },
  { "entityType": "sap.odm.businesspartner.BusinessPartner" }
]
```

### globalTenantId
- Identifies last significant writer on Events API
- 1-40 characters: alphanumeric, -, ., _, ~
- Configure only if application documentation requires it

### logSys
- Logical system of last significant writer
- Max 10 characters
- Configure only if application documentation requires it

## SOAP Endpoints

Base URL: `[https://one-mds.cfapps.{region}.hana.ondemand.com/businesspartner/v0/soap/`](https://one-mds.cfapps.{region}.hana.ondemand.com/businesspartner/v0/soap/`)

| Purpose | Endpoint |
|---------|----------|
| BP Inbound | BusinessPartnerBulkReplicateRequestIn |
| BP Confirmation | BusinessPartnerBulkReplicateRequestConfIn |
| BP Relationship Inbound | BusinessPartnerRelationshipBulkReplicateRequestIn |
| BP Relationship Confirmation | BusinessPartnerRelationshipBulkReplicateRequestConfirmIn |
| Key Mapping Inbound | KeyMappingBulkReplicateRequestIn |
| Key Mapping Confirmation | KeyMappingBulkReplicateRequestConfirmIn |

Authentication: Basic (clientid:clientsecret with tenantId param) or OAuth

## Destination Naming Convention (SOAP)

For business system ID `SYSTEMID`:
- `SYSTEMID_BPOUTBOUND` - Business Partner replication
- `SYSTEMID_BPCONFIRM` - Business Partner confirmation
- `SYSTEMID_BPRELOUTBOUND` - Relationship