Synchronizing ServiceNow change requests with BMC Helix ITSM change requests by using Jitterbit Harmony
BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template that enables you to synchronize BMC Helix ITSM change requests with ServiceNow change requests. 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 | ServiceNow to BMC Helix ITSM |
---|---|---|
Create tickets | Creates a ServiceNow change request from a new BMC Helix ITSM change request | Creates a BMC Helix ITSM change request from a new ServiceNow change request |
Synchronize updates | Updates a ServiceNow change request from an updated BMC Helix ITSM change request | Updates a BMC Helix ITSM change request from an updated ServiceNow change request |
Synchronize activity notes or attachments | Synchronizes an activity note or an attachment from a BMC Helix ITSM change request with the ServiceNow change request | Synchronizes an activity note or an attachment from a ServiceNow change request with the BMC Helix ITSM change request |
Synchronize statuses | Synchronizes the status of a BMC Helix ITSM change request with the ServiceNow change request | Synchronizes the status of a ServiceNow change request with the BMC Helix ITSM change request |
BMC Helix ITSM to ServiceNow data flow
The following image gives an overview of the data flow for creating a ServiceNow change request from a BMC Helix ITSM change request:
ServiceNow to BMC Helix ITSM data flow
The following image gives an overview of the data flow for creating a BMC Helix ITSM change request from a ServiceNow change request:
Before you begin
You require the following items to successfully set up and use this integration:
Required versions |
|
---|---|
Authentication and permissions |
|
Jitterbit Harmony subscription | A valid
BMC Helix iPaaS
|
Application registration | A client ID and secret for BMC Helix iPaaS in ServiceNow—Register BMC Helix iPaaS with your ServiceNow instance by creating 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. |
Task 1: To download and import the integration template project file
Download the Sync ServiceNow Change with BMC Helix ITSM Update 2022-07-01
to your system.
This file contains the BMC Helix iPaaS Cloud Studio project BiDirectional_Sync_ServiceNow_Change_With_BMC_Helix_ITSM_Change_Request.Important
Your ability to access product pages on the EPD website is determined by the license your company purchased.
As a developer, log in to BMC Helix iPaaS and navigate to the Cloud Studio.
- On the projects page, click Import.
Click Browse and then select the Sync ServiceNow Change with BMC Helix ITSM Update.json file downloaded.
The Project Name and Organization fields are automatically populated depending on the values you 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, select the BiDirectional_Sync_ServiceNow_Change_With_BMC_Helix_ITSM_Change_Request project, and click View/Edit.
Task 2: To assign roles and ACL permissions to your ServiceNow user
- Log in to your ServiceNow instance as an Administrator.
- 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:
- Click All and select System Security > Users and Roles > Roles.
- To create a new role, click New.
- Enter a name and description for the role, and click Submit.
- To open the roles record, on the Roles page, double-click the name of the role you created.
- To add the required roles, on the Contains Roles tab, click Edit...
Select the role to add from the Collection list, and click >.
Add the following roles:itil
personalize_dictionary
business_rule_admin
script_include_admin
Click Save.
The selected roles are displayed on the Contains Roles tab.- Click Update.
- Click the user profile icon and select Elevate Role to get the privileged role to be able to add ACL permissions for users.
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.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 To add access control list rules, complete the following steps for each rule listed in the Required access permissions table:
- On the Access Controls page, click New.
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( ).
- Click Submit.
- Click Save.
Task 3: To update the project variables for the integration template
- Next to the Environment name, click the ellipses ... and select Project Variables.
- 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_Company Enter a valid BMC Helix ITSM company for which the change request must be created; for example, Apex Global.
ITSM_Endpoint Enter the BMC Helix ITSM host URL. ITSM_CR_URL
Enter the BMC Helix ITSM change request URL that you want to display in the corresponding ServiceNow change record.
ITSM_Midtier_URL Enter the URL of the Mid Tier instance that you are using. ITSM_User Enter the user ID to access BMC Helix ITSM. ITSM_Password Enter the password for the user to access BMC Helix ITSM. ITSM_Service_Type Enter a valid BMC Helix ITSM Service Type.
You can set the following values for this variable:
- User Service Restoration
- User Service Request
- Infrastructure Restoration
- Infrastructure Event
- Security Problem
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.
ServiceNow ServiceNow_Endpoint Enter the URL of the ServiceNow instance. SNOW_User Enter the User ID to access ServiceNow. ServiceNow_Password Enter the password of the user to access ServiceNow. ServiceNow_Client_Id Enter the OAUTH API endpoint ID generated in ServiceNow. ServiceNow_Client_Secret Enter the OAUTH API endpoint client secret generated in ServiceNow. ServiceNow_Reference_Field1 Enter the name of a valid ServiceNow field to store the BMC Helix ITSM change request URL.
We recommend that you set this value to correlation_display.
ServiceNow_Reference_Field2 Enter the name of a valid ServiceNow field to populate the corresponding ITSM change number.
We recommend that you set this value to correlation_id.
ServiceNow_Webhook_APIKEY Enter the ServiceNow system property that has apikey for the BMC Helix iPaaS APIKEY authentication profile.
ServiceNow_Webhook_Basic_User Enter the ServiceNow system property name to store BMC Helix iPaaS BASIC authentication user name.
ServiceNow_Webhook_Basic_Password Enter the ServiceNow system property name to store BMC Helix iPaaS BASIC authentication password.
ServiceNow_Webhook_Business_Rule_Name Enter the name of the business rule to be created for the ServiceNow Webhook configuration. ServiceNow_Webhook_Property_Name Enter the name of the ServiceNow system property that stores the BMC Helix iPaaS integration API.
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_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_Name_Suffix Enter a suffix to be added to the name of the Webhook API that is created in BMC Helix iPaaS to handle requests from BMC Helix ITSM and ServiceNow.
BHIP_API_Response_Type_SNOW Enter the REST API response type used by the Webhook API to handle requests from ServiceNow. This value is added in the BMC Helix iPaaS Jitterbit API.
By default, the value is set to VARIABLE.
BHIP_API_Response_Type_ITSM 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_ApiKey_Key_Name_SNOW For security profile type APIKEY, enter the name of the APIKEY to be used for the security profile.
The Jitterbit API and the Webhook API use this APIKEY for authentication while accessing ServiceNow.
BHIP_API_Security_Profile_ApiKey_Key_Name_ITSM For security profile type APIKEY, enter the name of the APIKEY to be used for the security profile.
The Jitterbit API and the Webhook API use this APIKEY for authentication while accessing BMC Helix ITSM.
BHIP_API_Security_Profile_BASIC_Auth_Username_SNOW For security profile type BASIC, enter the user name to be used to create the ServiceNow security profile.
The Jitterbit API and the Webhook API use this user name for authentication while accessing ServiceNow.BHIP_API_Security_Profile_BASIC_Auth_Password_SNOW For security profile type BASIC, enter the password for the ServiceNow security profile created.
The Jitterbit API and the Webhook API use this password for authentication while accessing ServiceNow.BHIP_API_Security_Profile_BASIC_Auth_Username_ITSM For security profile type BASIC, enter the user name to be used to create the BMC Helix ITSM security profile.
The Jitterbit API and the Webhook API use this user name for authentication while accessing BMC Helix ITSM.BHIP_API_Security_Profile_BASIC_Auth_Password_ITSM For security profile type BASIC, enter the password for the BMC Helix ITSM security profile created.
The Jitterbit API and the Webhook API use this password for authentication while accessing BMC Helix ITSM.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.
BHIP_Webhook_Security_Profile_Type Enter a security profile type. Webhook uses the security profile to call the BMC Helix iPaaS API.
The default value is BASIC.
BHIP_API_Security_Profile_Type_SNOW Enter a security profile type.
You can set the following values for this variable:
- BASIC
- APIKEY
- ANONYMOUS
The default value is BASIC.
Use comma-separated values to specify multiple security profile types.
Security Profile Type defines the authentication type to be used by the Webhook API while accessing ServiceNow. This value is added in the BMC Helix iPaaS Jitterbit API.
BHIP_API_Security_Profile_Type_ITSM Enter a security profile type.
You can set the following values for this variable:
- BASIC
- APIKEY
- ANONYMOUS
The default value is BASIC.
A security profile type defines the authentication type to be used by the Webhook API while accessing BMC Helix ITSM. This value is added in the BMC Helix iPaaS Jitterbit API.
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.
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 Change Request Actions in Service Now and ITSM TO SNOW - Create New Change Request in ServiceNow operations in the Sync ITSM to ServiceNow Change Request 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 transformation element for the ITSM TO SNOW - Create New Change Request in ServiceNow operation:
ITSM fields | ServiceNow fields |
---|---|
Category | Category |
Change Request ID | Correlation ID |
Description | Description |
Detailed Description | Short Description |
Impact | Impact |
Instance ID | Correlation Display |
Priority | Priority Important: The Priority field in ServiceNow and BMC Helix ITSM is autopopulated based on the Urgency field. |
Status | State 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. |
Status Reason | Reason or On 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:
|
Type | Type |
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
- Open the Sync ITSM to ServiceNow Change Request project.
- On the Workflows tab, in the Sync ITSM to ServiceNow Change Request workflow, scroll to the Process Source Payload And Preparing Payload For Create and Update Change Request Actions in Service Now operation.
- Click the Mapping Response transformation element, and select View/Edit:
- In the Target pane, from the View menu, select Mapped.
- On the Variables tab, click Use Variables.
- From the variable list, drag the variable to the field mapping you want to update in the Mappings section.
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
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:
After you enable the integration, when a change request is created in BMC Helix ITSM, a corresponding change request is created in ServiceNow, and the converse is true. Any updates made to the BMC Helix ITSM change request are synced with the ServiceNow change request, and the converse is true. The Change Request Number is synced to the Correlation Id field in ServiceNow, and the ServiceNow change 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:
- In BMC Helix iPaaS, select API Manager > My APIs.
- Open the required API.
- Select Enable Debug Mode Until: and set it for the required date and time.
- Save and publish the API.
(Optional) Task 7: To update the default trigger conditions for the Sync ITSM to ServiceNow change 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
- As an administrator, log in to Mid Tier.
- In the Basic Information section, enter the value of the Source_Webhook_Name project variable in Description and click Search.
The following webhooks are displayed:CHG:ChangeInterface_Create—Creates a webhook in BMC Helix ITSM
CHG:ChangeInterface—Updates a webhook in BMC Helix ITSM
CHG:WorkLog—Creates a worklog in BMC Helix ITSM
- Click the configuration to update the trigger condition for that event.
- 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".
(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 custom field created in ServiceNow
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 Sync ITSM to ServiceNow Change project and click View/Edit.
- Expand the ITSM Change to SNOW Change workflow.
- Refresh the schema to include the custom fields added to ServiceNow.
- Select the Query ITSM change element in the Process Source Payload And Preparing Payload For Create and Update Change Actions in Service Now operation and click View/Edit.
- Click Step 1 in the query, and then click Refresh.
- From the Select an Object list, select the change request table, and click Next.
- On Step 2, to ensure that your custom field is added to the list of change request fields, click Refresh.
- When the change request field table is loaded, to select any new fields added to the BMC Helix ITSM change request table, clear and then select SELECT ALL.
- Click Next, and then on Step 3, click Finished.
- To create and update mappings for the custom field in other transformations, create a global variable for the custom field.
- Click the Mapping Response transformation element in the Process Source Payload And Preparing Payload For Create and Update Change Actions in Service Now operation, and click View/Edit.
- In the Target pane, click Settings and select Edit schema.
- To add the field mapping for the custom field, click +Add Field.
- Scroll to the bottom of the field list, enter the field name and select the Type, and then click Save Changes.
- To create and update the mapping for the custom field in other transformations, in the Target pane, click the script icon
$custom_field = OUTPUT$chaneg$Entity.u_custom_field$;
next to the new field and add a global variable entry for the field. For example, add the following global variable to the script:
- Follow these steps to map the custom field to an existing ServiceNow field:
- Click the Prepare ServiceNow Request Payload transformation element in the ITSM TO SNOW - Create New Change in ServiceNow operation and select View/Edit.
- On the Variables tab, click Use Variable .
- 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.
- Click Return to Workflow.
- Deploy the project.
For more information about deploying the project, see Task 4: To deploy and enable the project. 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, perform the following steps:- Refresh the schema in the Query ITSM change element in the Process Source Payload And Preparing Payload For Create and Update Change Actions in Service Now operation.
- Remove the global variable created in the Mapping Response transformation element in the Process Source Payload And Preparing Payload For Create and Update Change Actions in Service Now operation.
- Remove the field mappings defined for the custom field in the Prepare ServiceNow Request Payload transformation element in the ITSM TO SNOW - Create New Change in ServiceNow operation and the Mapping ServiceNow Change Response transformation element of the Update ServiceNow Change operation.
- 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. Refer to the following details for an overview of the tasks defined in the workflow operations and configurations defined within each workflow.
Enable Integration
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 |
---|---|
Enable Integration | Creates all the required webhooks for the template and enables the integration |
Create a Single API | Creates an API in BMC Helix iPaaS after you enable the integration |
Login into Jitterbit | Logs in to Jitterbit by using the credentials provided in the project variables |
Check Custom API and Security Profiles exist | Checks if the custom API and security profiles exist |
Delete API and Security Profiles if needed | Deletes existing APIs or security profiles, if required |
Creates Security Profiles and Custom API | Creates security profiles and REST APIs in BMC Helix iPaaS |
Publish Custom API | Publishes the custom APIs to BMC Helix iPaaS |
Create Webhook in ServiceNow | Logs in to ServiceNow by using the credentials provided in the project variables |
Check webhook artifact exist | Verifies if the Webhook API configurations exist in ServiceNow |
Create webhook artifact | Creates the Webhook API configuration in ServiceNow |
Update webhook artifact | If the Webhook API configuration exists in ServiceNow, updates the configuration with the new data |
Failure Notification | Sends an email notification if the Webhook API configuration is not added to ServiceNow |
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 whether 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 | Deletes existing APIs or security profiles, if required |
BHIP Publish API | Publishes the custom APIs to BMC Helix BMC Helix iPaaS and 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 ITSM 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 a webhook API configuration exists, deletes the existing configuration |
SNOW Change to ITSM Change
Operation name | Actions performed |
---|---|
Service Now Flow Controller | Enables all the API entry points by using the details provided in the project variables |
Query ServiceNow ChangeRequest | Gets details of the ServiceNow change request to create the corresponding change request in BMC Helix ITSM |
Create Change Request in ITSM | Creates a change request in BMC Helix ITSM from a new ServiceNow change request |
Update ITSM CR number in ServiceNow | Update the ServiceNow change request with the BMC Helix ITSM change request number |
Update Servicenow Url in Itsm CR Activity Log | Updates the ServiceNow change request URL in the BMC Helix ITSM change request activity notes |
Check CR Data Updated | Checks the ServiceNow change request data that is updated |
Change Request Query for Update | Gets the ServiceNow change request that is updated |
CR Update | Updates the BMC Helix ITSM change request with the corresponding ServiceNow change request updates |
Update Work Log of CR | Updates the ServiceNow change request worklog with the BMC Helix ITSM change request activity note |
Error Notification | Sends an email notification if change request creation or update fails. |
Login ITSM | Logs in to BMC Helix ITSM |
Get Worklog for ITSM CR | Gets the activity notes for a BMC Helix ITSM change request corresponding to the ServiceNow change request |
Get Attachment Details | Gets a list of attachments from ServiceNow to BMC Helix ITSM |
Query Attachment File from SNOW | Gets a list of attachments added to a ServiceNow change request |
Upload Attachment File to ITSM | Uploads an attachment to a BMC Helix ITSM change request |
ITSM Change to SNOW Change
This workflow creates the ServiceNow change request when a BMC Helix ITSM change request is created or updated. The following operations are included in this workflow:
Operation name | Actions performed |
---|---|
ITSM Flow Controller | Enables all the API entry points by using the details provided in the project variables |
Parse ITSM webhook Payload | Parses the BMC Helix ITSM ITSM payload |
Process Source Payload And Preparing Payload For Create and Update CR Actions in Service Now | Gets the BMC Helix ITSM change request data on a create event, and then based on the Vendor Ticket Number and Event Type, calls the next operation |
ITSM to SNOW - Create New CR in ServiceNow | For a new BMC Helix ITSM change request, maps the required BMC Helix ITSM fields to the ServiceNow change request fields to create a new change request in ServiceNow |
Fetch ServiceNow CR ID | Gets the Change Request ID and System ID of the ServiceNow change request |
Fetch requestid | Gets the BMC Helix ITSM change request ID |
SNOW TO ITSM - Update ServiceNow CR ID and URL in ITSM CR | Updates the BMC Helix ITSM change request with the ServiceNow change request URL and number |
Process Source WorkNote Payload And Preparing Payload For Creating WorkNote in ServiceNow | Gets the required data to create or update details of a worklog added to the BMC Helix ITSM change request |
Check ITSM CR Data changed | Checks for updates in the BMC Helix ITSM change request |
Update ServiceNow CR | Saves the updates to the ServiceNow change request
|
Check Worklog data changed | Checks the data in the BMC Helix ITSM change request activity note that is changed |
Update WorkNotes in ServiceNow | Updates the worklog updates in ServiceNow |
Query Attachment File in ITSM | Checks for attachments in the BMC Helix ITSM change request worklog |
Upload Attachment File to ServiceNow | Adds attachments from the BMC Helix ITSM change request to the ServiceNow change request. |
Get Vendor Ticket | Gets the ServiceNow change request details |
Pass WorkLogID return Change Request No | Passes the BMC Helix ITSM change request worklog ID and gets the ServiceNow change request number |
pass CRQ Return Req ID | Passes the BMC Helix ITSM change request ID and gets the ServiceNow change request ID |
Comments
Log in or register to comment.