Updating and setting primary attributes in SuccessFactors with PowerShell

Approximately five years ago I rolled through a number of Identity and Access lifecycle management projects that used SAP SuccessFactors as the source of authority for user data. It isn’t uncommon to use a HRM solution to source identity data, but it is never a one way street. At least 90% of the projects I’ve delivered with HRM integration I’ve needed to feed some data back. Data that the HRM system isn’t authoritative for but benefits from. The common data attributes are email address, business phone number and often the users primary loginID. Recently in an engagement and my first with SuccessFactors in many years this requirement surfaced again. I had memories of achieving it previously and knew there were some peculiarities but for whatever reason I had never written it up as a blog post. This post finally documents how to update email addresses and setting one of them as the primary address. This same logic can be expanded to other attributes that behave in a similar manner such as telephone numbers and setting primary attributes in SuccessFactors with PowerShell.

Prerequisites

Not covered in this post is how to enable API based access to SuccessFactors. If you are reading this post you’ve probably already got that working. You just want to know how to update email and phone numbers and flip which field is the primary. If not, this document will get you on the right path.

To utilise the example script functions in this post you will need your:

  • SSFUserID@TenantName (case sensitive)
  • API User Password
  • SSF Data Centre and Environment URI
    • You will be able to get the URI from your SSF Portal. You can find your different environment URIs for your tenant from this document.
  • Attribute labels of the attributes you will be updating
    • This is a number unique in your environment that you will need to get from your SuccessFactors administrator. The images below show the Option ID which is this number for Business and Personal email addresses that are used in this example.

Sample Script

The following example script contains 3 functions and a few global variables for your configuration with respect to your SuccessFactors tenant.

Make the following changes to the script.

  • $Global:SSFBaseURI = “https://api10preview.sapsf.com/odata/v2/”
    • Update this with the API endpoint for the environment your tenant is in. Also, see this reference
  • $Global:SSFBusinessEmailType = “159139”
    • The Email Type Option ID from SuccessFactors for Business Email. This is shown via the SuccessFactors Admin Portal screenshot above.
  • $Global:SSFPersonalEmailType = “159140”
    • The Email Type Option ID from SuccessFactors for Personal Email. This is shown via the SuccessFactors Admin Portal screenshot above.

Connect-SSF

This function does as the name suggests, connects to your SuccessFactors tenant and sets up some variables leveraged by the other functions. It prompts you for your API LoginID and Password.

Get-SSFUser

This function will connect to SuccessFactors using the credentials supplied in Connect-SFF function and lookup a record by employeeID and return it.

Update-SSFUser

Finally, the Update-SSFUser function has two capabilities. It will update business email if only business email is provided and make it the primary address. If both personal and business email are supplied it will update both and make the business email the primary address.

Using the Script

Running the Connect-SSF function (after configuring the SSFBaseURI variable) will prompt you for your SuccessFactors API credentials. It then does a test connection to verify access.

The Get-SSFUser function when passed an employeeID, the API URI and the global headers variable created from the Connect-SSF function will return that users record.

The record can be examined to determine if there are email addresses configured for that users record. For example, you can query and get the users personal email address that would have been provided during recruitment.

$personalEmail = ($userDetails.emailNav.results | Where-Object { $_.EmailType -eq $SSFPersonalEmailType }).emailAddress

Finally, the Update-SSFEmail function when provided the employeeID, API URI, the global headers variable, the business and personal email types and values will update the users SuccessFactors record. To switch which value is the primary (this example makes the business email primary), edit the Update-SSFEmail function and flip the `”isPrimary`”:true | false values.

Updating primary attributes in SuccessFactors with PowerShell

Summary

The key item here is using the purgeType=Full API function when updating and setting the primary attributes in SuccessFactors with PowerShell. This does what it sounds like. It flushes existing values and replaces with what is sent as part of the POST request to SuccessFactors using their Upsert function to update records.