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:

Use caseBMC Helix Business Workflows to WorkdayWorkday to BMC Helix Business Workflows
Get informationNA

Retrieves employee information from Workday to a BMC Helix Business Workflows case or task

Gets the PTO balance of an employee from Workday to a BMC Helix Business Workflows case

Create tickets

Creates a request for leave of absence in Workday from a BMC Helix Business Workflows case

NA

Synchronize updates

Updates the address of an employee in Workday from a BMC Helix Business Workflows case

NA

Updates an employee's legal name in Workday from BMC Helix Business Workflows

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: 

Required versions
  • Workday 2020 Release 2 and later
  • BMC Helix Business Workflows 20.08 and later

Authentication and permissions

Administrator access to BMC Helix Business Workflows

Jitterbit Harmony subscription

A valid BMC Helix iPaaS subscription

Others

Ensure that the Helix ITSM foundation data is synced in BMC Helix Business Workflows. For additional information about uploading and syncing ITSM data with BMC Helix Business Workflows, see  Setting up Foundation data about the people in your company

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

Workday integrationWorkday ServiceAPIDomain Security Policy or BP:Initiating Action for Business Process
Get PTO balance

Absence_Management

Get_Time_Off_Plan_Balances

Domain: Worker Data: Time Off (Time Off)

Request Leave of Absence

Absence_Management

Request_Leave_of_Absence

BP: Request Leave of Absence

Update Employee Address

Personal Data

Change_Personal_Information

BP:Personal Information Change

Update Employee Legal Name

Contact Information

Change_Legal_Name

BP:Legal Name Change

Get Employee Data

Staffing

Get_Workers

Domain: Worker Data: Public Worker Reports

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 2022-07-01 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 variableAction
      Workday
      Workday_HostEnter the name of the Workday host URL.
      Workday_TenantEnter the name of the Workday tenant.
      Workday_User_NameEnter 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 variablesAction
      Jitterbit_Project_NameEnter 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_NameEnter 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 for this application.
      • BMC Helix Business Workflows does not support APIKEY authentication.
      Jitterbit_Webhook_Security_Profile_TypeDefine 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_SuffixEnter 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_NameThis 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 variableAction
      Jitterbit_SMTP_HostnameEnter the SMTP host details for email configuration.
      Jiiterbit_To_Email_AddressEnter the email address to which you want to send the notification emails.
      Jitterbit_From_Email_AddressEnter 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

Deployment is a one-time activity that initializes the integration configurations. The UI displays a message for the deployment status.

To deploy the project and then enable the integration:

  1. To deploy the project, next to the project name, click the ellipsis ..., and select Deploy Project.
  2. To enable the integration, next to the Enable Integrations workflow, click the ellipsis ..., and select Deploy

The following image shows the steps to deploy the project and enable it by deploying the workflow:

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

    {
    "employeeSalary": "",
    "employeeStartDate": "",
    "jobTitle": "",
    "firstName":""
    }

    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

    NameType a name for the web request. For example, Workday - Get Employee Data.
    Request MethodSelect 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>

    BodyFrom 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 HeadersAdd the headers for this web request.
    (Optional)  Query ParametersAdd 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:

    FieldDescription
    Name 

    Enter a meaningful name for the REST API web service connection, such as BMC Helix iPaaS Endpoint Connection.

    Host NameEnter the hostname from the Service URL copied after deploying the project.
    PortEnter 443.
    ProtocolSelect HTTPS.
    AuthenticationSelect 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.

      ElementDescription
      Create DocumentInput 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:

      Update Task DataInput 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.
      ElementDescription
      Create DocumentInput 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 RequestInput 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 DataInput 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.
      ElementDescription
      Create DocumentInput 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:

      Update Task DataInput 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.
      ElementDescription
      Create DocumentInput 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:

      ElementDescription
      Create DocumentInput 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:

    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>"; 


        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

Operation nameActions performed
Master ControllerEnables all the API entry points by using the details provided in the project variables
Workday - Get PTO balance

Gets details of the PTO balance from Workday to the target application.

This operation populates the employee's PTO balance from Workday to the target application.

Workday - Get Employee Data

Gets employee data from Workday to the target application.

This operation gets the requested employee data from Workday to the target application. This information can be used to view details available in Workday in your target application record.

Workday - Request Leave of Absence

Creates a leave of absence request from a target application to Workday.

This operation creates a corresponding leave application request in Workday when you create a request in the target application. Enter the leave start and end dates when creating in the target application while creating the request.

Workday - Update Employee Address

Updates employee data in Workday by using the target application.

This operation updates the corresponding employee address in Workday when you update the address details in the target application.

Workday - Update Employee Legal Name

Updates an employee's legal name in Workday by using a third-party application.

This operation updates the legal name of an employee in Workday when you update the name in the target application.

Error HandlingSends an email notification if the operation in Workday is successful or failed

Enable Integration

Operation nameActions performed
Enable integrationCreates all the required webhooks for the template and enables the integration

Login to Jitterbit

Logs in to Jitterbit by using the credentials provided in the project variables

Check Custom API and Security Profiles exist

Checks if the Custom API and security profiles exist
Publish Custom API

Publishes the custom APIs to BMC Helix iPaaS

Create Security Profiles and Custom API

Creates security profiles and REST APIs in BMC Helix iPaaS

Delete API and Security Profile if neededDeletes existing APIs or security profiles, if required
Was this page helpful? Yes No Submitting... Thank you

Comments