SAP S/4HANA

Sync data from your warehouse to SAP S/4HANA entities via the OData API. Keep your business partners, sales orders, materials, and other SAP master data in sync with your latest customer and operational data from Zeotap.

Prerequisites

• An SAP S/4HANA system (Cloud or on-premise) with OData API access enabled
• A communication user with appropriate authorization objects, or an OAuth 2.0 client configured via SAP BTP or a Communication Arrangement
• The base URL of your S/4HANA system (e.g., https://myhost.s4hana.cloud.sap)
• Knowledge of the target OData service path and entity set name

Permissions

The authenticated user or communication arrangement must have:

• OData service access for the target API (e.g., API_BUSINESS_PARTNER, API_SALES_ORDER_SRV)
• Read and write authorization on the relevant business objects (e.g., authorization object S_BPA_ORG for business partners)
• For cloud systems, a Communication Arrangement must be set up with the appropriate Communication Scenario (e.g., SAP_COM_0008 for Business Partner)

Authentication

SAP S/4HANA supports two authentication methods:

Basic Authentication

1. Navigate to Destinations in the Zeotap sidebar
2. Click Add Destination and select SAP S/4HANA
3. Select Basic Authentication as the auth method
4. Enter the Username and Password of your SAP communication user
5. These credentials are stored securely and never exposed in the UI after saving

For on-premise systems, this is typically a dialog or communication user created in transaction SU01. For cloud systems, create a communication user in the Communication Management app.

OAuth 2.0 Client Credentials

1. Navigate to Destinations in the Zeotap sidebar
2. Click Add Destination and select SAP S/4HANA
3. Select OAuth 2.0 Client Credentials as the auth method
4. Enter the Client ID and Client Secret from your Communication Arrangement or SAP BTP service key
5. Enter the Token URL from your OAuth configuration (e.g., https://myhost.authentication.eu10.hana.ondemand.com/oauth/token)
6. Click Test Connection to verify the credentials

Configuration

Target Settings

Common Entity Sets

Use the entity set name exactly as documented in the SAP API Business Hub for your target service.

Supported Operations

Sync Modes

Audience Sync Modes

SAP S/4HANA does not have a native audience or list membership concept, so audience sync modes are not supported. Use standard sync modes to create or update entity records.

Features

• Field Mapping: Yes — map your warehouse columns to any OData entity property
• Schema Introspection: No — configure field mappings manually based on the target entity set’s metadata

Default Destination Fields

These common SAP Business Partner fields appear as suggestions in the field mapping editor:

These defaults are based on the Business Partner API. When syncing to other entity sets (Sales Orders, Products, etc.), configure field mappings based on the target entity’s OData metadata.

How It Works

1. Field mapping: Zeotap maps each warehouse row to SAP S/4HANA entity properties using your configured field mappings
2. CSRF token: Before writing, Zeotap fetches an X-CSRF-Token from the OData service (required by SAP for all modifying requests). The token is cached and automatically refreshed if it expires
3. API calls: Each record is sent individually via the OData API:
   • Insert: POST /{service_path}/{entity_set}
   • Update: PATCH /{service_path}/{entity_set}('{primary_key}') (partial update — only mapped fields are modified)
   • Upsert: Uses PATCH if a primary key is available, otherwise falls back to POST
4. Retry logic: Transient failures (HTTP 429, 5xx server errors) are retried with exponential backoff (up to 3 retries per request). CSRF token expiry (HTTP 403) triggers an automatic token refresh and retry
5. Progress tracking: Rows are processed sequentially with progress logged every 50 rows

Batch Size

The SAP S/4HANA OData API processes one record per request in this connector. While SAP supports OData $batch requests, individual entity creation and update are more reliable across different S/4HANA system configurations. Zeotap handles the batching internally with automatic retry and error tracking for each record.

Rate Limits

SAP S/4HANA rate limits vary by system configuration and deployment type:

• Cloud: Governed by the SAP BTP fair-use policy and Communication Arrangement quotas. Typical limits are around 1,000—5,000 requests per minute depending on the API
• On-premise: Limits are configured per ICF service and application server capacity. No hard API rate limits by default, but connection pools and work process availability are limiting factors
• Rate limit response: HTTP 429 with optional Retry-After header
• Zeotap behavior: Automatically retries on HTTP 429 with exponential backoff respecting Retry-After headers

If you experience rate limiting, consider:

• Increasing the quota in your Communication Arrangement (cloud)
• Adjusting ICF service parameters (on-premise)
• Reducing sync frequency or segment size

Best Practices

• Use a dedicated communication user with only the required authorization objects rather than a dialog user
• Map the primary key field (e.g., BusinessPartner for business partners) for upsert and update operations to avoid duplicate records
• Test with a small batch before running a full sync to verify field mappings and authorization
• Use OData V2 unless your specific API only supports V4 — V2 has broader support across S/4HANA versions
• Set up a Communication Arrangement (cloud) or RFC destination (on-premise) specifically for Zeotap integration
• Monitor sync results in the Zeotap sync run history to catch authorization or field validation errors early

Troubleshooting

Authentication failed (HTTP 401)

Verify that the username and password (or OAuth client credentials) are correct. For cloud systems, ensure the Communication Arrangement is active and the communication user is not locked. For on-premise systems, check that the user is not expired and has the SAP_BC_WEBSERVICE_CONSUMER role.

Authorization error (HTTP 403)

The authenticated user lacks the required authorization objects for the target entity set. Check the user’s role assignments in transaction PFCG (on-premise) or the Communication Arrangement’s scope (cloud). The error response typically includes the missing authorization object name.

CSRF token validation failed

SAP requires a valid X-CSRF-Token for all write operations. Zeotap automatically fetches and refreshes the token, but if you see persistent CSRF errors, verify that:

• The system’s session timeout is not extremely short
• No network proxy is stripping the X-CSRF-Token header
• The communication user has access to the OData service metadata endpoint

Entity set not found (HTTP 404)

The specified entity set or service path does not exist. Verify the service path and entity set name against the SAP API Business Hub or the system’s /$metadata document. Entity set names are case-sensitive (e.g., A_BusinessPartner, not a_businesspartner).

Update requires a primary key

When using Update sync mode, each row must have a primary key mapped (e.g., BusinessPartner for business partners). Without it, the OData API cannot identify which record to update. Switch to Upsert mode if some rows may not have a primary key.

Field validation error (HTTP 400)

The OData API rejected a field value. Common causes include:

• Wrong data type: Sending a string for a numeric field, or an incorrectly formatted date (SAP expects /Date(timestamp)/ for OData V2 date fields)
• Mandatory field missing: The entity requires certain fields that are not mapped
• Value too long: Exceeding the maximum field length (e.g., 10 characters for BusinessPartner)

Check the error response body for the specific field and constraint that failed.

Connection timeout

Large syncs may experience timeouts if the S/4HANA system is under heavy load. Zeotap uses a 120-second timeout per request. If timeouts persist, try syncing during off-peak hours or reducing the sync batch size.

OAuth token request failed

For OAuth 2.0 authentication, verify that:

• The Token URL is correct and reachable from Zeotap
• The Client ID and Client Secret are from an active service key
• The OAuth client has the client_credentials grant type enabled
• The token endpoint is not blocked by network policies