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

BMC Helix iPaaS, powered by Jitterbit provides a prebuilt integration template that enables you to perform multiple Workday operations from BMC Helix Business Workflows. To use the integration template with the values defined out of the box, you update the project variables with details of your systems and deploy the integration template. 

The template provides the following capabilities:

Workday to BMC Helix Business Workflows data flows

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

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

The following image gives an overview of the data flow for creating a leave request in Workday from BMC Helix Business Workflows:

Before you begin

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

Make sure you have access to the following security profiles in Workday:

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

1. Download the Manage Employee Information in Workday via BMC Helix Business Workflows Update 2023-01-03 file to your system.
   This file contains the BMC Helix iPaaS Cloud Studio project Manage Employee Information in Workday 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 Workday via BMC Helix Business Workflows Update.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 Workday via BWF 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 ... and select Project Variables.
2. Update the following project variables:

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

     Project variable	Action
     Workday
     Workday_Host	Enter the name of the Workday host URL.
     Workday_Tenant	Enter the name of the Workday tenant.
     Workday_User_Name	Enter the Workday user ID.
     Workday_Password	Enter the password of the user to access Workday.
     BMC Helix iPaaS
     Jitterbit_Url	Enter the URL to access BMC Helix iPaaS.
     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
     Jitterbit_Project_Name	Enter the name of the Workday project for which you want to create the Webhook API.
     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 The default value is Master Controller.
     Jitterbit_Integration_API_Name	Enter the name for the Webhook API that is created in Workday.
     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 DELETE 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 in the BMC Helix iPaaS Jitterbit API.  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 in 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_Webhook_Security_Profile_Type	Define which authentication method to use, if multiple values are defined in the Jitterbit_Integration_API_Security_Profile_Type project variable.
     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 username to be used to create the security profile. The Jitterbit API and the Webhook API use this username 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 username for authentication.
     Jitterbit_Integration_API_Security_Profile_ApiKey_Name	This authentication method is not supported for BMC Helix Business Workflows.
     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 90.

   • Email notification configurations

     Project variable	Action
     Jitterbit_SMTP_Hostname	Enter the SMTP host details for email configuration.
     Jiiterbit_To_Email_Address	Enter the email address to which you want to send the notification emails.
     Jitterbit_From_Email_Address	Enter the email address from which the notification emails must be sent.
     Jiiterbit_Email_On_Success	To disable email notifications for successful operations, set the value to false. By default, this value is set to true.
     Jitterbit_Email_Enabled	To disable email notifications, change the default value to false. By default, the value is set to true.
     Jitterbit_Email_Data_Error	To disable email notifications for errors in workflows, set the value to false. By default, this value is set to true.

Task 3: To deploy and enable the project

After you enable the project, you can perform multiple Workday operations by creating a case in BMC Helix Business Workflows.

Task 4: To update the BMC Helix Business Workflows operation details in the Workday API

To complete the deployment, update the Workday API for the operations you want to perform by using the integration.

1. Select API Manager > My APIs.

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

After you enable the integration and configure BMC Helix Business Workflows to receive the Workday data, you can perform multiple actions in Workday.

(Optional) Task 5: 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 Workday API.

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

4. Save and publish the API.

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

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

Define a document schema for each Workday use case 

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. In the Create Document Definition window, enter a unique name to identify the use case for which to use the document, for example, Workday - Request - Get Employee Data.

5. For each Workday use case, add the document schema for the Request format as described in the following table:

   Use Case	Request Document Schema
   Get Employee Data	{"id":""}
   Update Employee Address	{"id":"", "StreetAddress":"", "City":"", "State":"", "PostalCode":"" }
   Get PTO Balance	{"id":""}
   Request for leave of absence	{ "id":"", "firstDayOfLeave":"", "lastDayOfWork":"", "estLastDayOfLeave":"" }
   Update Employee Legal Name	{"id":"", "Prefix" :"", "firstname" : "", "middlename":"", "lastname":"" }

6. For selected Workday use cases, add the document schema for the Response format, as described in the following table:

   Use Case	Response Document Schema
   Get Employee Data	{     "isSuccess": "1",     "code": null,     "message": null,     "jobTitle": "",     "employeeStartDate": "",     "employeeSalary": "",     "employeeID": "",     "userId": "",     "countryISOCode": "",     "firstName": "",     "middleName": null,     "lastName": "",     "emailAddress": "",     "phoneNumberAreaCode": "",     "phoneNumber": "",     "phoneExtention": null,     "phoneDeviceType": "",     "addressLine": "",     "municipality": "",     "region": "",     "postalCode": "",     "maritalStatus": "",     "placeOfBirth": null,     "dateOfBirth": "",     "gender": "",     "governmentId": "",     "governmentIdType": "",     "currencyCode": "" }
   Get PTO balance	{"Balance":""}
   Request for leave of absence	{ "isSuccess": "1", "code": null, "message": null }

   Important

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

7. Click Save. 

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

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 Workday 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, Workday - Get Employee Data.
   Request Method	Select POST.
   Path	Enter the URL path of the Jitterbit API copied in after deploying the project. The format of the service URL includes the BMC Helix iPaaS host name, environment and the workday operation. Enter only path starting from the /environment name in the URL, and replace <workdayOperation>  with one of the following values, depending on the operation you want to perform: getEmployee  updateEmployeeAddress  updateEmployeeName requestLeave  getPTOBalance Format of the URL: /<environmentName>/<integrationName>/<workdayOperation>
   Body	From the list, select the document definitions you created for the request.
   Response	From the list, 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	Select the toggle button 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 values in Path parameter and Query parameter are applied as-is.

   If you have added the path parameters in the Path field, the parameters are populated automatically in the Path Parameters field.

7. Click Save. 

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 Connections > Web APIs. 
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. On the Authentication tab, enter the login credentials for the BMC Helix iPaaS admin user.

6. Click Save.

For additional details about creating a REST API web service request definition, see  Creating a REST API web service request definition .

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 Configure My Server > Connection Mappings > Web API.

3. From the Select 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 .

Create an automated task template in BMC Helix Business Workflows and add it to a Case template

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 .
   When creating the automated task for Create New Process?, select Yes. 
2. Save the task template. 
   The task template is displayed.
3. To add the fields to display the Workday data on your task template, on the Task Template screen, click Manage Process Fields. 
   For more information about adding dynamic fields, see the To add dynamic fields to the task template for an automated task process in  Automating tasks for quicker case resolution .
4. To add the required elements to post and get data from Workday, click Edit Process.
   The Input Variables are added to the process properties.
5. To add the process elements, complete the following steps:

   1. From the Elements palette, drag the process elements to the process canvas.

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

   3. In the Element Properties pane, enter the properties for the element for the use case for which you are creating the template.

       Get Employee Details

      Element	Description
      Create Document	Input Map: Document Definition Name - Select the document definition that you created for the Request format of the use case. Add/Remove Document Nodes - Click and select the fields added to the Request data schema of the Get Employee Details 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	Input Map: 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 Details use case created in the Rest API web service request definition. Document - Click Click to build an expression and map the element name Output to this value.
      Update Task Data	Input Map: 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 schema defined for the Response format of Update Employee Address. Add/Remove Document Nodes - Click and select the fields added to the document schema for the Response format of Update Employee Address.

       Get Employee Time Off Balance

      Element	Description
      Create Document	Input Map: Document Definition Name - Select the document definition that you created for the Request format of the Get Employee Time Off Balance use case. Add/Remove Document Nodes - Click and select the fields added to the Request data schema of the Get Employee Time Off Balance 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	Input Map: Connection - Select the Web API connection defined for the BMC Helix iPaaS endpoint. Web API - Select the REST API web service request definition.  Request - Select the Web API for the Get Employee Details use case created in the Rest API web service request definition. Document - Click Click to build an expression and map the element name Output to this value.
      Update Task Data	Input Map: 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 schema defined for the Response format of Get Employee Time Off Balance. Add/Remove Document Nodes - Click and select the fields added to the document schema for the Response format of Get Employee Time Off Balance.

       Request for leave of absence

      Element	Description
      Create Document	Input Map: Document Definition Name - Select the document definition that you created for the Request format of the Request for leave of absence use case. Add/Remove Document Nodes - Click and select the fields added to the Request data schema of the Request for leave of absence 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	Input Map: Connection - Select the BMC Helix iPaaS connection created for the BMC Helix Integration iPaaS Rest API services. Web API - Select the REST API web service request definition.  Request - Select the Web API for the Update Employee Time Off Balance use case created in the Rest API web service request definition. Document - Click Click to build an expression and map the element name Output to this value.
      Update Task Data	Input Map: 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 schema defined for the Response format of Update Employee Address. Add/Remove Document Nodes - Click and select the fields added to the document schema for the Response format of Request for leave of absence. 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	Description
      Create Document	Input Map: 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 Request data schema 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	Input Map: 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	Description
      Create Document	Input Map: 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 Request data schema 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	Input Map: 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.

   4. Save the automated task template.
6. Create a case template for each use case. For more information about creating a case template, see  Creating case templates and task templates .
   1. Create a new case template.
   2. Add the Workday fields that will be displayed in the template as dynamic fields in the template.
   3. Add the automated task in the task flow of the template. 
   4. Save the template. 

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

(Optional) Task 7: To update employee details displayed in notification emails for the Get Employee details operation

When the employee data is successfully displayed in BMC Helix Business Workflows, an email notification is sent out, which does not include details about the field information. You can configure the fields to be displayed in this email notification. The integration template provides the most common fields, but you can add fields, as required. 

Update the Response to Get Employee Details element of the Workday - Get Employee Details operation to add the details to be included in the email notification sent when data is successfully retrieved for Workday. For additional information about the workflow, see Workflows included in the integration template. 

To add employee detail fields in your target application:

1. Open the Manage Employee Information in Workday via BWF project.
2. Scroll to the Workday - Get Employee details operation in the Workday to BWF workflow.
3. Select the Response to Get Employee Details element, and select View/Edit.
4. To add the details to the email notification:
   1. Add the field values to $operationFailureResponseMsg = "" (line 25) of the script. Add the required values from the following fields available out of the box:

      • "<b>Employee ID :</b>" + $employeeID + "<p></p>"

      • "<b>First Name :</b>" + $firstName + "<p></p>"

      • "<b>Middle Name :</b>" + $middleName + "<p></p>"

      • "<b>Last Name :</b>" + $lastName + "<p></p>"

      • <b>Job Title :</b>" + $employeeJobTitle +"<p></p>"

      • "<b>Start date :</b>" + $employeeStartDate + "<p></p>"

      • "<b>User Id :</b>" + $userId + "<p></p>"

      • "<b>Country ISO Code :</b>" + $countryIsoCode + "<p></p>"

      • "<b>Email Address :</b>" + $emailAddress + "<p></p>"

      • "<b>Phone Number Aread Code :</b>" + $phoneNumberAreaCode + "<p></p>"

      • "<b>Phone Number :</b>" + $phoneNumber + "<p></p>"

      • "<b>Phone Extension :</b>" + $phoneExtension + "<p></p>"

      • "<b>Phone Device Type :</b>" + $phoneDeviceType + "<p></p>"

      • "<b>Address Line :</b>" + $addressLine + "<p></p>"

      • "<b>Municipality :</b>" + $municipality + "<p></p>"

      • "<b>Region :</b>" + $region + "<p></p>"

      • "<b>Postal Code :</b>" + $postalCode + "<p></p>"

      • "<b>Marital Status :</b>" + $maritalStatus + "<p></p>"

      • "<b>Date Of Birth :</b>" + $dateOfBirth + "<p></p>"

      • "<b>Gender :</b>" + $gender + "<p></p>"

      • "<b>Government ID :</b>" + $governmentId + "<p></p>"

      • "<b>Government ID Type :</b>" + $governmentIdType + "<p></p>"

      • "<b>Salary : </b>" + $employeeSalary +"<p></p>" 

      • "<b>Currency Code: </b>" + $currencyCode +"<p></p>";

        Example

        For example, to display the Employee ID, First Name, Middle Name, Last Name, and Date of Birth fields, add the following values:
        + "<b>Employee ID :</b>" + $employeeID + "<p></p>"
+ "<b>First Name :</b>" + $firstName + "<p></p>"
+ "<b>Middle Name :</b>" + $middleName + "<p></p>"
+ "<b>Last Name :</b>" + $lastName + "<p></p>"
+"<b>Date Of Birth :</b>" + $dateOfBirth + "<p></p>"

        


        
        

   2. Remove the following line from the code (line 26)
      emailErrorMessage = SendEmailMessage("<TAG>email:Operation Success for getEmployeedata</TAG>");
   3. From the icon list on the right of the pane, click .
   4. Drag the Operation Success notification to replace the line removed in the previous task. 
   5. Click to return to the project page. 
   6. To deploy the integration after you update the script, see Task 3: To deploy and enable the project.

The email notification sent when the Get Employee Details operation is completed successfully will include the fields that you added.

(Optional) Task 8: To add fields to display in your target application for the Get Employee details operation

For the Get Employee details use case, the fields to be displayed are defined in the Get Employee Details Response Schema transformation element of the Get Employee details operation. For additional information about the workflow, see Workflows included in the integration template. You can update the fields defined in the transformation element to view additional fields in BMC Helix Business Workflows.

To add employee detail fields BMC Helix Business Workflows:

1. Open the Manage Employee Information in Workday via BWF project.
2. Scroll to the Workday - Get Employee details operation in the Workday to BWF workflow.
3. Select the Get Employee Details Response Target Schema transformation element, and select View/Edit.
4. From the Source tab, add fields from the [0] response section to the Target pane.
5. Click Return To Workflow .
6. To deploy the integration after you update the field mappings, on the project page, see Task 3: To deploy and enable the project. 
7. In BMC Helix Business Workflows, update the Jitterbit API response to display the fields added to the Target pane.

For the Get Employee Details operation, you can now display the fields you added to the transformation element in BMC Helix Business Workflows cases.

Workflows included in the integration template

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

Workday Integration

Enable Integration