Initial commit

2025-11-30 08:55:12 +08:00
commit 2bc6bda6b5
13 changed files with 3009 additions and 0 deletions
--- a/references/extensibility.md
+++ b/references/extensibility.md
@@ -0,0 +1,204 @@
+# Extensibility
+
+Custom extensions for SAP Master Data Integration.
+
+**Source**: [https://github.com/SAP-docs/sap-btp-master-data-integration/blob/main/docs/initial-setup-and-administration/extensibility-7612e09.md](https://github.com/SAP-docs/sap-btp-master-data-integration/blob/main/docs/initial-setup-and-administration/extensibility-7612e09.md)
+
+## Overview
+
+SAP Master Data Integration enables custom extensions to integration models through field and node additions for master data objects like Business Partner, Product, and Workforce Person.
+
+## Why Extensibility?
+
+Standard SAP software covers many processes, but customer landscapes have specific requirements:
+- Control business processes with custom attributes
+- Enable distribution based on custom fields
+- Support analytics functions
+
+## Configuration Methods
+
+### UI Method
+Use **Manage Business Object Type** in Business Data Orchestration
+
+### API Method
+Extensibility APIs for direct implementation, particularly for composition-based extensions.
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| Role | ExtensionDeveloper |
+| Access | Assigned via BTP Cockpit role collections |
+
+## Extension Principles
+
+### Version Compatibility
+- Extensions valid across compatible One Domain Model versions
+- Extension in v2.0.0 applies to v3.0.0 automatically
+- Does NOT apply to earlier versions
+
+### Immutability
+**Critical**: Extension fields cannot be updated or deleted once created.
+
+### Scope
+Extensions exist only within MDI. Ensure upstream and downstream applications support the extended fields.
+
+---
+
+## Extension Types
+
+### Field-Level Extensions
+
+Supported primitive types:
+
+| Type | Additional Parameters |
+|------|----------------------|
+| String | Length constraints |
+| Boolean | - |
+| Date | - |
+| DateTime | - |
+| Double | - |
+| Time | - |
+| Integer | - |
+| Decimal | Precision, scale |
+| UUID | - |
+
+### Node-Level Extensions (Composition)
+
+Create new entity types within the extended model:
+
+| Property | Description |
+|----------|-------------|
+| type | "Composition" |
+| relationship | "one" or "many" |
+| fields | Array of embedded fields |
+
+---
+
+## SOAP Integration Extensions
+
+### Supported Entities
+- BusinessPartner
+- BusinessPartnerRelationship
+
+### Namespace Requirement
+Namespace prefix must begin with `extns`
+
+### soapParameters.target
+Specifies corresponding SOAP model field name for cross-system mapping.
+
+---
+
+## Extension API Workflow
+
+### 1. Create Extension
+
+```http
+POST /extensibility/v1/businessObjectTypes/{type}/extensions
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "name": "customField",
+  "type": "String",
+  "length": 100
+}
+```
+
+### 2. Check Activation Status
+
+| Status | Description |
+|--------|-------------|
+| activationInProgress | Extension being processed |
+| activated | Ready for use |
+| failed | Activation error |
+
+### 3. Generate Extended WSDL
+
+After successful activation:
+
+```http
+PUT /extensibility/v1/wsdl/generate
+```
+
+### 4. Retrieve WSDL
+
+```http
+GET /extensibility/v1/wsdl/{serviceName}
+```
+
+Use for integration documentation and client configuration.
+
+---
+
+## Extension Examples
+
+### Simple Field Extension
+
+```json
+{
+  "name": "customerPriority",
+  "type": "String",
+  "length": 20
+}
+```
+
+### Composition Extension (Node)
+
+```json
+{
+  "name": "customAddresses",
+  "type": "Composition",
+  "relationship": "many",
+  "fields": [
+    {
+      "name": "addressType",
+      "type": "String",
+      "length": 10
+    },
+    {
+      "name": "isPrimary",
+      "type": "Boolean"
+    }
+  ]
+}
+```
+
+---
+
+## Using Extensions in Distribution Models
+
+Created extensions can be used as filter criteria:
+1. Access Distribution Model configuration
+2. Select extended fields in filter conditions
+3. Apply object selection or data scope filters
+
+---
+
+## Deprecation Notice
+
+| API | Status | Timeline |
+|-----|--------|----------|
+| Extensibility v0 API | Deprecated | Q2 2022 |
+| Extensibility v1 API | Current | Use this |
+
+---
+
+## Best Practices
+
+1. **Plan extensions carefully** - Cannot be modified or deleted
+2. **Coordinate with applications** - Ensure upstream/downstream support
+3. **Use consistent naming** - Follow organization conventions
+4. **Document extensions** - Track all custom fields
+5. **Test thoroughly** - Validate in non-production first
+6. **Use appropriate types** - Match business requirements
+
+---
+
+## Limitations
+
+- Extensions cannot be updated after creation
+- Extensions cannot be deleted
+- SOAP extensions limited to BusinessPartner and BusinessPartnerRelationship
+- Namespace must start with `extns` for SOAP
+- Custom extensions not included in API Business Accelerator Hub specifications