Setting up SAP S/4HANA Cloud Private Edition

Syncari's SAP S/4HANA Private Cloud synapse connects to SAP S/4HANA Private Edition systems through SAP Gateway OData V2 services. Use this synapse when your S/4HANA system exposes APIs such as API_PURCHASEORDER_PROCESS_SRV, API_WORK_CENTERS, or other activated OData V2 services under /sap/opu/odata/sap.

This synapse is separate from C4C and from SAP S/4HANA Public Cloud OData V4 integrations. S/4HANA Private Cloud commonly exposes released APIs as OData V2 services, and each activated service can contain one or more entity sets.

Prerequisites

Before creating the synapse, confirm the following in SAP and in your network environment:

• The required OData V2 service is activated in SAP Gateway. SAP administrators can verify this in /IWFND/MAINT_SERVICE or the equivalent Activate and Maintain Services UI.
• The Syncari environment can reach the SAP Gateway host and port over HTTP or HTTPS.
• You have a technical SAP user or OAuth client with authorization to read $metadata and the entity sets you plan to sync.
• If your SAP system requires a client, know the SAP client number, for example 100.
• If your SAP system returns language-specific descriptions or validation messages, know the SAP language code, for example EN.

Create The Synapse

In Syncari, create a new SAP S/4HANA Private Cloud synapse and enter the connection details for your SAP Gateway endpoint.

• Endpoint: Required. Enter the SAP Gateway base URL, including protocol and port when needed. Example: https://sap.example.com:443. Syncari appends /sap/opu/odata/sap/<service> for service calls.
• Auth Type: Required. Choose username/password or OAuth 2.0 client credentials, depending on how SAP Gateway is configured.
• SAP Client: Optional. Adds sap-client to SAP requests.
• SAP Language: Optional. Adds sap-language and an Accept-Language header to SAP requests.
• Service Names: Required. Enter one or more OData service names, separated by commas or new lines. Example: API_PURCHASEORDER_PROCESS_SRV or API_WORK_CENTERS.

Authentication

The synapse supports username/password authentication and OAuth 2.0 client credentials. The correct option depends on your SAP Gateway and identity provider setup.

• Username/Password: Use a technical SAP user authorized for the activated OData services.
• OAuth 2.0 Client Credentials: Use the token endpoint, client ID, client secret, and optional scope configured by SAP Basis or your identity provider.

For write operations, the synapse automatically fetches a CSRF token and SAP session cookies before sending create, update, or delete requests.

Entity Discovery

Syncari reads each configured service's $metadata document and creates one Syncari entity schema for each discovered entity set. A single service can expose many entity sets. For example, a work center service can expose entities such as A_WorkCenters, A_WorkCenterCapacity, and related capacity interval or text entities.

The schema is editable in Syncari so users can set or adjust Syncari-specific schema controls such as watermark fields and composite IDs.

• Key fields from SAP metadata are marked as ID fields. Composite keys are represented as a Syncari composite ID.
• SAP metadata controls whether an entity is treated as read-only or write capable.
• Navigation properties are discovered from metadata. Navigation targets that also have standalone entity sets are represented as reference fields.
• True child navigation objects are represented as object fields with child schema information when metadata provides it.

Navigation And Expanded Data

Some SAP entities include navigation properties such as to_PurchaseOrderItem or to_WorkCenterDescription. The synapse exposes these as schema fields and also supports read-time expansion through an entity source parameter.

• Expand Navigation Paths: Optional source parameter. Enter comma or newline separated navigation names or paths to send as $expand.
• For standalone navigation targets, the original navigation field remains a reference value. Expanded object data is added to a dynamic field using the __expanded suffix, for example to_PurchaseOrderItem__expanded.
• For true child objects, values are returned as maps or arrays of maps, not as separate Syncari entity records.

Reading Data

The synapse supports initial and incremental reads through OData V2 entity set requests. Reads use server-side paging with $top and follow SAP __next links when more data is available.

• Initial sync: Reads the configured entity without applying a watermark filter.
• Incremental sync: Uses the schema watermark field to build an OData V2 $filter when a watermark is configured.
• Read by ID: Uses the entity key segment from the schema. For composite keys, Syncari joins key values with |.
• Page Size: Controls the read page size for OData requests. If not set, the synapse uses its default page size.

Writing Data

Create, update, and delete support is determined per entity from SAP OData metadata. If SAP marks an entity set as not creatable, not updatable, or not deletable, Syncari treats that operation as unsupported for that entity.

Write behavior is configured through entity destination parameters. These settings let you adapt write payloads to differences across SAP services without storing hidden behavior in schema additional properties.

• SAP Update Method: Optional. Defaults to PATCH. Supported values are PATCH, MERGE, and PUT.
• SAP Omit On Create: Optional. Comma or newline separated field names to remove from create payloads.
• SAP Omit On Update: Optional. Comma or newline separated field names to remove from update payloads.
• SAP Deep Insert Fields: Optional. Comma or newline separated navigation fields to include in create payloads. Use this when SAP requires a child object during create, such as a language-specific description.
• SAP CSRF Token Fetch Mode: Optional. Defaults to SERVICE_ROOT. Use ENTITY_SET if your SAP Gateway requires fetching the CSRF token from the entity set URL.

Write Example

Some SAP services require additional child data during create. For example, creating a work center can require an English description object. In that case, configure SAP Deep Insert Fields with:

to_WorkCenterDescription

Then map the child value in the outgoing payload:

{
  "WorkCenterTypeCode": "A",
  "WorkCenter": "ZSYNC01",
  "WorkCenterDesc": "Syncari Work Center",
  "Plant": "1710",
  "WorkCenterCategoryCode": "0001",
  "WorkCenterResponsible": "001",
  "WorkCenterUsage": "009",
  "to_WorkCenterDescription": {
    "results": [
      {
        "Language": "EN",
        "WorkCenterDesc": "Syncari Work Center"
      }
    ]
  }
}

Data Types

The synapse maps common OData V2 EDM types to Syncari field types during schema discovery and normalizes values during read and write.

• Edm.Boolean maps to boolean.
• Edm.Int16 and Edm.Int32 map to integer.
• Edm.Int64 maps to long.
• Edm.Decimal maps to decimal.
• Edm.Double and Edm.Single map to double.
• Edm.DateTime and Edm.DateTimeOffset map to datetime.
• Edm.Date maps to date.
• Edm.Time, Edm.Guid, and Edm.Binary map to string.

SAP date values returned in /Date(...)/ format and ISO date values are normalized into Syncari date or datetime values. Date and datetime values written back to SAP are serialized in OData V2-compatible JSON format.

Troubleshooting

• Service does not appear or metadata fails: Confirm the service name is activated and that the user can access /sap/opu/odata/sap/<service>/$metadata.
• HTTP 401 or 403: Check the technical user's authorization, OAuth client setup, SAP client, and network allowlisting.
• HTTP 406 on metadata: Confirm the endpoint is the OData V2 service endpoint and that SAP Gateway can return XML metadata for the service.
• Invalid token detected: Check the entity URL, key syntax, and OData query options. Entity set names should not start with an extra slash.
• Create requires additional fields: Review the SAP error detail. Some APIs require deep insert child objects or language-specific descriptions even when the top-level metadata marks only a few fields as required.
• Update fails: Try changing SAP Update Method from PATCH to MERGE or PUT if your SAP Gateway requires a different update method for that entity.
• CSRF token errors: Try changing SAP CSRF Token Fetch Mode from SERVICE_ROOT to ENTITY_SET.