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

Important

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

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:

  1. Open your SuccessFactors administrator account.

  2. Open Manage OAuth2 Client Applications.

  3. Select your registered OAuth2 Client Application.

  4. Click View.

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

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

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 SuccessFactors 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/Successfactors?_action=test"
{
  "name" : "Successfactors",
  "enabled" : true,
  "config" : "config/provisioner.openicf/Successfactors",
  "connectorRef" : {
    "bundleVersion" : "[1.5.0.0,1.6.0.0)",
    "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

Important

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

Actions on accounts

Important

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

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

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.

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
}

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"
}

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"
}

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.

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
}

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"
}

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

Important

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

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
}

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"
}

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
}

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

Important

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

AttributeDescription
userIdThe user's User ID.
userNameThe user's username.
statusThe user's status.
firstNameThe user's first name.
lastNameThe user's last name.
miThe user's middle name.
emailThe user's email address.
dateOfBirthThe user's birthdate.
defaultFullNameThe default full name for the user.
passwordThe user's password.
lastModifiedDateTimeThe last modified date and time without time zone information.
countryThe user's country of residence.
citizenshipThe user's country of citizenship.
marriedThe user's marital status.
stateThe state where the user lives.
cityThe city where the user lives.
divisionThe division the user works in.
departmentThe department the user works in.
jobCodeThe Job code of the user.
jobLevelThe Job level of the user.
timeZoneThe user's time zone.
locationThe user's location.
managerThe user's manager.
hireDateThe date the user was hired.
lastModifiedWithTZThe last modified date and time with time zone information.
lastModifiedThe last modified date.

Group Attributes

Important

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

The following group attributes are supported by the SuccessFactors Connector:

AttributeDescription
groupIdThe unique ID of the group.
groupNameThe name of the group.
groupTypeThe type of the group.
activeMembershipCountThe number of active members.
totalMemberCountThe number of total members.
deExcludePoolsUsers excluded from the group.
dgIncludePoolsUsers included in the group.
createdByThe user who created the group.
lastModifiedDateThe last modified date.

Person Attributes

Important

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

PerPerson Attributes

Important

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

The following PerPerson attributes are supported by the SuccessFactors connector:

AttributeDescription
personIdExternalAn ID used to represent the person externally.
personIdAn ID used to represent the person internally.
userIdThe person's user ID.
dateOfBirthThe person's date of birth.
lastModifiedOnThe date the person was last modified.
lastModifiedDateTimeThe time the person was last modified.
countryOfBirthThe country the person was born in.
createdByThe ID of the user who created the person.
createdDateTimeThe time the person was created.
lastModifiedByThe ID of the last user to modify the person.
perPersonUuidA UUID for the person.
regionOfBirthThe person's birth region.

PerPersonal Attributes

Important

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

AttributeDescription
personIdExternalAn ID used to represent the employee externally.
endDateThe end date of the employment.
startDateThe start date of the employment.
firstNameThe person's first name.
lastNameThe person's last name.
genderThe person's gender.
nativePreferredLangThe person's preferred native language code.
salutationThe salutation to be used for the person.
maritalStatusThe person's marital status.
nationalityThe person's nationality.
middleNameThe person's middle name.
preferredNameThe person's preferred name.
lastModifiedDateTimeThe time when the PerPersonal was last updated.

EmpEmployment Attributes

Important

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

AttributeDescription
personIdExternalAn ID used to represent the employee externally.
userIdThe employee's user ID.
assignmentIdExternalAn assignment ID used to identify users across the suite.
firstDateWorkedThe first date the employee worked.
endDateThe end date of the employment.
startDateThe start date of the employment.
eligibleForStockWhether or not the user is eligible for stock.
initialOptionGrantThe initial grant value of the employment.
serviceDateThe service date of employment.
professionalServiceDateThe professional service date of employment.
initialStockGrantThe employment's initial stock grant.
seniorityDateThe date of seniority.
lastModifiedDateTimeThe time when the EmpEmployment object was last updated.
lastDateWorkedThe date of the last day the employee worked.

EmpJob Attributes

Important

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

AttributeDescription
seqNumberThe sequence number associated with the job.
userIdThe employee's user ID.
eventReasonThe reason for action.
companyThe company the job is for.
managerIdThe ID of the manager of the job.
timezoneThe time zone the job is in.
startDateThe date the job begins.
endDateThe date the job ends.
payGradeThe job's pay grade.
jobCodeThe job's code.
positionThe position of the job.
locationThe job's location.
payScaleTypeThe payscale type for the job.
payScaleAreaThe payscale area for the job.
businessUnitThe business unit the job belongs to.
lastModifiedDateTimeThe 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

PropertyTypeDefault Encrypted [a] Required [b]
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

PropertyTypeDefault Encrypted [a] Required [b]
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.

Read a different version of :