> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/gateways-custom-sap-successfactors/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

{% hint style="info" %}
This version of the gateway is currently compatible with Elimity Insights server versions matching `>3.42.0`.
{% endhint %}

## 1. Setting up a dedicated user in SAP SuccessFactors

The SAP SuccessFactors connector for Elimity Insights authenticates as an OAuth client application bound to a user. We recommend creating a dedicated user to assign the minimal amount of permissions. Refer to [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/534356acc0ab4b0e8977ebfb2eb432f7/02e3e0b3966c42299653b495a42b292f.html) for instructions on how to create a new user in SAP SuccesFactors. Note down the newly created user's username.

## 2. Setting up a dedicated permission role in SAP SuccessFactors

We also recommend creating a dedicated permission role for the newly created user. This permission role should only grant the 'Employee Export' permission. The official documentation contains more information about creating a new permission role in SAP SuccessFactors.

## 3. Setting up a dedicated permission group in SAP SuccessFactors

To assign the newly created permission role to the newly created user, we recommend using a dedicated static permission group. Refer to [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/b569eee64d3f4159b2b5272ba7d6b127/c15b3696a56e4601ae110c1c37c34a3d.html) for instructions in how to create a new static permission group in SAP SuccessFactors.

## 4. Assigning the permission role in SAP SuccessFactors

Follow the instructions listed in [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/b569eee64d3f4159b2b5272ba7d6b127/fbaadf758e00485893d6f099e9f342fa.html) to assign the newly created permission role to the newly created permission group.

## 5. Setting up an OAuth client application in SAP SuccessFactors

Create a new OAuth client application as described in [the official documentation](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/6b3c741483de47b290d075d798163bc1.html). We recommend enabling the 'Bind to Users' option and entering the newly created user's username in the 'User IDs' field. For the 'X.509 Certificate' field, we recommend to generate your own certificate and private key; for example by using the following OpenSSL command:

```shell-session
$ openssl req -days 999 -keyout key.pem -newkey rsa -nodes -out cert.pem -subj '/CN=elimity-insights' -x509
```

Remember to strip out the beginning and ending lines from the certificate contents before pasting into the 'X.509 Certificate' field. Securely store the private key you generated, you will need it to set up the new source in Elimity Insights. Also note down the newly created application's API key.

## 6. Deploying the gateway

The next step in setting up automatic imports via a custom SAP SuccessFactors gateway is deploying the gateway itself. As usual, please make sure your instance of Elimity Insights can reach the gateway and that the gateway can reach your SAP SuccessFactors tenant. Since we distribute the gateway as a Docker image, our recommendation for deployment is to use a CaaS solution like Google Cloud Run or Azure Container Apps. If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to [our documentation about gateways and import agents](/technical-guides/gateways-and-import-agents.md) for additional details.

## 7. Creating a custom source in Elimity Insights

To set up automatic imports via the custom SAP SuccessFactors gateway we need to create a custom source in Elimity Insights itself first. Use the export file below as a starting point for the new source's data model:

{% file src="/files/9Tv3swvt7iLJgjzdb2J4" %}

This file just defines the only `user` entity type and a single (fixed) `status` attribute type. You can simply add attribute types to the data model later on.

## 8. Enabling automatic imports

Having a the new custom source, you can now navigate to its detail page in Elimity Insights and open the 'CONFIG' tab. Click the 'EDIT' button and enter your gateway's URL and the desired CRON schedule. Also add the following configuration values:

<table data-full-width="true"><thead><tr><th>Key</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>apiKey</code></td><td>Text</td><td>API key you noted down in step 5</td></tr><tr><td><code>apiUrl</code></td><td>Text</td><td>URL of the API server for your SAP SuccessFactors tenant; refer to <a href="https://help.sap.com/docs/successfactors-platform/sap-successfactors-api-reference-guide-odata-v2/list-of-sap-successfactors-api-servers#api-servers">the official documentation</a> for more information</td></tr><tr><td><code>attributes</code></td><td>JSON</td><td>JSON array describing which attributes to import from SAP SuccessFactors; refer to <a href="#attributes">the dedicated section on this page</a> for more information</td></tr><tr><td><code>companyId</code></td><td>Text</td><td>Your SAP SuccessFactors company identifier; refer to <a href="https://me.sap.com/notes/0002655655">the official documentation</a> for instructions on how to find this information</td></tr><tr><td><code>userId</code></td><td>Text</td><td>Username of the newly created user, which you noted down in step 1</td></tr><tr><td><code>x509PrivateKeyFile</code></td><td>Secret file</td><td>Private key you stored in step 5</td></tr></tbody></table>

### Attributes

The `attributes` configuration value determines which attributes the gateway should import from SAP SuccessFactors. It should be a JSON array of objects, where each object should have the following properties:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>string</code></td><td>Unique identifier of the attribute type for which the gateway should import assignments</td></tr><tr><td><code>path</code></td><td><code>string</code></td><td>Path of the property to read from user objects returned by SAP SuccessFactors; refer to <a href="#path">the dedicated section on this page</a> for more information</td></tr></tbody></table>

### Path

For each attribute you want to import, the gateway needs to know where to find it in user objects returned by SAP SuccessFactors. The table below shows which values of `path` we currently support, and what their corresponding data types are:

| Path                                    | Type      |
| --------------------------------------- | --------- |
| `companyExitDate`                       | Date-time |
| `custom01`, `custom02`, ..., `custom15` | String    |
| `department`                            | String    |
| `division`                              | String    |
| `email`                                 | String    |
| `empId`                                 | String    |
| `firstName`                             | String    |
| `hireDate`                              | Date-time |
| `jobCode`                               | String    |
| `lastModified`                          | Date-time |
| `lastName`                              | String    |
| `manager.displayName`                   | String    |
| `username`                              | String    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.elimity.com/gateways-custom-sap-successfactors/step-by-step-deployment-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.