Connect SAP SuccessFactors

Connect SAP SuccessFactors Employee Central so the people, teams, positions and pay in Flowstate follow what HR records there. Hires, leavers, job changes and pay changes reach the forecast without anyone re-keying them.

Setting it up takes your SuccessFactors administrator, your integration team and a Flowstate admin. First decide whether SuccessFactors is your source of truth. See Get your people data into Flowstate.

How it connects

SuccessFactors raises events for changes such as a new hire or a termination. An Integration Center job can send the details on to another system. Its API requires OAuth with a signed SAML assertion, so it connects through your integration platform. That can be SAP Integration Suite, or a platform such as Workato, Boomi or MuleSoft. The platform updates Flowstate through its REST API.

Route	How it works	Best for
Event-driven (recommended)	SuccessFactors raises an event, and an Integration Center job sends the worker's details to your integration platform. The platform updates Flowstate through the REST API. It also re-reads SuccessFactors on a schedule, to catch changes that don't raise an event.	Every SuccessFactors organisation
Scheduled sync	A Flowstate custom integration reads SuccessFactors on a schedule.	Not used for SuccessFactors. A custom integration can't create the signed assertion SuccessFactors' OAuth needs, and basic authentication is being retired. Your platform can read on a schedule instead.

Why event-driven is recommended: it's the route SuccessFactors' security allows. Signing in to its API means signing an assertion with a private key, which only your integration platform can do. SAP also advises re-reading a wide date range and comparing it, rather than trusting last-modified dates alone, so your platform does both.

If your tenant only allows API calls from listed IP addresses, this route still works: put your integration platform's addresses on the list.

What you need from SuccessFactors

• An API user whose role-based permissions let it read the Employee Central data you sync. SAP also offers an admin mode for technical integrations, which ignores role-based permissions. Decide which one with your security team.
• Permission to read positions. Positions are MDF objects, so the API user also needs MDF permissions for Position.
• An OAuth client registered with your integration platform's X.509 certificate. It gives you the API key (client ID). The private key stays in your platform.
• Access to Intelligent Services Center and Integration Center in Admin Center, for whoever sets up the events.
• Your API server address. It depends on your data centre, and SAP lists them all.

Set it up

Your Flowstate contact provides the integration logic for SAP SuccessFactors, and works through it with your integration team. There's no one-click connection.

In SuccessFactors

1. Create the API user and give it a permission role that can read the Employee Central data you sync.
2. Under Admin Center → Manage Permission Roles, give that role MDF permissions for Position.
3. Under Manage OAuth2 Client Applications, register a client with the certificate from your integration platform. Give the API key to your integration team.
4. In Integration Center, build a job that sends the worker's details from What syncs to your integration platform's receiving address. Check which destination types your tenant offers.
5. Go to Admin Center → Intelligent Services Center and choose an event, such as new hire, job information change, manager change or termination.
6. Add Custom Activities → Integration and attach the Integration Center job. Repeat for each event you need.

Event-driven: connect your integration platform

1. In Flowstate, go to Settings → Users & Access → API Keys and select Create API Key. Name it after the sync, such as "SuccessFactors sync", and tick view, create and update for employees, contractors, vacancies and teams. See Create and manage API keys.
2. Copy the key and give it to your integration team to store in the platform. Keys last 90 days at most, so put a reminder in to replace it.
3. If people are already in Flowstate, your integration team gives each one their SuccessFactors person ID first. See Adopt people who are already in Flowstate.
4. Your integration team loads everyone once from SuccessFactors, past and future-dated records and leavers included. The platform creates or updates each person in Flowstate by their person ID.
5. They switch on event handling, and schedule a regular re-read. For each change, the platform sends it to Flowstate. How: Sync people from an HR system with the REST API.

Scheduled sync

Not used for SuccessFactors, because a Flowstate custom integration can't sign in with a SAML assertion. Your integration platform's scheduled re-read, above, does that job.

What syncs

In SuccessFactors	In Flowstate	Notes
Person ID (person-id-external)	The person's external ID	SuccessFactors keeps a person ID and a separate user ID for each employment. Use the person ID so someone with more than one employment stays one person in Flowstate. Check how your tenant uses them.
Employee	Employee
Contingent worker	Contractor	SuccessFactors can mark a contingent worker on their employment. Check how your tenant records them. If it doesn't hold a contractor's rate, add it in Flowstate.
Position, or job requisition	Vacancy	Positions need MDF permissions. Requisitions come from Recruiting.
Department	Team
Manager	Line manager
Job information	Job role
FTE, from standard weekly hours	FTE on the person's team allocation	Flowstate records FTE, not hours.
Hire date and termination date	Start date and end date	From the person's employment information.
Recurring pay components	Pay changes	Each change carries annual base salary, currency and the date it takes effect. Your platform converts each amount to an annual figure using its frequency.
Name and work email	Name and work email	Work email links the person to their activity in your other tools.

The REST API also sets a person's location, resource type and notice date, when your integration team maps them.

How changes arrive

• Events. A change arrives once its event is raised and the Integration Center job has sent it. SAP gives guidance on how many events an integration should handle an hour (see For your technical team). Big changes, such as an annual pay review, are better picked up by the scheduled re-read.
• Scheduled re-read. Your platform re-reads on its own schedule and catches anything no event covered.
• Effective dates. Job and pay records in SuccessFactors are effective-dated. Without a date range, the API returns only today's records, so future-dated hires, leavers and pay changes are invisible. Your platform asks for a date range. Future pay changes show as Scheduled on the person's Compensation tab until their date.
• Leavers. The termination date becomes the person's last day. They stay in Flowstate for past months.
• Rehires. A rehire under the same person ID updates the same person, and your platform clears their old end date through the REST API.
• Edits made in Flowstate. Anything your platform sends from SuccessFactors is put back the next time that person is updated. Details it doesn't send stay as you set them.

Check it's working

1. Make a test change to a worker in SuccessFactors that raises one of your events, such as a job information change.
2. The change shows on the People tab under Resourcing → People and teams.
3. On Settings → Users & Access → API Keys, the key shows recent use.

If something's not right

Future-dated hires, leavers or pay changes are missing. The request asked for today's records only. Your integration team adds a date range from and to.

Signing in to SuccessFactors fails. The OAuth client's certificate has changed, or the connection still uses basic authentication, which is being retired. Register the current certificate and use OAuth.

Positions don't come through. The API user has no MDF permissions for Position. Add them under Admin Center → Manage Permission Roles.

Calls to SuccessFactors are refused, though the sign-in details are right. Your tenant only allows API calls from listed IP addresses, and your integration platform's addresses aren't on the list. Add them.

For your technical team

SuccessFactors APIs

• API choice. OData is SAP's recommended API. SFAPI (SOAP) is being deprecated, except the Compound Employee API. Employee Central entities are documented in OData v2.
• Address. https://<api-server>/odata/v2/<Entity>, HTTPS on port 443 only.
  • The API server depends on your data centre (KBA 2215682). Examples: DC68 api4.successfactors.com, DC33 api012.successfactors.eu, DC57 api2.successfactors.eu.
  • Preview tenants have their own hosts, such as api4preview.sapsf.com.
• Enablement. OData API v2 is on by default in Provisioning. Only user permissions are needed.
• Auth.
  • Register the client in Manage OAuth2 Client Applications with an X.509 certificate. Sign a SAML assertion and exchange it at /oauth/token for a bearer token.
  • SAP discourages /oauth/idp, which generates the assertion server-side, because it means sending the private key over the internet.
  • Basic authentication is being retired; use OAuth.
• Permissions. In user mode, role-based permissions decide what the API user reads. Admin mode overrides them. Position needs MDF permissions.
• Entities.
  • EmpJob, filtered by userId, has startDate, fte and standard-hours fields. FTE is derived from standard weekly hours.
  • Manager: /odata/v2/User?$select=userId,manager/userId&$expand=manager.
  • Pay: EmpPayCompRecurring with payComponent, paycompvalue, currencyCode and frequency. It's effective-dated with EmpCompensation.
  • Position is an MDF entity.
  • Check in your tenant's $metadata: EmpEmployment and EmpEmploymentTermination for hire and termination, isContingentWorker and WorkOrder for contingent workers, JobRequisition in Recruiting, and the department and personal-information property names.
• Dates.
  • Effective-dated entities default to asOfDate of today. Use fromDate and toDate for history and future rows, for example fromDate=1900-01-01.
  • On effective-dated entities, lastModifiedDateTime matches across segments: a person comes back if any segment falls inside the window. The row returned may be outside it.
  • SAP's options: extract the full range (1900-01-01 to 9999-12-31) and diff against a staging table, or extract the full range and filter on lastModifiedDateTime in middleware.
• Paging. Add paging=snapshot (non-MDF entities) and follow __next, which carries $skiptoken, until it's absent. A response holds at most 1,000 records. Reuse the session Cookie and X-CSRF-Token from the first response.

Events

• Intelligent Services publishes events such as new hire, job information change, manager change and termination. Third-party products can subscribe.
• Set-up: Admin Center → Intelligent Services Center, pick the event, add Custom Activities → Integration, and attach an Integration Center job. The job queries Employee Central fields and sends them to a destination.
  • SAP's worked example (KBA 2769349) uses an SFTP destination.
  • SAP's Help Portal documents REST outbound destinations. Check the destination types and authentication options in your tenant.
• The payload is whatever the Integration Center job defines. There's no fixed event schema.
• Throughput (partly confirmed, check the current KBA): KBA 3063887 advises keeping event-based Intelligent Services and Integration Center integrations under 500 events an hour. A REST endpoint should process each event within 30 seconds.

Flowstate

• REST API. https://{tenant}.flowstate.inc/api/v1/org/{orgId} with Authorization: Bearer <key>.
  • There's no upsert. GET /employees/{personIdExternal}, then POST on 404 or PATCH on 200. Contractors, vacancies and teams work the same way.
  • PATCH /employees/:id sets managerId, geographyId, workTypeId and noticeDate, and { "endDate": null } clears a leaving date.
  • See the recipe and Permissions by endpoint.
• Why not a custom integration. crypto isn't available in a hook, so it can't sign a SAML assertion. See Context API.

SAP documentation

• Which API to use (KBA 2613670)
• API servers by data centre (KBA 2215682)
• OData API enablement (KBA 2250344)
• OAuth SAML bearer assertion (KBA 3462403) and OAuth FAQ (KBA 3146449)
• Basic authentication retirement (KBA 3472405)
• User mode and admin mode (KBA 2732680)
• Position MDF permissions (KBA 2390866)
• Intelligent Services events (KBA 2534598) and Integration Center with Intelligent Services (KBA 2769349)
• Effective-dated queries (KBA 2148752) and lastModifiedDateTime on effective-dated entities (KBA 2920680)
• Snapshot paging (KBA 3308165)
• Person and user IDs (KBA 2495643)
• FTE and standard hours (KBA 2576250)
• Manager through the User entity (KBA 3008583)
• Recurring pay components (KBA 3515091)