Jitterbit Harmony template changes

1. Review introduction section. 

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template that enables you to bidirectionally synchronize problem records between ServiceNow and  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. 

2. For templates that are bi-directional use statement in blue. 

3. Add use cases in a table instead of a bullet list. Check sentence construction for the use case. 

The template provides the following capabilities: 

The following image is an example of the <productName> record details displayed in the corresponding BMC Helix ITSM change request.

BMC Helix ITSM to ServiceNow data flows

4. Make sure the title of this section is prod A to prodB data flow(s).

5. Add lead in statements for each workflow, and remove the title from the image.

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

6. Preceding is the example data flow diagram with text format approved by the editors.  

ServiceNow to BMC Helix ITSM data flows

Before you begin

6. Change this to a side table format

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

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

8. Change the title back to "To download and import", and add the download step to this procedure.  

1. Download the templateName - Link to EPD DeepLink project file to your system.
   This file contains the BMC Helix iPaaS Cloud Studio project BiDirectional - Sync ServiceNow with BMC Helix ITSM.

   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 Cloud Studio.
3. On the projects page, click Import.
4. Click Browse and then select the BHIP 21.05.00 Sync BMC Helix ITSM Problems with ServiceNow Update 2021-06-01.json (NOTE: 9. Remember to update this file name based on the EPD file name) 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 then 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 BiDirectional - Sync ServiceNow with BMC Helix ITSM project, and click View/Edit.

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

10. Update step 1 statement to put location, and then action

11. Update table headers to Value Action

12. Make variable descriptions parallel and add examples where necessary

13. Change . For example to ; for example, 

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 variable	Action
     BMC Helix ITSM
     ITSM_Endpoint	Enter the BMC Helix ITSM host URL.
     ITSM_User	Enter the User ID to access BMC Helix ITSM.
     ITSM_Password	Enter the Password of the user to access BMC Helix ITSM.
     ITSM_Company	Enter a valid BMC Helix ITSM company for which the problem must be created; for example, Calbro Services.
     ITSM_Problem_URL	Enter the REST API URL of the BMC Helix ITSM instance. The integration uses this URL to construct the Problem URL. The ServiceNow field defined in the Source_Reference_Field1 project variable stores this URL. Important: If both ITSM_Problem_URL and ITSM_Midtier_URL are provided, the ITSM_Problem_URL is given preference.
     ITSM_Midtier_URL	Enter the REST API URL for Mid Tier.Important: Provide the Remedy Mid Tier URL if you have not implemented BMC Remedy with Smart IT.
     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 The default value for this variable is User Service Restoration.
     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
     ServiceNow_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. For details about obtaining this ID, see the Application registration section in the Before you beginsection.
     ServiceNow_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 beginsection.
     ServiceNow_Reference_Field1	Enter the name of a valid ServiceNow field to store the URL of the ITSM problem. We recommend that you set this value to correlation_display. Important: If you have provided the Target_Midtier_URL value, 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 the correlation_display value, you need to manually update the field size to 300 characters.
     ServiceNow_Reference_Field2	Enter the name of a valid ServiceNow field to populate the corresponding ITSM problem number. We recommend that you set this value to correlation_id.
     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 variable	Action
     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. 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_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 FINAL_TARGET.
     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 NO_RESPONSE.
     BHIP_Webhook_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.
     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. Enter comma separated values to select multiple profile types (ANONYMOUS,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. 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_BASIC_Auth_Username_ITSM	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 while accessing BMC Helix ITSM.
     BHIP_API_Security_Profile_BASIC_Auth_Password_ITSM	For security profile type BASIC, enter the password for the security profile created.  The Jitterbit API and the Webhook API use this password for authentication while accessing BMC Helix ITSM.
     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. Important: For profile types supported by the ServiceNow 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_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_ApiKey_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_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 60.
     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.
     ServiceNow_Webhook_Script_Include_Name	Enter the name of the script include value to be used for the Webhook configuration.

   • Email notification configurations

     Project variable	Action
     BHIP_SMTP_Hostname	Enter 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 3: To review and update out-of-the-box field mappings

The integration templates provide default field mappings between the two applications. To modify the field mappings, update the transformation elements in the following operations:

• Query ServiceNow problem operation in the SNOW to ITSM workflow
• Process Source Payload And Preparing Payload For Create and Update Problem Actions in Service Now operation in the ITSM to SNOW workflow

For additional information about the workflow, see Workflows included in the integration template.

ServiceNow to BMC Helix ITSM field mappings

The following out-of-the-box fields are mapped in the Mapping servicenow problem to variable transformation element for the SNOW to ITSM - Query ServiceNow problem operation.

For Contact Type, Impact, State, and Urgency fields that support only specific values, corresponding value mappings are provided in the following table:

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 ServiceNow to BMC Helix ITSM field mappings

1. Open the BiDirectional - Sync ServiceNow with BMC Helix ITSM project.
2. In the SNOW to ITSM workflow, scroll to the Query ServiceNow problem operation.
3. Click the Mapping servicenow problem to variable transformation element, and then click View/Edit.
4. In the Target pane, from the View menu, select Mapped.
5. From the Variables tab in the Source pane, drag a variable to a field mapping you want to update in the Mappings section.
6. Click Return to workflow .

BMC Helix ITSM to ServiceNow field mappings

The following table lists out-of-the-box fields mapped in the Mapping Response transformation element of the ITSM to SNOW - Process Source Payload And Preparing Payload For Create and Update Problem Actions in Service Now operation.

For Impact, Investigation Status, Status, and Urgency fields that support only specific values, corresponding value mappings are provided in the following table:

Long term goal (add a section on OOTB mappings for fields that support only specific values.

You can edit the BMC Helix ITSM to ServiceNow 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 BMC Helix ITSM to ServiceNow field mappings

1. Open the BiDirectional - Sync ServiceNow with BMC Helix ITSM project.
2. In the ITSM to SNOW workflow, scroll to the Process Source Payload And Preparing Payload For Create and Update Problem Actions in Service Now operation.
3. Click the Mapping Response transformation element, and then click View/Edit.
4. In the Target pane, from the View menu, select Mapped.
5. From the Variables tab in the Source pane, drag a variable to a field mapping you want to update in the Mappings section.
6. Click Return to workflow .

Task 4: To deploy and enable the project

14. Use the Include Page macro so include the Deploy and enable project page and add a conclusion about the template capabilities.

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, when a problem record is created in ServiceNow, a corresponding problem is created in BMC Helix ITSM, and the converse is true. Any updates made to the ServiceNow problem are synced with the BMC Helix ITSM problem, and the converse is true. The Problem Number field is synced to the Correlation Id field in ServiceNow, and the ServiceNow problem ID is synced to the Vendor Ticket Number field in BMC Helix ITSM.

(Optional) Task 5: To set the time for API debug mode

15. Add (Optional) in italics, to the title of this section.

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, select API Manager > My APIs.
2. Open the API created for the integration. The API name is the value defined in the BHIP_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 ITSM to ServiceNow problem 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 then click Search. 
   The three Webhook configurations for create, update, and worklog events are displayed. They are defined, respectively, for creating a webhook, updating a webhook, and creating a worklog. 

1. Click the configuration to update the trigger condition for that event. 
2. In the Event Information section, 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 6: 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 a developer and navigate to the Cloud Studio.
2. Select the environment where the integration templates are available.
3. Select the BiDirectional - Sync ServiceNow with BMC Helix ITSM project.
4. Expand the SNOW to ITSM workflow.
5. Refresh the schema to include the custom fields added to ServiceNow.
   1. In the Query ServiceNow problem operation, click the Query problem element, and then click View/Edit.
   2. Click Step 1 in the query, and then click Refresh.
   3. From the Select an Object list, select the problem table, and then click Next.
   4. On Step 2, to ensure that your custom field is added to the list of problem fields, click Refresh.
   5. When the problem field table is loaded, to select any new fields added to the ServiceNow problem table, clear the SELECT ALL option and then select it again. 
   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 Query ServiceNow problem operation, click the Mapping servicenow problem to variable transformation element, and then 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$problem$Entity.u_custom_field$;
7. Follow these steps to map the custom field to an existing BMC Helix ITSM field:
   1. In the Create problem in ITSM operation, click the Create Problem Request transformation element, and then click View/Edit.
   2. From the Variables tab in the Source pane, drag the global variable you created for your custom field, and then map it to the BMC Helix ITSM field in the Target pane.
   3. Click Return to workflow .
   4. Similarly, map the global variable to the BMC Helix ITSM field in the Update Problem Transformation element of the Update ITSM problem operation.
8. To deploy the integration after you update the field mappings, follow the instructions provided in 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. In the Query ServiceNow problem operation, refresh the schema in the Query problem element.
   2. Remove the global variable created in the Mapping servicenow problem to variable transformation element in the Query ServiceNow problem operation.
   3. In the Create problem in ITSM operation, remove the field mappings defined for the custom field in the Create Problem Request transformation element.
   4. In the Update ITSM problem operation, remove the field mappings defined for the custom field in the Update Problem Transformation transformation element.
   5. Deploy the integration.

Mapping custom BMC Helix ITSM fields to existing ServiceNow fields

You can also 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 BMC Helix ITSM

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 BiDirectional - Sync ServiceNow with BMC Helix ITSM project.
4. Expand the ITSM to SNOW workflow.
5. Refresh the schema to include the custom fields added to BMC Helix ITSM.
   1. In the Process Source Payload And Preparing Payload For Create and Update Problem Actions in Service Now operation, click the Query element, and then click View/Edit.
   2. Click Step 1 in the query, select SELECT FROM LIST option, and then click Refresh.
   3. From the Select a Form list, select the problem interface, and click Next.
   4. On Step 2, to ensure that your custom field is added to the list of problem fields, click Refresh, and then 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 Problem Actions in Service Now operation, click the Mapping Response transformation element, and then 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$problem$Entity.u_custom_field$;
7. Follow these steps to map the custom field to an existing ServiceNow field:
   1. In the Create New Problem in ServiceNow operation, click the Create SNOW Problem transformation element, and then click View/Edit.
   2. From the Variables tab in the Source pane, drag the global variable you created for your custom field, and then map it to the ServiceNow field in the Target pane.
   3. Click Return to workflow .
   4. Similarly, map the global variable to the BMC Helix ITSM field in the Prepare ServiceNow Update Request Payload element of the Update ServiceNow Problem operation.
8. To deploy the integration after you update the field mappings, follow the instructions provided in 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. In the Process Source Payload And Preparing Payload For Create and Update Problem Actions in Service Now operation, refresh the schema in the Query element.
   2. Remove the global variable created in the Mapping Response transformation element in the Process Source Payload And Preparing Payload For Create and Update Problem Actions in Service Now operation.
   3. In the Create New Problem in ServiceNow operation, remove the field mappings defined for the custom field in the Create SNOW Problem transformation element.
   4. In the Update ServiceNow Problem operation, remove the field mappings defined for the custom field in the Prepare ServiceNow Update Request Payload transformation element.
   5. Deploy 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.

Enable Integration

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

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:

ITSM Operations

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

SNOW to ITSM

ITSM to SNOW

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