Migrating Salesforce users to BMC Helix ITSM people records by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template that enables you to migrate Salesforce User data to BMC Helix ITSM People data. The integration template provides the workflow to migrate Salesforce users to create corresponding BMC Helix ITSM People data. 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. 

Migration is a periodic activity, and you need to manually run the integration template to migrate the data. 

Salesforce to BMC Helix ITSM data flow

The following image gives an overview of the data flow for migrating user data from Salesforce to BMC Helix ITSM:

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 BHIP 21.05.00 Migrate Salesforce User with BMC Helix ITSM People Update 2021-06-01 file to your system.
   This file contains the BMC Helix iPaaS Integration Studio project Migrate Salesforce User with BMC Helix ITSM People.

   Important

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

2. As an Administrator, log in to BMC Helix iPaaS and navigate to the Integration Studio.
3. On the projects page, click Import.
4. Click Browse and then select the BHIP 21.05.00 Migrate Salesforce User with BMC Helix ITSM People Update 2021-06-01.json file you downloaded. 
   The Project Name and Organization 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, and then select the Migrate Salesforce User with BMC Helix ITSM People project, and click View/Edit.

Task 2: To update the project variables for the integration

1. Next to the Environment name, click ... and select Project Variables.
2. Update the required project variables. You must update the values for the following project variables:

   • Access points and authentication details for Salesforce and Helix ITSM application

     Project variable	Action
     Salesforce
     Source_Host	Enter the Salesforce host URL.By default, the value is set to https://login.salesforce.com/.
     Source_Username	Enter the user ID to access Salesforce.Important: The user must have super administrator permissions.
     Source_Password	Enter the password of the user to access Salesforce.
     Source_Security_Token	Enter the value of the Salesforce security token.
     Source_Filter_Query	Enter the filter criteria for the type of data to be synchronized. This will use the query defined in the Query Salesforce end point in the Get Salesforce User operation. Define the query for filtering the data to be synced.  For example, to synchronize data created for the company Apex Global, enter CompanyName = 'Apex Global'.
     ITSM
     Target_Host	Enter the BMC Helix ITSM host URL.
     Target_Username	Enter the user ID to access BMC Helix ITSM.
     Target_Password	Enter the password of the user to access BMC Helix ITSM.Warning: The user must have super admin permissions.

   • Mandatory Helix ITSM fields

     The following ITSM fields do not have a corresponding field in Salesforce and must be mapped manually before you run the integration:

     Project variable	Value
     Target_Client_Senstivity	By default, set to Standard.
     Target_Client_Type	By default, set to Office-Based Employee.
     Target_Profile_Status	By default, set to Proposed.
     Target_Support_Staff	By default, set to No.
     Target_VIP	By default, set to No.
     Target_Company	Enter a valid Helix ITSM company name. If blank, the value is set to the Salesforce Company Name.

   • Email notification configurations

     Project variable	Action
     Jitterbit_SMTP_HOSTNAME	Enter SMTP host details for email configuration.
     Jitterbit_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.
     Jitterbit_Email_Enabled	To disable email notifications, change the default value to false. By default, the value is set to true.
     Jitterbit_Email_Summary	Enter a summary for the email notification.
     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.

(Optional) Task 3: To review and update out-of-the-box field mappings

You can edit the Salesforce to Helix ITSM field mappings provided by the integration template. To do so, you need to update the transformation element in the workflow and map the fields. The following fields are mapped out of the box:

Out-of-the-box field mappings between ITSM People record and Salesforce User record

Pre-populated values for mandatory Helix ITSM fields with no equivalent Salesforce field

To update out-of-the-box field mappings

1. Open the Migrate Salesforce to ITSM project.
2. In the Get the Salesforce users operation, click the Get users from Salesforce transformation element, and select View/Edit.
   
3. In the Mappings section, select Mapped from the View menu.
4. On the Variables tab, click Use Variable.
5. From the variable list, drag and drop the variable to the field mapping you want to update in the Mappings section.

6. Click Return to Workflow. 

   Important

   If the integration template is already deployed, you must deploy it again after you make changes to the mappings.

Task 4: To deploy and enable the integration

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 Initial Data Load workflow, click the ellipsis ... for the Enable Integration operation, and select Run. 

The following image shows the steps to deploy the project and enable it by running the operation:

To migrate Salesforce user data to BMC Helix ITSM People data, after successfully deploying the integration, click the ellipses ... next to the Initial Data Load operation, and select Run. 

(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 Salesforce API created for the integration.
3. Select Enable Debug Mode Until: and set it for the required date and time.
4. Save and publish the API.

(Optional) Task 6: To map custom Salesforce fields to existing Helix ITSM fields

You can map custom fields created in Salesforce to existing Helix ITSM fields by updating the mappings in the integration template. If you delete a custom field that is not mapped to a mandatory field in Helix ITSM, the integration continues to work. However, we recommend that you delete the field mappings from the integration template project.

To add the field mapping for a new custom field created in Salesforce

1. Log in to BMC Helix iPaaS as a developer and navigate to the Integration Studio.
2. Select the environment where the integration templates are available.
3. Select the Migration Salesforce To ITSM Person project and click View/Edit.
4. Expand the Migration Salesforce To ITSM Person workflow.
5. To refresh the schema to include the custom fields added to Salesforce, perform the following steps:
   1. Select the Query salesforce users element in the Get the Salesforce users operation and click View/Edit.
   2. Click Step 1 in the query, and then click Refresh next to SELECT RELATED OBJECT(S) OPTIONAL. The field names in the PREVIEW FIELDS: User panel are updated. 
      Verify that your custom field is available in this list.
   3. Click Next.
   4. On Step 2, click Next.
   5. On Step 3, verify that your custom field exists in the response, and then click Finished. 
6. To add the custom field to the schema, perform the following steps:
   1. Click the Get users from the salesforce transformation element in the 1.1 Get the Salesforce users operation and click View/Edit.
   2. In the Target pane, click Settings, and select Edit schema.
   3. For the User record, in the Fields column, click the edit icon .
   4. Click +Add Field.
   5. Scroll to the bottom of the field list, enter the name and select the Type of the custom field created in Salesforce, and then click Save Changes.
   6. To add the field mapping for the custom field, drag the custom field from the source panel to the new field you added in the target panel.
   7. Click Return to Workflow.
7. To update the temporary storage schema to ensure that the custom field is available, perform the following steps; 
   1. Click the temporary storage element Read salesForce user of the 1.2 Get users one by one operation, and click View/Edit.

   2. Click Step 1, select Salesforce User Schema from the SAVED SCHEMAS list and then click Next.

      Important

      If the Salesforce User Schema is already selected, select a different schema, and then reselect the Salesforce User Schema from the list.

      The Yes, Use Saved Schema option must be selected.

   3. Verify that the new field has been added in the response, and click Finished.
8. To map the custom field to a Helix ITSM field, create a global variable by performing the following steps:
   1. Click the Split users transformation element of the 1.2 Get users one by one operation.
   2. To create and update the mapping for the custom field in other transformations, in the Target pane, click the script icon  next to ITSMFields (string) and add a global variable entry for the field, similar to the other global variables in the script. 
   3. Click Return to Workflow.
9. To map the custom field to an existing Helix ITSM field, perform the following steps:
   1. Click the Preparing payload request transformation element in the 1.3 Create user in ITSM operation and select View/Edit.
   2. On the  Variables  tab, click  Use Variables.
   3. From the variable list, drag the global variable you created for your custom field, and map it to the Helix ITSM field in the Target pane.
   4. Click Return to Workflow.
10. Deploy the project.
11. If you delete the custom field from Salesforce, you must delete the custom field mapping in the integration template. To delete the custom field mappings:
    1. Refresh the schema in the Query salesforce users element in the Get the Salesforce users operation.
    2. Remove the custom field from the schema in the Get users from the salesforce transformation element in the 1.1 Get the Salesforce users operation.
    3. Update the temporary storage schema to ensure that the custom field has been removed.
    4. Split users transformation element of the 1.2 Get users one by one operation.
    5. Remove the field mappings defined for the custom field in the Preparing payload request transformation element in the 1.3 Create user in ITSM operation.
    6. Deploy the integration.

Workflow 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.

Migrate Salesforce User to ITSM People