An owner or admin on the Business plan connects your SAP SuccessFactors instance in Settings, under Integrations, with your API server address and the details of an OAuth client you register in SuccessFactors for SignWren. After that, an onboarding template can be filled from the new hire’s onboarding process, and when everyone has signed, the signed PDF is attached to the new hire in SuccessFactors.

SignWren connects to your own SuccessFactors instance through SAP’s published OData API. It isn’t an SAP product, and SAP doesn’t review or endorse it.

What do we set up in SuccessFactors first?

Someone who administers SuccessFactors does these steps:

  1. An API user. Pick or create the user SignWren’s calls run as. Its role needs the Onboarding object permission for ONB2Process (to read onboarding processes) and, under Manage Integration Tools, “OData API Attachment Import” and “OData API Attachment Export” (to add the signed PDF and to check it isn’t there already).
  2. A key pair and certificate. Make an RSA key pair and an X.509 certificate for it with your own tools, or generate one in SuccessFactors. SAP recommends SHA-2; SHA-1 is no longer accepted. You keep the private key; SuccessFactors gets the certificate.
  3. An OAuth client. In Admin Center, go to API Center, then OAuth Configuration for OData, and choose Register Client Application. Give it a name and a URL (it is only used to identify the client), paste the certificate without its BEGIN and END lines, and register it. If you bind the client to users, include the API user from step 1. Then choose View on the client to see its API key.

How do we connect it in SignWren?

  1. Go to Settings, then Integrations, and choose Connect next to SAP SuccessFactors.
  2. Enter your API server address, such as https://api17.sapsf.com. It is the API server of your data center from SAP’s list, not the address you sign in at, and not a “.cert” address.
  3. In the API key box, paste one JSON value with four parts:
{"companyId": "ACMECORP", "userId": "signwren_api", "apiKey": "<the client's API key>", "privateKey": "<the private key in PEM form, line breaks written as \n>"}

SignWren checks the details by signing in and reading one onboarding process and one attachment, then stores them encrypted. For each request it signs a short-lived SAML assertion with the private key, the way SAP’s OAuth guide describes, and swaps it for an access token. The private key never leaves SignWren’s encrypted store and is never shown again.

User name and password instead? SignWren also accepts Basic sign-in, with the user name written as username@companyID. SAP has deprecated Basic sign-in for its APIs and says it will be retired, so use it only until your OAuth client is ready.

Which merge fields can a template use?

Link the envelope to an onboarding process (ONB2Process, by its process ID) or to a user (by user ID). These names fill from SuccessFactors:

  • onboarding.process_id, onboarding.target_date, onboarding.status
  • new_hire.user_id, new_hire.first_name, new_hire.last_name, new_hire.full_name, new_hire.email, new_hire.department
  • manager.user_id, manager.first_name, manager.last_name, manager.full_name, manager.email

A field the record doesn’t have stays empty, so check the draft before sending.

Where does the signed PDF go?

It is added as an attachment of the new hire’s user, in the Onboarding module unless your connection settings say otherwise. SAP’s documentation says such attachments can be found in Manage Documents. On the connection’s settings you can pick the module, a module category and a document category code, if your SuccessFactors admin uses them.

One thing to check on your instance: SAP’s documentation doesn’t describe a way to file a document straight into an onboarding activity of the current Onboarding product, so look at where the first signed copy shows up and adjust the settings with your admin.

SuccessFactors accepts attachments up to 5 MB by default; a bigger signed PDF stays in SignWren and the envelope page says why. If SignWren has to try again, it first looks for the copy it already added, so one envelope never adds two.

What if filing fails?

SignWren retries for up to three days. If SuccessFactors refuses the request, for example because the API user lacks a permission or the OAuth client was disabled, the envelope page shows “Couldn’t save to SAP SuccessFactors” with the reason, and the sender gets one email. A refused sign-in marks the connection “Needs reconnect” in Integrations. The signed PDF stays in SignWren either way.