--- title: SAP S/4HANA connector description: Connectors continue to be released outside the IDM release. For the latest documentation, refer to the OpenICF documentation. component: pingidm version: 7.2 page_id: pingidm:connector-reference:sap-hana canonical_url: https://docs.pingidentity.com/pingidm/7.2/connector-reference/sap-hana.html section_ids: before_you_start: Before you start install_the_sap_s4hana_connector: Install the SAP S/4HANA connector configure_the_sap_s4hana_connector: Configure the SAP S/4HANA connector use_the_sap_s4hana_connector: Use the SAP S/4HANA connector implemented-interfaces-org-forgerock-openicf-connectors-saphana-SapHanaConnector-1.5.20.15: OpenICF Interfaces Implemented by the SAP HANA Connector config-properties-org-forgerock-openicf-connectors-saphana-SapHanaConnector-1.5.20.15: SAP HANA Connector Configuration basic-configuration-properties-org-forgerock-openicf-connectors-saphana-SapHanaConnector-1.5.20.15: Basic configuration properties --- # SAP S/4HANA connector | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Connectors continue to be released outside the IDM release. For the latest documentation, refer to the [OpenICF documentation](https://docs.pingidentity.com/openicf/index.html). | The SAP S/4HANA connector lets you manage and synchronize accounts between SAP S/4HANA and IDM managed user objects. An SAP S/4HANA administrator account is required for this connector to work. | | | | - | ------------------------------------------------------------------------------------ | | | The SAP S/4HANA connector only supports SAP HANA Cloud. It does not support HANA DB. | ## Before you start Before you configure the connector, log in to your AWS administrator account and note the following: * Username Inbound Communication user of SAP S/4HANA. * Password Inbound Communication user password of SAP S/4HANA. * Tenant ID Which tenant the SAP S/4HANA instance is hosted on. ## Install the SAP S/4HANA connector Download the connector .jar file from the [Backstage download site](https://backstage.forgerock.com/downloads). * If you are running the connector locally, place it in the `/path/to/openidm/connectors` directory, for example: ``` mv ~/Downloads/saphana-connector-1.5.20.15.jar /path/to/openidm/connectors/ ``` * If you are using a remote connector server (RCS), place it in the `/path/to/openicf/connectors` directory on the RCS. ## Configure the SAP S/4HANA connector Create a connector configuration using the admin UI: 1. Select Configure > Connectors and click New Connector. 2. Enter a Connector Name. 3. Select SAP HANA Connector - 1.5.20.15 as the Connector Type. 4. Provide the Base Connector Details. 5. Click Save. When your connector is configured correctly, the connector displays as Active in the admin UI. Alternatively, test that the configuration is correct by running the following command: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/system/saphana?_action=test" { "name": "saphana", "enabled": true, "config": "config/provisioner.openicf/saphana", "connectorRef": { "bundleVersion": "[1.5.0.0,1.6.0.0)", "bundleName": "org.forgerock.openicf.connectors.saphana-connector", "connectorName": "org.forgerock.openicf.connectors.saphana.SapHanaConnector" }, "displayName": "SAP HANA Connector", "objectTypes": [ "__ACCOUNT__", "__ALL__" ], "ok": true } ``` If the command returns `"ok": true`, your connector has been configured correctly, and can authenticate to the SAP S/4HANA system. ## Use the SAP S/4HANA connector The following SAP S/4HANA account attributes are supported by the SAP S/4HANA connector: | Attribute | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PersonUUID` | Unique identifier for a user. | | `PersonExternalID` | The external ID of the user. This can only include uppercase letters, numbers, `.`, `-`, and `_`. Required. | | `UserId` | Auto-generated user id. | | `PersonID` | Auto-generated user id. | | `__USER__` | Login username for the user. This can only include uppercase letters, numbers, `.`, `-`, and `_`. Required. | | `FirstName` | First name of the user. Required. | | `LastName` | Last name of the user. Required. | | `MiddleName` | Middle name of the user. | | `LockedIndicator` | Status of the user. Either `active` or `inactive`. | | `GenderCode` | Gender of the user. Permitted values are `1` (Male), or `2` (Female). Required; use `0` to leave it unspecified. If specified, this must match the values listed in `FormOfAddress`. | | `FormOfAddress` | Salutation of the user. Permitted values are `00001` or `1` (Mr), or `00002` or `2` (Mrs). Values must match `GenderCode`. | | `StartDate` | Start date for the created user, in YYYY-MM-DD format. Required. | | `EndDate` | End date for the created user, in YYYY-MM-DD format. | | `PersonFullName` | Full name of the user. | | `AcademicTitle` | Academic title of the user. Permitted values are `0001` (DR.), `0002` (PROF.), `0003` (PROF. DR.), `0004` (B.A.), `0005` (MBA), or `0006` (PH.D.). | | `CorrespondenceLanguage` | The correspondence language for the user. For example, `DE`, or `EN`. | | `AdditionalLastName` | Additional last name of the user. | | `BirthName` | Birth name of the user. | | `NickName` | Nickname of the user. | | `Initials` | Initials of the user. | | `AcademicSecondTitle` | Academic secondary title of the user. Permitted values are `0001` (DR.), `0002` (PROF.), `0003` (PROF. DR.), `0004` (B.A.), `0005` (MBA), or `0006` (PH.D.). | | `NameSupplement` | Supplemental titles of the user. Permitted values are `0001` or `1` (Earl), `0002` or `2` (Freifrau), `0003` or `3` (Freiherr), `0004` or `4` (Fürst), `0005` or `5` (Fürstin), `0006` or `6` (Graf), `0007` or `7` (Gräfin), and `0008` or `8` (Sir). | | `PhoneInformation` | Object with the following sub-attributes:- `PhoneNumberType`: Type of phone number. Permitted values are `ECPC` (Cell phone), or `ECPB` (Landline). - `CountryDialingCode`: Country dialing code, such as `1` (USA) or `33` (France). Numbers only, `+` is not allowed. - `PhoneNumberSubscriberID`: Phone number of the user. | | `EmailAddress` | Email address of the user. | | `CompanyCode` | Predefined code of the company of the user. Required. | | `WorkAgreementStatus` | Status of the work agreement for the user. Permitted values are `0` (Inactive), or `1` (Active). | | `LogonLanguageCode` | [Language code](https://help.sap.com/docs/SAP_IOT_APPLICATION_SERVICES/350cb3262cb8496b9f5e9e8b039b52db/51a1c2ff17ba4c248e929ef70447ad27.html) for the user. | | `DateFormatCode` | What format dates should be displayed in. For example, `6` formats dates according to ISO 8601 (YYYY-MM-DD). Available codes:- `1` - DD.MM.YYYY (Gregorian Date) - `2` - MM/DD/YYYY (Gregorian Date) - `3` - MM-DD-YYYY (Gregorian Date) - `4` - YYYY.MM.DD (Gregorian Date) - `5` - YYYY/MM/DD (Gregorian Date) - `6` - YYYY-MM-DD (Gregorian Date, ISO 8601) - `7` - GYY.MM.DD (Japanese Date) - `8` - GYY/MM/DD (Japanese Date) - `9` - GYY-MM-DD (Japanese Date) - `A` - YYYY/MM/DD (Islamic Date 1) - `B` - YYYY/MM/DD (Islamic Date 2) - `C` - YYYY/MM/DD (Iranian Date) | | `TimeFormatCode` | What format times should be displayed in. For example, `0` formats times in a 24 hour format (14:35:59 PM). Available codes:- `0` - 24 Hour Format (Example: 12:05:10) - `1` - 12 Hour Format (Example: 12:05:10 PM) - `2` - 12 Hour Format (Example: 12:05:10 pm) - `3` - Hours from 0 to 11 (Example: 00:05:10 PM) - `4` - Hours from 0 to 11 (Example: 00:05:10 pm) | | `TimeZoneCode` | Time zone code of the user. | | `DecimalFormatCode` | What decimal notation numbers should be displayed in. Available codes:- `1.234.567,89` - `X` - 1,234,567.89 - `Y` - 1 234 567,89 | | `Role` | Role assignment of the user. | | `PersonWorkAgreementUUID` | Unique ID of the work agreement associated with the user. | | `PersonWorkAgreementExternalID` | External ID of the work agreement associated with the user. | | `PersonWorkAgreementType` | Role of the work agreement associated with the user. Permitted values are `1` (User), or `3` (Service performer). | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The following attributes are mapped in the connector automatically:- `PersonWorkAgreementUUID` is mapped to `PersonExternalID` - `PersonWorkAgreementExternalID` is mapped to `PersonExternalID` - `PersonWorkAgreementType` is assigned to its default value | You can use the SAP S/4HANA connector to perform the following actions on an SAP S/4HANA account: > **Collapse: Create an SAP S/4HANA user** > > The following example creates a user with the minimum required attributes: > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --request POST \ > --data '{ > "__NAME__": "BJENSEN", > "FirstName": "Barbara", > "LastName": "Jensen", > "StartDate": "2022-06-02", > "PersonExternalID": "BJENSEN", > "CompanyCode": 1010, > "GenderCode": 2 > }' \ > "http://localhost:8080/openidm/system/saphana/__ACCOUNT__?_action=create" > { > "_id": "9980004320", > "TimeFormatCode": "0", > "PersonFullName": "Barbara Jensen", > "__UID__": "9980004320", > "FirstName": "Barbara", > "UserID": "CB9980004320", > "__NAME__": "BJENSEN", > "DecimalFormatCode": "X", > "StartDate": "2022-06-02", > "LogonLanguageCode": "EN", > "LastName": "Jensen", > "PersonExternalID": "BJENSEN", > "PersonUUID": "FA163EA9-3617-1EEC-B8DA-AD865EF3B625", > "__ENABLE__": true, > "TimeZoneCode": "CET", > "EndDate": "9999-12-31", > "DateFormatCode": "1" > } > ``` > > | | | > | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | When you create a new user, you must specify *at least*:- `__NAME__` > > - `PersonExternalID` > > - `FirstName` > > - `LastName` > > - `GenderCode` > > - `StartDate` > > - `CompanyCode`See the list of available attributes for more information. | > **Collapse: Update an SAP S/4HANA user** > > You can modify an existing user with a PUT request, including all attributes of the account in the request. The following attributes can be modified on a user: > > * `__USER__` > > * `PersonExternalID` > > * `FirstName` > > * `LastName` > > * `GenderCode` > > * `EmailAddress` > > * `PhoneInformation` > > * `PersonFullName` > > * `AcademicTitle` > > * `CorrespondenceLanguage` > > * `MiddleName` > > * `AdditionalLastName` > > * `BirthName` > > * `NickName` > > * `Initials` > > * `AcademicSecondTitle` > > * `NameSupplement` > > * `WorkAgreementStatus` > > * `CompanyCode` > > * `StartDate` > > * `EndDate` > > * `LockedIndicator` > > * `DateFormatCode` > > * `DecimalFormatCode` > > * `TimeFormatCode` > > * `TimeZoneCode` > > * `LogonLanguageCode` > > * `Role` > > | | | > | - | ------------------------------------------------------------------------------------------ | > | | When updating the validity period for a user, both `StartDate` and `EndDate` are required. | > > For example, to add an email address to a user: > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --header "If-Match:*" \ > --request PUT \ > --data '{ > "__NAME__": "BJENSEN", > "FirstName": "Barbara", > "LastName": "Jensen", > "StartDate": "2022-06-02", > "PersonExternalID": "BJENSEN", > "CompanyCode": 1010, > "GenderCode": 2, > "EmailAddress": "bjensen@example.com" > }' \ > "http://localhost:8080/openidm/system/saphana/__ACCOUNT__/9980004320" > { > "_id": "9980004320", > "TimeFormatCode": "0", > "PersonFullName": "Barbara Jensen", > "__UID__": "9980004320", > "EmailAddress": "bjensen@example.com", > "FirstName": "Barbara", > "UserID": "CB9980004320", > "__NAME__": "BJENSEN", > "DecimalFormatCode": "X", > "StartDate": "2022-06-02", > "LogonLanguageCode": "EN", > "LastName": "Jensen", > "PersonExternalID": "BJENSEN", > "PersonUUID": "FA163EA9-3617-1EEC-B8DA-AD865EF3B625", > "__ENABLE__": true, > "TimeZoneCode": "CET", > "EndDate": "9999-12-31", > "DateFormatCode": "1" > } > ``` > **Collapse: Query SAP S/4HANA users** > > The following example queries all SAP S/4HANA users: > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --request GET \ > "http://localhost:8080/openidm/system/saphana/__ACCOUNT__?_queryId=query-all-ids" > { > "result": [ > { > "_id": "9980000000" > }, > { > "_id": "9980000002" > }, > { > "_id": "9980000004" > }, > { > "_id": "9980000006" > }, > [ ... ] > { > "_id": "9980004314" > }, > { > "_id": "9980004316" > }, > { > "_id": "9980004318" > }, > { > "_id": "9980004320" > } > ], > "resultCount": 2139, > "pagedResultsCookie": null, > "totalPagedResultsPolicy": "NONE", > "totalPagedResults": -1, > "remainingPagedResults": -1 > } > ``` > > The following command queries a specific user by their ID: > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --request GET \ > "http://localhost:8080/openidm/system/saphana/__ACCOUNT__/9980004320" > { > "_id": "9980004320", > "TimeFormatCode": "0", > "PersonFullName": "Barbara Jensen", > "__UID__": "9980004320", > "EmailAddress": "bjensen@example.com", > "FirstName": "Barbara", > "UserID": "CB9980004320", > "__NAME__": "BJENSEN", > "DecimalFormatCode": "X", > "StartDate": "2022-06-02", > "LogonLanguageCode": "EN", > "LastName": "Jensen", > "PersonExternalID": "BJENSEN", > "PersonUUID": "FA163EA9-3617-1EEC-B8DA-AD865EF3B625", > "__ENABLE__": true, > "TimeZoneCode": "CET", > "EndDate": "9999-12-31", > "DateFormatCode": "1" > } > ``` > **Collapse: Enable an SAP S/4HANA user** > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --header "If-Match:*" \ > --request PUT \ > --data '{ > "__NAME__": "BJENSEN", > "__ENABLE__": true > }' \ > "http://localhost:8080/openidm/system/saphana/__ACCOUNT__/9980004320" > { > "_id": "9980004320", > "TimeFormatCode": "0", > "PersonFullName": "Barbara Jensen", > "__UID__": "9980004320", > "EmailAddress": "bjensen@example.com", > "FirstName": "Barbara", > "UserID": "CB9980004320", > "__NAME__": "BJENSEN", > "DecimalFormatCode": "X", > "StartDate": "2022-06-02", > "LogonLanguageCode": "EN", > "LastName": "Jensen", > "PersonExternalID": "BJENSEN", > "PersonUUID": "FA163EA9-3617-1EEC-B8DA-AD865EF3B625", > "__ENABLE__": true, > "TimeZoneCode": "CET", > "EndDate": "9999-12-31", > "DateFormatCode": "1" > } > ``` > **Collapse: Disable an SAP S/4HANA user** > > ``` > curl \ > --header "X-OpenIDM-Username: openidm-admin" \ > --header "X-OpenIDM-Password: openidm-admin" \ > --header "Content-Type: application/json" \ > --header "If-Match:*" \ > --request PUT \ > --data '{ > "__NAME__": "BJENSEN", > "__ENABLE__": false > }' \ > "http://localhost:8080/openidm/system/saphana/__ACCOUNT__/9980004320" > { > "_id": "9980004320", > "TimeFormatCode": "0", > "PersonFullName": "Barbara Jensen", > "__UID__": "9980004320", > "EmailAddress": "bjensen@example.com", > "FirstName": "Barbara", > "UserID": "CB9980004320", > "__NAME__": "BJENSEN", > "DecimalFormatCode": "X", > "StartDate": "2022-06-02", > "LogonLanguageCode": "EN", > "LastName": "Jensen", > "PersonExternalID": "BJENSEN", > "PersonUUID": "FA163EA9-3617-1EEC-B8DA-AD865EF3B625", > "__ENABLE__": false, > "TimeZoneCode": "CET", > "EndDate": "9999-12-31", > "DateFormatCode": "1" > } > ``` ## OpenICF Interfaces Implemented by the SAP HANA Connector The SAP HANA Connector implements the following OpenICF interfaces. For additional details, see [OpenICF interfaces](interfaces.html): * Create Creates an object and its `uid`. * Schema Describes the object types, operations, and options that the connector supports. * Script on Connector Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics: * The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access. * The script has access to a `connector` variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. * The script has access to any script arguments passed in by the application. * Search Searches the target resource for all objects that match the specified object class and filter. * Test Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid. This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out). You can invoke the test operation before a connector configuration has been validated. * Update Updates (modifies or replaces) objects on a target resource. ## SAP HANA Connector Configuration The SAP HANA Connector has the following configurable properties: ### Basic configuration properties | Property | Type | Default | Encrypted(1) | Required(2) | | ----------------------------------------------------------- | --------------- | ------- | ------------------------ | ------------------------- | | `userName` | `String` | `null` | | [icon: check, set=fas]Yes | | Provide the Username to authorize the SAP HANA APIs | | | | | | `password` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]Yes | | Provide the Password to authorize the SAP HANA APIs | | | | | | `tenantId` | `String` | `null` | | [icon: check, set=fas]Yes | | Provide the Tenant ID to identify your custom SAP HANA APIs | | | | | | `pageSize` | `Integer` | `1000` | | [icon: times, set=fas]No | | Page Size for search operation | | | | | | `httpProxyHost` | `String` | `null` | | [icon: times, set=fas]No | | Provide the HTTP Proxy Host | | | | | | `httpProxyPort` | `Integer` | `null` | | [icon: times, set=fas]No | | Provide the HTTP Proxy Port | | | | | | `httpProxyUsername` | `String` | `null` | | [icon: times, set=fas]No | | Provide the HTTP Proxy Username | | | | | | `httpProxyPassword` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: times, set=fas]No | | Provide the HTTP Proxy Password | | | | | (1) Whether the property value is considered confidential, and is therefore encrypted in IDM. (2) A list of operations in this column indicates that the property is required for those operations.