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:

Use caseSalesforce to BMC Helix ITSM
Create ticketsCreates a new people record in BMC Helix ITSM from a new user record in Salesforce

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: 

Required versions
  • Salesforce Service Cloud Summer '20 and later
  • BMC Helix ITSM 20.08 and later
Authentication and permissions
  • Administrator access to the Salesforce account
  • Administrator access to BMC Helix ITSM
Jitterbit Harmony subscription

A valid BMC Helix iPaaS  subscription

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 variableAction
      Salesforce
      Source_HostEnter 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_TokenEnter 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_NameEnter 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_NameEnter 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_HostEnter the BMC Helix ITSM host URL.
      Target_UsernameEnter the user ID to access BMC Helix ITSM.
      Target_PasswordEnter 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 variableAction
      Target_Client_SenstivityEnter 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_StatusEnter any of the following valid values:
      • Proposed 
      • Enabled
      • Offline
      • Obsolete
      • Archive
      • Delete

      By default, this value is set to Proposed.

      Target_Support_StaffEnter any of the following valid values
      • No
      • Yes

      By default, this value is set to No.

      Target_VIPEnter any of the following valid values
      • No
      • Yes

      By default, this value is set to No.

      Target_CompanyEnter a valid BMC Helix ITSM company name. If blank, the value is set to the Salesforce Company Name.
    • Email notification configurations

      Project variableAction
      Jitterbit_SMTP_HOSTNAMEEnter SMTP host details for email configuration.
      Jitterbit_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.
      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_SummaryEnter 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 variableAction
      Jitterbit_Project_NameEnter 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_TypeDefine 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_NameFor 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:

ITSM fieldSalesforce field
Phone_Number_HomePhone
CC_Business_FaxFax
DepartmentDepartment
Home_CityCity
Internet_EmailEmail
Last_NameLastName
Home_StreetStreet
Home_State_ProvinceState
Corporate_IDEmployeeNumber
Short_DescriptionAboutMe
CompanyCompanyName
First_NameFirstName
Corporate_EMailEmail
Home_CountryCountry
Nick_NameCommunityNickname
Extension_BusinessExtension
Home_Zip_Postal_CodePostalCode
Phone_Number_BusinessPhone
Remedy_Login_IDUsername
JobTitleTitle


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:

ITSM fieldValues
Profile_StatusProposed
Client_TypeOffice-Based Employee
Client_SensitivityStandard
VIPNo
Support_StaffNo

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

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 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:

Operation nameActions performed
Initial Data Loading

Accepts the API request received from Salesforce via BMC Helix iPaaS API Manager and controls the complete flow of events including execution of validation scripts and Request Dispatcher

Get Salesforce User DetailsGets all the user details from Salesforce by using the username provided in the request and filter query provided by user

Create Person in ITSM

Creates person in ITSM by using the user details
Get Person Details in ITSMGets person details from ITSM by using Salesforce username as Remedy login ID
Read Person Details in ITSMReads and parses person details to send them to the validation scripts
Update Person in ITSMUpdates the Person record in ITSM based on the Salesforce User details
Operation Failure notification

Sends out a failure message if any operation fails.

The notification email contains the details and includes the reasons for the failure.


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

Operation nameActions performed
Enable integrationCreates all the required webhooks for the template and enables the integration
Log in to Jitterbit

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

Check Custom API and Security Profile exists

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 Profiles if neededDeletes existing APIs or security profiles, if required
Create or Update Apex ClassCreates an Apex class for defining the Webhook API
Create or Update Apex TriggerCreates an Apex trigger for executing the Webhook API
Was this page helpful? Yes No Submitting... Thank you

Comments