SAP connector

The SAP connector is an implementation of the Scripted Groovy connector toolkit that connects to any SAP system using the SAP JCo Java libraries. This topic describes how to install and configure the scripted SAP connector and how to test the sample scripts bundled with the connector.

You can configure the SAP connector to work with either SAP HR or SAP ERP systems.

The sample scripts illustrate the following scenarios:

Synchronization of users between an SAP HR module and IDM
Synchronization of users between IDM and an SAP (R/3) system

Install the SAP 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	No	Yes

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/sap-connector-1.5.20.26.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.

Download the connector dependencies.

The SAP connector requires the SAP Java Connector (JCo) libraries, version 3.0.12 or later. Ping distributes the SAP connector without these JCo libraries. Before you can use the SAP connector, you must obtain the JCo libraries that correspond to your architecture.

Copy the required SAP JCo libraries to the /path/to/openidm/lib directory. For example:
```
cp sapjco3.jar /path/to/openidm/lib
cp libsapjco3.so /path/to/openidm/lib
```

Change your IDM logging configuration to log messages from the SAP connector. By default, IDM logs nothing for the SAP connector. To troubleshoot any issues with the connector, set the following properties in your project’s conf/logging.properties file:

# SAP Connector Logging
org.forgerock.openicf.connectors.sap.level=FINER
scripts.sap.r3.level=FINER
scripts.sap.hr.level=FINER
scripts.sap.level=FINER

Using the SAP connector with an SAP HR system

The SAP HR sample scripts let you manage the email address and global employee UID of records in an SAP HR system.

The following sections explain how to configure IDM to use these sample scripts, how to test the connection to the SAP HR system, and how to update user records.

Setting up IDM for the SAP HR samples

Create a connector configuration file for the SAP connector and place it in your project’s conf/ directory.

Edit that file with the connection details for your SAP HR system. Specifically, set at least the following properties:
destination

An alias to the SAP system to which you are connecting, for example, SAP1. If you are connecting to more than one SAP system, the destination property for each system must be unique.

The sample connector configuration assumes a connection to a single SAP system, so the value for this property in the sample configuration is OPENIDM.

asHost

The FQDN of your SAP Application Server, for example sap.example.com.

user

Your SAP user account.

password

The password of this SAP user account.

client

The SAP Client number that will be used to connect to the SAP system.

systemNumber

The SAP system number.

directConnection

A boolean (true/false). If true, the connection goes directly to an SAP ABAP Application server or SAP router. If false, the connection goes to a group of SAP instances through an SAP message server.

sapRouter
The IP address, port, and optional password of the SAP router, if applicable. The syntax is /H/host/S/port/W/optionalPassword. For example:
/H/203.0.113.0/S/3299/W/48npb_hg815.77rr62.hdj
poolCapacity

The maximum number of idle connections kept open by the destination. If there is no connection pooling, set this to 0. The default value is 1.

For optimum performance, set this value to an integer between 5 and 10.

The connector bundles a number of sample Groovy scripts:

TestSAP.groovy
SearchSAPHR.groovy
UpdateSAPHR.groovy
SchemaSAPHR.groovy

EmplComm.groovy

If necessary, you can customize these scripts to suit your deployment by extracting them from the connector JAR and updating the connector configuration to point to the new file path.

The sample connector configuration assumes the following locations for the scripts (relative to the value of the scriptRoots property):

"testScriptFileName" : "TestSAP.groovy",
"searchScriptFileName" : "hr/SearchSAPHR.groovy",
"updateScriptFileName" : "hr/UpdateSAPHR.groovy",
"schemaScriptFileName" : "hr/SchemaSAPHR.groovy",

You must place the EmplComm.groovy in the same location as the Search, Update, and Schema scripts.

The Groovy scripts belong to a specific package. The parent directory where the scripts are located must be the same as the package name. So the TestSAP.groovy script must be under a scripts/sap directory (because it belongs to the scripts/sap package) and the remaining HR scripts must be under a scripts/sap/hr directory (because they belong to the hr package).

Testing the connection to the SAP HR system

Start IDM with the configuration for your SAP connector project.

This procedure assumes that the configuration is in the default path/to/openidm directory. If your SAP project is in a different directory, use the -p option with the startup command to point to that directory:
```
path/to/openidm/startup.sh
```

Test that the connector has been configured correctly and that the SAP HR system can be reached:

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/saphr/?_action=test"
{
  "name" : "saphr",
  "enabled" : true,
  "config" : "config/provisioner.openicf/saphr2",
  "objectTypes" : [ "__ALL__", "employee" ],
  "connectorRef" : {
    "connectorName" : "org.forgerock.openicf.connectors.sap.SapConnector",
    "bundleName" : "org.forgerock.openicf.connectors.sap-connector",
    "bundleVersion" : "[1.5.0.0,1.6.0.0)"
  },
  "displayName" : "Sap Connector",
  "ok" : true
}

Retrieve a list of the existing users (with their employee number) in the SAP HR system:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/saphr/employee?_queryId=query-all-ids"
{
  "result" : [
    {
      "_id" : "00000010",
      "__NAME__" : "00000010"
    },
    {
      "_id" : "00000069",
      "__NAME__" : "00000069"
    },
    {
      "_id" : "00000070",
      "__NAME__" : "00000070"
    },
    ...
  ]
}

Retrieve the complete record of an employee in the SAP HR system by including the employee’s ID in the URL.

The following command retrieves the record for employee Maria Gonzales:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/saphr/employee/55099307"
{
  "_id" : "55099307",
  "PERSONAL_DATA" : {
    "PERNO" : "55099307",
    "INFOTYPE" : "0002",
    "TO_DATE" : "Fri Dec 31 00:00:00 CET 9999",
    "FROM_DATE" : "Tue Mar 30 00:00:00 CET 1954",
    "SEQNO" : "000",
    "CH_ON" : "Thu Mar 27 00:00:00 CET 2003",
    "CHANGED_BY" : "MAYROCK",
    "LAST_NAME" : "Gonzales",
    "FIRSTNAME" : "Maria",
    "NAME_FORM" : "00",
    "FORMOFADR" : "2",
    "GENDER" : "2",
    "BIRTHDATE" : "Tue Mar 30 00:00:00 CET 1954",
    "LANGU" : "D",
    "NO_O_CHLDR" : "0",
    "BIRTHYEAR" : "1954",
    "BIRTHMONTH" : "03",
    "BIRTHDAY" : "30",
    "LASTNAME_M" : "GONZALES",
    "FSTNAME_M" : "MARIA"
  },
  ...
}

Using the SAP connector to manage employee information (SAP HR)

The following sample commands show how you can use the SAP connector to manage the email account of user Maria Gonzales, retrieved in the previous step. Management of the global UID (SYS-UNAME) works in the same way.

Check if Maria Gonzales already has an email account on the SAP HR system by filtering a query on her user account for the EMAIL field:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/saphr/employee/55099307?_fields=EMAIL"
{
  "_id" : "55099307",
}

No email account is found for Maria Gonzales.

Add an email account by sending a PUT request. The JSON payload should include the email address as the value of the ID property:

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 PUT \
--data '{
  "EMAIL": { "ID": "maria.gonzales@example.com" }
}' \
"http://localhost:8080/openidm/system/saphr/employee/55099307"
{
  "_id" : "55099307",
  "EMAIL" : [ {
    "EMPLOYEENO" : "55099307",
    "SUBTYPE" : "0010",
    "VALIDEND" : "Fri Dec 31 00:00:00 CET 9999",
    "VALIDBEGIN" : "Fri March 18 00:00:00 CET 2016",
    "RECORDNR" : "000",
    "COMMTYPE" : "0010",
    "NAMEOFCOMMTYPE" : "E-mail",
    "ID" : "Maria.Gonzales@example.com"
  } ],
  ...
}

By default, the connector sets the VALIDBEGIN date to the current date, and the VALIDEND date to the SAP "END" date (12/31/9999). You can specify different temporal constraints by including these properties in the JSON payload, with the format YYYYMMDD. For example:

{
  "EMAIL": {
    "ID": "maria.gonzales@example.com"
    "VALIDBEGIN": "20160401",
    "VALIDEND": "20161231"
  }
}

To change the value of an existing email account, provide a new value for the ID.

The JSON payload of the change request must also include the RECORDNR attribute, as well as the VALIDBEGIN and VALIDEND dates, in SAP format (YYYYMMDD).

The following example changes Maria Gonzales' email address to maria.gonzales-admin@example.com:

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 PUT \
--data '{
  "EMAIL": {
    "ID": "maria.gonzales-admin@example.com",
    "RECORDNR" : "000",
    "VALIDEND" : "99991231",
    "VALIDBEGIN" : "20000101"
  }
}' \
"http://localhost:8080/openidm/system/saphr/employee/55099307"

To change the temporal constraint (VALIDEND date) of the record, include the existing VALIDEND data in the JSON payload, and specify the new end date as a value of the DELIMIT_DATE attribute.

The following example changes the end date of Maria Gonzales' new mail address to December 31st, 2016:

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 PUT \
--data '{
  "EMAIL": {
    "ID": "maria.gonzales-admin@example.com",
    "RECORDNR" : "000",
    "VALIDEND" : "99991231",
    "VALIDBEGIN" : "20000101",
    "DELIMIT_DATE": "20161231"
  }
}' \
"http://localhost:8080/openidm/system/saphr/employee/55099307"

To delete the email address of the record, send a PUT request with the current RECORDNR, VALIDBEGIN, and VALIDEND attributes, but without the ID.

The following request removes the email address from Maria Gonzales' record:

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 PUT \
--data '{
  "EMAIL": {
    "RECORDNR" : "000",
    "VALIDEND" : "99991231",
    "VALIDBEGIN" : "20000101"
  }
}' \
"http://localhost:8080/openidm/system/saphr/employee/55099307"

Using the SAP connector to manage SAP Basis System (R/3) users

The SAP connector enables you to perform the following operations on SAP system user accounts:

List all users
List all activity groups (roles)
List all user profiles
List all user companies
List all user groups
Obtain a user’s details
Create a user
Update a user
Assign roles to a user
Lock a user account
Unlock a user account
Delete a user account

Setting up IDM for the SAP R/3 samples

Create a connector configuration file for the SAP connector and place it in your project’s conf/ directory.

Edit that file with the connection details for your SAP R/3 system. Specifically, set at least the following properties:
destination

An alias to the SAP system to which you are connecting, for example, SAP1. If you are connecting to more than one SAP system, the destination property for each system must be unique.

The sample connector configuration assumes a connection to a single SAP system, MYSAP.

asHost

The FQDN of your SAP Application Server, for example sap.example.com.

user

Your SAP user account.

password

The password of this SAP user account.

client

The SAP Client number that will be used to connect to the SAP system.

systemNumber

The SAP system number.

directConnection

A boolean (true/false). If true, the connection goes directly to an SAP ABAP Application server or SAP router. If false, the connection goes to a group of SAP instances through an SAP message server.

sapRouter
The IP address and port of the SAP router, if applicable. The syntax is /H/host/S/port/W/optionalPassword. For example:
/H/203.0.113.0/S/3299/W/48npb_hg815.77rr62.hdj
poolCapacity

The maximum number of idle connections kept open by the destination. If there is no connection pooling, set this to 0. The default value is 1.

For optimum performance, set this value to an integer between 5 and 10.

The connector bundles a number of sample Groovy scripts:

TestSAP.groovy
SearchSAPR3.groovy
CreateSAPR3.groovy
UpdateSAPR3.groovy
DeleteSAPR3.groovy
SyncSAPR3.groovy
SchemaSAPR3.groovy
ListR3Objects.groovy
R3User.groovy
R3UserActivityGroup.groovy
R3UserAddress.groovy
R3UserGroup.groovy
R3UserLogonData.groovy
R3UserProfile.groovy
R3Config.groovy
ListTablesR3Objects.groovy

QueryTable.groovy

If necessary, you can customize these scripts to suit your deployment by extracting them from the connector JAR and updating the connector configuration to point to the new file path.

The sample connector configuration assumes the following locations for the scripts (relative to the value of the scriptRoots property):

"testScriptFileName" : "TestSAP.groovy",
"searchScriptFileName" : "r3/SearchSAPR3.groovy",
"createScriptFileName" : "r3/CreateSAPR3.groovy",
"updateScriptFileName" : "r3/UpdateSAPR3.groovy",
"deleteScriptFileName" : "r3/DeleteSAPR3.groovy",
"syncScriptFileName" : "r3/SyncSAPR3.groovy",
"schemaScriptFileName" : "r3/SchemaSAPR3.groovy",

The Groovy scripts belong to a specific package. The parent directory where the scripts are located must be the same as the package name. So the TestSAP.groovy script must be under a scripts/sap directory (because it belongs to the scripts/sap package) and the R/3 scripts must be under a scripts/sap/r3 directory (because they belong to the r3 package).

Testing the connection to the SAP R/3 system

Start IDM with the configuration for your SAP R/3 project.

This procedure assumes that the configuration is in the default path/to/openidm directory. If your SAP project is in a different directory, use the -p option with the startup command to point to that directory:
```
/path/to/openidm/startup.sh
```

Test that the connector has been configured correctly and that the SAP R/3 system can be reached:

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/mysap/?_action=test"
{
  "name": "mysap",
  "enabled": true,
  "config": "config/provisioner.openicf/mysap",
  "objectTypes": [
    "__ALL__",
    "user",
    "activity_group",
    "company",
    "profile",
    "group"
  ],
  "connectorRef": {
    "connectorName": "org.forgerock.openicf.connectors.sap.SapConnector",
    "bundleName": "org.forgerock.openicf.connectors.sap-connector",
    "bundleVersion": "[1.5.0.0,1.6.0.0)"
  },
  "displayName": "Sap Connector",
  "ok": true
}

Using the SAP connector to manage SAP R/3 users

This section provides sample commands for managing users in an SAP system.

Listing the users in the SAP system

The following command returns a list of the existing users in the SAP system, with their IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/mysap/user?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "BJENSEN",
      "__NAME__": "BJENSEN"
    },
    {
      "_id": "DDIC",
      "__NAME__": "DDIC"
    },
    ...
    {
      "_id": "USER4",
      "__NAME__": "USER4"
    },
    {
      "_id": "USER6",
      "__NAME__": "USER6"
    },
    {
      "_id": "USER7",
      "__NAME__": "USER7"
    }
  ],
  "resultCount": 9,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Obtaining the details of an SAP user

The following command uses the SAP connector to obtain a user’s details from a target SAP system:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/mysap/user/BJENSEN"
{
  "__NAME__": "BJENSEN",
  "__ENABLE__": true,
  "__ENABLE_DATE__": "2015-09-01",
  "__DISABLE_DATE__": "2016-09-01",
  "__LOCK_OUT__": false,
  "ADDTEL": [
    {
      "COUNTRY": "DE",
      "TELEPHONE": "19851444",
      ...
    },
    ...
  ],
  "PROFILES": [
    "T_ALM_CONF",
    ...
  ],
  "ISLOCKED": {
    "WRNG_LOGON": "U",
    ...
  },
  "ACTIVITYGROUPS": [
    {
      "AGR_NAME": "MW_ADMIN",
      "FROM_DAT": "2015-07-15",
      "TO_DAT": "9999-12-31"
    },
    ...
  ],
  "DEFAULTS": {
    ...
  },
  "COMPANY": {
    "COMPANY": "SAP AG"
  },
  "ADDRESS": {
    ...
  },
  "UCLASS": {
    ...
  },
  "LASTMODIFIED": {
    "MODDATE": "2015-07-15",
    "MODTIME": "14:22:57"
  },
  "LOGONDATA": {
    "GLTGV": "2015-09-01",
    "GLTGB": "2016-09-01",
    ...
  },
  "GROUPS": {
    "USERGROUP": "SUPER"
    ...
  },
  "_id": "BJENSEN"
}

When using Central User Administration (CUA), the system also returns the SUBSYSTEMS attribute. Additionally, PROFILES and ACTIVITYGROUPS have a different definition:

"SYSTEMS": [
  "TE9CLNT200",
  "TE9CLNT300",
  \...
],
"PROFILES": [
  {
    "BAPIPROF": "T_ALM_CONF",
    "SUBSYSTEM: "TE9CLNT200"
  },
  {
    "BAPIPROF": "T_ALM_CONF",
    "SUBSYSTEM: "TE9CLNT300"
  },
  \...
],
"ACTIVITYGROUPS": [
  {
    "AGR_NAME": "MW_ADMIN",
    "FROM_DAT": "2015-07-15",
    "TO_DAT": "9999-12-31",
    "SUBSYSTEM": "TE9CLNT200"
  },
  {
    "AGR_NAME": "MW_ADMIN",
    "FROM_DAT": "2015-07-15",
    "TO_DAT": "9999-12-31",
    "SUBSYSTEM": "TE9CLNT300"
  },
  \...
]
...

In addition to the standard user attributes, the GET request returns the following ICF operational attributes:

__ENABLE__ - indicates whether the account is enabled, based on the value of the LOGONDATA attribute
__ENABLE_DATE__ - set to the value of LOGONDATA/GLTGV (date from which the user account is valid)
__DISABLE_DATE__ - set to the value of LOGONDATA/GLTGB (date to which the user account is valid)
__LOCK_OUT__ - indicates whether the account is locked

Creating SAP user accounts

To create a user, you must supply at least a username and password. If you do not provide a lastname, the connector uses the value of the username.

The following command creates a new SAP user, SCARTER:

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 POST \
--data '{
  "__NAME__" : "SCARTER",
  "__PASSWORD__": "Passw0rd"
}' \
"http://localhost:8080/openidm/system/mysap/user/?_action=create"
{
  "_id": "SCARTER",
  "COMPANY": {
    "COMPANY": "SAP AG"
  },
  "__LOCK_OUT__": false,
  "ADDRESS": {
    ...
  },
  "__NAME__": "SCARTER",
  "LASTMODIFIED": {
    "MODDATE": "2016-04-20",
    "MODTIME": "04:14:29"
  },
  "UCLASS": {
    "COUNTRY_SURCHARGE": "0",
    "SUBSTITUTE_FROM": "0000-00-00",
    "SUBSTITUTE_UNTIL": "0000-00-00"
  },
  "__ENABLE__": true,
  "DEFAULTS": {
    "SPDB": "H",
    "SPDA": "K",
    "DATFM": "1",
    "TIMEFM": "0"
  },
  "LOGONDATA": {
    ...
  },
  "ISLOCKED": {
    "WRNG_LOGON": "U",
    "LOCAL_LOCK": "U",
    "GLOB_LOCK": "U",
    "NO_USER_PW": "U"
  }
}

The SAP account that is created is valid and enabled, but the password is expired by default. To log in to the SAP system, the newly created user must first provide a new password.

To create a user with a valid (non-expired) password, include the __PASSWORD_EXPIRED__ attribute in the JSON payload with a value of false. For example:

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 POST \
--data '{
  "__NAME__" : "SCARTER",
  "__PASSWORD__": "Passw0rd",
  "__PASSWORD_EXPIRED__": false
}' \
"http://localhost:8080/openidm/system/mysap/user/?_action=create"

To create an account that is locked by default, include the __LOCK_OUT__ attribute in the JSON payload with a value of true. For example:

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 POST \
--data '{
  "__NAME__" : "SCARTER",
  "__PASSWORD__": "Passw0rd",
  "__LOCK_OUT__": true
}' \
"http://localhost:8080/openidm/system/mysap/user/?_action=create"
{
  "__NAME__": "SCARTER",
  "__ENABLE__": false,
  "__LOCK_OUT__": true,
  "LOGONDATA": {
    "GLTGV": "0000-00-00",
    "GLTGB": "0000-00-00",
    "USTYP": "A",
    "LTIME": "00:00:00"
  },
  "LASTMODIFIED": {
    "MODDATE": "2015-10-01",
    "MODTIME": "15:25:18"
  },
  "ISLOCKED": {
    "WRNG_LOGON": "U",
    "LOCAL_LOCK": "L",     (1)
    "GLOB_LOCK": "U",     (2)
    "NO_USER_PW": "U"
  },
  ...
}

1	"L" indicates that the user is locked on the local system.
2	On CUA Systems "GLOB_LOCK" will be marked as locked instead of "LOCAL_LOCK".

Schema used by the SAP connector for user accounts

For the most part, the SAP connector uses the standard SAP schema to create a user account. The most common attributes in an SAP user account are as follows:

ADDRESS - user address data
LOGONDATA - user logon data
DEFAULTS - user account defaults
COMPANY - the company to which the user is assigned
REF_USER - the usernames of the Reference User
ALIAS - an alias for the username
UCLASS - license-related user classification
LASTMODIFIED - read-only attribute that indicates the date and time that the account was last changed
ISLOCKED - read-only attribute that indicates the lockout status of the account
IDENTITY - assignment of a personal identity to the user account
PROFILES - any profiles assigned to the user account (see Managing user profiles).
ACTIVITYGROUPS - activity groups assigned to the user (Roles)
ADDTEL - telephone numbers assigned to the user
GROUPS - groups assigned to the user
SYSTEMS - subsystems assigned to the user (Only on CUA systems)

In addition, the SAP connector supports the following ICF operational attributes for CREATE requests:

LOCK_OUT
PASSWORD
PASSWORD_EXPIRED

The following example creates a user, KVAUGHAN, with all the standard attributes:

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 POST \
--data '{
  "__NAME__" : "KVAUGHAN",
  "__PASSWORD__": "Passw0rd",
  "__PASSWORD_EXPIRED__": false,
  "LOGONDATA": {
    "GLTGV": "2016-04-01",
    "GLTGB": "2016-12-01",
    "USTYP": "A"
  },
  "ADDRESS": {
    "FIRSTNAME": "Katie",
    "LASTNAME": "Vaughan",
    "TEL1_NUMBR": "33297603177",
    "E_MAIL": "katie.vaughan@example.com",
    "FUNCTION": "Test User"
  },
  "COMPANY": {
    "COMPANY": "EXAMPLE.COM"
  },
  "ALIAS": {
    "USERALIAS": "KVAUGHAN"
  }
}' \
"http://localhost:8080/openidm/system/mysap/user/?_action=create"
{
  "_id": "KVAUGHAN",
  "ADDRESS": {
    "PERS_NO": "0000010923",
    "ADDR_NO": "0000010765",
    "FIRSTNAME": "Katie",
    "LASTNAME": "Vaughan",
    "FULLNAME": "Katie Vaughan",
    ...
    "E_MAIL": "katie.vaughan@example.com",
    "LANGU_CR_P": "E",
    "LANGUCPISO": "EN"
  },
  "LOGONDATA": {
    "GLTGV": "2016-04-01",
    "GLTGB": "2016-12-01",
    ...
  },
  "COMPANY": {
    "COMPANY": "SAP AG"
  },
  "__ENABLE__": true,
  "ADDTEL": [
    {
      ...
    }
  ],
  "ISLOCKED": {
    "WRNG_LOGON": "U",
    "LOCAL_LOCK": "U",
    "GLOB_LOCK": "U",
    "NO_USER_PW": "U"
  },
  "UCLASS": {
    "COUNTRY_SURCHARGE": "0",
    "SUBSTITUTE_FROM": "0000-00-00",
    "SUBSTITUTE_UNTIL": "0000-00-00"
  },
  "ALIAS": {
    "USERALIAS": "KVAUGHAN"
  },
  "__NAME__": "KVAUGHAN",
  "__LOCK_OUT__": false,
  "LASTMODIFIED": {
    "MODDATE": "2016-04-20",
    "MODTIME": "04:55:08"
  },
  "__ENABLE_DATE__": "2016-04-01",      (1)
  "DEFAULTS": {
    "SPDB": "H",
    "SPDA": "K",
    "DATFM": "1",
    "TIMEFM": "0"
  },
  "__DISABLE_DATE__": "2016-12-01"     (2)
}

1	Value of LOGONDATA/GLTGV.
2	Value of LOGONDATA/GLTGB.

Updating SAP user accounts

The following sections provide sample commands for updating an existing user account.

Locking and unlocking an account

To lock or unlock a user’s account, send a PUT request, and set the value of the user’s __LOCK_OUT__ attribute to true or false.

The following example locks user KVAUGHAN’s account:

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 '{
  "__LOCK_OUT__": true
}' \
"http://localhost:8080/openidm/system/mysap/user/KVAUGHAN"

The following example unlocks KVAUGHAN’s account:

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 '{
  "__LOCK_OUT__": false
}' \
"http://localhost:8080/openidm/system/mysap/user/KVAUGHAN"

Updating the standard attributes of a user’s account

To update a user’s standard attributes, send a PUT request to the user ID. The JSON payload must respect the structure for each attribute, as indicated in Schema used by the SAP connector for user accounts.

The following command updates the ADDRESS attribute of user KVAUGHAN:

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 '{
  "ADDRESS": {
    "FIRSTNAME": "Katie",
    "LASTNAME": "Vaughan",
    "FULLNAME": "Katie Vaughan",
    "FUNCTION": "Administrator",
    "TITLE": "Company",
    "NAME": "EXAMPLE.COM",
    "CITY": "San Francisco",
    "POSTL_COD1": "94105",
    "STREET": "Sacramento St",
    "HOUSE_NO": "2912",
    "COUNTRY": "US",
    "COUNTRYISO": "US",
    "LANGU": "E",
    "LANGU_ISO": "EN",
    "REGION": "CA",
    "TIME_ZONE": "PST",
    "TEL1_NUMBR": "33297603177",
    "E_MAIL": "katie.vaughan@example.com",
    "LANGU_CR_P": "E",
    "LANGUCPISO": "EN"
  }
}' \
"http://localhost:8080/openidm/system/mysap/user/KVAUGHAN"

Resetting a user’s password

To reset the user’s password, provide the new password as the value of the __PASSWORD__ attribute in a PUT request. The following command resets KVAUGHAN’s password to MyPassw0rd:

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 '{
  "__PASSWORD__": "MyPassw0rd"
}' \
"http://localhost:8080/openidm/system/mysap/user/KVAUGHAN"

Note that unless you set the __PASSWORD_EXPIRED__ attribute to false, the user will be required to reset her password the next time she logs into the SAP system.

The following command resets KVAUGHAN’s password to MyPassw0rd, and ensures that she does not have to reset her password the next time she logs in:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request PUT \
--data '{
  "__PASSWORD__": "MyPassw0rd",
  "__PASSWORD_EXPIRED__": false
}'
"http://localhost:8080/openidm/system/mysap/user/KVAUGHAN"

Deleting user accounts

To delete a user account, send a DELETE request to the user ID. The following example deletes KVAUGHAN:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/system/mysap/user/KVAUGHAN"

The command returns the complete user object that was deleted.

Get the latest changes with LiveSync

The following example updates the user’s data since the last synchronization:

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?_action=liveSync&source=system/mysap/__ACCOUNT__"
{
  "connectorData": {
    "nativeType": "string",
    "syncToken": "20230707160932"
  },
  "_rev": "b69ca221-6610-484a-983f-142e8544e519-101",
  "_id": "SYSTEMMYSAP+ACCOUNT+"
}

Managing user profiles

An SAP system uses profiles to manage authorization. The following examples demonstrate how to add, change, and remove a user’s profiles.

Creating a user with one or more profiles

Profiles are added as an array of one or more strings.

The following command creates a user BJENSEN with the system administrator profile (S_A.SYSTEM):

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 POST \
--data '{
  "__NAME__" : "BJENSEN",
  "__PASSWORD__": "Passw0rd",
  "__PASSWORD_EXPIRED__": false,
  "PROFILES": [
    "S_A.SYSTEM"
  ]
}' \
"http://localhost:8080/openidm/system/mysap/user/?_action=create"
{
  "_id": "BJENSEN",
  "PROFILES": [
    "S_A.SYSTEM"
  ],
  ...
  "__NAME__": "BJENSEN"
}

Note that the additional information regarding that profile is added to the user account automatically.

Updating a user’s profiles

To update a user’s profiles, send a PUT request to the user’s ID, specifying the new profiles as an array of values for the PROFILES attribute. The values provided in the PUT request will replace the current profiles, so you must include the existing profiles in the request.

The following example adds the SAP_ALL profile to user BJENSEN’s account:

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 '{
  "PROFILES": [
    "S_A.SYSTEM",
    "SAP_ALL"
  ]
}' \
"http://localhost:8080/openidm/system/mysap/user/BJENSEN"
{
  "_id": "BJENSEN",
  "PROFILES": [
    "SAP_ALL",
    "S_A.SYSTEM"
  ],
  ...
  "__NAME__": "BJENSEN"
}

Removing all profiles from a user account

To remove all profiles from a user’s account, update the account with an empty array. The following example removes all profiles from BJENSEN’s account:

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 '{
  "PROFILES": []
}' \
"http://localhost:8080/openidm/system/mysap/user/BJENSEN"
{
  "_id": "BJENSEN",
  ...
  "__NAME__": "BJENSEN"
}

The output shows no PROFILES attribute, as this attribute is now empty for this user.

When using CUA systems, each PROFILE has to be specified with a SUBSYSTEM like the next example:

"PROFILES": [
  {
    "BAPIPROF": "SAP_ALL",
    "SUBSYSTEM: "TE9CLNT200"
  },
  {
    "BAPIPROF": "S_A.SYSTEM",
    "SUBSYSTEM: "TE9CLNT200"
  },
],
...

Managing user roles

SAP user roles (or activity groups) are an alternative mechanism to grant authorization to an SAP system. Essentially, a role encapsulates a set of one or more profiles.

Roles can be granted with temporal constraints, that is, a period during which the role is valid. If no temporal constraints are specified, the SAP connector sets the FROM date to the current date and the TO date to 9999-12-31.

Creating a user with one or more profiles

Roles are added as an array of one or more objects.

The following command creates a user SCARTER, with two roles: SAP_AUDITOR_SA_CCM_USR and SAP_ALM_ADMINISTRATOR. The auditor role includes a temporal constraint, which is only valid from May 1st, 2016 to April 30th, 2017. The format of the temporal constraint is YYYY-mm-dd:

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 POST \
--data '{
  "__NAME__" : "SCARTER",
  "__PASSWORD__": "Passw0rd",
  "__PASSWORD_EXPIRED__": false,
  "ACTIVITYGROUPS": [
    {
      "AGR_NAME": "SAP_AUDITOR_SA_CCM_USR",
      "FROM_DAT": "2016-05-01",
      "TO_DAT": "2017-04-30"
    },
    {
      "AGR_NAME": "SAP_ALM_ADMINISTRATOR"
    }
  ]
}' \
"http://localhost:8080/openidm/system/mysap/user/?_action=create"
{
  "_id": "SCARTER",
  "PROFILES": [
    "T_ALM_CONF"
  ],
  ...
  "ACTIVITYGROUPS": [
    {
      "AGR_NAME": "SAP_ALM_ADMINISTRATOR",
      "FROM_DAT": "2016-04-20",
      "TO_DAT": "9999-12-31"
    },
    {
      "AGR_NAME": "SAP_AUDITOR_SA_CCM_USR",
      "FROM_DAT": "2016-05-01",
      "TO_DAT": "2017-04-30"
    }
  ],
  "__NAME__": "SCARTER"
}

When a role is granted, the corresponding profiles are attached to the user account automatically.

Updating a user’s roles

To update a user’s roles, send a PUT request to the user’s ID specifying the new roles as an array of values of the ACTIVITYGROUPS attribute. The values provided in the PUT request will replace the current ACTIVITYGROUPS.

The following example removes the SAP_AUDITOR_SA_CCM_USR role and changes the temporal constraints on the SAP_ALM_ADMINISTRATOR role for SCARTER’s account:

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 '{
  "ACTIVITYGROUPS": [
    {
      "AGR_NAME": "SAP_ALM_ADMINISTRATOR",
      "FROM_DAT": "2015-06-02",
      "TO_DAT": "2016-06-02"
    }
  ]
}' \
"http://localhost:8080/openidm/system/mysap/user/SCARTER"
{
  "_id": "SCARTER",
  "PROFILES": [
    "T_ALM_CONF"
  ],
  ...
  "ACTIVITYGROUPS": [
    {
      "AGR_NAME": "SAP_ALM_ADMINISTRATOR",
      "FROM_DAT": "2015-06-02",
      "TO_DAT": "2016-06-02"
    }
  ],
  "__NAME__": "SCARTER"
}

Removing all roles from a user account

To remove all roles from a user’s account, update the value of the ACTIVITYGROUPS attribute with an empty array. The following example removes all roles from SCARTER’s account:

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 '{
  "ACTIVITYGROUPS": []
}' \
"http://localhost:8080/openidm/system/mysap/user/SCARTER"
{
  "_id": "SCARTER",
  ...
  "LASTMODIFIED": {
    "MODDATE": "2016-04-21",
    "MODTIME": "04:27:00"
  },
  "__NAME__": "SCARTER"
}

The output shows no ACTIVITYGROUPS attribute, as this attribute is now empty.

On CUA systems, each ACTIVITYGROUP has to be specified with a SUBSYSTEM like the next example:

"ACTIVITYGROUPS": [
  {
    "AGR_NAME": "SAP_ALM_ADMINISTRATOR",
    "SUBSYSTEM": "T9CLNT200",
    "FROM_DAT": "2015-06-02",
    "TO_DAT": "2016-06-02"
  }
],
...

Managing user groups

One of the Primary uses of user groups is to sort users into logical groups. This allows users to be categorized in a method that is not dependent on roles, AG’s, Responsibilities, Profiles, and so on.

User Groups also allow segregation of user maintenance, this is especially useful in a large organisation as you can control who your user admin team can maintain - an example would be giving a team leader the authority to change passwords for users in their team.

Creating a user with one or more groups

You add groups as an array of one or more strings.

The following command creates a user SCARTER, with two groups, SUPER and TEST_GROUP:

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 POST \
--data '{
  "__NAME__" : "SCARTER",
  "__PASSWORD__": "Passw0rd",
  "__PASSWORD_EXPIRED__": false,
  "GROUPS": [
    "SUPER",
    "TEST_GROUP"
  ]
}' \
"http://localhost:8080/openidm/system/mysap/user/?_action=create"
{
  "_id": "SCARTER",
  "GROUPS": [
    "SUPER",
    "TEST_GROUP"
  ],
  ...
  "__NAME__": "SCARTER"
}

Updating a user’s groups

To update a user’s groups, send a PUT request to the user’s ID, specifying the new groups as an array of values of the GROUPS attribute. The values provided in the PUT request replaces the current GROUPS.

The following example removes the SUPER group for SCARTER’s account:

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 '{
  "GROUPS": [
    "TEST_GROUP"
  ]
}' \
"http://localhost:8080/openidm/system/mysap/user/SCARTER"
{
  "_id": "SCARTER",
  ...
  "GROUPS": [
    "TEST_GROUP"
  ],
  "__NAME__": "SCARTER"
}

Removing all groups from a user account

To remove all groups from a user’s account, update the value of the GROUPS attribute with an empty array. The following example removes all groups from SCARTER’s account:

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 '{
  "GROUPS": []
}' \
"http://localhost:8080/openidm/system/mysap/user/SCARTER"
{
  "_id": "SCARTER",
  ...
  "LASTMODIFIED": {
    "MODDATE": "2016-04-21",
    "MODTIME": "04:27:00"
  },
  "__NAME__": "SCARTER"
}

The output shows no GROUPS attribute, as this attribute is now empty.

Configuring the SAP connector for OpenIDM user interface for R3

Create a connector configuration using the IDM admin UI:

From the navigation bar, click Configure > Connectors.
On the Connectors page, click New Connector.
On the New Connector page, type a Connector Name.
From the Connector Type drop-down list, select SAP Connector - 1.5.20.26.
Complete the Base Connector Details.

For a list of all configuration properties, refer to SAP Connector Configuration
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.

Base Connector Details

To run the connector, you need the following minimum configuration:

Gateway Host: Host name or IP address of the SAP Gateway Server
Application Server Host: Host name or IP address of the SAP Application Server (or SAP Netweaver Gateway)
Client: Name of the SAP logon client
Language: Language of the remote SAP System
SAP Router
User: Logon used for authenticating on the remote SAP System
Password: Password of the previously specified logon, used for authenticating on the remote SAP System
Scripts Root: Full Path To Script Files
Search Script
Create Script
Update Script
Delete Script
Sync Script
Test Script
Schema Script

Object Types

You must add or edit your Object Types including the following four objects with the listed minimum properties:

__ACCOUNT__

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED	ITEM TYPE	ITEM NATIVE TYPE
__NAME__	String	String	YES	-	-
__PASSWORD__	String	JAVA_TYPE_GUARDEDSTRING	YES	-	-
ALIAS	String	String	YES	-	-
LOGONDATA	Object	Object	NO	-	-
COMPANY	Object	Object	NO	-	-
ADDRESS	Object	Object	YES	-	-
__LOCK_OUT__	Boolean	JAVA_TYPE_PRIMITIVE_BOOLEAN	NO	-	-
ACTIVITYGROUPS	Array	Object	NO	Object	Object
PROFILES ⁽²⁾	Array	String	NO	String	String
GROUPS	Array	String	NO	String	String
SYSTEMS ⁽¹⁾	Array	String	NO	String	String

PROPERTY NAME

TYPE

NATIVE TYPE

REQUIRED

ITEM TYPE

ITEM NATIVE TYPE

__NAME__

String

YES

__PASSWORD__

String

JAVA_TYPE_GUARDEDSTRING

YES

ALIAS

String

YES

LOGONDATA

Object

COMPANY

Object

ADDRESS

Object

YES

__LOCK_OUT__

Boolean

JAVA_TYPE_PRIMITIVE_BOOLEAN

ACTIVITYGROUPS

Array

Object

PROFILES ⁽²⁾

Array

String

GROUPS

Array

String

SYSTEMS ⁽¹⁾

Array

String

⁽¹⁾ On CUA Systems only.

⁽²⁾ On CUA Systems it works as an array of objects.

profile

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED
MANDT	String	String	NO
BAPIPTEXT	String	String	NO
PROFN	String	String	NO
TYP	String	String	NO
SUBSYSTEMS ⁽¹⁾	Array	String	NO
SUB_PROF ⁽²⁾	Array	String	NO

PROPERTY NAME

TYPE

NATIVE TYPE

REQUIRED

MANDT

String

BAPIPTEXT

String

PROFN

String

TYP

String

SUBSYSTEMS ⁽¹⁾

Array

String

SUB_PROF ⁽²⁾

Array

String

⁽¹⁾ On CUA Systems only.

⁽²⁾ Currently on non CUA Systems only.

activity_group

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED
AGR_NAME	String	String	NO
MANDT	String	String	NO
SUBSYSTEMS ⁽¹⁾	Array	String	NO
SUB_AGR ⁽²⁾	Array	String	NO
PROFILES ⁽²⁾	Array	String	NO
T_CODES ⁽²⁾	Array	String	NO

PROPERTY NAME

TYPE

NATIVE TYPE

REQUIRED

AGR_NAME

String

MANDT

String

SUBSYSTEMS ⁽¹⁾

Array

String

SUB_AGR ⁽²⁾

Array

String

PROFILES ⁽²⁾

Array

String

T_CODES ⁽²⁾

Array

String

⁽¹⁾ On CUA Systems only.

⁽²⁾ Currently on non CUA Systems only.

group

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED
USERGROUP	String	String	NO
MANDT	String	String	NO

PROPERTY NAME

TYPE

NATIVE TYPE

REQUIRED

USERGROUP

String

MANDT

String

system

This object type is available on CUA Systems only

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED
SYSNAME	String	String	NO
SYSTEMTYPE	String	String	NO
RFCDEST	String	String	NO
RCVSYSTEM	String	String	NO
NEW_SYSTEM	String	String	NO
MODEL	String	String	NO
SYSCLIENT	String	String	NO
CLIENT	String	String	NO

PROPERTY NAME

TYPE

NATIVE TYPE

REQUIRED

SYSNAME

String

SYSTEMTYPE

String

RFCDEST

String

RCVSYSTEM

String

NEW_SYSTEM

String

MODEL

String

SYSCLIENT

String

CLIENT

String

Configuring the SAP connector for SNC

The SAP connector supports an SNC (Secure Network Connection) configuration. SNC is a software layer in the SAP System architecture that provides an interface to an external security product.

For a list of the configuration properties specific to SNC, refer to SAP Secure Network Connection Configuration Properties.

Implementation specifics

For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The SAP connector implements the add, remove, and replace operations but the sample scripts provided with the connector implement only the replace operation. If you use these sample scripts, a PATCH request will therefore always replace the entire attribute value with the new value.

Setting productive passwords on the SAP system

Synchronization of passwords to the SAP system requires that you configure SNC and SSO. If you do not configure these two elements correctly, passwords that are updated by IDM are set as initial passwords rather than productive passwords, and users are forced to change their passwords on login.

To configure the SAP connector to use SNC, set the sncMode property to "1".

To configure the connector to use SSO with SNC, set the sncSSO property to "1".
The logon session during which a productive password is set must be secured using the authentication method Single Sign-On (SSO) using Secure Network Communications (SNC). IDM must request and receive an SSO logon ticket from the SAP system to allow the BAPI_USER_CHANGE process to set a productive password. For more information, refer to SAP Note 1287410.

To configure the connector to request this logon ticket, set the value of the x509Cert property as follows:
- If you are using an X509 certificate to negotiate with the SAP server, set the x509Cert property to the base 64-encoded certificate.
  
  Note that the certificate must be a valid, CA-signed certificate. You cannot use a self-signed certificate here.
- If you do not use an X509 certificate to negotiate with the SAP server, set the x509Cert property to null.
  
  In this case, the connector will use the user and password specified in the connector configuration to request the SSO logon ticket.

OpenICF Interfaces Implemented by the SAP Connector

The SAP Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:

Authenticate

Provides simple authentication with two parameters, presumed to be a user name and password.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Resolve Username

Resolves an object by its username and returns the uid of the object.

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.

Script on Resource

Runs a script on the target resource that is managed by this connector.

Search

Searches the target resource for all objects that match the specified object class and filter.

Sync

Polls the target resource for synchronization events, that is, native changes to objects on the target resource.

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 Connector Configuration

The SAP Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Encrypted⁽¹⁾	Required⁽²⁾
`gwHost`	`String`	`null`		No
SAP gateway host name.
`gwServ`	`String`	`null`		No
SAP gateway service.
`asHost`	`String`	`null`		No
The FQDN of your SAP Application Server, for example sap.example.com.
`user`	`String`	`null`		Yes
SAP Logon user.
`password`	`GuardedString`	`null`	Yes	Yes
SAP Logon password.
`client`	`String`	`000`		Yes
SAP client.
`systemNumber`	`String`	`00`		Yes
SAP system number.
`language`	`String`	`EN`		Yes
SAP Logon language.
`destination`	`String`	`OPENIDM`		Yes
SAP JCo destination name.
`directConnection`	`boolean`	`true`		Yes
If true, direct connection to an SAP ABAP Application server or SAP router. If false connection to a group of SAP instances through an SAP message server.
`sapRouter`	`String`	`null`		No
SAP router string to use for a system protected by a firewall. (/H/host[/S/port]).
`cua`	`boolean`	`false`		Yes
Description is not available
`threadPoolSize`	`int`	`8`		No
Description is not available

gwHost

String

null

SAP gateway host name.

gwServ

String

null

SAP gateway service.

asHost

String

null

The FQDN of your SAP Application Server, for example sap.example.com.

user

String

null

Yes

SAP Logon user.

password

GuardedString

null

Yes

SAP Logon password.

client

String

000

Yes

SAP client.

systemNumber

String

00

Yes

SAP system number.

language

String

EN

Yes

SAP Logon language.

destination

String

OPENIDM

Yes

SAP JCo destination name.

directConnection

boolean

true

Yes

If true, direct connection to an SAP ABAP Application server or SAP router. If false connection to a group of SAP instances through an SAP message server.

sapRouter

String

null

SAP router string to use for a system protected by a firewall. (/H/host[/S/port]).

cua

boolean

false

Yes

Description is not available

threadPoolSize

int

8

Description is not available

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

Advanced Configuration

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Required⁽²⁾
`r3Name`	`String`	`null`	No
Specifies the name of the SAP system, used when you log in to a logon group that uses load balancing.
`msHost`	`String`	`null`	No
Specifies the host that the message server is running on.
`msServ`	`String`	`null`	No
Name of the service where the message server can be reached.
`group`	`String`	`null`	No
Specifies the group name of the application servers, used when you log in to a logon group that uses load balancing.

r3Name

String

null

Specifies the name of the SAP system, used when you log in to a logon group that uses load balancing.

msHost

String

null

Specifies the host that the message server is running on.

msServ

String

null

Name of the service where the message server can be reached.

group

String

null

Specifies the group name of the application servers, used when you log in to a logon group that uses load balancing.

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

SAP Secure Network Connection Configuration

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Encrypted⁽¹⁾	Required⁽²⁾
`x509Cert`	`String`	`null`	Yes	No
The X509 certificate supplied for authentication.
`sncPartnerName`	`String`	`null`		No
Specifies the AS ABAP SNC name, for example, "p:CN=ABC, O=MyCompany, C=US". You can find the application server SNC name in the profile parameter snc/identity/as on the AS ABAP.
`sncQoP`	`String`	`3`		No
Specifies the security level to use for the connection. Possible values are 1 - Authentication only, 2 - Integrity protection, 3 - Privacy protection, 8 - Use the value from snc/data_protection/use on the application server, 9 - Use the value from snc/data_protection/max on the application server.
`sncMyName`	`String`	`null`		No
Specifies the connector SNC name, for example, "p:CN=OpenIDM, O=MyCompany, C=US". This parameter is optional, but you should set it to make sure that the correct SNC name is used for the connection.
`sncMode`	`String`	`0`		Yes
Flag used to activate SNC. Possible values are 0 (OFF) and 1 (ON).
`sncSSO`	`String`	`0`		No
Specifies whether the connection should be configured for single sign-on (SSO). Possible values are 0 (OFF) and 1 (ON).
`sncLibrary`	`String`	`null`		No
Specifies the path to the external library that provides Secure Network Connection service. The default is the system-defined library as defined in the environment variable SNC_LIB.

x509Cert

String

null

Yes

The X509 certificate supplied for authentication.

sncPartnerName

String

null

Specifies the AS ABAP SNC name, for example, "p:CN=ABC, O=MyCompany, C=US". You can find the application server SNC name in the profile parameter snc/identity/as on the AS ABAP.

sncQoP

String

3

Specifies the security level to use for the connection. Possible values are 1 - Authentication only, 2 - Integrity protection, 3 - Privacy protection, 8 - Use the value from snc/data_protection/use on the application server, 9 - Use the value from snc/data_protection/max on the application server.

sncMyName

String

null

Specifies the connector SNC name, for example, "p:CN=OpenIDM, O=MyCompany, C=US". This parameter is optional, but you should set it to make sure that the correct SNC name is used for the connection.

sncMode

String

0

Yes

Flag used to activate SNC. Possible values are 0 (OFF) and 1 (ON).

sncSSO

String

0

Specifies whether the connection should be configured for single sign-on (SSO). Possible values are 0 (OFF) and 1 (ON).

sncLibrary

String

null

Specifies the path to the external library that provides Secure Network Connection service. The default is the system-defined library as defined in the environment variable SNC_LIB.

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

JCo Connection Pool Configuration

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Required⁽²⁾
`peakLimit`	`String`	`0`	No
Maximum number of active connections that can be created for a destination simultaneously. The value 0 means unlimited.
`poolCapacity`	`String`	`1`	No
Maximum number of idle connections kept open by the destination. 0 = no connection pooling.
`expirationTime`	`String`	`60000`	No
Time in ms after that a free connection can be closed.
`expirationPeriod`	`String`	`60000`	No
Period in ms after that the destination checks the released connections for expiration.
`maxGetTime`	`String`	`30000`	No
Maximum time in ms to wait for a connection, if the maximum allowed number of connections is allocated by the pool.

peakLimit

String

0

Maximum number of active connections that can be created for a destination simultaneously. The value 0 means unlimited.

poolCapacity

String

1

Maximum number of idle connections kept open by the destination. 0 = no connection pooling.

expirationTime

String

60000

Time in ms after that a free connection can be closed.

expirationPeriod

String

60000

Period in ms after that the destination checks the released connections for expiration.

maxGetTime

String

30000

Maximum time in ms to wait for a connection, if the maximum allowed number of connections is allocated by the pool.

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

SAP Jco Logs Configuration

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Required⁽²⁾
`cpicTrace`	`String`	`0`	No
Enable/disable CPIC trace [0..3].
`trace`	`String`	`0`	No
Enable/disable RFC trace (0 or 1).

cpicTrace

String

0

Enable/disable CPIC trace [0..3].

trace

String

0

Enable/disable RFC trace (0 or 1).

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

Groovy Engine configuration

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Encrypted⁽¹⁾	Required⁽²⁾
`scriptRoots`	`String[]`	`['!/scripts/sap/']`		Yes
The root folder to load the scripts from. If the value is null or empty the classpath value is used.
`classpath`	`String[]`	`[]`		No
Classpath for use during compilation.
`debug`	`boolean`	`false`		No
If true, debugging code should be activated.
`disabledGlobalASTTransformations`	`String[]`	`null`		No
Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled.
`minimumRecompilationInterval`	`int`	`100`		No
Sets the minimum of time after a script can be recompiled.
`recompileGroovySource`	`boolean`	`false`		No
If set to true recompilation is enabled.
`scriptBaseClass`	`String`	`null`		No
Base class name for scripts (must derive from Script).
`scriptExtensions`	`String[]`	`['groovy']`		No
Gets the extensions used to find groovy files.
`sourceEncoding`	`String`	`UTF-8`		No
Encoding for source files.
`targetDirectory`	`File`	`null`		No
Directory into which to write classes.
`tolerance`	`int`	`10`		No
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.
`verbose`	`boolean`	`false`		No
If true, the compiler should produce action information.
`warningLevel`	`int`	`1`		No
Warning Level of the compiler.
`customConfiguration`	`String`	`null`		No
Custom Configuration script for Groovy ConfigSlurper.
`customSensitiveConfiguration`	`GuardedString`	`null`	Yes	No
Custom Sensitive Configuration script for Groovy ConfigSlurper.

scriptRoots

String[]

['!/scripts/sap/']

Yes

The root folder to load the scripts from. If the value is null or empty the classpath value is used.

classpath

String[]

[]

Classpath for use during compilation.

debug

boolean

false

If true, debugging code should be activated.

disabledGlobalASTTransformations

String[]

null

Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled.

minimumRecompilationInterval

int

100

Sets the minimum of time after a script can be recompiled.

recompileGroovySource

boolean

false

If set to true recompilation is enabled.

scriptBaseClass

String

null

Base class name for scripts (must derive from Script).

scriptExtensions

String[]

['groovy']

Gets the extensions used to find groovy files.

sourceEncoding

String

UTF-8

Encoding for source files.

targetDirectory

File

null

Directory into which to write classes.

tolerance

int

10

The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

verbose

boolean

false

If true, the compiler should produce action information.

warningLevel

int

1

Warning Level of the compiler.

customConfiguration

String

null

Custom Configuration script for Groovy ConfigSlurper.

customSensitiveConfiguration

GuardedString

null

Yes

Custom Sensitive Configuration script for Groovy ConfigSlurper.

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

Operation Script Files

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Required⁽²⁾
`authenticateScriptFileName`	`String`	`null`	Authenticate
The name of the file used to perform the AUTHENTICATE operation.
`createScriptFileName`	`String`	`null`	Create
The name of the file used to perform the CREATE operation.
`customizerScriptFileName`	`String`	`null`	No
The script used to customize some function of the connector. Read the documentation for more details.
`deleteScriptFileName`	`String`	`null`	Delete
The name of the file used to perform the DELETE operation.
`resolveUsernameScriptFileName`	`String`	`null`	Resolve Username
The name of the file used to perform the RESOLVE_USERNAME operation.
`schemaScriptFileName`	`String`	`null`	Schema
The name of the file used to perform the SCHEMA operation.
`scriptOnResourceScriptFileName`	`String`	`null`	Script on Resource
The name of the file used to perform the RUNSCRIPTONRESOURCE operation.
`searchScriptFileName`	`String`	`null`	Read Search
The name of the file used to perform the SEARCH operation.
`syncScriptFileName`	`String`	`null`	Sync
The name of the file used to perform the SYNC operation.
`testScriptFileName`	`String`	`TestSAP.groovy`	Test
The name of the file used to perform the TEST operation.
`updateScriptFileName`	`String`	`null`	Update
The name of the file used to perform the UPDATE operation.

authenticateScriptFileName

String

null

Authenticate

The name of the file used to perform the AUTHENTICATE operation.

createScriptFileName

String

null

Create

The name of the file used to perform the CREATE operation.

customizerScriptFileName

String

null

The script used to customize some function of the connector. Read the documentation for more details.

deleteScriptFileName

String

null

Delete

The name of the file used to perform the DELETE operation.

resolveUsernameScriptFileName

String

null

Resolve Username

The name of the file used to perform the RESOLVE_USERNAME operation.

schemaScriptFileName

String

null

Schema

The name of the file used to perform the SCHEMA operation.

scriptOnResourceScriptFileName

String

null

Script on Resource

The name of the file used to perform the RUNSCRIPTONRESOURCE operation.

searchScriptFileName

String

null

Read
Search

The name of the file used to perform the SEARCH operation.

syncScriptFileName

String

null

Sync

The name of the file used to perform the SYNC operation.

testScriptFileName

String

TestSAP.groovy

Test

The name of the file used to perform the TEST operation.

updateScriptFileName

String

null

Update

The name of the file used to perform the UPDATE operation.

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

ICF 1.5.20.26

SAP connector

Install the SAP connector

Using the SAP connector with an SAP HR system

Setting up IDM for the SAP HR samples

Testing the connection to the SAP HR system

Using the SAP connector to manage employee information (SAP HR)

Using the SAP connector to manage SAP Basis System (R/3) users

Setting up IDM for the SAP R/3 samples

Testing the connection to the SAP R/3 system

Using the SAP connector to manage SAP R/3 users

Listing the users in the SAP system

Obtaining the details of an SAP user

Creating SAP user accounts

Schema used by the SAP connector for user accounts

Updating SAP user accounts

Locking and unlocking an account

Updating the standard attributes of a user’s account

Resetting a user’s password

Deleting user accounts

Get the latest changes with LiveSync

Managing user profiles

Creating a user with one or more profiles

Updating a user’s profiles

Removing all profiles from a user account

Managing user roles

Creating a user with one or more profiles

Updating a user’s roles

Removing all roles from a user account

Managing user groups

Creating a user with one or more groups

Updating a user’s groups

Removing all groups from a user account

Configuring the SAP connector for OpenIDM user interface for R3

Configuring the SAP connector for SNC

Implementation specifics

Setting productive passwords on the SAP system

OpenICF Interfaces Implemented by the SAP Connector

SAP Connector Configuration

Basic Configuration Properties

Advanced Configuration

SAP Secure Network Connection Configuration

JCo Connection Pool Configuration

SAP Jco Logs Configuration

Groovy Engine configuration

Operation Script Files