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:
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
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:
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" : "[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.
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
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:
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
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:
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
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
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
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
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
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
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 | 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
Property | Type | Default | 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. |