Initial commit

2025-11-30 08:55:12 +08:00
commit 2bc6bda6b5
13 changed files with 3009 additions and 0 deletions
--- a/references/setup-guide-complete.md
+++ b/references/setup-guide-complete.md
@@ -0,0 +1,465 @@
+# Complete Setup and Administration Guide
+
+Comprehensive setup and administration documentation for SAP Master Data Integration.
+
+## Table of Contents
+
+- [Technical Prerequisites](#technical-prerequisites)
+- [Tenant Management](#tenant-management)
+- [Client Configuration Attributes](#client-configuration-attributes)
+- [Business Data Orchestration](#distribution-model-configuration)
+- [SAP Cloud ALM Monitoring](#sap-cloud-alm-monitoring)
+- [Version History](#version-history)
+
+**Source**: [https://github.com/SAP-docs/sap-btp-master-data-integration/tree/main/docs/initial-setup-and-administration](https://github.com/SAP-docs/sap-btp-master-data-integration/tree/main/docs/initial-setup-and-administration)
+
+---
+
+## Technical Prerequisites
+
+### Account Hierarchy
+
+```
+Global Account (Enterprise)
+    └── Subaccount (in supported region)
+            └── Space (Cloud Foundry)
+```
+
+### Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| Global Account | SAP BTP Enterprise account (**Trial/Free Tier NOT supported**) |
+| Environment | Cloud Foundry |
+| Subaccount | Must be in supported region |
+| Space | Required within subaccount |
+
+### Supported Regions
+
+| Region | Code | Location |
+|--------|------|----------|
+| Europe | EU10 | Frankfurt |
+| US East | US10 | Virginia |
+| Australia | AP10 | Sydney |
+| Asia Pacific | AP11 | Singapore |
+
+---
+
+## Tenant Management
+
+### Creating Tenants
+
+**Prerequisites**:
+- Global enterprise account (no trial/free tier)
+- Subaccount in supported region
+
+**Steps**:
+1. Create subaccount in available region
+2. Subscribe to "SAP Master Data Integration Tenant application"
+3. Create service instances for client connectivity
+
+### Key Limitations
+
+| Constraint | Details |
+|------------|---------|
+| One tenant per subaccount | Cannot host multiple tenants in single subaccount |
+| Data isolation | Neither data nor configuration shared between tenants |
+| Dedicated subaccount | Recommended exclusively for MDI tenant |
+
+### Multi-Tenant Strategy
+
+**Recommended**: Three-tenant model for development lifecycle:
+- **Development** tenant (separate subaccount)
+- **Test** tenant (separate subaccount)
+- **Production** tenant (separate subaccount)
+
+**Production**: Single tenant recommended to maintain data consistency across connected applications.
+
+### Deleting Tenants
+
+**28-Day Retention**: Deleted data retained for 28 days before permanent deletion.
+
+**Protection Mechanism**: Deleting the last service instance triggers tenant deletion warning. To proceed:
+```json
+{
+  "enableTenantDeletion": true
+}
+```
+
+---
+
+## Connecting Applications
+
+### Critical Rule
+**Every application MUST use its own dedicated service instance.** Sharing instances causes unexpected behavior and inconsistencies.
+
+### Why NOT to Use Subscriptions
+
+SAP Master Data Integration **must NOT be consumed via subscription mechanism**.
+
+**Reasons**:
+- Flexibility issues for MDI operations
+- Configurability constraints
+- Security concerns for master data handling
+
+**Always use**: Service instances with explicit configuration.
+
+### Service Instance Creation
+
+**Step 1: Navigate**
+Services → Service Marketplace → Master Data Integration
+
+**Step 2: Configure**
+
+| Setting | Value |
+|---------|-------|
+| Runtime Environment | Other |
+| Service Plan | See below |
+| Instance Name | Descriptive (identify application) |
+
+**Step 3: Set Parameters**
+
+```json
+{
+  "application": "<application-code>"
+}
+```
+
+### Service Plans
+
+| Plan | Target | Cost | Requirements |
+|------|--------|------|--------------|
+| sap-integration | SAP cloud apps | FREE | Default entitlement |
+| s4hana-onpremise | S/4HANA On-Premise | PAID | CPEA-enabled account |
+
+### Application Codes
+
+| Application | Code |
+|-------------|------|
+| SAP S/4HANA Cloud | `s4` |
+| SAP Ariba | `ariba` |
+| SAP SuccessFactors | `sfsf` |
+| SAP Fieldglass | `fieldglass` |
+| SAP Commerce Cloud | `commerce` |
+| SAP Cloud for Customer | `c4c` |
+
+*Check application-specific documentation for exact codes.*
+
+### Service Binding Best Practices
+
+**Naming Convention**: Include creation date for tracking
+```
+ValidFrom_20240501
+```
+
+**Benefits**:
+- Track credential age
+- Assess security incident timelines
+- Plan rotation schedules
+
+---
+
+## Client Configuration Attributes
+
+### businessSystemId
+
+| Property | Details |
+|----------|---------|
+| Purpose | Display name in Business Data Orchestration UI |
+| Required for | SOAP API integration with business partners |
+| Max Length | 60 characters |
+| Characters | Alphanumeric, underscore, hyphen |
+| Uniqueness | Must be unique per tenant |
+
+**Important**: Cannot change after SOAP replication starts.
+
+```json
+{
+  "businessSystemId": "S4HCLOUD_PRD"
+}
+```
+
+**Configuration via Generic API** (alternative to UI):
+```http
+POST <BASE_URL>/businesspartner/v0/odata/API_GENERIC_CONFIGURATIONS/GenericConfigurations
+
+{
+  "ConfigurationName": "Business System",
+  "ConfigurationValue": "<Business System Name>"
+}
+```
+
+**Alignment Required With**:
+- DRF business system names (S/4HANA On-Premise)
+- Communication System UI (S/4HANA Cloud)
+- `RecipientBusinessSystemID` in SOAP payloads
+
+### writePermissions
+
+Controls create/modify/delete authorization per entity type.
+
+```json
+{
+  "writePermissions": [
+    { "entityType": "sap.odm.finance.costobject.CostCenter" },
+    { "entityType": "sap.odm.businesspartner.BusinessPartner" }
+  ]
+}
+```
+
+**Principle**: Least privilege - grant only required permissions.
+
+**Requirement (2022+)**: Write permissions must be explicitly configured when connecting clients.
+
+### globalTenantId
+
+| Property | Details |
+|----------|---------|
+| Purpose | Identifies last significant writer on Events API |
+| Length | 1-40 characters |
+| Characters | Alphanumeric, -, ., _, ~ |
+| When to use | Only if application documentation requires |
+
+```json
+{
+  "globalTenantId": "tenant-identifier"
+}
+```
+
+### logSys
+
+| Property | Details |
+|----------|---------|
+| Purpose | Logical system of last significant writer |
+| Max Length | 10 characters |
+| When to use | Only if application documentation requires |
+
+```json
+{
+  "logSys": "S4CLOUD"
+}
+```
+
+---
+
+## Connecting Specific Systems
+
+### S/4HANA Cloud (via Communication Arrangements)
+
+**Communication Arrangements Required**:
+- **SAP_COM_0659**: Master Data Integration
+- **SAP_COM_0594**: Business Data Orchestration (inbound only)
+
+**Steps**:
+1. Create service instance with `application: "s4"`
+2. Create service binding
+3. Configure communication arrangement in S/4HANA Cloud
+4. Set up BTP destination
+
+### S/4HANA On-Premise (via drfimg)
+
+**Transaction**: `drfimg`
+
+**Step 1 - Technical Settings**:
+1. Define business system (subdomain from BTP Cockpit)
+2. Add entry 986 for Business Partner with Relationships
+3. Set "Replication via Services" as channel
+4. Add entry 1376 for key mapping (optional)
+
+**Step 2 - Replication Model**:
+1. Create model with description
+2. Assign outbound implementation: `986_3 Outbound Impl. for BP/REL via Services`
+3. Set target systems and PACK_SIZE_BULK
+4. Activate model
+
+**Reference**: SAP Note 3065614
+
+### SOAP Applications
+
+**Prerequisites**:
+1. businessSystemId configured
+2. SOAP endpoints accessible
+3. Destinations configured
+
+**Required Destinations** (per businessSystemId):
+- `{businessSystemId}_BPOUTBOUND`
+- `{businessSystemId}_BPCONFIRM`
+- `{businessSystemId}_BPRELOUTBOUND`
+- `{businessSystemId}_BPRELCONFIRM`
+- `{businessSystemId}_KMOUTBOUND`
+- `{businessSystemId}_KEYMAPCONFIRM`
+
+**Max Destinations**: 6 per unique client connection
+
+---
+
+## Authentication Methods
+
+### OAuth2 Client Credentials (Default)
+
+Automatically created during service binding.
+
+**Token Request**:
+```bash
+curl --request POST "$xsuaa_url/oauth/token" \
+  --header "Content-Type: application/x-www-form-urlencoded" \
+  --user "$client_id:$client_secret" \
+  --data-urlencode "grant_type=client_credentials"
+```
+
+### Mutual TLS with X.509 Certificates (Recommended)
+
+**Configuration**:
+```json
+{
+  "xsuaa": {
+    "credential-type": "x509",
+    "x509": {
+      "key-length": 2048,
+      "validity": 7,
+      "validity-type": "DAYS"
+    }
+  }
+}
+```
+
+**Validity Types**: DAYS, MONTHS, YEARS
+
+**Token Endpoint**: `<uaa.certurl>/oauth/token` (different from client credentials)
+
+**Important**: Authentication only works while certificate is valid. Renewal requires recreating service binding.
+
+### Externally-Managed Certificates
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| ensure-uniqueness | false | Enforce certificate uniqueness |
+| certificate-pinning | true | When false, allows DN comparison for rotation |
+
+---
+
+## Business User Authentication
+
+### Roles Required
+
+| Role | Purpose |
+|------|---------|
+| BusinessConfigurationAdmin | Configuration tasks |
+| ExtensionDeveloper | Extensibility tasks |
+
+**Assignment**: Via BTP Cockpit role collections
+
+### Authentication Flows
+
+**Passcode Flow (Recommended)**:
+1. Visit `$xsuaa_url/passcode`
+2. Obtain passcode
+3. Exchange via POST with service instance credentials
+
+**Password Flow**:
+Direct authentication with username/password plus service instance credentials.
+
+---
+
+## Distribution Model Configuration
+
+### Creating Models (Business Data Orchestration UI)
+
+1. Access Fiori Launchpad
+2. Select "Manage Distribution Model"
+3. Create model with:
+   - Provider (sender)
+   - Consumer (receiver) identified by businessSystemId
+   - Business Object Type
+   - API selection (REST or SOAP)
+   - Package size
+   - Scheduling
+
+### Model Constraints
+
+- BP Relationship model requires active BP model
+- Cannot deactivate BP model with active BP Relationship model
+
+### Filters
+
+| Type | Purpose |
+|------|---------|
+| Object Selection | Which records to replicate |
+| Data Scope | Which parts of records to replicate |
+
+---
+
+## Disconnecting Applications
+
+**Steps**:
+1. Deactivate distribution models using the client
+2. Delete service binding
+3. Delete service instance
+
+**Data Cleanup**: Proactively delete master data no longer needed by remaining clients (not automatic).
+
+---
+
+## SAP Cloud ALM Monitoring
+
+**Recommendation**: Use SAP Cloud ALM for monitoring MDI and data flow processing.
+
+**Setup**:
+1. Subscribe to SAP Cloud ALM
+2. Register clients for SAP Passport Event acceptance
+3. Configure mapping between MDI service instances and Cloud ALM services
+
+**Do NOT**:
+- Disable SAP Passport Events
+- Filter SAP Passport Events
+
+---
+
+## Version History (What's New)
+
+### 2024
+- Business Data Orchestration rebranding (from Master Data Orchestration)
+- Client certificate authentication for ABAP environment
+- Display Clients feature (read-only client information)
+
+### 2023
+- 5 new ODM entities: ExchangeRate 4.0.0, Equipment 5.1.0, FunctionalLocation 5.0.0, Product 5.0.0
+- GTID configuration (`globalTenantId`)
+- `logSys` metadata for last significant writer
+- Two service plans with pricing structure
+- Service degradation incident (Note 3344090)
+
+### 2022
+- Extensibility v1 API (unified REST, SOAP, ODATA)
+- Mandatory write permissions for new clients
+- BusinessConfigurationAdmin role requirement
+- v0 Extensibility API deprecated
+- SOAP APIs for Product decommissioned
+
+### 2021
+- **December**: ODM 3.0.0 entities exposed to production
+- **November**: SAP One Domain Model adoption ("MDI is based on the SAP ODM")
+- **November**: Extension fields creation with SOAP mapping for BP services
+- **November**: Destination mapping configuration (MDI ↔ SAP Cloud ALM)
+- **November**: Distribution status monitoring with replication retry
+- **June**: Product replication via distribution models
+- **June**: BP distribution model configuration
+- **May**: BP deletion via SOAP + SAP Data Retention Manager
+- **May**: SOAP API for Business Partner replication
+- **May**: Manage Data Ownership app (system-level ownership assignment)
+- **May**: Cost center filtering + Business Context Manager data category support
+
+**Business Data Orchestration Apps (2021)**:
+- Manage Data Ownership - specify ownership at object type level
+- Configure Destination Mapping - map between MDI and Cloud ALM
+- Display Distribution Status - monitor with retry functionality
+- Manage Business Object Type - extension fields with SOAP mapping
+
+---
+
+## Documentation Links
+
+- **Initial Setup**: [https://help.sap.com/docs/master-data-integration/sap-master-data-integration/initial-setup-and-administration](https://help.sap.com/docs/master-data-integration/sap-master-data-integration/initial-setup-and-administration)
+- **Creating Tenants**: [https://help.sap.com/docs/master-data-integration/sap-master-data-integration/creating-tenants](https://help.sap.com/docs/master-data-integration/sap-master-data-integration/creating-tenants)
+- **Connecting Applications**: [https://help.sap.com/docs/master-data-integration/sap-master-data-integration/connecting-applications](https://help.sap.com/docs/master-data-integration/sap-master-data-integration/connecting-applications)
+- **Authentication**: [https://help.sap.com/docs/master-data-integration/sap-master-data-integration/authentication-and-authorization](https://help.sap.com/docs/master-data-integration/sap-master-data-integration/authentication-and-authorization)