SAP SuccessFactors Connector

Important

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

The SAP SuccessFactors connector lets you synchronize SAP SuccessFactors users with IDM managed users.

Before you start

Before you configure the connector, gather the following details:

Host

The SuccessFactors API hostname. For example, apisalesdemo2.successfactors.eu.

Client ID

The SuccessFactors API Key or client ID. To find this:

Open your SuccessFactors administrator account.
Open Manage OAuth2 Client Applications.
Select your registered OAuth2 Client Application.
Click View.
Copy the API key.

User ID

The API User ID of the SuccessFactors user who authenticates to the REST server.

Private Key

A private key. To configure this, generate a key pair from the X.509 certificate and copy the value of the private key.

Company ID

The API Company ID of the admin user. This is specified in the SuccessFactors login URL.

Person Segments

SuccessFactors person segments; for example, EmpJob, EmpEmployment, PerPersonal.

Install the SuccessFactors connector

Download the connector .jar file from the link:{fr_download_site_url}[{fr_download_site_name}].

If you are running the connector locally, place it in the /path/to/openidm/connectors directory; for example:
```
mv ~/Downloads/successfactors-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 SuccessFactors connector

Create a connector configuration using the Admin UI:

Select Configure > Connectors and click New Connector.
Enter a Connector Name.
Select SuccessFactors Connector - 1.5.20.12 as the Connector Type.
Provide the Base Connector Details.
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/Successfactors?_action=test"
{
  "name" : "Successfactors",
  "enabled" : true,
  "config" : "config/provisioner.openicf/Successfactors",
  "connectorRef" : {
    "bundleVersion" : "${bundleVersion}",
    "bundleName" : "org.forgerock.openicf.connectors.successfactors-connector",
    "connectorName" : "org.forgerock.openicf.connectors.successfactors.SuccessFactorsConnector"
  },
  "displayName" : "SuccessFactors Connector",
  "objectTypes" : [ "__GROUP__", "__PERSON__", "__ACCOUNT__", "__ALL__" ],
  "ok" : true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the Cerner system.

Use the SuccessFactors connector

Actions on accounts

You can perform the following actions on a SAP SuccessFactors account:

Create a SuccessFactors user

The following example creates a user with every available attribute:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request  POST \
--data '{
  "userId": "BJENSEN",
  "username": "bjensen",
  "__ENABLE__": true,
  "email": "bjensen@example.com",
  "firstName": "Barbara",
  "lastName": "Jensen",
  "country": "USA",
  "married": false,
  "timeZone": "US/Eastern",
  "department": "Cloud",
  "state": "New York",
  "city": "New York City",
  "jobLevel": "2",
  "location": "40.6635°N 73.9387°W",
  "__PASSWORD__": "Test@123",
  "division": "Manufacturing",
  "hireDate": "2021-07-26 00:00:00",
  "dateOfBirth": "2012-08-22 00:00:00",
  "__GROUP__": [
    {"groupId": "6895"},
    {"groupId": "6095"}
  ]
}' \
"http://localhost:8080/openidm/system/Successfactors/__ACCOUNT__?_action=create"
{
  "_id" : "BJENSEN",
  "userId" : "BJENSEN",
  "jobLevel" : "2",
  "__GROUP__" : [ {
    "groupId" : "1586",
    "groupName" : "$$EVERYONE$$"
  }, {
    "groupId" : "6895",
    "groupName" : "SAP_Managers"
  }, {
    "groupId" : "6095",
    "groupName" : "SAP_ONB2_ErrorFlowAdmins"
  } ],
  "department" : "Cloud",
  "dateOfBirth" : "2012-08-22 00:00:00",
  "lastModifiedDateTime" : "2022-11-02 09:13:49",
  "__ENABLE__" : true,
  "email" : "bjensen@example.com",
  "country" : "USA",
  "lastModified" : "2022-11-02 10:13:49",
  "location" : "40.6635°N 73.9387°W",
  "lastName" : "Jensen",
  "lastModifiedWithTZ" : "2022-11-02 09:13:49",
  "username" : "bjensen",
  "timeZone" : "US/Eastern",
  "city" : "New York City",
  "state" : "New York",
  "__NAME__" : "bjensen",
  "hireDate" : "2021-07-26 00:00:00",
  "married" : false,
  "division" : "Manufacturing",
  "firstName" : "Barbara"
}

Note

New users must have at least the username, userId, and status properties.

Query all users

The following example queries all SuccessFactors 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/successfactors/__ACCOUNT__?_queryId=query-all-ids"
{
  "result":[
    {"_id":"1007373"},
    {"_id":"1007371"},
    {"_id":"1007376"},
    {"_id":"1007370"},
    {"_id":"1007377"}
  ],
  "resultCount":5,
  "pagedResultsCookie":null,
  "totalPagedResultsPolicy":"NONE",
  "totalPagedResults":-1,
  "remainingPagedResults":-1
}

Query a single user

The following example queries a single 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/successfactors/__ACCOUNT__?_queryFilter=_id%20eq%20%22BJENSEN%22"
{
  "_id" : "BJENSEN",
  "userId" : "BJENSEN",
  "jobLevel" : "2",
  "__GROUP__" : [ {
    "groupId" : "1586",
    "groupName" : "$$EVERYONE$$"
  }, {
    "groupId" : "6895",
    "groupName" : "SAP_Managers"
  }, {
    "groupId" : "6095",
    "groupName" : "SAP_ONB2_ErrorFlowAdmins"
  } ],
  "department" : "Cloud",
  "dateOfBirth" : "2012-08-22 00:00:00",
  "lastModifiedDateTime" : "2022-11-02 09:13:49",
  "__ENABLE__" : true,
  "email" : "bjensen@example.com",
  "country" : "USA",
  "lastModified" : "2022-11-02 10:13:49",
  "location" : "40.6635°N 73.9387°W",
  "lastName" : "Jensen",
  "lastModifiedWithTZ" : "2022-11-02 09:13:49",
  "username" : "bjensen",
  "timeZone" : "US/Eastern",
  "city" : "New York City",
  "state" : "New York",
  "__NAME__" : "bjensen",
  "hireDate" : "2021-07-26 00:00:00",
  "married" : false,
  "division" : "Manufacturing",
  "firstName" : "Barbara"
}

Modify a user

You can use the SuccessFactors connector to modify the following attributes of a user entry:

username
email
status
country
department
timeZone
jobLevel
married
city
state
division
citizenship
location
firstName
lastName
gender
dateOfBirth
jobCode

The following example updates the `division` property on 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 '{
  "division": "Engineering"
}' \
"http://localhost:8080/openidm/system/successfactors/__ACCOUNT__/BJENSEN"
{
  "_id" : "BJENSEN",
  "userId" : "BJENSEN",
  ...
  "division" : "Engineering",
  "firstName" : "Barbara"
}

Reset a user's password

The following example resets the password for a SuccessFactors user account:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[{
  "operation": "replace",
  "field": "__PASSWORD__",
  "value": "__CHANGEME__"
}]' \
"http://localhost:8080/openidm/system/successfactors/__ACCOUNT__/BJENSEN"
{
  "_id" : "BJENSEN",
  "userId" : "BJENSEN",
  ...
}

Note

The updated password is not included in the response object; however, the value is updated in the system.

Activate a user

The following example activates 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" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "username": "bjensen",
  "__ENABLE__": true,
  "firstName": "Barbara",
  "userId": "BJENSEN"
}' \
"http://localhost:8080/openidm/system/successfactors/__ACCOUNT__/BJENSEN"
{
  "_id": "BJENSEN",
  "userId": "BJENSEN",
  ...
  "__ENABLE__": true
}

Deactivate a user

The SuccessFactors connector does not support deleting accounts. To deactivate an unwanted account, set the account's __ENABLE__ attribute value to false. A deactivated account remains in the SuccessFactors system and can still be queried by its ID, but cannot be accessed.

The following example deactivates a SuccessFactors account:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "username": "bjensen",
  "__ENABLE__": false,
  "firstName": "Barbara",
  "userId": "BJENSEN"
}' \
"http://localhost:8080/openidm/system/successfactors/__ACCOUNT__/BJENSEN"
{
  _id: "BJENSEN"
}

Assign a user to a group

The following example assigns a user to a group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PUT \
--data '{
  "__ENABLE__": true,
  "__GROUP__": [{"groupId":1001}]
}' \
"http://localhost:8080/openidm/system/successfactors/__ACCOUNT__/BJENSEN"
{
  "_id" : "BJENSEN",
  "userId" : "BJENSEN",
  "jobLevel" : "2",
  "__GROUP__" : [ {
    "groupId" : "1001",
    "groupName" : "Example Working Group"
  },
  ...
}

Actions on other objects

Query all groups

The following example queries all groups in the system:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request GET \
"http://localhost:8080/openidm/system/successfactors/__GROUP__?_queryId=query-all-ids"
{
  "result": [
    {"_id":"6637"},
    {"_id":"2202"},
    {"_id":"1588"},
    {"_id":"6877"},
    {"_id":"2203"}
  ],
  "resultCount":5,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Query a single group

The following example queries a single group:

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/successfactors/__GROUP__?/1001"
{
  "_id": "1001",
  "__NAME__": "1001",
  "groupName": "Example Working Group",
  "lastModifiedDate" : "2015-01-04 23:29:38",
  "createdBy" : "v4admin",
  "totalMemberCount" : "33590",
  "activeMembershipCount" : "2294",
  "groupID" : "1001",
  "groupType" : "permission"
}

Query all persons

The following example queries all persons in the system:

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/successfactors/__PERSON__?_queryId=query-all-ids"
{
  "result":[
    {"_id":"69119"},
    {"_id":"69120"},
    {"_id":"69121"},
    {"_id":"80279"},
    {"_id":"80280"}
  ],
  "resultCount":5,
  "pagedResultsCookie":null,
  "totalPagedResultsPolicy":"NONE",
  "totalPagedResults":-1,
  "remainingPagedResults":-1
}

Query a single person

The following example queries a single person:

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/successfactors/__PERSON__?_queryFilter=_id%20%22scarter%22"
{
  "result":[{
    "_id":"scarter",
    "EmpJob_payGrade":"GR-08",
    "EmpEmployment_firstDateWorked":"2002-03-17 00:00:00",
    "PerPersonal_maritalStatus":"10819",
    "PerPersonal_nationality":"USA",
    "EmpEmployment_lastDateWorked":null,
    "EmpEmployment_userId":"scarter",
    "PerPersonal_personIdExternal":"scarter",
    "EmpEmployment_initialStockGrant":null,
    "PerPerson_countryOfBirth":"USA",
    "PerPersonal_endDate":"9999-12-31 00:00:00",
    "PerPersonal_firstName":"Sam",
    "EmpEmployment_eligibleForStock":null,
    "PerPersonal_lastName":"Carter",
    "EmpJob_payScaleArea":"USA/US2",
    "EmpJob_jobCode":"50070968",
    "PerPerson_regionOfBirth":null,
    "PerPersonal_startDate":"2002-03-17 00:00:00",
    "PerPerson_personIdExternal":"scarter",
    "PerPerson_lastModifiedDateTime":"2015-10-30 10:05:06",
    "EmpEmployment_lastModifiedDateTime":"2018-07-15 23:12:06",
    "PerPersonal_lastModifiedDateTime":"2018-10-25 23:51:29",
    "EmpJob_timezone":"US/Eastern",
    "PerPersonal_gender":"M",
    "PerPerson_dateOfBirth":"1983-02-15 00:00:00",
    "PerPersonal_nativePreferredLang":"10223",
    "EmpEmployment_serviceDate":null,
    "EmpEmployment_assignmentIdExternal":"scarter",
    "EmpJob_lastModifiedDateTime":"2020-06-23 10:50:43",
    "PerPerson_createdOn":"2015-01-05 23:34:22",
    "EmpJob_company":"1710",
    "EmpEmployment_originalStartDate":"2002-03-17 00:00:00",
    "EmpEmployment_endDate":null,
    "EmpJob_position":"3000325",
    "EmpJob_jobTitle":"Administrative Support",
    "PerPersonal_salutation":"10810",
    "EmpEmployment_seniorityDate":"2002-03-17 00:00:00",
    "PerPerson_createdDateTime":"2015-01-05 22:34:22",
    "EmpEmployment_professionalServiceDate":null,
    "EmpJob_startDate":"2017-01-01 00:00:00",
    "PerPersonal_middleName":null,
    "PerPerson_createdBy":"v4admin",
    "PerPersonal_preferredName":null,
    "PerPerson_lastModifiedBy":"scarter",
    "EmpJob_businessUnit":"CORP",
    "EmpJob_seqNumber":"1",
    "PerPerson_perPersonUuid":"87AF10389BCC4F29BC3F3A225B321E14",
    "EmpJob_location":"1710-2001",
    "EmpJob_managerId":"108743",
    "EmpJob_eventReason":"PAYOTH",
    "PerPerson_lastModifiedOn":"2015-10-30 11:05:06",
    "EmpJob_payScaleType":"USA/US2",
    "EmpJob_userId":"scarter",
    "EmpEmployment_initialOptionGrant":null,
    "EmpEmployment_personIdExternal":"scarter",
    "PerPerson_personId":"8",
    "__NAME__":"scarter"}],
  "resultCount":1,
  "pagedResultsCookie":null,
  "totalPagedResultsPolicy":"NONE",
  "totalPagedResults":-1,
  "remainingPagedResults":-1
}

Accout Status

Attribute	Description
`userId`	The user's User ID.
`userName`	The user's username.
`status`	The user's status.
`firstName`	The user's first name.
`lastName`	The user's last name.
`mi`	The user's middle name.
`email`	The user's email address.
`dateOfBirth`	The user's birthdate.
`defaultFullName`	The default full name for the user.
`password`	The user's password.
`lastModifiedDateTime`	The last modified date and time without time zone information.
`country`	The user's country of residence.
`citizenship`	The user's country of citizenship.
`married`	The user's marital status.
`state`	The state where the user lives.
`city`	The city where the user lives.
`division`	The division the user works in.
`department`	The department the user works in.
`jobCode`	The Job code of the user.
`jobLevel`	The Job level of the user.
`timeZone`	The user's time zone.
`location`	The user's location.
`manager`	The user's manager.
`hireDate`	The date the user was hired.
`lastModifiedWithTZ`	The last modified date and time with time zone information.
`lastModified`	The last modified date.

Group Attributes

The following group attributes are supported by the SuccessFactors Connector:

Attribute	Description
`groupId`	The unique ID of the group.
`groupName`	The name of the group.
`groupType`	The type of the group.
`activeMembershipCount`	The number of active members.
`totalMemberCount`	The number of total members.
`deExcludePools`	Users excluded from the group.
`dgIncludePools`	Users included in the group.
`createdBy`	The user who created the group.
`lastModifiedDate`	The last modified date.

Person Attributes

`PerPerson` Attributes

The following PerPerson attributes are supported by the SuccessFactors connector:

Attribute	Description
`personIdExternal`	An ID used to represent the person externally.
`personId`	An ID used to represent the person internally.
`userId`	The person's user ID.
`dateOfBirth`	The person's date of birth.
`lastModifiedOn`	The date the person was last modified.
`lastModifiedDateTime`	The time the person was last modified.
`countryOfBirth`	The country the person was born in.
`createdBy`	The ID of the user who created the person.
`createdDateTime`	The time the person was created.
`lastModifiedBy`	The ID of the last user to modify the person.
`perPersonUuid`	A UUID for the person.
`regionOfBirth`	The person's birth region.

`PerPersonal` Attributes

Attribute	Description
`personIdExternal`	An ID used to represent the employee externally.
`endDate`	The end date of the employment.
`startDate`	The start date of the employment.
`firstName`	The person's first name.
`lastName`	The person's last name.
`gender`	The person's gender.
`nativePreferredLang`	The person's preferred native language code.
`salutation`	The salutation to be used for the person.
`maritalStatus`	The person's marital status.
`nationality`	The person's nationality.
`middleName`	The person's middle name.
`preferredName`	The person's preferred name.
`lastModifiedDateTime`	The time when the `PerPersonal` was last updated.

`EmpEmployment` Attributes

Attribute	Description
`personIdExternal`	An ID used to represent the employee externally.
`userId`	The employee's user ID.
`assignmentIdExternal`	An assignment ID used to identify users across the suite.
`firstDateWorked`	The first date the employee worked.
`endDate`	The end date of the employment.
`startDate`	The start date of the employment.
`eligibleForStock`	Whether or not the user is eligible for stock.
`initialOptionGrant`	The initial grant value of the employment.
`serviceDate`	The service date of employment.
`professionalServiceDate`	The professional service date of employment.
`initialStockGrant`	The employment's initial stock grant.
`seniorityDate`	The date of seniority.
`lastModifiedDateTime`	The time when the `EmpEmployment` object was last updated.
`lastDateWorked`	The date of the last day the employee worked.

`EmpJob` Attributes

Attribute	Description
`seqNumber`	The sequence number associated with the job.
`userId`	The employee's user ID.
`eventReason`	The reason for action.
`company`	The company the job is for.
`managerId`	The ID of the manager of the job.
`timezone`	The time zone the job is in.
`startDate`	The date the job begins.
`endDate`	The date the job ends.
`payGrade`	The job's pay grade.
`jobCode`	The job's code.
`position`	The position of the job.
`location`	The job's location.
`payScaleType`	The payscale type for the job.
`payScaleArea`	The payscale area for the job.
`businessUnit`	The business unit the job belongs to.
`lastModifiedDateTime`	The date the job was last modified.

OpenICF Interfaces Implemented by the SuccessFactors Connector

The SuccessFactors Connector implements the following OpenICF interfaces.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by 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.

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.

SuccessFactors Connector Configuration

The SuccessFactors Connector has the following configurable properties.

Configuration properties

Property	Type	Default
`host`	`String`	`null`
Hostname of the target

`clientId`	`String`	`null`
The client identifier

`userId`	`String`	`null`
User id for authentication

`privateKey`	`GuardedString`	`null`
The private key which is used for signing JWT

`companyId`	`String`	`null`
Company id as present in target application

`personSegments`	`String`	`null`
To retrieve data based on person segments

`pageSize`	`int`	`0`
Page size for search operation

^[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.

Basic configuration properties

Property	Type	Default
`maximumConnections`	`Integer`	`10`
Provide the maximum connections

`connectionTimeout`	`int`	`600`
Provide the maximum connection timeout in seconds

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

SAP SuccessFactors Connector

Important

Before you start

Install the SuccessFactors connector

Configure the SuccessFactors connector

Use the SuccessFactors connector

Actions on accounts

Note

Note

Actions on other objects

Accout Status

Group Attributes

Person Attributes

PerPerson Attributes

PerPersonal Attributes

EmpEmployment Attributes

EmpJob Attributes

OpenICF Interfaces Implemented by the SuccessFactors Connector

SuccessFactors Connector Configuration

Configuration properties

Basic configuration properties

`PerPerson` Attributes

`PerPersonal` Attributes

`EmpEmployment` Attributes

`EmpJob` Attributes