# OData system notes - SAP and Microsoft

S/4HANA, SuccessFactors, Dynamics 365 and Business Central - what to put in the connection's form for each platform.

The protocol is the same everywhere, yet each platform has its own service root layout, auth expectations and quirks. The notes below list what to put in the connection's form for each of the four big OData platforms.

## SAP S/4HANA {#sap-s4hana}

S/4HANA exposes classic Gateway services over OData V2 and newer ones over V4. SAP systems also have their own connection type and [a dedicated chapter](https://zato.io/docs/dev/sap/index.html) - the notes below apply to plain OData connections pointed at S/4HANA.

- Address: `https://host:port/sap/opu/odata/sap/API_BUSINESS_PARTNER` (V2) or `https://host:port/sap/opu/odata4/sap/...` (V4)
- OData version: match the service - `2.0` for `/sap/opu/odata/`, `4.0` for `/sap/opu/odata4/`
- Auth type: Basic with a technical user, or OAuth2 in BTP-fronted setups
- Needs CSRF token: enable it - Gateway requires X-CSRF-Token for every write
- The `sap-client` parameter, when needed, is passed through the custom query option:

```python
partners = conn.read('A_BusinessPartner',
    top=10,
    custom={'sap-client': '100'},
)
```

## SAP SuccessFactors {#sap-successfactors}

SuccessFactors uses OData V2 and its entity model is large - User, EmpJob, PerPersonal and hundreds of others.

- Address: `https://apisalesdemo2.successfactors.eu/odata/v2` - the host depends on the data center
- OData version: `2.0`
- Auth type: OAuth2 - SuccessFactors issues tokens through its own token endpoint, `https://<host>/oauth/token`
- Paging: SuccessFactors caps pages and returns `__next` links - use .iter and the client follows them

## Microsoft Dynamics 365 Finance and Operations {#microsoft-dynamics-365-finance-and-operations}

- Address: `https://<environment>.operations.dynamics.com/data`
- OData version: `4.0`
- Auth type: OAuth2 against Microsoft Entra ID
  - Token URL: `https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token`
  - Tenant ID: your Entra ID tenant
  - Scopes: `https://<environment>.operations.dynamics.com/.default`
- Entity names are plural and case-sensitive, e.g. `CustomersV3`, and most entity sets use composite keys that include `dataAreaId`:

```python
customer = conn.get('CustomersV3', {'dataAreaId': 'usmf', 'CustomerAccount': 'US-001'})
```

## Microsoft Business Central {#microsoft-business-central}

Business Central publishes its standard API under version-numbered paths and every entity is scoped to a company.

- Address: `https://api.businesscentral.dynamics.com/v2.0/<tenant>/<environment>/api/v2.0`
- OData version: `4.0`
- Auth type: OAuth2 against Microsoft Entra ID with the `https://api.businesscentral.dynamics.com/.default` scope - sandboxes also accept Basic with web-service access keys
- Companies come first - read the `companies` entity set once, then address everything else through the company's ID:

```python
companies = conn.read('companies')
company_id = companies[0]['id']

customers = conn.read(f'companies({company_id})/customers', top=10)
```

- Business Central enforces optimistic concurrency - pass the `@odata.etag` an entity came with when updating or deleting it.

## Learn more {#learn-more}

- [OData integrations](https://zato.io/docs/dev/odata/) - Entity sets as Python dicts, across OData V2 and V4 systems
- [Query options](https://zato.io/docs/dev/odata/query/) - Filters, ordering, paging, expansion and counting
- [OData security](https://zato.io/docs/dev/odata/security/) - Basic Auth, bearer tokens and OAuth2 client credentials
- [OData tutorial](https://zato.io/tutorials/odata.html) - From an empty connection to reading and writing records