SAP OData Connection

Use TDK to read from and write to SAP tables over an OData service, without a direct database (JDBC) connection to SAP HANA.

Overview

The SAP OData connector lets the Synthesized Platform exchange table data with an SAP system through a purpose-built OData v2 service running on the SAP Gateway, rather than over a JDBC connection to the underlying database.

This is useful when:

  • Direct database access to SAP HANA is not permitted (network, security, or licensing policy).

  • You want SAP to broker access through the application layer and its standard authorizations.

  • The platform runs outside the SAP network and can only reach SAP over HTTPS.

This is a dedicated integration, not a generic OData client. It talks to a Synthesized-provided ABAP/Gateway service that exposes a fixed set of endpoints for catalog metadata, reading table records, and writing table records. A standard OData service or an arbitrary $metadata document will not work — see Prerequisites.

How a connection is used depends on its role in a workflow:

  • Source (input) — TDK reads records from the OData service and materialises them into a local working directory before transforming them. Used as the input of a masking/subsetting workflow.

  • Target (output) — TDK writes transformed or generated rows back to the OData service. The service is write-only on this side; TDK does not read data back from the target.

All standard TDK transformation modes (MASKING, GENERATION, KEEP) are supported. Transformation is performed by the TDK pipeline as usual; the OData connector only moves data in and out.

How It Works

The connector communicates with three endpoints exposed by the SAP Gateway service (SERVICE_NAME below is the activated service, e.g. ZTDK_SRV):

Endpoint Purpose

/dbHeaderSet

Catalog metadata — the list of exposed tables with their fields, primary keys, and foreign keys. Read once and cached.

/readTableRecords

Paged read of the rows of a single table.

/createTableHeaderSet

Write of a batch of rows to a single table.

The connection flow is:

  1. Authenticate. Every request carries an HTTP Basic Authorization header and an X-Requested-With: XMLHttpRequest header (the latter stops the SAP Gateway redirecting API calls to an HTML login page).

  2. Read metadata. TDK fetches the whole catalog from /dbHeaderSet in one call ($expand pulls fields and foreign keys together) and builds the schema: tables, primary keys (fields flagged as key), and foreign keys. Foreign keys pointing at tables that are not exposed by the service are dropped.

  3. Read data (source). For each table, TDK pages through /readTableRecords using $top/$skip (10,000 rows per page by default), filtering by table name, until the service returns an empty page. Rows are coerced from their ABAP/DDIC types into typed values and stored in a local mirror for transformation.

  4. Write data (target). For each batch, TDK fetches a CSRF token (X-CSRF-Token: Fetch), then POST`s the rows to `/createTableHeaderSet. If the token has expired the request returns 403; TDK fetches a fresh token and retries once.

The connector retries automatically on transient network errors and server (5xx) responses with exponential backoff, since SAP Gateways can surface 502/503/504 during long reads.

Prerequisites

Before configuring a connection, the following must be in place on the SAP side:

  • The Synthesized OData service is installed and activated on the SAP Gateway, exposing the /dbHeaderSet, /readTableRecords, and /createTableHeaderSet endpoints, and configured to expose the tables you want to work with. Note the service name (e.g. ZTDK_SRV).

  • A SAP user with authorization to call the service and to read (and, for a target connection, write) the exposed tables. Use a dedicated technical/service user — see Best Practices.

  • Network access from the platform (or agent) to the Gateway host and HTTPS port (commonly 443, or 44300 for an SSL-enabled Gateway).

  • A valid TLS certificate on the Gateway, trusted by the platform host. If the certificate is self-signed or not yet trusted, you can disable validation for testing — see TLS Configuration.

Connection Configuration

Service URL Format

The connection URL is the root of the OData service:

https://<host>:<port>/sap/opu/odata/sap/<SERVICE_NAME>
Component Description

host

Hostname or IP of the SAP Gateway.

port

HTTPS port of the Gateway (e.g. 443, 44300).

SERVICE_NAME

The activated OData service name (e.g. ZTDK_SRV).

Authentication is username / password (HTTP Basic). No OAuth, SAML, or client-certificate authentication is supported.

Internally TDK marks an OData connection with an odata: URL prefix to route it to this connector. You do not need to add the prefix yourself — enter the plain https://…​; service URL in the UI or config. TDK adds and strips the prefix automatically.

Optional URL parameters

You can append query parameters to the service URL to tune behaviour:

Parameter Default Description

insecureTls

false

Set to true to skip TLS certificate validation. Use only for testing against systems with self-signed certificates. See TLS Configuration.

requestTimeoutMs

60000

Per-request timeout in milliseconds. Increase for tables that are slow to page on the Gateway.

Example with parameters:

https://saphost.company.com:44300/sap/opu/odata/sap/ZTDK_SRV?requestTimeoutMs=120000

Adding a Data Source

Via the UI

  1. Navigate to Data Sources.

  2. Click Add Data Source.

  3. Select the SAP OData type.

  4. Enter the connection details:

    Field Value

    Name

    A label for the connection.

    API endpoint URL

    The service root, e.g. https://your-system/sap/opu/odata/sap/SERVICE_NAME.

    Username

    SAP user with access to the service.

    Password

    Password for that user.

  5. Click Test Connection. This calls the service and fetches a CSRF token to confirm credentials and reachability.

  6. Save.

Required Permissions

The SAP user must be authorized, through standard SAP authorizations, to:

  • Call the OData service on the Gateway (the service must be in the user’s authorized list).

  • Read the exposed tables — required for a source connection.

  • Write the exposed tables via the service — required for a target connection.

Because access is brokered by the ABAP service, table-level permissions are governed by SAP’s own authorization objects rather than by SQL GRANT statements. Work with your SAP Basis team to assign a role that covers the service and the tables in scope.

TLS Configuration

By default the connector validates the Gateway’s TLS certificate against the trust store of the host running the platform (or agent).

For systems with a self-signed or not-yet-trusted certificate, you can disable validation for testing by appending insecureTls=true to the service URL:

https://saphost.company.com:44300/sap/opu/odata/sap/ZTDK_SRV?insecureTls=true

insecureTls=true accepts any certificate and disables protection against man-in-the-middle attacks. Use it only for testing. For production, install the Gateway’s certificate (or its CA) into the trust store of the host and leave validation enabled.

Limitations

Because access goes through a curated OData service rather than the database, some behaviour differs from the JDBC connectors:

  • No schema concept. The service exposes a single, flat namespace. A connection may target at most one schema; the tables appear under the synthetic public schema. Configuring more than one schema is rejected.

  • Source reads only the exposed tables. TDK works with exactly the tables the service exposes via /dbHeaderSet. Foreign keys that reference non-exposed tables are dropped from the model.

  • No schema (DDL) reproduction. TDK cannot create or alter tables over OData. The target tables must already exist and be exposed by the service. Schema transfer between a source and an OData target is not supported.

  • Target is write-only. TDK does not read data back from a target OData connection.

  • Authentication is HTTP Basic only.

  • OData v2 only, against the Synthesized service endpoints — generic OData entity sets and $metadata discovery are not used.

Supported Data Types

TDK maps ABAP Dictionary (DDIC) types to its internal types as follows. Unknown types fall back to text (VARCHAR) with a warning.

DDIC type TDK type Notes

C, N, g

VARCHAR

Character, numeric-text, and string fields.

D

DATE

T

TIME

P

DECIMAL

Packed number; precision from length, scale from decimals.

F

DOUBLE

Floating point.

b

TINYINT

s

SMALLINT

I

INTEGER

8

BIGINT

X, y

VARBINARY

Raw/byte fields.

Performance Notes

  • Source connections need a working directory. TDK materialises read rows into a local mirror (DuckDB) before transforming them; an SAP mirror can be several gigabytes, so make sure the working directory has enough disk space.

  • Reads are paged at 10,000 rows per request by default; writes are batched. Tune requestTimeoutMs upward for tables that are slow to page on the Gateway.

  • A failed write batch aborts the run — TDK does not partially commit a target table.

Troubleshooting

Test Connection fails with an HTML/login response
The Gateway is redirecting the API call to a login page. Confirm the service is activated and the user is authorized to call it. (TDK already sends X-Requested-With to avoid this; persistent redirects usually indicate an authorization or activation problem.)

Authentication failed (401)
Check the username and password. Confirm the user is not locked and is permitted to use the service.

Forbidden (403) on write
Usually a CSRF token issue — TDK refetches and retries automatically. Persistent 403 indicates the user lacks write authorization for the table or the service.

SSL handshake failed
The Gateway certificate is not trusted by the host. Install the certificate (or CA) into the host trust store, or use insecureTls=true for testing only.

Slow reads / timeouts (502 / 503 / 504)
The Gateway is slow to page large tables. TDK retries 5xx responses automatically; increase requestTimeoutMs if individual pages are timing out.

Best Practices

  • Use a dedicated SAP service user with only the authorizations needed for the service and the in-scope tables, and a different user per environment for auditability.

  • Secure credentials with a secret manager rather than storing plain-text passwords; rotate them periodically.

  • Keep TLS validation on in production; reserve insecureTls=true for testing.

  • Test the connection before running a workflow, and confirm the user has read (source) or write (target) access to every table in scope.

See Also