# SAP SuccessFactors

API server addresses, OAuth2 authentication, the employee entity model and server-driven paging.

SuccessFactors exposes its HR data - users, employments, personal information, time off - through an OData V2 API with an entity model that spans hundreds of sets. An outgoing SAP connection pointed at the API server gives services access to all of them.

## Connection settings {#connection-settings}

- Address: `https://apisalesdemo2.successfactors.eu/odata/v2` - the API server host depends on the data center that hosts your instance
- OData version: `2.0`
- Auth type: OAuth2 - SuccessFactors issues tokens through its own token endpoint, `https://<host>/oauth/token`
- Needs CSRF token: disable it - SuccessFactors does not use the X-CSRF-Token exchange

## The entity model {#the-entity-model}

The core of the model revolves around a few entity sets:

- `User` - accounts, names and contact data
- `EmpJob` - employment details, positions, departments
- `PerPersonal` - personal information
- `EmpTime` - time off requests

```python
conn = self.sap['SAP.SuccessFactors']

# Active users from one department, selected fields only
users = conn.read('User',
    filter="department eq 'Engineering' and status eq 't'",
    select='userId,firstName,lastName,email',
)

for user in users:
    self.logger.info('User -> %s %s', user['firstName'], user['lastName'])
```

## Paging {#paging}

SuccessFactors caps every page and returns `__next` links for the rest. Use .iter and the client follows the links until the result set is exhausted:

```python
for user in conn.iter('User', filter="status eq 't'"):
    self.logger.info('Received -> %s', user['userId'])
```

## Related entities {#related-entities}

Navigation properties connect the sets - a user's employment records, an employment's job information. The expand option reads them in one round trip:

```python
users = conn.read('User',
    filter="userId eq '10001'",
    expand='empInfo/jobInfoNav',
)
```

## Learn more {#learn-more}

- [SAP integrations](https://zato.io/docs/dev/sap/) - Business entities as Python dicts, over OData V2 and V4
- [Querying SAP](https://zato.io/docs/dev/sap/query/) - Filters, paging, counting and related entities
- [S/4HANA and ECC](https://zato.io/docs/dev/sap/s4hana/) - Gateway services, their entity sets and what they expect
- [SAP security](https://zato.io/docs/dev/sap/security/) - Basic Auth, API keys, bearer tokens and OAuth2 client credentials
- [SAP in enmasse](https://zato.io/docs/dev/sap/enmasse/) - Connections as YAML, with secrets read from the environment