---
title: SAP OData Setup
seo_title: "OData Source Setup — Receive S/4HANA Cloud Documents | FileRelay"
description: "Pull invoices and attachments from released S/4HANA Cloud OData APIs (API_CV_ATTACHMENT_SRV and friends) and route them to SharePoint, S3, and 15+ destinations. No ABAP, no BTP DMS."
---

# SAP OData Setup

S/4HANA Cloud exposes released OData APIs for business-object attachments. FileRelay queries the attachment lists, fetches binaries, and routes them.

> **Use OData when** you're on **S/4HANA Cloud** (Public or Private/RISE), want **released, future-proof endpoints**, and your document model is **attachment-centric** (FI invoices, MM POs, HR records). For free-form DMS storage, use [CMIS](/docs/sources/cmis) instead. Decision matrix: [protocol comparison](/docs/sources/protocol-comparison).

## Which OData APIs?

Pick by business object. The most common:

| API | What it exposes |
|---|---|
| `API_CV_ATTACHMENT_SRV` | Generic attachments on any business object |
| `I_AttachmentForBusinessObject` (CDS) | Read-only view of every attachment with its parent object key |
| `API_SUPPLIERINVOICE_PROCESS_SRV` | Supplier invoice attachments (FI) |
| `API_PURCHASEORDER_PROCESS_SRV` | Purchase order attachments (MM) |
| `API_OUTBOUND_DELIVERY_SRV` | Delivery note attachments (SD) |

Any released v2 or v4 service that exposes attachments works. Full catalog at [api.sap.com](https://api.sap.com/).

## SAP-side setup

### Communication Arrangement

In **SAP Fiori → Communication Arrangements**, create one using the template matching your target API.

| Template | Use case |
|---|---|
| **`SAP_COM_0204`** | Generic OData attachment access |
| **`SAP_COM_0276`** | Document Management integration |
| **`SAP_COM_0008`** | Supplier invoice integration |
| **`SAP_COM_0053`** | Purchase order integration |

Each arrangement needs a Communication System (logical SAP-side rep of FileRelay), a Communication User (FileRelay's identity, inbound), and an auth method — **OAuth 2.0 with X.509 client certificate** or **OAuth 2.0 with client credentials**. Both are supported.

Once saved, the arrangement exposes a **Service URL** plus OAuth credentials.

### Optional — Event Mesh subscription

If your tenant has SAP Event Mesh, subscribe FileRelay to the relevant lifecycle events (`sap.s4.beh.supplierinvoice.v1.SupplierInvoice.Created.v1`, etc.) to trigger immediate fetches instead of polling. Optional — polling works everywhere.

## Configure the source

1. **Repositories → Add Source → OData**.
2. Fill in: name, service URL, OData version (`v2` for most S/4HANA APIs), entity set (e.g. `AttachmentContentSet`), OAuth token URL, client ID/secret, auth method (`client-credentials` or `client-certificate`).
3. **Test connection** — FileRelay mints a token, fetches `$metadata`, validates the entity set, returns a sample result.
4. Save.

For X.509 auth, upload the cert + private key under **Certificates**; FileRelay attaches them on every token request.

## How fetching works

### Polling (default, 60 s)

Each poll runs an incremental query:

```http
GET /sap/opu/odata/sap/API_CV_ATTACHMENT_SRV/AttachmentContentSet
    ?$filter=CreationDateTime gt datetime'2026-05-26T10:00:00'
    &$orderby=CreationDateTime asc
    &$top=100
Authorization: Bearer <token>
```

For each result, FileRelay calls `GET <entity>/$value` to fetch the binary, then forwards it through your connections. Lower poll intervals are fine — S/4HANA Cloud's rate limits are generous.

### Event-driven (Event Mesh)

If subscribed, events arrive at `https://<your-deployment-host>/odata/<source-slug>/events` and trigger immediate fetches.

## Authentication + rotation

OAuth tokens are ~12 h. FileRelay refreshes on demand.

- **Client secret rotation** — paste the new secret; next token request uses it.
- **Certificate rotation** (X.509) — upload the new cert before the old one expires; overlap is supported, no downtime.
- **Communication User password** — not used directly (OAuth, not basic), but the user record must stay active.

## Forwarded metadata

| OData property | Forwarded as |
|---|---|
| `BusinessObjectTypeName` | parent object type (e.g. `BUS2032`) |
| `BusinessObjectKey` / `LinkedSAPObjectKey` | parent object key (PO number, invoice ID) |
| `FileName` | filename |
| `MimeType` | MIME type |
| `CreatedByUser` / `CreationDateTime` | provenance |
| `ArchiveDocumentID` | original SAP archive ID for traceability |

Per-connection mapping in [Document Routing](/docs/connections/routing).

## Gotchas

- **Released APIs only on Public Edition** — no custom CDS / OData. On Private/RISE you *can* roll your own, but released APIs survive upgrades; custom ones are yours to maintain forever.
- **Entity set ≠ entity type** — FileRelay needs the entity *set* name (URL-addressable collection). If `$metadata` lists multiple sets per type, pick the one that returns binary via `$value`.
- **`$value` returns raw bytes** — that's normal.
- **Per-user rate limits** — for many concurrent sources, use a dedicated Communication User per source so one busy stream doesn't starve the others.
- **UTC in filters** — timestamps are UTC; format as `datetime'YYYY-MM-DDTHH:MM:SS'` with no zone suffix.

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| `401` from token URL | Communication User isn't bound as inbound, or wrong scope |
| `403` on `$value` but `200` on the list | Principal has list access but not download — fix the Communication Scenario role |
| `404` on the entity set | Typo, or the scenario doesn't expose that set (check `<service-url>/$metadata`) |
| Polling works, no docs found | Filter wrong (timezone, non-indexed field), or genuinely no new docs |
| Events configured but never fire | Wrong event type, or inbound endpoint unreachable from SAP egress |

Raw request/response captures: [Request Viewer](/docs/api/request-viewer).

## Next steps

- [CMIS Setup](/docs/sources/cmis) — alternative pull-based source for DMS
- [Protocol Comparison](/docs/sources/protocol-comparison)
- [Connections Overview](/docs/connections/overview)