Managing employee data in Oracle Fusion Cloud HCM from BMC Helix Business Workflows by using Jitterbit Harmony

To perform multiple Oracle Fusion Cloud Human Capital Management (HCM) operations from BMC Helix Business Workflows, use the prebuilt integration template provided by BMC Helix iPaaS, powered by Jitterbit. For example, you can retrieve employee information from Oracle Fusion Cloud HCM to BMC Helix Business Workflows or update an employee's address or legal name in Oracle Fusion Cloud HCM. 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:

The following image shows an example of employee details from Oracle Fusion Cloud HCM in a BMC Helix Business Workflows case:

Oracle Fusion Cloud HCM to BMC Helix Business Workflows data flow

The following image shows how to retrieve employee data from Oracle Fusion Cloud HCM to BMC Helix Business Workflows:

BMC Helix Business Workflows to Oracle Fusion Cloud HCM data flow

The following image shows how to update the address of an employee in Oracle Fusion Cloud HCM from BMC Helix Business Workflows:

The following image shows how to update an employee's legal name in Oracle Fusion Cloud HCM from BMC Helix Business Workflows:

Before you begin

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

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

1. Download the Manage Employee Information in Oracle HCM via BMC Helix Business Workflows 2023-05-01  file to your system.
   This file contains the BMC Helix iPaaS Cloud Studio project Manage Employee Information in Oracle HCM 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 Oracle HCM via BMC Helix Business Workflows 2023-05-01.json 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 Oracle HCM via BMC Helix Business Workflows project, and click View/Edit.

Task 2: 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 Oracle Fusion Cloud HCM and BMC Helix iPaaS applications

     Project variable	Action
     Oracle Fusion Cloud HCM
     OracleHCM_UserName	Enter the user name to access the Oracle Fusion Cloud HCM instance.
     OracleHCM_Password	Enter the password for the user name to access the Oracle Fusion Cloud HCM instance.
     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_Integration_API_Name	Enter the name for the Webhook API that is created in Oracle Fusion Cloud HCM.
     Jitterbit_Integration_API_Security_Profile_Type	Enter a security profile type. You can set the following values for this variable: BASIC ANONYMOUS APIKEY 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, APIKEY). 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.
     Jitterbit_Integration_API_Security_Profile_BASIC_Auth_Username	For security profile type BASIC, enter the user name 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	For security profile type APIKEY, enter the name of the APIKEY to set on the security profile. This APIKEY is used for authentication by the Jitterbit API and the Webhook API.

   • 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 3: To review out-of-the-box field mappings

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

Task 4: To deploy and enable the project

After you enable the project, you can perform multiple Oracle Fusion Cloud HCM operations. For example, you can retrieve employee information from Oracle Fusion Cloud HCM to BMC Helix Business Workflows or update an employee's address or legal name in Oracle Fusion Cloud HCM.

Task 5: To retrieve the BMC Helix Business Workflows operation details from the Oracle Fusion Cloud HCM API

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

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

2. Open the API created for Oracle Fusion Cloud HCM.
   The API name is the value that you entered for the Jitterbit_Integration_API_Name variable.
3. 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 Oracle Fusion Cloud HCM operation. For example, https://<hostname>/<environmentName>/<integrationName>/<OracleOperation>.
   2. Add this URL as the Path value when you define the web requests for the Oracle Fusion Cloud HCM use cases in BMC Helix Business Workflows. Replace <OracleOperation> 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 Oracle Fusion Cloud HCM data, you can perform multiple actions in Oracle Fusion Cloud HCM. For example, you can retrieve employee information from Oracle Fusion Cloud HCM to BMC Helix Business Workflows or update an employee's address or legal name in Oracle Fusion Cloud HCM.

(Optional) Task 6: 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 during the debug mode. To increase the duration of the debug mode, perform the following steps:

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

2. Open the Oracle Fusion Cloud HCM API.

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

4. Save and publish the API.

Task 7: To configure BMC Helix Business Workflows to use the Oracle Fusion Cloud HCM API by using BMC Helix iPaaS

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

To define a document schema for each Oracle Fusion Cloud HCM use case 

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

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, Oracle Fusion Cloud HCM - 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	{ "id" : "", "AddressLine1": "", "AddressLine2": "", "AddressLine3": "", "TownOrCity": "",  "PostalCode": "", "EffectiveStartDate": "" }	Important: Currently, you cannot add any custom fields to update the employee's address. Only the listed address fields are supported.
      Update Employee Legal Name	{  "id" : "",  "EffectiveStartDate" :  "FirstName" :"",  "LastName" :"", }	The following fields are mandatory:  id EffectiveStartDate Based on the requirements of your organization, you can add either FirstName or LastName, or both these fields. Important: Currently, you cannot add any custom fields to update the employee's legal name. Only the listed fields are supported.

   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, Oracle Fusion Cloud HCM - 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	Note
      Get Employee Data	{   "PersonNumber": "",   "DateOfBirth": "",   "CountryOfBirth": "",   "FirstName": "",   "LastName": "",   "Email": "",   "WorkPhone": "",   "Country": "",   "City": "",   "AddressLine1": "",   "AddressLine2": "",   "AddressLine3": "",   "Postalcode": "",   "HireDate": "",   "TerminationDate": "",   "AssignmentId": "",   "AssignmentEffectiveStartDate": "",   "BusinessUnitName": "",   "UserPersonType": "",   "JobCode": "",   "DepartmentName": "",   "AssignmentCategory": "",   "Basic Salary": "",   "CurrencyCode": "",   "SalaryFrequency": "" }	Important: Currently, you cannot add any custom fields to retrieve the employee information. Only the listed fields are supported.

      Important

      You do not need to define a response document schema for the Update Employee Address and Update Employee Legal Name workflows.

   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, click New Web Request. 

   You must add a web request for each Oracle Fusion Cloud HCM 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, Oracle Fusion Cloud HCM - 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 Oracle Fusion Cloud HCM operation. Enter the path starting from the /environment name in the URL. Replace <OracleOperation>  with one of the following values, depending on the operation you want to perform: getEmployee  updateEmployeeAddress  updateEmployeeName Format of the URL: /<environmentName>/<integrationName>/<OracleOperation> 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 Oracle Fusion Cloud HCM data on your template.
   1. Log in to BMC Helix Business Workflows and click My Application Settings .
   2. Select 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	Action
      Get Employee Data	Employee ID Birth Date First Name Last Name Email Address Phone Number Country City Address Line 1 Address Line 2 Street Address Postal Code Hire Date Termination Date Assignment ID Assignment Effective Start Date Business Unit Name User Person Type Job Code Department Name Assignment Category Basic Salary Currency Code Salary Frequency	You can choose the dynamic fields that you want to include in the template. However, a BMC Helix Business Workflows case or task that uses this template will display only the employee details for the fields that you have added.
      Update Employee Address	Employee ID Effective Date for Address Change Address Line 1 Address Line 2 Street Address City Postal Code	The following fields are mandatory:  Employee ID Effective Date for Address Change You can add other fields based on the requirements of your organization.
      Update Employee Legal Name	Employee ID Effective Date for Name Change First Name Last Name	The following fields are mandatory:  Employee ID Effective Date for Name Change You can add other fields based on the requirements of your organization.

      Important

      The Employee ID field in BMC Helix Business Workflows is mapped to the PersonNumber field in Oracle Fusion Cloud HCM. 

      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 Oracle Fusion Cloud HCM.

   1. Log in to BMC Helix Business Workflows and click My Application Settings .
   2. Select 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 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.

   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 Oracle Fusion Cloud HCM 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. Select 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	Note
      Get Employee Data	Employee ID	NA
      Update Employee Address	Employee ID Effective Date for Address Change Address Line 1 Address Line 2 Street Address City Postal Code	The following fields are mandatory:  Employee ID Effective Date for Address Change You can add other fields based on the requirements of your organization.
      Update Employee Legal Name	Employee ID Effective Date for Name Change First Name Last Name	The following fields are mandatory:  Employee ID Effective Date for Name Change You can add other fields based on the requirements of your organization.

      Important

      The Employee ID field in BMC Helix Business Workflows is mapped to the PersonNumber field in Oracle Fusion Cloud HCM.  

   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 Oracle Fusion Cloud HCM operations, the Oracle Fusion Cloud HCM 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

This workflow defines the operations required to enable the integration after all the required project configurations are completed. The following operations are included in this workflow:

Master Controller

This workflow determines an operation to be called based on details provided in the project variables. The following operation is included in this workflow:

Get Employee details from Oracle HCM

This workflow gets employee information from Oracle Fusion Cloud HCM to BMC Helix Business Workflows. This information can be used to view details available in Oracle Fusion Cloud HCM in your BMC Helix Business Workflows record. The following operations are included in this workflow:

Update Employee Home Address

This workflow updates an employee's home address in Oracle Fusion Cloud HCM when you update the address details in BMC Helix Business Workflows. The following operations are included in this workflow:

Update Employee Legal Name

This workflow updates the legal name of an employee in Oracle Fusion Cloud HCM when you update the name in BMC Helix Business Workflows. The following operations are included in this workflow:

Error Handling

This workflow sends email notifications if operations are successful or failed. The following operation is included in this workflow: