Creating a ServiceNow integration

About this task

Similar incidents, such as from a ServiceNow integration, are called similar tickets. Similar tickets are grouped with other tickets from other integrations as input to IBM Cloud Pak for AIOps AI algorithms.

If your connected ServiceNow application is version 4.4.0 or later, IBM Cloud Pak® for AIOps incidents and alerts are kept up to date in ServiceNow. Specifically the following fields:

• incidents: short description, description, priority, and state
• alerts: alert summary, state, severity, event count, and last occurrence

Prerequisites

• Before you create a ServiceNow integration, you must create users and configure ServiceNow. For more information about configuring ServiceNow, see Configuring the ServiceNow App for IBM Cloud Pak for AIOps.

• Your ServiceNow application must be version 4.4 to connect with IBM Cloud Pak® for AIOps version 4.6.0. This integration is not supported for earlier versions of the ServiceNow application.
• ServiceNow instances with self-signed certificates are not supported for connecting with IBM Cloud Pak for AIOps.
• You can have only one ServiceNow integration per instance.

For more information about working with a ServiceNow integration, see the following sections:

• Creating a ServiceNow integration
• Enabling a ServiceNow integration
• Editing a ServiceNow integration
• Deleting a ServiceNow integration
• Troubleshooting a ServiceNow integration
• Known issue with a ServiceNow integration

Creating a ServiceNow integration

To create a ServiceNow integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. On the Integrations page, click Add integration.

4. From the list of available integrations, find and click the ServiceNow tile.

   Note: If you do not immediately see the integration that you want to create, you can filter the tiles by type of integration. Click the type of integration that you want in the Category section.

5. On the side-panel, review the instructions and when ready to continue, click Get started.

6. On the Add integration page, define the general integration details:

   • Name: The display name of your integration.

   • Description: An optional description for the integration.

   • URL: The URL of your ServiceNow instance.

     Important: If you have any restrictive EgressNetworkPolicies in place, ensure that they are updated to allow for this outbound integration. For more information, see Postinstallation tasks.

   • User ID: A ServiceNow user with say a ibm.aiops user ID and an x_ibm_waiops.admin role.

     

     Important: You must create a new, unique user in ServiceNow specifically for your ServiceNow integration before you create your integration. Make sure that you are using the correct user role, the x_ibm_waiops.admin, for your integration. You must also make sure that the time zone set for this user matches your system time zone in ServiceNow. For more information about ServiceNow users, see Managing roles.

   • Password: Your ServiceNow password for ibm.aiops user.

   • Select the orchestration or deployment type as Local or Remote.

     Note: If you select 'Remote' you will be provided with a bootstrap command to finish the orchestration.

   Click Test Connection to validate the ServiceNow instance and credentials. If the test fails, verify the ServiceNow instance is stable and that the credentials are correct.

   

7. Click Next.

8. (Optional) Enter Field mapping information.

   

   With this field, you can map custom data fields to default fields in ServiceNow. The change_request and incident tables are queried from ServiceNow. These fields are used for AI training. These tables can be modified to include additional columns.

   • The following change_request fields are extracted:

     "u_environment", "u_environment_id", "cmdb_ci", "short_description", "u_purpose", "description", "backout_plan", "close_notes", "state", "close_category", "sys_created_by", "assigned_to", "sys_domain", "category", "business_service", "priority", "approval", "type", "contact_type", "production_system", "impact", "reason", "justification", "start_date", "end_date", "work_start", "work_end", "calendar_duration", "close_code","delivery_task", "implementation_plan", "test_plan", "work_notes_list"
     

   • The following incident fields are extracted:

     "short_description", "description", "u_caused_by_change", "caused_by", "close_code", "u_detection_source", "close_notes", "u_environment","cmdb_ci", "comments_and_work_notes", "impact", "problem_id", "priority", "severity", "state", "resolved_at", "closed_at", "opened_at", "parent", "made_sla", "watch_list", "upon_reject","sys_updated_on", "child_incidents", "hold_reason", "approval_history", "resolved_by", "sys_updated_by","opened_by", "user_input", "sys_created_on", "sys_domain", "sys_created_by", "knowledge", "order","calendar_stc", "delivery_plan", "contract", "active", "business_service", "sys_domain_path", "rfc","time_worked", "expected_start", "business_duration", "group_list", "work_end", "caller_id", "reopened_time", "approval_set", "subcategory", "correlation_display", "delivery_task", "work_start",
     "assignment_group", "additional_assignee_list", "business_stc", "calendar_duration", "notify", "service_offering", "sys_class_name", "closed_by", "follow_up", "parent_incident", "contact_type", "reopened_by", "incident_state", "urgency", "company", "reassignment_count", "activity_due", "assigned_to", "comments", "approval", "sla_due", "due_date", "sys_mod_count", "reopen_count", "sys_tags", "escalation", "upon_approval", "correlation_id", "location", "category", "work_notes_list"
     

   Example: If you add a custom column (named my_custom_field1_name) into the table, the prefix u_ is added so the field must be queried as u_my_custom_field1_name. If this field contains useful description information for training, you might want the existing description field to be updated for both change requests and incidents to use this data. To support this mapping, you need to add the following JSON to the Field mapping:

   {
     "codec": "servicenow",
     "description": "u_my_custom_field1_name"
   }
   

   With this mapping, the description value is replaced with the value from u_my_custom_field1_name. For example, assume the default description field has the value Server down for 2 hours due to an upgrade and the u_my_custom_field1_name field had the value Impact: server down, Duration: 2 hours, Cause: server upgrade. With the above mapping in place, the description now has the value Impact: server down, Duration: 2 hours, Cause: server upgrade. This description value is also now used for AI training. If the mapping is not in place, the u_my_custom_field1_name value is not used for AI training as it is not examined through the integration.

   Adding the field mapping can give you flexibility to add your own custom fields into AI training. Also, if an existing field should not be used for training, you can add a new custom column with a default value to use for training instead of the existing field value.

   Notes:

   • The field mapping is applied to both historic and live data. Once the mapping is set in the integration and training is completed, the mapping should not be changed. Otherwise, if new change requests or incidents are queried, the mapping is not applied properly, which can cause results to be less accurate.

   • Currently, the field mapping applies to all tables. If a custom field does not exist in a table, a workaround is to create that custom field with default values to ensure that the mapping does not fail. Otherwise, the data is not be retrieved properly for that table.

9. Click Next.

10. (Optional) Select whether to Collect topology data, and if selected, set the options for data collection:

    • Collect inventory and topology data: Set to On for inventory and topology data collection. You can also set advanced options.

    • Schedule request: Set to On and this allows you set the Job Schedule (optional)

      • Start date: The start date of when the job is to run.

      • Time: The time to run the observer job.

      • Time interval (period): How frequently to run the job (either by hour, minute, days, or weeks).

      • Interval: The duration of time between runs based on the Time interval (period). For example, if you wanted the job to run every 2 hours, set the interval to 2 and the Time interval (period) to hours. Enter 0 for the Interval to run the observer job one time (and manually through the interface otherwise).

    • Set advanced options section:

      • Number of records to fetch per API calls from a table: The number of records to fetch per API calls from a table. Default value is 10000. The value should be between 100 and 10000.

      • Entity mapping for the sysClassNames parameter to overwrite the entity type: To use a user-defined entity type, enter a parameter to overwrite the default sys_class_name. Separate the values of the class name and the new entity type name with a colon. For example, cmdb_ci_linux_server:node.

      • ServiceNow tables to be discovered by observer: The supported tables to be discovered are sys_user and tables that are either system or user created children of cmdb_ci.

      • Trust all certificates by bypassing certificate verification: If On, the observer allows the integration to the target environment without verification. The default value is On.

        • Options to exclude entity edges: Select an exclude option to exclude resource edges. You can select the following options. The default value is none.

          • none
          • uniqueID
          • entityType

        • List of entities to exclude edge modelling: The listed entities will be not have any edge connectivity to any entities.

        • Use an 'include' or 'exclude' filter in API requests: Specify that the API filter should use include or exclude in every ServiceNow API call. Enter the filter attributes in the filter_resources parameter.

        • Filter resources based on defined JSON attributes: To use a filter in API calls to retrieve resources, enter the JSON key:value attribute. Use the format key=value where value can be more than one, for example key=value1,value2,value3. For more than one key, use | as a delimiter, for example, key=value1|key=value1,value2,value3.

        • Number of connection retries: Set the number of times a connection should try again. The default value is 2.

        • Delay before a connection retry (milliseconds): Specify the period of time in milliseconds to delay before a connection tries again.

        • Maximum number of tables per cmdb_ci_rel api batch call: Specify this configurable parameter to split one long call into multiple small calls. This prevents the cmdb_ci_rel (relationship) query from being too long. The default and maximum value is 10.

        • Integration timeout: The amount of time before a connection times out in milliseconds. The default value is 5000 milliseconds.

        • Read timeout: The amount of time before a read operation times out in milliseconds. The default value is 5000 milliseconds.

        • Proxy Host: The proxy host for your ServiceNow instance.

        • Proxy Port: The proxy port for your ServiceNow instance. The default value is 8080.

        • Proxy Username: Specify the username for connecting to the proxy.

        • Proxy Password: Specify the password for connecting to the proxy.

        • Proxy Secure: Specify whether the proxy server is secure. The default value is false

        • Access Scope: An optional CSV String that lists the values which can be used to provide a scope for the resources. These values can be used to aid the mapping of alerts to resources when resources that are in different scopes share the same matchTokens. Examples of scope can be locations, project names, or namespaces.

        • Generate debug support file: Set to On to generate the debug support file. The default is Off.

    

    For information about REST APIs and ServiceNow, see Configuring ServiceNow Observer jobs and Topology REST Observer APIs.

11. Click Next.

12. (Optional) Enter the Collect and synchronize operations data information.

    • Live data - Train and use Change risk and Similar tickets algorithms; synchronize alert and incident data

      Select the Live data collection mode to enable the following capabilities:

      • Provide risk assessments on change requests (after model is trained and deployed).
      • Update alerts in Cloud Pak for AIOps when corresponding incident-based alerts are updated in ServiceNow.
      • Update incidents in Cloud Pak for AIOps when corresponding incidents are updated in ServiceNow.
      • Collect resolved ServiceNow incidents for Similar tickets training. This option is required for similar tickets functionality.
      
      

      Note: If you are interested in utilizing change risk or similar tickets AI algorithms, you must first set Mode to Historical data for ticket data collection to collect a minimum amount of data, and then run AI training on that data. For more information, see Planning data loading and training.

      • Configuring polling intervals for live data collection: Live data collection is done at configurable intervals ranging anywhere from every 10 seconds to once a day. For risk assessments and similar tickets polling, the default is 15 minutes. For alert and incident polling, the default is 1 minute. The default values serve as a starting point but polling can be done at longer or shorter intervals depending on user preference.

        Important: Updates made to Cloud Pak for AIOps data (incidents and alerts) in ServiceNow by the integration user (ibm.aiops) will not be synchronized in Cloud Pak for AIOps. A different ServiceNow user must be used when making updates to Cloud Pak for AIOps data in ServiceNow.

        

    • Historical data - Train Change risk and Similar tickets algorithms

      To enable the change risk and similar ticket algorithms, a single set of training data is necessary to train the AI model. You complete the 'Start' and 'End' date fields.

      • Ticket types: Specify the types of ServiceNow tickets that you want to pull in to the system. By default, change request and incident tickets are included and data is queried from those ServiceNow tables. You can edit this list to remove any types you don't want to sample.

        Important: Different types of AI models have different requirements to properly train a model. Make sure that your settings satisfy minimum data requirements. For more information about how much data you need to train different AI models, see Configuring AI training.

        

13. Click Done.

You have created a ServiceNow integration in your instance.

After the integration creation is complete, and if you selected the Remote option for integration deployment, you can download the bootstrap script by selecting the created integration, and clicking download from the options menu (three vertical dots). If a script is regenerated, it invalidates the credentials of previously downloaded scripts for that integration.

Note: You can either copy the script or download as an sh file to run it on a remote cluster.

Prerequisites before running the bootstrap script on remote cluster:

• Podman needs to be installed on the remote cluster.
• Log in to the Image registry for the script to pull in the image that uses the Podman login command.

After you create your integration, you must enable the data collection to connect your integration with the AI of IBM Cloud Pak for AIOps. For more information about enabling your integration, see Enabling a ServiceNow integration. To verify that your job completed successfully, view the schedule status of your ServiceNow integration in the Schedule integrations tab.

To create more integrations (such as a ChatOps integration), see Configuring Integrations.

For more information about working with the insights provided by your integrations, see ChatOps insight management. For more information about change risk from ServiceNow, see Change risk.

Training a Change Risk model

For more information about training a change risk model, see Training a Change Risk model.

Enabling and disabling a ServiceNow integration

If you didn't enable your data collection during creation, you can enable your integration afterward. You can also disable a previously enabled integration the same way. If you selected Live data for initial AI training when you created your integration, you must disable the integration before AI model training. To enable or disable a created integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. On the Manage integrations tab of the Integrations page, click the ServiceNow integration type.

4. Click the integration that you want to enable or disable.

5. Go to the Collect ticket data section. Set Data collection to On or Off to enable or disable data collection. Disabling data collection for an integration does not delete the integration.

   

You enabled or disabled your integration. For more information about deleting a integration, see Deleting a ServiceNow integration.

Editing a ServiceNow integration

After you create your integration, your can edit the integration. For example, if you specified Historical data for initial AI training but you now want your integration to sample live data for continuous monitoring, you can edit it. To edit a integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. Click the ServiceNow integration type on the Manage integrations tab of the Integrations page.

4. On the ServiceNow integrations page, click the name of the integration that you want to edit. Alternatively, you can click the options menu (three vertical dots) for the integration and click Edit. The integration configuration opens.

5. Edit your integration. Click Next to go through the integration configurationn pages. Click Save when you are done editing.

You edited your integration. If you did not enable ticket data collection when creating your integration, you can enable the integration directly from the interface. For more information about enabling and disabling your integration, see Enabling and disabling a ServiceNow integration. For more information about deleting a integration, see Deleting a ServiceNow integration.

Note: After you upgrade, you might find that the Next run field in the Scheduled integrations tab is showing the last run time of the scheduled job, instead of the next run time. If this happens, the next run time should be regarded as the last run time.

Deleting a ServiceNow integration

If you no longer need your ServiceNow integration and want to not only disable it, but delete it entirely, you can delete the integration from the console.

Note: You must disable ticket data collection before you delete your ServiceNow integration. For more information about disabling ticket data collection, see Enabling and disabling a ServiceNow integration.

To delete a integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. Click the ServiceNow integration type on the Manage integrations tab of the Integrations page.

4. On the ServiceNow integrations page, click the options menu (three vertical dots) for the integration that you want to delete and click Delete.

5. Enter the name of the integration to confirm that you want to delete your integration. Then, click Delete.

Your integration is deleted.

Note: Alerts that are generated from the ServiceNow integration are automatically cleared when the integration is deleted.