SAP SuccessFactors

​

Overview

• Badge readers and gate terminals publish clock-in / clock-out punches on MQTT, and the connector sends them to Clock In Clock Out.
• A kiosk or HMI books or cancels an absence, or shows the remaining vacation balance.
• Line planning and andon boards read who is assigned to a plant and department, with standard hours (EmpJob with asOfDate).

​

Setup

1. Create or choose an API user with role-based permissions for the entities the broker uses (for example User, Employee Central job information, Time Off) and Employee Central API / SFAPI access. Every call runs with this user’s permissions.
2. In Admin Center > Manage OAuth2 Client Applications, register a client: application name and URL, Bind to Users with the API user, and Generate X.509 Certificate. Download the certificate (it holds the private key) and save the API Key (the client_id).
3. For Clock In Clock Out punches, register a second client bound to the technical user TECHNICAL_USER_CICOTERMINAL_9D3F8AC1. SuccessFactors accepts punches only with that user’s token (SAP KBA 3206348).
4. Note your company ID. Keep SF_COMPANY_ID, SF_CLIENT_ID, the private key or assertions, and the current token in broker secrets and inject them with GET SECRET.

​

Authentication

1. Get a SAML assertion for the API user, signed with the client’s private key. Generate it outside the broker (for example with SAP’s assertion generator or an integration platform), or use SamlAssertion (POST /oauth/idp with client_id, user_id, token_url, private_key). SAP has deprecated /oauth/idp because the private key travels in the call (KBA 3239495); it still answers today, but prefer generating the assertion yourself.
2. Get a token with OAuthToken: POST /oauth/token with company_id, client_id and assertion (the grant type urn:ietf:params:oauth:grant-type:saml2-bearer is fixed in the template). The reply has access_token, token_type Bearer and expires_in.
3. Every other event sends Authorization: Bearer <access_token> from the payload. TokenValidate checks a token.

{"company_id": "<SF_COMPANY_ID>", "client_id": "<SF_CLIENT_ID>", "assertion": "<URL-encoded SAML assertion>"}

​

Events

​

Payloads

​

Basic Syntax

DEFINE ROUTE SapSuccessFactorsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_API_SERVER"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT OAuthToken
        WITH SOURCE_TOPIC "finance/sap-successfactors/auth/token"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/auth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "company_id={value.json.company_id}&client_id={value.json.client_id}&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&assertion={value.json.assertion}"
    ADD EVENT EmpJobList
        WITH SOURCE_TOPIC "finance/sap-successfactors/jobs/list"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/jobs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/odata/v2/EmpJob?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EmployeeTimeCreate
        WITH SOURCE_TOPIC "finance/sap-successfactors/employee-time/create"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/employee-time/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/odata/v2/EmployeeTime"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT Upsert
        WITH SOURCE_TOPIC "finance/sap-successfactors/odata/upsert"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/odata/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/odata/v2/upsert?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TimeEventsCreate
        WITH SOURCE_TOPIC "finance/sap-successfactors/clock/events/create"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/clock/events/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/timemanagement/timeeventprocessing/v1/TimeEvents"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"

​

Examples

​

Keep a token for the other actions

DEFINE MODEL SfTokenRequest COLLAPSED
    ADD STRING "company_id"
    ADD STRING "client_id"
    ADD STRING "assertion"

DEFINE ACTION SfToken
ON TOPIC "state/sf/assertion" DO
    SET "company" WITH GET SECRET "SF_COMPANY_ID"
    SET "client" WITH GET SECRET "SF_CLIENT_ID"
    SET "assertion" WITH PAYLOAD AS STRING
    PUBLISH MODEL SfTokenRequest TO "finance/sap-successfactors/auth/token" WITH
        company_id = {company}
        client_id = {client}
        assertion = {assertion}

DEFINE ACTION SfKeepToken
ON TOPIC "finance/sap-successfactors/auth/token/response" DO
    SET "token" WITH (GET JSON "access_token" IN PAYLOAD AS STRING)
    KEEP TOPIC "state/sf/access_token" WITH {token}

​

Who works where today

DEFINE MODEL SfQuery COLLAPSED
    ADD STRING "access_token"
    ADD STRING "query"

DEFINE ACTION SfShiftRoster
ON EVERY 60 MINUTES DO
    SET "token" WITH (GET TOPIC "state/sf/access_token" AS STRING)
    PUBLISH MODEL SfQuery TO "finance/sap-successfactors/jobs/list" WITH
        access_token = {token}
        query = "$filter=location%20eq%20'PORTO'&$select=userId,jobTitle,department,location,standardHours,managerId&$top=200"

​

Send badge punches to Clock In Clock Out

{"access_token": "<CICO access_token>", "body": [{"id": "1", "assignmentId": "cgrant", "typeCode": "P10", "timestamp": "2026-10-05T07:58:00+01:00", "terminalId": "PORTO-GATE-1", "timeTypeCode": "WORKING_TIME"}]}

{"access_token": "<access_token>", "query": "$filter=workAssignmentId%20eq%20'cgrant'%20and%20timestampUTC%20ge%202026-10-05T00:00:00Z&$orderby=timestampUTC&$top=100"}

​

Book and cancel an absence

{"access_token": "<access_token>", "body": {"externalCode": "CF-0001", "userId": "cgrant", "timeType": "TT_VAC_REC", "startDate": "/Date(1791763200000)/", "endDate": "/Date(1791763200000)/", "comment": "Booked from the plant kiosk"}}

{"access_token": "<access_token>", "query": "$format=json", "body": {"__metadata": {"uri": "EmployeeTime('CF-0001')"}, "externalCode": "CF-0001", "approvalStatus": "CANCELLED"}}

​

Notes

• Effective-dated entities (EmpJob, EmpEmployment, Foundation Objects) return the record valid today unless you pass asOfDate, or fromDate / toDate for history.
• EmpJob cannot be created with POST; it is upsert only (the metadata marks it upsertable, not creatable). Upsert works for any upsertable entity, but HR master data changes usually belong in SuccessFactors itself; the template only shows time records.
• TimeEventsExport needs the export permission; without it SuccessFactors returns an empty list with 200.
• Use Metadata (/odata/v2/<entity>/$metadata) to see the custom fields of your instance, and EntityQuery to read entity sets that have no dedicated event.
• Errors: OData v2 returns 401 with [LGN0007]Invalid OAuth token for a bad token; the Clock In Clock Out APIs answer 401 AuthenticationRequired without a token and 400 AuthenticationFailed for a malformed one; /oauth/token answers 400 with errorHttpCode / errorMessage.
• Not packaged on purpose: every DELETE, the Clock In Clock Out mass delete (PATCH with deleted: true), PUT / MERGE updates (use Upsert), $batch, SFAPI and Compound Employee, the OData v4 Employee Central APIs, and HTTP Basic authentication.

​

Status