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:
|Authentication and permissions|
|Jitterbit Harmony subscription|
A valid subscription
Task 1: To download and import the integration template project file
Download the file to your system.
This file contains the BMC Helix iPaaS Cloud Studio project Migrate Salesforce User with BMC Helix ITSM People.
Your ability to access product pages on the EPD website is determined by the license your company purchased.
- As an Administrator, log in to BMC Helix iPaaS and navigate to the Cloud Studio.
- On the projects page, click Import.
- 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.
- 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.
- 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
- Next to the Environment name, click ... and select Project Variables.
- 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'.
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.
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
|ITSM field||Salesforce field|
Pre-populated values for mandatory Helix ITSM fields with no equivalent Salesforce field
To update out-of-the-box field mappings
- Open the Migrate Salesforce to ITSM project.
- In the Get the Salesforce users operation, click the Get users from Salesforce transformation element, and select View/Edit.
- In the Mappings section, select Mapped from the View menu.
- On the Variables tab, click Use Variable.
- From the variable list, drag and drop the variable to the field mapping you want to update in the Mappings section.
Click Return to Workflow.
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
To deploy the project and then enable the integration:
- To deploy the project, next to the project name, click the ellipsis ..., and select Deploy Project.
- 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:
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 element of the Enable Integration workflow, 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:
In BMC Helix iPaaS, powered by Jitterbit, select API Manager > My APIs.
Open the Salesforce API created for the integration.
Select Enable Debug Mode Until: and set it for the required date and time.
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
- Log in to BMC Helix iPaaS as a developer and navigate to the Cloud Studio.
Select the environment where the integration templates are available.
- Select the Migration Salesforce To ITSM Person project and click View/Edit.
- Expand the Migration Salesforce To ITSM Person workflow.
- To refresh the schema to include the custom fields added to Salesforce, perform the following steps:
- Select the Query salesforce users element in the Get the Salesforce users operation and click View/Edit.
- 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.
- Click Next.
- On Step 2, click Next.
- On Step 3, verify that your custom field exists in the response, and then click Finished.
- To add the custom field to the schema, perform the following steps:
- Click the Get users from the salesforce transformation element in the 1.1 Get the Salesforce users operation and click View/Edit.
- In the Target pane, click Settings, and select Edit schema.
- For the User record, in the Fields column, click the edit icon .
- Click +Add Field.
- 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.
- 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.
- Click Return to Workflow.
- To update the temporary storage schema to ensure that the custom field is available, perform the following steps;
- Click the temporary storage element Read salesForce user of the 1.2 Get users one by one operation, and click View/Edit.
Click Step 1, select Salesforce User Schema from the SAVED SCHEMAS list and then click Next.
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.
Verify that the new field has been added in the response, and click Finished.
- To map the custom field to a Helix ITSM field, create a global variable by performing the following steps:
- Click the Split users transformation element of the 1.2 Get users one by one operation.
- 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.
- Click Return to Workflow.
- To map the custom field to an existing Helix ITSM field, perform the following steps:
- Click the Preparing payload request transformation element in the 1.3 Create user in ITSM operation and select View/Edit.
- On the Variables tab, click Use Variables.
- 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.
- Click Return to Workflow.
- Deploy the project.
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:
- Refresh the schema in the Query salesforce users element in the Get the Salesforce users operation.
- 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.
- Update the temporary storage schema to ensure that the custom field has been removed.
- Split users transformation element of the 1.2 Get users one by one operation.
- 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.
- 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
|Operation name||Actions performed|
|Initial Data Load||Consolidates details required for the migration|
|Get Salesforce Users||Gets the Salesforce user data|
|Get User One by One|
Reads each Salesforce user record by using the temporary Read operation
|Create User in ITSM||Creates BMC Helix ITSM people data for the Salesforce User data|
|Check if Error Occurred||Verifies if the operation was successful or not|
|Failure Email||Sends an error notification email if the migration was not successful|