Synchronizing Salesforce users with BMC Helix ITSM people records by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template to synchronize Salesforce user data with 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.

The template provides the following capabilities:

Salesforce to BMC Helix ITSM data flow

The following image gives an overview of the data flow for creating a people record in BMC Helix ITSM from a Salesforce people record:

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

1. Download the Sync Salesforce User with BMC Helix ITSM People Update 2022-07-01 file to your system.
   

   This file contains the BMC Helix iPaaS Cloud Studio project Sync_Salesforce_Users_to_ITSM_People.

   Important

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

   
   

2. Log in to BMC Helix iPaaS as a developer and navigate to the Cloud Studio.
3. On the projects page, click Import.
4. Click Browse to navigate to and then select the Sync Salesforce User with BMC Helix ITSM People Update.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, select the Sync_Salesforce_Users_to_ITSM_People project and click View/Edit. 

Task 2: To update the project variables for the integration

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 Salesforce, BMC Helix ITSM, and BMC Helix iPaaS applications

     Project variable	Action
     Salesforce
     Source_Host	Enter the Salesforce host URL. By default, this value is set to https://login.salesforce.com/.
     Source_Username	Enter the user ID to access Salesforce. Important: The user must have super admin permissions.
     Source_Password	Enter the password of the user to access Salesforce.
     Source_Security_Token	Enter the API security token for Salesforce user, if required for the user.
     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. For example, to synchronize data created for Calbro Services, enter the following filter criteria: WHERE CompanyName = 'Calbro Services'
     Source_Apex_Class_Name	Enter the Apex class name used to call the Webhook API. The class is generated in Salesforce and is used to call the Jitterbit API.
     Source_Apex_Trigger_Name	Enter the Apex trigger on user class which uses the Apex class to call the Jitterbit API, if there is any change in user record. Important: Verify that the Apex class and Apex trigger are not defined in Salesforce.
     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. Important: The user must have super admin permissions.
     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.

   • Mandatory ITSM fields to be updated manually

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

     Project variable	Action
     Target_Client_Senstivity	Enter any of the following valid values: Standard Sensitive By default, this value is set to Standard.
     Target_Client_Type	Enter any of the following valid values: Office-Based Employee Field-Based Employee Home-Based Employee Contractor Customer Prospect Vendor By default, this value is set to Office-Based Employee.
     Target_Profile_Status	Enter any of the following valid values: Proposed  Enabled Offline Obsolete Archive Delete By default, this value is set to Proposed.
     Target_Support_Staff	Enter any of the following valid values No Yes By default, this value is set to No.
     Target_VIP	Enter any of the following valid values No Yes By default, this value is set to No.
     Target_Company	Enter a valid BMC 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.  This value defines if notification emails should be sent.
     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.

   • Webhook API variables

     Project variable	Action
     Jitterbit_Project_Name	Enter the name of the Salesforce project for which to create the Webhook API. By default, this value is set to Sync Salesforce Users to ITSM People.
     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. By default, this value is set to Initial Data Loading.
     Jitterbit_Integration_API_Name	Enter the name for the API that is created for the integration in the BMC Helix iPaaS API Manager.
     Jitterbit_Integration_API_Method	Enter a REST API method. You can set the following values for this variable: POST GET PUT DELETE The default value is POST. The webhook API uses this method. This value is added to the BMC Helix iPaaS Jitterbit API.
     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.  You can set the following values for this variable: FINAL_TARGET VARIABLE NO_RESPONSE The default value is FINAL_TARGET.
     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 set to BASIC. Enter comma separated values to select multiple profile types (APIKEY,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. 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.
     Jitterbit_Integration_API_Authentication_Type	Define which authentication method to use from the ones defined in 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 user name to be used 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. The Jitterbit API and the Webhook API use this APIKEY name for authentication.
     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.

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

You can edit the Salesforce to BMC 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 between the Salesforce User record and ITSM People record:

The following fields are mandatory in BMC Helix ITSM, but do not have an equivalent field in Salesforce. The values for these fields are prepopulated:

To update out of the box field mappings

1. Select the Real time Sync Salesforce Users to ITSM People workflow in the Sync_Salesforce_Users_to_ITSM_People project.
2. Scroll through the workflow, click the Read Salesforce User transformation element, and select View/Edit.
   
3. In the Mappings section, select Mapped from the View menu.
4. On the Variables tab, click Use Variables.
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.

   For more information about deploying the project, see Task 4: To deploy and enable the integration.

Task 4: To deploy and enable the integration

After you enable the integration, Salesforce user data and BMC Helix ITSM Person data are synchronized. 

(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 API created for the integration. The API name is the value defined in the Jitterbit_Integration_API_Name project variable.
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 update the default trigger conditions for the Sync_Salesforce_Users_to_ITSM_People project

1. Log in the Salesforce as an Administrator.
2. On the Salesforce Administrator, click .
3. From the left navigation panel, select Custom Code > Apex Triggers.
   
4. Update the trigger conditions and save your changes. 

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

You can map custom fields defined in Salesforce to existing BMC 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 BMC 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 Cloud Studio.

2. Select the environment where the integration templates are available.

3. Select the Sync Salesforce User to ITSM People project and click View/Edit.
4. Expand the Real time Sync Salesforce User to ITSM People workflow.
5. Refresh the schema to include the custom fields added to Salesforce.
   1. Select the Query element in the 2.1 Get Salesforce User Details 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. Create a global variable to map the custom field to a BMC Helix ITSM field.
   1. Click the Salesforce User Details transformation element of the 2.1 Get Salesforce User Details 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 result (string) and add a global variable entry for the field, similar to the other global variables in the script. 
   3. Click Return to Workflow
7. Map the custom field to an existing BMC Helix ITSM field.
   1. Click the Create ITSM Person Request transformation element in the 2.2 Create Person 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 BMC Helix ITSM field in the Target pane.
   4. Click Return to Workflow.
   5. Deploy the integration. 
      For more information about deploying the project, see Task 4: To deploy and enable the integration.

8. 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 element in the 2.1 Get Salesforce User Details operation.
   2. Remove the global variable created in the Salesforce User Details transformation element of the 2.1 Get Salesforce User Details operation.
   3. Create ITSM Person Request transformation element in the 2.2 Create Person in ITSM operation.
   4. Deploy the integration.
      For more information about deploying the project, see Task 4: To deploy and enable the integration.

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.

The Real time Sync Salesforce Users to ITSM People workflow includes the following operations to update existing people data:

The API Creation workflow includes the following operations to enable the integration: