SAP S/4HANA Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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.

Note

The SAP S/4HANA connector only supports SAP HANA Cloud. It does not support HANA DB.

Before you start

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

Before you configure the connector, log in to your SAP S/4HANA 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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

Download the connector .jar file from the ForgeRock BackStage download site.

  • 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.12.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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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.12 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 server.

Use the SAP S/4HANA connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

The following SAP S/4HANA account attributes are supported by the SAP S/4HANA connector:

AttributeDescription
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.
PersonIDAuto-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.
LastNameLast name of the user. Required.
MiddleNameMiddle 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).

Note

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:

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 "Accept-API-Version: resource=1.0" \
--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"
}

Note

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.

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

Note

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 "Accept-API-Version: resource=1.0" \
--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"
}

The following example queries all SAP S/4HANA users: 

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--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 "Accept-API-Version: resource=1.0" \
--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"
}
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--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"
}
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--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.

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

PropertyTypeDefault Encrypted [a] Required [b]
userName String null

Provide the Username to authorize the SAP HANA APIs

password GuardedString null

Provide the Password to authorize the SAP HANA APIs

tenantId String null

Provide the Tenant ID to identify your custom SAP HANA APIs

pageSize Integer 1000

Page Size for search operation

httpProxyHost String null

Provide the HTTP Proxy Host

httpProxyPort Integer null

Provide the HTTP Proxy Port

httpProxyUsername String null

Provide the HTTP Proxy Username

httpProxyPassword GuardedString null

Provide the HTTP Proxy Password

[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM.

[b] A list of operations in this column indicates that the property is required for those operations.

Read a different version of :