Creating BMC Helix ITSM incidents for ServiceNow incidents by using, Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template to synchronize incidents created and updated in ServiceNow with BMC Helix ITSM. 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 integration template provides the following capabilities:

Use case

ServiceNow to BMC Helix ITSM

Create incidents

Creates a BMC Helix ITSM incident from a new ServiceNow incident

Creates a BMC Helix ITSM incident from an updated ServiceNow incident that had been created before the integration was deployed

Update incidents

Updates a BMC Helix ITSM incident from an updated ServiceNow incident

Important

When a BMC Helix ITSM incident is created or updated from a ServiceNow incident, the BMC Helix ITSM incident ID and link to the incident record is provided in the ServiceNow incident, and the ServiceNow incident ID is displayed in the BMC Helix ITSM incident.

ServiceNow to BMC Helix ITSM data flows

The following image gives an overview of the data flow for creating a BMC Helix ITSM incident from a ServiceNow incident:


The following image gives an overview of the data flow for updating a BMC Helix ITSM incident from a ServiceNow incident:


Before you begin

You require the following items to successfully set up and use this integration: 

Required versions
  • Service Now Paris or later
  • BMC Helix ITSM version 20.08 or later
Authentication and permissions
  • ServiceNow
  • BMC Helix ITSM
    • Administrator access to BMC Helix ITSM
Jitterbit Harmony subscription

A valid  BMC Helix iPaaS Open link  subscription

Application registration

Generate client ID and secret for BMC Helix iPaaS to register your BMC Helix iPaaS instance with ServiceNow. To do this, you must create an OAUTH API endpoint in ServiceNow, and then add the client ID and secret in the client_id and client_secret project variables defined in the project.
For more information about generating an OAUTH endpoint, see the ServiceNow documentation Open link  to create an endpoint for clients to access the instance.

Notes

  • The value of the Caller defined when you create an incident in ServiceNow, must correspond to a valid Customer First Name and Customer Last Name in BMC Helix ITSM and belong to the company defined in the Target_Company global variable. The incident create operation fails if the Caller name does not exist in ServiceNow.
  • If you are using Remedy Mid Tier to create and view the BMC Helix ITSM incidents, the minimum length of the field used to store the BMC Helix ITSM incident URL is 300. You must update the field length in BMC Helix ITSM to view the complete incident URL. For more information, see the project variables, described in Fields for ITSM incident details.

Task 1: To download and import the integration template project file

  1. Download the  Sync ServiceNow Incidents with BMC Helix ITSM Update 2023-01-03 Open link file.
    This file contains the BMC Helix iPaaS Cloud Studio project Sync ServiceNow Incidents with BMC Helix ITSM project

    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 iPaaSand navigate to the Cloud Studio.
  3. On the projects page, click Import.
  4. Click Browse to navigate to and select the Sync ServiceNow Incidents with BMC Helix ITSM Update 2023-01-03 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. 
    To open the project file at a later time, select the environment where the integration templates are available, select the Sync ServiceNow Incidents with BMC Helix ITSM project and click View/Edit.

Task 2: To assign roles and ACL permissions to your ServiceNow user

  1. Log in to your ServiceNow instance as an Administrator.
  2. To create a new custom role, and add the roles required by the ServiceNow user defined in the servicenow_user project variable for the integration, perform the following steps:
    1. Click All and select System Security > Users and Roles > Roles.
    2. To create a new role, click New.
    3. Enter a name and description for the role, and click Submit.
    4. To open the roles record, on the Roles page, double-click the name of the role you created.
    5. To add the required roles, on the Contains Roles tab, click Edit..
    6. Select the role to add from the Collection list, and click >.
      Add the following roles:

      • itil

      • personalize_dictionary

      • business_rule_admin

      • script_include_admin

    7. Click Save.
      The selected roles are displayed on the Contains Roles tab.

    8. Click Update.
  3. Click the user profile icon and select Elevate Role to get the privileged role to be able to add ACL permissions for users.
  4. When prompted, select security_admin from the list of Available Roles and click Update

    Important

    The  security_admin  elevated role ends when the session times out or when you log out of your ServiceNow instance.

  5. Click All and select System Security > Access Control (ACL).

    Required access permissions
    The following table lists the values required when you configure the access control settings. 

    TypeOperationName
    For creating and updating incidents and creating comments
    recordReadTable [sys_db_object]None
    recordReadField class [sys_glide_object]None
    recordReadDictionary Entry [sys_dictionary]*
    For creating the webhook required for the integration template
    recordReadSystem Property [sys_properties]None
    recordWriteSystem Property [sys_properties]None
    recordExecuteSystem Property [sys_properties]None
    recordCreateSystem Property [sys_properties]None
  6. To add access control list rules, complete the following steps for each rule listed in the Required access permissions table:

    1. On the Access Controls page, click New.
    2. Configure the following settings for the new record: 

      • TypeSelect record from the list.
      • OperationSelect a value.
      • NameSelect a value and the fields for that value.
      • Requires roleUnder Role, double-click Insert a new row, enter the value for role you created in Step 2 and click Save( ).
    3. Click Submit.
    4. Click Save.

Task 3: To update the project variables for the integration template

  1. Next to the Environment name, click the ellipsis ... and select Project Variables.
  2. Update the following project variables:
    • Access points and authentication details for ServiceNow, BMC Helix ITSM, and BMC Helix iPaaS applications

      Project variableAction
      ServiceNow
      Source_EndpointEnter the ServiceNow host URL.
      Source_UserEnter the user ID to access ServiceNow.
      Source_PasswordEnter the password of the user to access ServiceNow.
      Source_Client_Id

      Enter the OAUTH API endpoint ID generated in ServiceNow.

      Source_Client_Secret

      Enter the OAUTH API endpoint client secret generated in ServiceNow.

      Source_Webhook_Basic_User

      Enter the ServiceNow system property name to store BMC Helix iPaaSBASIC authentication username.

      Source_Webhook_Basic_Password

      Enter the ServiceNow system property name to store BMC Helix iPaaS BASIC authentication password.

      Source_Webhook_APIKEY

      Enter the name of the ServiceNow system property to store BMC Helix iPaaS basic authentication profile user name.

      Source_Webhook_Script_Include_NameEnter the name of the Script include to be used for the Webhook configuration.
      Source_Webhook_Property_Name

      Enter the ServiceNow system property that has apikey for the BMC Helix iPaaS APIKEY authentication profile.

      Source_Webhook_Business_Rule_Name

      Enter the name of the business rule created for the ServiceNow Webhook configuration.

      By default, set to Jitterbit send new incident for itsm.

      BMC Helix ITSM
      Target_Incident_URL

      Enter the RestAPI URL of the BMC Helix ITSM instance.

      The integration uses this URL to construct the Incident URL populated in the ServiceNow field defined in the Source_Reference_Field1 project variable.

      Important: If both Target_Incident_URL and Target_Midtier_URL are provided, the Target_Incident_URL is given preference.

      Target_Midtier_URL

      Enter the RestAPI URL for the Remedy Mid-Tier.

      Important: Provide the Remedy Mid-Tier URL if you have not implemented Smart IT.

      Target_EndpointEnter the URL of the BMC Helix ITSM instance.
      Target_UserEnter the user ID to access BMC Helix ITSM.
      Target_PasswordEnter the password for the user ID to access BMC Helix ITSM.
      Target_Service_Type

      Enter a valid BMC Helix ITSM Service Type.

      By default, this value is set to User Service Restoration.

      BMC Helix iPaaS

      BHIP_Url

      Enter the URL to access BMC Helix iPaaS.

      BHIP_User

      Enter the user ID to access BMC Helix iPaaS.

      BHIP_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 ServiceNow project for which 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.

      By default, the value is set to Integration API Flow Controller.

      Jitterbit_Integration_API_NameEnter the name for the Webhook API that is created in ServiceNow; for example, set the value to ServiceNowToITSMAPI.
      Jitterbit_Integration_API_Method

      Enter the RestAPI method that is used by the Webhook API. This value is added to the BMC Helix iPaaS Jitterbit API.

      Valid values include:

      • POST (Default)
      • GET
      • PUT
      • DELETE
      Jitterbit_Integration_API_Response_Type
      Enter the RestAPI response type used by the Webhook API created. This value is added in the BMC Helix iPaaS Jitterbit API. 

      By default, set to FINAL_TARGET.

      Jitterbit_Integration_API_Security_Profile_Type

      Enter a security profile type. 

      Valid values include:

      • BASIC (Default)
      • ANONYMOUS
      • APIKEY

      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_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 a suffix to be added to the name of the security profiles created.
      Jitterbit_Integration_API_Security_Profile_BASIC_Auth_Username

      For the security profile type BASIC, enter the user name to be used to create the security profile.

      This username is used for authentication by the Jitterbit API and the Webhook API.

      Jitterbit_Integration_API_Security_Profile_BASIC_Auth_Password

      For the security profile type BASIC, enter the password for the security profile created.

      This password is used for authentication by the Jitterbit API and the Webhook API.

      Jitterbit_Integration_API_Security_Profile_ApiKey_Name

      For the security profile type APIKEY, enter the name of the APIKEY to set on the security profile.

      This APIKEY is used for authentication by the Jitterbit API and the Webhook API.

      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.
    • Mandatory ITSM fields to be updated manually

      Important

      You must define a valid BMC Helix ITSM company and the user for whom to create the incident for the integration to work. If you need to change any of these values, you must update them and deploy the project again to apply the updated values for the integration.

      The following field values must be populated before you run the integration:

      Project variableAction
      Target_CompanyEnter the name of a valid BMC Helix ITSM company for which the incident should be created.
      Target_Service_Type

      Enter a service type for the incident created in Remedy ITSM.

      By default, this value is set to User Service Restoration.

    • Fields for ITSM incident details

      Project variableAction
      Source_Reference_Field1Enter the name of a valid field to store the URL of the ITSM incident. We recommend that you set this to correlation_display.

      Important: If you have provided a Target_Midtier_URL, the allowed field length of the ServiceNow field must be 300 characters or more for the complete URL to be stored in the field. If you choose to select correlation_display field, you need to manually update the field size to 300 characters.

      Source_Reference_Field2Enter the name of a valid field to populate the corresponding ITSM incident number. We recommend that you set this to correlation_id.
    • Email notification configurations

      Project variableAction
      Jitterbit_SMTP_HostnameEnter SMTP host details for emails 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 should be sent.
      Jitterbit_Email_SubjectEnter default subject line for the notification email.
      Jitterbit_Email_Enabled

      Define if notification emails should be sent.

      By default, the value is set to true. If you want to disable email notifications, set the value to false.

      Jiiterbit_Email_On_Success

      Define if emails should be sent if workflow is successful.

      By default, this value is set to true. To disable email notifications for successful operations, set the value to false.

      Jitterbit_Email_On_Error

      Define if emails should be sent if an error occurs in the data migration.

      By default, this value is set to true. To disable email notifications for errors, set the value to false.

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

Out-of-the-box field mappings are defined in the transformation elements of the  Create incidents in ITSM  and  Update ITSM incident  operations in the Sync ServiceNow Incidents to ITSM workflow. For additional information about the workflow, see Workflows included in the integration template.

The following out of the box field are mapped in the Prepare ITSM request transformation element for the Create incidents in ITSM operation:

ServiceNow fieldsITSM fields

State

Status

Important: The State values are mapped to the same BMC Helix ITSM Status values. The State On Hold is mapped to the ITSM Status Pending.

Caller

(First name, Last name)

Customer First Name, Customer Last Name.
Short DescriptionDescription
DescriptionDetailed Description
ImpactImpact
Contact TypeReported Source
Incident ID and System IDVendor Ticket ID
UrgencyUrgency

The following ITSM fields are mapped to project variables or prepopulated.

Important

To update these mappings, you must update the values defined in the project variables.


ITSM fieldProject variable

Contact Company and Company

Target_Company

Service Type

Target_Service_Type

Created ByPrepopulated to ServiceNow


The same fields are mapped for the Update ITSM incident operation in the Map ServiceNow to ITSM incident data transformation element. The following additional fields are also mapped in the Map ServiceNow to ITSM incident data transformation element:

ServiceNow fieldITSM field
StatusStatus Reason
Request IDRequest ID
Close NotesResolution

You can edit the ServiceNow 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. 

To update out of the box field mappings

  1. Open the Sync ServiceNow Incidents with BMC Helix ITSM project.
  2. Scroll through the workflow, and select the appropriate transformation element and select View/Edit:
    1. To update field mappings for the Create Incident operation, click the Mapping ITSM response transformation element.
    2. To update field mappings for the Update Incident operation, click Map ServiceNow to ITSM incident transformation element.
  3. In the Target pane, from the View menu, select Mapped.
  4. On the Variables tab, click Use Variables
  5. From the variable list, drag 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 project.

Task 5: 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 ... 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:

After you enable the integration, a corresponding incident is created in BMC Helix ITSM when an incident records created in ServiceNow. Any updates made to the ServiceNow incident are synced with the BMC Helix ITSM incident. The ServiceNow Incident ID is displayed in the Vendor Ticket No field in BMC Helix ITSM.

(Optional) Task 6: 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 7: To update the default trigger conditions for the ServiceNow Incidents to ITSM project 

You can update the trigger condition defined out of the box for the integration by updating the Webhook configuration added to ServiceNow. 

  1. Log in to ServiceNow as an Administrator.
  2. From the navigation menu, select System Definition - Business Rule.
  3. Select the Jitterbitsendnewincidentforitsm rule.
  4. On the When to run tab, select your trigger conditions.
  5. To add additional conditions to trigger the integration, add the required filters under Filter Conditions. 
    For example, to create ITSM incidents only for High priority ServiceNow incidents, click Add Filter Condition, then select the Priority field, select is operation, and select High as the value. 
  6. Additionally, you can add filter conditions if you want to disable any of the integration template use cases.
    For example, if you do not want to create new incidents in BMC Helix ITSM for existing ServiceNow incidents, you can add the filter condition:
    Select field Created and enter date criteria as on or before <date of the integration was deployed>.

(Optional) Task 8: To map custom ServiceNow fields to existing BMC Helix ITSM fields

You can map custom fields created in ServiceNow 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 ServiceNow

  1. Log in to BMC Helix iPaaS as an administrator and navigate to the Cloud Studio.

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

  3. Select the Sync ServiceNow Incidents with BMC Helix ITSM project and click View/Edit.
  4. Expand the Sync ServiceNow Incidents to ITSM workflow.
  5. Refresh the schema to include the custom fields added to ServiceNow.
    1. Select the Query incident element in the Query ServiceNow Incident workflow and click View/Edit.
    2. Click Step 1 in the query, and then click Refresh.
    3. From the Select an Object list, select the incident table, and click Next.
    4. On Step 2, to ensure that your custom field is added to the list of incident fields, click Refresh.
    5. When the incident field table is loaded, to select any new fields added to ServiceNow incident table, deselect and then select SELECT ALL
    6. Click Next, and then on Step 3, click Finished.  
  6. To create and update mappings for the custom field in other transformations, create a global variable for the custom field.
    1. Click the Mapping Servicenow incident to variable transformation element in the Query ServiceNow Incident operation, and click View/Edit.
    2. In the Target pane, click Settings and select Edit schema.
    3. To add the field mapping for the custom field, click  Add Field.
    4. Scroll to the bottom of the field list, enter the field name and select the Type, and then click Save Changes..
    5. To create and update the mapping for the custom field in other transformations, in the Target pane, click the script icon  next to the new field and add a global variable entry for the field. For example, add the following global variable to the script:
      $custom_field = OUTPUT$incident$Entity.u_custom_field$;
  7. Map the custom field to an existing BMC Helix ITSM field.
    1. Click the Prepare ITSM request transformation element in the Create incident in ITSM operation and select View/Edit.
    2. On the  Variables  tab, click Use Variables. .
    3. From the variable list, drag and drop 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. Similarly, map the global variable to the BMC Helix ITSM field in the Map ServiceNow to ITSM incident data transformation element of the Update incident in ITSM operation.
  8. Deploy the integration.
    For more information about deploying the project, see Task 4: To deploy and enable the project.
  9. If you delete the custom field from ServiceNow, you must delete the custom field mapping in the integration template. To delete the custom field mappings:

    1. Refresh the schema in the Query incident element of the Query ServiceNow Incident workflow.
    2. Remove the global variable created in the Mapping ServiceNow incident to variable transformation element of the Query ServiceNow Incident operation
    3. Remove the field mappings defined for the custom field in the Prepare ITSM request transformation element in the Create incident in ITSM operation and the Map ServiceNow to ITSM incident data transformation element of the Update incident in ITSM operation.
    4. Deploy the integration.
      For more information about deploying the project, see Task 4: To deploy and enable the project.

Workflows included in the integration template

The following workflows are defined as a part of the integration template. This section describes the details of the operations and configurations defined within each workflow.

Enable Integration

This workflow defines the operations required to enable the integration after all the required project configurations are completed. The following operations are included in this workflow:

Operation nameActions performed
Login to Jitterbit

Logs in to BMC Helix iPaaS by using the Jitterbit credentials provided in the project variables

Check Custom API and Security Profiles existVerifies if any custom APIs or security profiles exist for the ServiceNow integration
Delete API and Security Profile if neededDeletes existing APIs or security profiles, if required
Create Security Profiles and Custom API

Creates the security profiles and RestAPIs in BMC Helix iPaaS

Create Webhook in ServiceNowLogs in to ServiceNow by using the credentials provided in the project variables
Check Webhook artifact existVerifies if the Webhook API configurations exist in ServiceNow

Create Webhook artifact

Creates the Webhook API configuration to ServiceNow

Update Webhook artifact

Updates the configuration with the new data if Webhook API configuration exists
Failure notificationSends an email notification if the Webhook API configuration is not added to ServiceNow

Sync ServiceNow Incident to ITSM

This workflow creates or updates the BMC Helix ITSM incident when a ServiceNow incident is created or updated. The following operations are included in this workflow:

Operation nameActions performed
Integration API Flow ControllerEnables all the API entry points by using the details provided in the project variables
Query ServiceNow incidentGets details of the ServiceNow incident to create the corresponding incident in BMC Helix ITSM
Create incidents in ITSMMaps the required ServiceNow fields to the BMC Helix ITSM incident fields
Update ITSM incident number in ServiceNowUpdates the ServiceNow incident with the BMC Helix ITSM incident URL and number
Update ITSM incident
  • Queries BMC Helix ITSM for a corresponding incident request when a ServiceNow incident is updated
  • Maps the ServiceNow fields to BMC Helix ITSM fields
  • Updates the existing BMC Helix ITSM incident with the updated values
Update Work NotesUpdates the Work Info field in BMC Helix ITSM
Error NotificationSends an email notification if incident creation or update fails
Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Sudeepkumar Chandrasekaran

    Helix IPAAS subscription is it BMC license ? or license procured from Jitterbit ?

    Mar 14, 2023 11:56
    1. Priya Shetye

      Sudeepkumar Chandrasekaran 

      BMC Helix iPaaS subscription is a BMC license.

      For information about the subscription details, see BMC Helix iPaaS service

      May 08, 2023 06:55
  2. Sudeepkumar Chandrasekaran

    if i buy BMC Helix IPAAS , will i get only BMC excllusive connectors ? do i get the integration templates as well ?

    what is the difference if i buy the license on jitterbit ? its not so clear in documentation,.

    Mar 14, 2023 12:01
    1. Priya Shetye

      Sudeepkumar Chandrasekaran 

      The License entitlements for BMC Helix iPaaS, powered by Jitterbit section in the BMC Helix iPaaS service document should help answer your query in detail. 

      May 08, 2023 06:57