ICF 1.5.20.25

SAP S/4HANA connector

The SAP S/4HANA connector lets you manage and synchronize accounts between SAP S/4HANA and IDM and Advanced Identity Cloud 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. To connect to HANA DB use the SAP HANA Database connector.

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

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

SAP S/4HANA

No

No

Download the connector .jar file from Backstage.

  • 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.23.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 IDM admin UI:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select SAP S/4HANA Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to SAP S/4HANA Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Test the SAP S/4HANA connector

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.

SAP S/4HANA remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the SAP S/4HANA connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the SAP S/4HANA connector from here.

Refer to Remote connectors for configuring the SAP S/4HANA remote connector.

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 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:

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.
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"
}
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"
}
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"
}
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 ICF interfaces:

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

Yes

Provides the Username to authorize the SAP HANA APIs.

password

GuardedString

null

Yes

Yes

Provides the Password to authorize the SAP HANA APIs.

tenantId

String

null

Yes

Provides the Tenant ID to identify your custom SAP HANA APIs.

pageSize

Integer

1000

No

Page Size for search operation.

httpProxyHost

String

null

No

Provides the HTTP Proxy Host.

httpProxyPort

Integer

null

No

Provides the HTTP Proxy Port.

httpProxyUsername

String

null

No

Provides the HTTP Proxy Username.

httpProxyPassword

GuardedString

null

Yes

No

Provides 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.