Managing employee data in SAP SuccessFactors from BMC Helix Business Workflows by using Jitterbit Harmony

To perform multiple SAP SuccessFactors operations from BMC Helix Business Workflows, use the prebuilt integration template provided by BMC Helix iPaaS, powered by Jitterbit. To use the integration template with the values defined out of the box, update the project variables with details of your systems and deploy the integration template. 

The template provides the following capabilities:

SuccessFactors to BMC Helix Business Workflows data flow

The following image gives an overview of the data flow for retrieving employee data from SuccessFactors to BMC Helix Business Workflows:

BMC Helix Business Workflows to SuccessFactors data flow

The following image gives an overview of the data flow for updating the address of an employee in SuccessFactors from BMC Helix Business Workflows:

The following image gives an overview of the data flow for updating an employee's legal name in SuccessFactors from BMC Helix Business Workflows:

Before you begin

You require the following items to successfully set up and use this integration: 

Task 1: To configure data access permissions in SuccessFactors

To get access to employee data in SuccessFactors, set the permissions to view and edit employee details required for each use case.

1. Log in to SAP SuccessFactors and navigate to Admin Center. 
2. In the Tools section, click Manage Permission Roles. 
3. In the Permission Role List section, selected the required permission role. 
4. On the Permission Role Detail page, click the Permissions... button.
5. Under User Permissions, select Employee data.
6. Select the View or Edit option, or both for each employee data field that you must have access to. 
7. Click Done.

Based on the permissions assigned, you can view or edit information in an employee profile in SuccessFactors.

Learn more about setting permissions in Configuring Permissions in SuccessFactors Admin Center . 

Task 2: To download and import the integration template project file

1. Download the Manage Employee Information in SucessFactor via BMC Helix Business Workflows 2024-03-01  file to your system.
   This file contains the BMC Helix iPaaS Cloud Studio project Manage Employee Information in SucessFactor via BMC Helix Business Workflows.

   Important

   Your ability to access product pages on the EPD website is determined by the license your company purchased.

2. As a developer, log in to BMC Helix iPaaS and navigate to the Cloud Studio.
3. On the projects page, click Import.
4. Click Browse and then select the Manage Employee Information in SucessFactor via BMC Helix Business Workflows 2024-03-01 file you downloaded. 
   The Project Name and Organization fields are automatically populated depending on the values defined. 
5. From the Environment list, select the environment to which you want to import this integration template, and click Import.
   The project opens after the integration template is imported. 
6. To open the project file at a later time, select the environment where the integration templates are available, select the Manage Employee Information in SucessFactor via BMC Helix Business Workflows project and click View/Edit.

Task 3: To update the project variables for the integration template

1. Next to the Environment name, click the ellipses ... icon and select Project Variables.
2. Update the following project variables:

   • Access points and authentication details for SuccessFactors and BMC Helix iPaaS applications

     Project variable	Action
     SuccessFactors
     SuccessFactor_Autorization_Key	Enter the authorization key to access SuccessFactors. The authorization key is a Base64 format of username@companyname:password. username represents the SuccessFactors user ID. companyname represents a company of the user. password represents the password of the user to access SuccessFactors.
     BMC Helix iPaaS
     Jitterbit_Url	Enter the URL to access BMC Helix iPaaS in the following format: [http/https]://[host name and port]
     Jitterbit_User	Enter the user ID to access BMC Helix iPaaS.
     Jitterbit_User_Password	Enter the password of the user ID to access BMC Helix iPaaS.

   • Webhook API variables

     Project variables	Action
     BHIP_API_TimeOut	Enter a value, in seconds, for an API timeout. The minimum value must range between 30 and 180. By default, the value is set to 60.
     BHIP_API_User_Roles	Enter comma-separated values of the user roles assigned for the BMC Helix iPaaS API. Only a user with these roles can access the APIs. Leave this value blank to restrict access only to administrators.
     Jitterbit_Project_Name	Enter the name of the SuccessFactors project for which you want to create the Webhook API. If you leave this value empty, the current project name is used.
     Jitterbit_Operation_Name	Enter the name of the operation to trigger when the Webhook API is triggered. This value is added to the BMC Helix iPaaS Jitterbit API. By default, this value is empty. You must enter the name if the main operation name has been changed.
     Jitterbit_Integration_API_Name	Enter the name for the Webhook API that is created in SuccessFactors.
     Jitterbit_Integration_API_Method	Enter the REST API method that is used by the Webhook API. This value is added to the BMC Helix iPaaS Jitterbit API. The following values are valid: POST GET PUT The default value is POST.
     Jitterbit_Integration_API_Response_Type	Enter the REST API response type used by the Webhook API created. This value is added to the BMC Helix iPaaS Jitterbit API.  The following values are valid: FINAL_TARGET VARIABLE The default value is VARIABLE.
     Jitterbit_Integration_API_Security_Profile_Type	Enter a security profile type. You can set the following values for this variable: BASIC ANONYMOUS The default value is BASIC. A security profile type defines the authentication type to be used by the Webhook API. This value is added to the BMC Helix iPaaS Jitterbit API. Enter comma separated values to select multiple profile types (ANONYMOUS, BASIC). Important: For profile types supported by the source application, the security profiles are automatically created by the integration template when you enable the integration.  BMC Helix iPaaS does not support OAuth authentication. BMC Helix Business Workflows does not support APIKEY authentication.
     Jitterbit_Integration_API_Security_Profile_Name_Suffix	Enter the suffix to be added to the name of security profiles created.
     Jitterbit_Integration_API_Security_Profile_BASIC_Auth_Username	For security profile type BASIC, enter the user name to be used to create the security profile. The Jitterbit API and the Webhook API use this user name for authentication.
     Jitterbit_Integration_API_Security_Profile_BASIC_Auth_Password	For security profile type BASIC, enter the password for the security profile created. The Jitterbit API and the Webhook API use this user name for authentication.
     Jitterbit_Integration_API_Security_Profile_ApiKey_Name	This authentication method is not supported for BMC Helix Business Workflows.

   • Email notification configurations

     Project variable	Action
     Jitterbit_SMTP_HOSTNAME	Enter the SMTP host details for email configuration.
     Jitterbit_To_Email_Address	Enter the email address to which you want to send the notification emails.  Enter comma separated values to select multiple email addresses.
     Jitterbit_From_Email_Address	Enter the email address from which the notification emails must be sent.
     Jitterbit_Email_Enabled	Define if notification emails must be sent. By default, the value is set to true. To disable email notifications, change the default value to false.
     Jitterbit_Email_Data_Error	Define if emails must be sent if an error occurs in the workflow. By default, this value is set to true. To disable email notifications for errors in workflows, set the value to false.
     Jiiterbit_Email_On_Success	Define if emails must be sent if the workflow is successful. By default, this value is set to true. To disable email notifications for successful operations, set the value to false.

(Optional) Task 4: To review out-of-the-box field mappings

The following table lists out-of-the-box field mappings defined between the SuccessFactors and BMC Helix Business Workflows fields: 

Task 5: To deploy and enable the project

After you enable the project, you can perform multiple SuccessFactors operations, such as retrieving employee information from SuccessFactors or updating an employee's address or legal name in SuccessFactors, by creating a case in BMC Helix Business Workflows.

Task 6: To retrieve the BMC Helix Business Workflows operation details from the SuccessFactors API

To complete the integration, retrieve service URLs for the operations you want to perform by using the integration.

1. Select API Manager > My APIs.

2. Open the SuccessFactors API and perform the following operations:
   1. From the top of the page, copy the service URL. 
      The format of the service URL includes the BMC Helix iPaaS host name, environment, and the SuccessFactors operation. For example, https://<hostname>/<environmentName>/<integrationName>/<SuccessFactorsOperation>.
   2. Add this URL as the Path when you define the web requests for the SuccessFactors use cases in BMC Helix Business Workflows. Replace <SuccessFactorsOperation> with one of the following values, depending on the operation you want to perform:
      
      • getEmployee 
      • updateEmployeeAddress 
      • updateEmployeeName

After you enable the integration and configure BMC Helix Business Workflows to receive the SuccessFactors data, you can perform multiple actions in SuccessFactors, such as retrieving employee information from SuccessFactors or updating an employee's address or legal name in SuccessFactors.

(Optional) Task 7: To set the time for API debug mode

By default, the debug mode is set to 2 hours after you run the integration. Debug logs are updated for the time set for the debug mode. To increase the debug mode for a longer period of time, perform the following steps:

1. In BMC Helix iPaaS, powered by Jitterbit, select API Manager > My APIs.

2. Open the SuccessFactors API.

3. Select Enable Debug Mode Until: and set it for the required date and time.

4. Save and publish the API.

Task 8: To set up BMC Helix Business Workflows to use the SuccessFactors API by using BMC Helix iPaaS

After you deploy the integration, configure BMC Helix Business Workflows to use the SuccessFactors API to perform operations in SuccessFactors from BMC Helix Business Workflows. Complete the following procedures to configure BMC Helix Business Workflows to use SuccessFactors APIs.

To define a document schema for each SuccessFactors use case 

For each SuccessFactors use case, create a document definition to establish the request and response communication between BMC Helix Business Workflows and SuccessFactors. 

1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab. 

2. Select the BMC Helix Business Workflows application.

3. On the Documents tab, click New.

4. To create a Request document definition for a specific use case, perform the following steps:
   1. In the Document Name field, enter a unique name to identify the use case for which to use the document, for example, SuccessFactors - Request - Get Employee Data.

   2. In the Document Schema field, enter the document schema for the Request format as described in the following table:
      

      Use Case	Request Document Schema	Note
      Get Employee Data	{"id":""}	NA
      Update Employee Address	{  "Address Type": "",  "Employee Id": "",  "Effective Date for Address Change": "",  "Address Line 1": "",  "Address Line 2":"",  "State": "",  "City": "",  "Country": "",  "Postal Code": "", }	NA
      Update Employee Legal Name	{  "Employee ID": "",  "Effective Date for Name Change": "",  "Last Name": "",  "First Name": "" }	The following fields are mandatory:  Effective Date for Name Change Employee ID First Name Last Name

   3. In the Scope/Customization Options field, define the scope of the document definition by selecting the Public option. 
   4. Click Save.
5. To create a Response document definition for a specific use case, perform the following steps:
   1. In the Document Name field, enter a unique name to identify the use case for which to use the document, for example, SuccessFactors - Response - Get Employee Data.

   2. In the Document Schema field, enter the document schema for the Response format as described in the following table:
      

      Use Case	Response Document Schema
      Get Employee Data	{ "gender" : "", "firstName" : "", "lastName" : "", "maritalStatus" : "", "employeeId" : "" , "Country" : "", "City" : "", "Address1" : "", "Address2" : "", "PostalCode" : "" , "jobTitle" : "", "workerCategory" : "", "company" : "", "position" : "", "managerId" :"", "emplStatus" : "", "emailAddress":"", "phone":"", "Basic Salary":"" "fte" : "" }
      Update Employee Address	{ "key": "", "status": "", "editStatus": "", "message": null, "index": 0, "httpCode": 200, "inlineResults": null }
      Update Employee Legal Name	{ "key": "", "status": "", "editStatus": "", "message": null, "index": 0, "httpCode": 200, "inlineResults": null }

   3. In the Scope/Customization Options field, define the scope of the document definition by selecting the Public option. 

   4. Click Save. 

For additional details about defining a document schema, see Defining a document schema .

To create a REST API web service request definition for the Jitterbit API 

1. Log in to BMC Helix Innovation Studio. 
2. On the Workspace tab, select Business Workflows. 

3. Click the Web APIs tab and click New. 

4. On the  Properties tab, provide a name for the RESTful Service, such as Jitterbit API.

5. On the New Web API page, to create a new Web API, click New Web Request. 

   You must add a web request for each SuccessFactors use case.

6. On the Settings tab, fill out the fields as described in the following table:

   Field	Description
   Name	Type a name for the web request. For example, SuccessFactors - Get Employee Data.
   Request Method	Select POST.
   (Optional) Multipart Request	Do not turn on this toggle key.
   Path	Enter the URL path of the Jitterbit API copied after deploying the project. The format of the service URL includes the BMC Helix iPaaS host name, environment and the SuccessFactors operation. Enter the path starting from the /environment name in the URL. Replace <SuccessFactorsOperation>  with one of the following values, depending on the operation you want to perform: getEmployee  updateEmployeeAddress  updateEmployeeName Format of the URL: /<environmentName>/<integrationName>/<SuccessFactorsOperation> Important: If you have added the path parameters in the Path field, the parameters are populated automatically in the Path Parameters field.
   Body	Select the document definition you created for the request.
   Response	Select the document definition you created for the response.
   Error on Unsuccessful Response	Select this option so that if an error occurs when the web API is run, the process associated with the web API is not run.
   (Optional) Add Headers	Add the headers for this web request.
   (Optional) Query Parameters	Add the query parameters for this web request.
   Encode Request Parameters	Turn on the toggle key to encode the following parameters: Path parameter and its value Query parameter and its value Important: You cannot choose the parameters or values that you want to encode. If you do not encode the parameters, the values in the Path parameter and Query Parameters are applied as is.

7. Click Save. 

For more information, see Creating a REST API web service request definition .

To define the Web API connection for the BMC Helix iPaaS endpoint  

1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab. 
2. Select Integrations > Web APIs > Web API connections. 
3. On the Web API Connection page, click New.

4. On the General tab, enter the following information:

   Field	Description
   Name	Enter a meaningful name for the REST API web service connection, such as BMC Helix iPaaS Endpoint Connection.
   Host Name	Enter the hostname from the Service URL copied after deploying the project.
   Port	Enter 443.
   Protocol	Select HTTPS.
   Authentication	Select Basic Auth.

5. To add the authentication credentials, click Next. 

6. On the Authentication tab, enter the login credentials for the BMC Helix iPaaS admin user.

7. Click Save.

For additional details about creating a REST API web service request definition, see  Configuring the authentication credentials of REST API web services .

To map the REST API web service request alias to the BMC Helix iPaaS connection

1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab. 
2. Select Integrations > Web APIs > Web API mapping.

3. From the Application list, select bwfa.
   A list of web request aliases that you configured for the selected application are displayed as Connection Target.  

4. In Connection Configuration, select the authentication credentials for BMC Helix iPaaS. 

5. Click Save. 

For additional details about mapping the REST API web service request alias to the BMC Helix iPaaS connection, see  Mapping the REST API web service request alias to an appropriate connection .

To create an automated task template in BMC Helix Business Workflows 

1. Create an automated task template in BMC Helix Business Workflows.
   For more information about creating an automated task template, see  Automating tasks for quicker case resolution .

   Important

   When creating the automated task for Create New Process?, select Yes. 

2. Add dynamic fields to the task template to display the SuccessFactors data on your template.
   1. Log in to BMC Helix Business Workflows and click My Application Settings .
   2. Navigate to Task Management > Templates.
   3. Select the created task template for an automated task. Ensure that the template is not in the Active status.
   4. On the template page, click Manage Process Fields.

   5. Add the required dynamic fields for the use case for which you are creating the template, as described in the following table:

      Use Case	Dynamic fields
      Get Employee Data	Employee ID City First Name Last Name Gender Country Address Line 1 Address Line 2 Job Title Employee Manager Job Position Birth Date Basic Salary Email Address Phone Number Postal Code
      Update Employee Address	Employee ID Country State/Province City Address Line 1 Address Line 2 Effective Date for Address Change Address Type Postal Code
      Update Employee Legal Name	Employee ID First Name Last Name Effective Date for Name Change

      Important

      The Employee ID field in BMC Helix Business Workflows is mapped to the Person ID field in SuccessFactors. 

      For more information about adding dynamic fields, see the To add dynamic fields to the task template for an automated task section in Automating tasks for quicker case resolution .

3. Add the required elements to the task process to post and get data from SuccessFactors.

   1. Log in to BMC Helix Business Workflows and click My Application Settings .
   2. Navigate to Task Management > Templates.
   3. Select the created task template for an automated task. Ensure that the template is not in the Active status.
   4. On the template page, click Edit Process.
      The Input Variables are added to the process properties.

   5. From the Elements palette, drag the following process elements for the selected use case to the process canvas:

      • Create Document
      • Web Request
      • Update Task Data

   6. In the General Properties pane, enter a Name and Description for the element.

   7. In the Element Properties pane, enter the properties for the element for the selected use case.

       Get Employee Data

      Element	Input Map fields	Action
      Create Document	Document Definition Name	Select the document definition that you created for the Request format of the Get Employee Data use case.
      	Add/Remove Document Nodes	Click and select the fields added to the document schema for the Request format of the Get Employee Data use case. After you add the fields, click Click to build an expression and map the values to the dynamic fields in the expression builder.
      Web Request	Connection	Select the BMC Helix iPaaS connection created for the Jitterbit Rest API services.
      	Web API	Select the REST API web service request definition.
      	Request	Select the Web API for the Get Employee Data use case created in the Rest API web service request definition.
      	Document	Click Click to build an expression and map this value to the Output element in the expression builder.
      Update Task Data	Task ID	Click Click to build an expression and map the ID field of the Record Instance to this field.
      	Document Definition Name	Select the document definition that you created for the Response format of the Get Employee Data use case.
      	Add/Remove Document Nodes	Click and select the fields added to the document schema for the Response format of the Get Employee Data use case. After you add the fields, click Click to build an expression and map the values to the dynamic fields in the expression builder.

       Update Employee Address

      Element	Input Map fields	Action
      Create Document	Document Definition Name	Select the document definition that you created for the Request format of the Update Employee Address use case.
      	Add/Remove Document Nodes	Click and select the fields added to the document schema for the Request format of the Update Employee Address use case. After you add the fields, click Click to build an expression and map the values to the dynamic fields in the expression builder.
      Web Request	Connection	Select the BMC Helix iPaaS connection created for the BMC Helix iPaaS Jitterbit Rest API services.
      	Web API	Select the REST API web service request definition.
      	Request	Select the Web API for the Update Employee Address use case created in the Rest API web service request definition.
      Update Task Data	Task ID	Click Click to build an expression and map the ID field of the Record Instance to this field.
      	Document Definition Name	Select the document definition that you created for the Response format of the Update Employee Address use case.
      	Add/Remove Document Nodes	Click and select the fields added to the document schema for the Response format of the Update Employee Address use case. After you add the fields, click Click to build an expression and map the values to the dynamic fields in the expression builder.

       Update Employee Legal Name

      Element	Input Map fields	Action
      Create Document	Document Definition Name	Select the document definition that you created for the Request format of the Update Employee Legal Name use case.
      	Add/Remove Document Nodes	Click and select the fields added to the document schema for the Request format of the Update Employee Legal Name use case. After you add the fields, click Click to build an expression and map the values to the dynamic fields in the expression builder.
      Web Request	Connection	Select the BMC Helix iPaaS connection created for the BMC Helix iPaaS Jitterbit Rest API services.
      	Web API	Select the REST API web service request definition.
      	Request	Select the Web API for the Update Employee Legal Name use case created in the Rest API web service request definition.
      	Document	Click Click to build an expression and map this value to the Output element in the expression builder.
      Update Task Data	Task ID	Click Click to build an expression and map the ID field of the Record Instance to this field.
      	Document Definition Name	Select the document definition that you created for the Response format of the Update Employee Legal Name use case.
      	Add/Remove Document Nodes	Click and select the fields added to the document schema for the Response format of the Update Employee Legal Name use case. After you add the fields, click Click to build an expression and map the values to the dynamic fields in the expression builder.

   8. Click Save and return to the previous window to see the template details page.
   9. Change the status of the template to Active.

For more information about editing the task process, see the To edit process and manage dynamic fields associated with a task template for an automated task section in Automating tasks for quicker case resolution .

To create a case template in BMC Helix Business Workflows and associate the automated task template with it

1. Create a case template for each use case.
   For more information about creating a case template, see  Creating case templates and task templates .
2. Add the SuccessFactors fields that will be displayed as dynamic fields in the template.
   1. Log in to BMC Helix Business Workflows and click My Application Settings .
   2. Navigate to Case Management > Templates.
   3. Select the created case template. Ensure that the template is not in the Active status.
   4. On the template page, click Manage Process Fields.

   5. Add the required dynamic fields for the specific use case as described in the following table:

      Use Case	Dynamic fields
      Get Employee Data	Employee ID
      Update Employee Address	Employee ID Country State/Province City Address Line 1 Address Line 2 Effective Date for Address Change Address Type Postal Code
      Update Employee Legal Name	Employee ID First Name Last Name Effective Date for Name Change

      Important

      The Employee ID field in BMC Helix Business Workflows is mapped to the Person ID field in SuccessFactors. 

   6. Change the status of the template to Active.
      For more information about adding dynamic fields, see the To add a dynamic field to a case template or task template section in Adding dynamic fields for storing additional case information .
3. Associate the automated task template you created to this case template. 
   For more information about adding an automated task template to the case template, see the To associate a task template for an automated task to a case template section in Automating tasks for quicker case resolution .
   

Now, when you create a case by using the case template defined for the SuccessFactors operations, the SuccessFactors data is available in the case.

Workflows included in the integration template

The following workflows are defined as a part of the integration template. Refer to the following tables for an overview of the tasks defined in the workflow operations and configurations defined within each workflow.

Enable Integration

SuccessFactors Integration