Creating ServiceNow incidents from BMC Helix ITSM incidents by using Jitterbit Harmony


BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template that enables you to create ServiceNow incidents from BMC Helix ITSM incidents. 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 case

BMC Helix ITSM to ServiceNow

Create tickets

Creates a ServiceNow incident from a new BMC Helix ITSM incident

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

Synchronize updates

Updates a ServiceNow incident from an updated BMC Helix ITSM incident

Synchronize activity notes or attachments

Synchronizes an activity note or an attachment from a BMC Helix ITSM incident with a ServiceNow incident

BMC Helix ITSM to ServiceNow data flow

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

221_ServiceNow_ITSM_createSNOWIncident.png

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

221_ServiceNow_ITSM_updateSNOWIncident.png

Before you begin

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

Required versions

  • ServiceNow Paris or later
  • BMC Helix ITSM 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 subscription

Application registration

A client ID and secret for BMC Helix iPaaS in ServiceNow - Register BMC Helix iPaaS with your ServiceNow instance. 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 to create an endpoint for clients to access the instance.

Important

If you are using 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 length of the field you used to store the BMC Helix ITSM incident URL in ServiceNow to view the complete incident URL.

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

  1. Download the Sync BMC Helix ITSM Incidents with ServiceNow Update 2023-01-03 file to your system.
    This file contains the BMC Helix iPaaS Integration Studio project Sync BMC Helix ITSM Incidents with ServiceNow Update.

    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 iPaaS and navigate to the Integration Studio.
  3. On the projects page, click Import.
  4. Click Browse and then select the Sync BMC Helix ITSM Incidents with ServiceNow 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. 
  6. To open the project file at a later time, select the environment where the integration templates are available, select the Sync BMC Helix ITSM Incidents with ServiceNow Update 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. 

    Type

    Operation

    Name

    For creating and updating incidents and creating comments

    record

    Read

    Table [sys_db_object]

    None

    record

    Read

    Field class [sys_glide_object]

    None

    record

    Read

    Dictionary Entry [sys_dictionary]

    *

    For creating the webhook required for the integration template

    record

    Read

    System Property [sys_properties]

    None

    record

    Write

    System Property [sys_properties]

    None

    record

    Execute

    System Property [sys_properties]

    None

    record

    Create

    System 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:
      • Type—Select record from the list.
      • Operation—Select a value.
      • Name—Select a value and the fields for that value.
      • Requires role—Under Role, double-click Insert a new row, enter the value for role you created in Step 2 and click Save( icon_SNOW_save.png).
    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 ellipses ... 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 variable

      Action

      BMC Helix ITSM

      ITSM_Endpoint

      Enter the BMC Helix ITSM host URL.

      ITSM_Username

      Enter the User ID to access BMC Helix ITSM.

      ITSM_Password

      Enter the Password of the user to access BMC Helix ITSM.

      ITSM_Webhook_Security_Profile_Type

      Enter a security profile type.

      You can set the following values for this variable:

      • BASIC
      • No authentication

      The default value is 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.

      ITSM_Webhook_Name

      Enter a name for the webhook that is created in the BMC Helix ITSM instance.

      By default, this value is set to BHIP_Webhook.

      ITSM_HelpDesk_Qualifier

      Enter the qualifiers to add conditions to the Webhook to define urgency filters for incidents for which an incident should be created in ServiceNow.

      You can use qualifiers like =, !=, and so on. Urgency type values include: 1-Critical, 2-High, 3-Medium,4-Low.

      The default value is set to

      'Urgency' ="2-High" OR 'Urgency' ="1-Critical"

      ITSM_Worknote_Qualifier

      Enter the qualifiers to add conditions to the Webhook to define filters for the worknotes for which incidents should be updated. The default value is set to('Submitter'= "Remedy Application Service" OR 'Submitter'= "Allen") 

      ServiceNow

      SNOW_Endpoint

      Enter the URL of the ServiceNow instance.

      SNOW_User

      Enter the user ID to access ServiceNow.

      SNOW_Password

      Enter the password for the user to access ServiceNow.

      SNOW_Client_ID

      Enter the OAUTH API endpoint ID generated in ServiceNow.

      For details about obtaining this ID, see the Application registration section in the Before you begin section.

      SNOW_Client_Secret

      Enter the OAUTH API endpoint client secret generated in ServiceNow.

      For details about obtaining the client secret, see the Application registration section in the Before you begin section.

      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 to access BMC Helix iPaaS.

    • Webhook API variables

      Project variables

      Action

      BHIP_Project_Name

      Enter the name of the ServiceNow project for which you want to create the Webhook API.

      BHIP_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. BMC Helix ITSM calls this operation when a create or update event occurs.By default, the value is set to Integration API Flow Controller.

      BHIP_API_Name

      Enter the name of the Webhook API that is created in ServiceNow.By default, this value is set to SyncITSMToSnow.

      BHIP_API_User_Roles

      Enter comma-separated values of the user roles assigned for the BMC Helix iPaaS API.

      Only a user with these roles can access the APIs. Leave this value blank to restrict access only to administrators.

      BHIP_API_Response_Type

      Enter the REST API response type used by the Webhook API to handle requests from BMC Helix ITSM. This value is added in the BMC Helix iPaaS Jitterbit API. 

      By default, the value is set to VARIABLE.

      BHIP_API_Security_Profile_Type

      Enter a security profile type.
      You can set the following values for this variable:

      • BASIC
      • ANONYMOUS

      The default value is 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 ITSM 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.

      BHIP_API_Security_Profile_Name_Suffix

      Enter the suffix to be added to the name of security profiles created.

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

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

      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.

    • Email notification configurations

      Project variable

      Action

      BHIP_SMTP_Hostname

      Enter the SMTP host details for email configuration.

      BHIP_To_Email_Address

      Enter the email address to which you want to send the notification emails.

      BHIP_From_Email_Address

      Enter the email address from which the notification emails must be sent.

      BHIP_Email_Subject

      Enter the default subject line for the notification email.

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

      BHIP_Email_On_Success

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

      BHIP_Email_On_Error

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

(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 Process Source Payload And Preparing Payload For Create and Update Incident Actions in Service Now and ITSM TO SNOW - Create New Incident in ServiceNow operations in the Sync ITSM to ServiceNow Incident workflow. For additional information about the workflow, see Workflows included in the integration template.

The following out-of-the-box fields are mapped in the Prepare ServiceNow Request Payload transformation element for the ITSM TO SNOW - Create New Incident in ServiceNow operation:

ITSM fields

ServiceNow fields

Customer First Name, Customer Last Name.

Caller

(First name, Last name)

Description/Summary

Short Description

Detailed Description

Description

Impact

Impact

Priority

Priority

Important: The Priority field in ServiceNow and BMC Helix ITSM is autopopulated based on the Urgency field.

Resolution

Resolution Notes

Reported Source

Contact Type

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.

State

Status Reason

Resolution code or Hold Reason

Important:

When the Status in BMC Helix ITSM is set to Pending and a Status Reason is selected, in ServiceNow the following values are selected by default:

  • Hold_reason is set to Awaiting Caller.
  • When Status is set to Resolved, close_code is set to Solved (Permanently)
  • When Status is set to Closed, close_code is set to Closed/Resolved by Caller

Vendor Ticket Number

Incident ID and System ID

Urgency

Urgency

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 BHIP 21.3.04 Sync BMC Helix ITSM Incidents with ServiceNow Update project.
  2. On the Workflows tab, in the Sync ITSM to ServiceNow Incident workflow, scroll to the Process Source Payload And Preparing Payload For Create and Update Incident Actions in Service Now operation.
  3. Click the Mapping Response transformation element, and select View/Edit:
    itsmSnowMappingResponseTransformation.png

  4. In the Target pane, from the View menu, select Mapped.
  5. On the Variables tab, click Use Variables.
  6. From the variable list, drag the variable to the field mapping you want to update in the Mappings section.
  7. Click Return to Workflowreturn_to_workflow.png.

    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

After you enable the integration, when an incident is created in BMC Helix ITSM, a corresponding incident is created in ServiceNow. Any updates made to the BMC Helix ITSM incident are synced with the ServiceNow incident. The Incident Number is synced to the Correlation Id field in ServiceNow, and the ServiceNow incident ID is synced to 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 BHIP_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 Sync ITSM to ServiceNow incident project

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

To update or define filters for the trigger condition

  1. As an administrator, log in to Mid Tier.  
  2. In the Basic Information section, enter the value of the Source_Webhook_Name project variable in Description and click Search
    The two Webhook configurations defined for the HPD:Help Desk for create and update events and HPD:Work Log for work log events are displayed.
  3. Click the configuration to update the trigger condition for that event. 
  4. In the Event Information section, you can select the Events, or in Qualification, enter the qualification to trigger the Webhook configuration. For example, you can set the qualification to 'Status' != "Closed".
    midTierTrigger.png
  5. Click Save.

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

You can map custom fields created in BMC Helix ITSM to existing ServiceNow fields by updating the mappings in the integration template. If you delete a custom field that is not mapped to a mandatory field in ServiceNow, 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 a developer and navigate to the Integration Studio.
  2. Select the environment where the integration templates are available.
  3. Select the BHIP 21.3.04 Sync BMC Helix ITSM Incidents with ServiceNow Update project and click View/Edit.
  4. Expand the Sync ITSM Incidents to ServiceNow Operations workflow.
  5. To refresh the schema to include the custom fields added to ServiceNow, complete the following procedure:
    1. In the Process Source Payload And Preparing Payload For Create and Update Incident Actions in Service Now operation, next to the Query ITSM incident element, click the ellipses ... 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 the BMC Helix ITSM 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. In the Process Source Payload And Preparing Payload For Create and Update Incident Actions in Service Now operation, next to the Mapping Response transformation element, click the ellipses ... and click View/Edit.
    2. In the Target pane, click Settings and select Edit schema.
      snowEditSchema.png
    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 icon_viewScript.png 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. To map the custom field to an existing ServiceNow field, complete the following procedure:
    1. In the ITSM TO SNOW - Create New Incident in ServiceNow operation, next to the Prepare ServiceNow Request Payload transformation element, click the ellipses ... and click 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 ServiceNow field in the Target pane.
    4. Click Return to Workflow return_to_workflow.png.
  8. To deploy the integration after you update the field mappings, see Task 4: To deploy and enable the project.
  9. If you delete the custom field from BMC Helix ITSM, you must delete the custom field mapping in the integration template. To delete the custom field mappings:
    1. Refresh the schema in the Query ITSM incident element in the Process Source Payload And Preparing Payload For Create and Update Incident Actions in Service Now operation.
    2. Remove the global variable created in the Mapping Response transformation element in the Process Source Payload And Preparing Payload For Create and Update Incident Actions in Service Now operation.
    3. Remove the field mappings defined for the custom field in the Prepare ServiceNow Request Payload transformation element in the ITSM TO SNOW - Create New Incident in ServiceNow operation and the Mapping ServiceNow Incident Response transformation element of the Update ServiceNow incident operation.
    4. Deploy the integration.
      For more information about deploying the workflow, 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. Refer to the following details for an overview of the tasks defined in the workflow operations and configurations defined within each workflow.

Enable or Disable Integration Operations

This workflow defines the operations to control the sync between BMC Helix ITSM and ServiceNow. The following operations are included in this workflow:

Operation name

Actions performed

Create and Enable integration

Creates the required configurations for the integration template

Pause Record Sync

Pauses the sync between BMC Helix ITSM and ServiceNow

Resume Record Sync

Resumes the sync between BMC Helix ITSM and ServiceNow

Purge integrations

Deletes existing APIs or security profiles, if required

BHIP Operations

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 name

Actions performed

BHIP Login

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

BHIP Get Api and Security Profiles details

Verifies if any custom APIs or security profiles exist for the ServiceNow integration

BHIP Create Security Profiles or Custom API

Creates the security profiles and REST APIs in BMC Helix iPaaS

BHIP Delete API or Security Profile

Delete existing APIs or security profiles, if required

BHIP Publish API

Publishes the custom APIs to BMC Helix BMC Helix iPaaSand ServiceNow

ITSM Operations

This workflow creates the Webhook required for BMC Helix ITSM. The following operations are included in this workflow:

Operation name

Actions performed

Create Webhook Driver

Creates all the required Webhook APIs for the integration

Login to ITSM

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

Get all Webhooks

Retrieves Webhook API configurations that exist in BMC Helix ITSM for the integration

Check ITSM Webhook Existence

Verifies if the Webhook API configurations exist in BMC Helix ITSM

Create ITSM Webhook

Creates the Webhook API configuration to BMC Helix ITSM

Update ITSM Webhook

Updates the Webhook API configuration

Delete existing ITSM Webhook

If Webhook API configuration exists, deletes the existing configuration

Failure Notification

Sends an email notification if the Webhook API configuration is not added to BMC Helix ITSM

Sync ITSM incidents to ServiceNow Operations

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

Operation name

Actions performed

Integration API Flow Controller

Enables all the API entry points by using the details provided in the project variables

Process Source Payload And Preparing Payload For Create and Update Incident Actions in ServiceNow

Gets the ITSM incident data on a create event, and then calls the next operation based on the Vendor Ticket Number and Event Type

ITSM to SNOW - Create New Incident in ServiceNow

For a new BMC Helix ITSM incident, maps the required ITSM fields to the ServiceNow incident fields to create a new incident in ServiceNow

Fetch ServiceNow Incident Number

Gets the Incident Number and System ID of the ServiceNow incident

Fetch requestID

Gets the number of the BMC Helix ITSM incident 

SNOW TO ITSM - Update ServiceNow Incident Number and URL in ITSM Incident

Updates the ITSM incident with the ServiceNow incident URL and number

Process Source WorkNote Payload And Preparing Payload For Creating WorkNote in ServiceNow

Gets required data to create or update details of a worklog added to the BMC Helix ITSM incident

ITSM Login

Logs in to BMC Helix ITSM

Update WorkNotes in ServiceNow

Updates the worklog in the ServiceNow incident

Query Attachment File in ITSM

Checks for attachments in the BMC Helix ITSM worklog

Upload Attachment File to ServiceNow

Add attachments from the BMC Helix ITSM incident to the ServiceNow incident

Check Incident Data changed

Checks for updates in the BMC Helix ITSM incident

Update ServiceNow incident

Saves the updates to the ServiceNow incident

  • When a BMC Helix ITSM incident is updated, query ServiceNow for a corresponding incident request
  • Maps the BMC Helix ITSM fields to the ServiceNow fields
  • Updates the existing ServiceNow incident with the updated values.

Error Notification

Sends an email notification if incident creation or update fails

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*