IDM 7.2.2

SAP SuccessFactors connector

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

The SAP SuccessFactors connector enables you to manage and synchronize objects between SuccessFactors and the IDM managed user repository. These instructions assume you have a SuccessFactors administrator account and you have created an OAuth2 Client Application.

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:

  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

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

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/successfactors-connector-1.5.20.15.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:

  1. Select Configure > Connectors and click New Connector.

  2. Enter a Connector Name.

  3. Select SuccessFactors Connector - 1.5.20.15 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&prettyprint=true"
{
  "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 has been configured correctly, and can authenticate to the SuccessFactors 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"}
]}'
"https://localhost:8443/openidm/system/Successfactors/__ACCOUNT__?_action=create&_prettyprint=true"
{
  "_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"
}
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 \
"https://localhost:8443/openidm/system/successfactors/__ACCOUNT__?_queryId=query-all-ids&_prettyPrint=true"
{
  "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 \
"https://localhost:8443/openidm/system/successfactors/__ACCOUNT__?_queryFilter=_id%20eq%20%22BJENSEN%22&_prettyprint=true"
{
  "_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"
}'
"https://localhost:8443/openidm/system/Successfactors/__ACCOUNT__/BJENSEN?_prettyprint=true"
{
  "_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__"
}]'
"https://localhost:8443/openidm/system/successfactors/__ACCOUNT__/BJENSEN?_prettyprint=true"
{
  "_id" : "BJENSEN",
  "userId" : "BJENSEN",
  ...
}
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"
}'
"https://localhost:8443/openidm/system/successfactors/__ACCOUNT__/BJENSEN?prettyprint=true"
{
  "_id": "BJENSEN",
  "userId": "BJENSEN",
  ...
  "__ENABLE__": true
}
Deactivate a user account

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"
}'
"https://localhost:8443/openidm/system/successfactors/__ACCOUNT__/BJENSEN?prettyprint=true"
{
  _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}]
}'
"https://localhost:8443/openidm/system/successfactors/__ACCOUNT__/BJENSEN?prettyprint=true"
{
  "_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 \
"https://localhost:8443/openidm/system/successfactors/__GROUP__?_queryId=query-all-ids&_prettyprint=true"
{
  "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 \
"https://localhost:8443/openidm/system/successfactors/__GROUP__?/1001?_prettyprint=true"
{
  "_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 \
"https://localhost:8443/openidm/system/successfactors/__PERSON__?_queryId=query-all-ids&_prettyPrint=true"
{
  "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 group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"https://localhost:8443/openidm/system/successfactors/__PERSON__?_queryFilter=_id%20%22scarter%22&_prettyprint=true"
{
  "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
}

Account attributes

The following account attributes are supported by the SuccessFactors connector:

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

The following PerPersonal attributes are supported by the SuccessFactors connector:

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

The following EmpEmployment attributes are supported by the SuccessFactors connector:

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

The following EmpJob attributes are supported by the SuccessFactors connector:

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. For additional details, see ICF 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(1) Required(2)

host

String

null

Yes

Hostname of the target

clientId

String

null

Yes

The client identifier

userId

String

null

Yes

User id for authentication

privateKey

GuardedString

null

Yes

The private key which is used for signing JWT

companyId

String

null

Yes

Company id as present in target application

personSegments

String

null

No

To retrieve data based on person segments

pageSize

int

0

No

Page size for search operation

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.

Basic configuration properties

Property Type Default Encrypted(1) Required(2)

maximumConnections

Integer

10

No

Provide the maximum connections

connectionTimeout

int

600

No

Provide the maximum connection timeout in seconds

httpProxyHost

String

null

No

Provide the HTTP proxy host

httpProxyPort

Integer

null

No

Provide the HTTP proxy port

httpProxyUsername

String

null

No

Provide the HTTP proxy username

httpProxyPassword

GuardedString

null

Yes

No

Provide the HTTP proxy password

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.