Creating IBM Tivoli Netcool/Impact integrations

About this integration

By connecting with IBM Tivoli Netcool/Impact, IBM Cloud Pak for AIOps can then leverage your existing IBM Tivoli Netcool/Impact deployment to run automation policies that you manage with IBM Tivoli Netcool/Impact. New policies that you create in IBM Tivoli Netcool/Impact can reference the extension framework API for IBM Cloud Pak for AIOps. With these policies, you can write automation processes in IBM Tivoli Netcool/Impact to complete operations in IBM Cloud Pak for AIOps, such as to query alerts and incidents, and request changes to alerts.

Note: You can create multiple integrations between IBM Cloud Pak for AIOps and IBM Tivoli Netcool/Impact. Each integration must point to a unique Impact endpoint.

When you create the integration in IBM Cloud Pak for AIOps to IBM Tivoli Netcool/Impact, the integration automatically creates the RESTful DSA data source in IBM Tivoli Netcool/Impact. To complete the integration with IBM Tivoli Netcool/Impact integration after creating the integration in IBM Cloud Pak for AIOps, you need to edit this RESTful DSA data source in IBM Tivoli Netcool/Impact to define your authentication settings for communicating with IBM Cloud Pak for AIOps API. After editing and verifying the authentication settings, you can begin to create and run your automation policies from IBM Tivoli Netcool/Impact.

Note: If the IBM Tivoli Netcool/Impact cluster uses a non-default cluster name ("NCICLUSTER"), the integration might fail to validate the integration. For more information, see Impact integration fails for Impact server with non-default cluster name.

Before you begin

• Ensure that you have IBM Tivoli Netcool/Impact Version 7.1 with fix pack level 33 or later and IBM Cloud Pak for AIOps 4.9.0 installed.

• Obtain the following details for your IBM Tivoli Netcool/Impact deployment:

  • The endpoint for the GUI server (example: https://noi-impact.fyre.ibm.com:16311)

  • The endpoint(s) for the primary Impact server and any secondary servers (example: https://noi-impact.fyre.ibm.com:9081)

  • If Impact is deployed with Event Manager on OpenShift, you can use the oc describe noi command to retrieve the endpoints.

  • The username and password for the IBM Tivoli Netcool/Impact administrator (example: impactadmin) for connecting to the IBM Tivoli Netcool/Impact endpoint.

  • The set of CA certificates for IBM Tivoli Netcool/Impact if the endpoint is secured by SSL/TLS. If self-signed this means all the certificates from all the servers.

    You can extract these certificates from your IBM Tivoli Netcool/Impact deployment with openssl:

    • For the GUI server (port 16311)

      openssl s_client -showcerts -servername noi-impact.mycluster.com -connect noi-impact.mycluster.com:16311 </dev/null
      

    • For the backend server (port 9081)

      openssl s_client -showcerts -servername noi-impact.mycluster.com -connect noi-impact.mycluster.com:9081 </dev/null
      

    To combine multiple certificates (there is a minimum requirement of two) in the integration settings, you can list them sequentially in no specific order. The combined certificates resembles the following structure:

    -----BEGIN CERTIFICATE-----
    ABCDEfGHIjklMnOPQrSTUVWXYZABCdefghiJ1k2LMNoPQRSTUVwxYZABCDEFGhij
    ... Server 1 ...
    r+wGXNPwrw==
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    ABCDEfGHIjklMnOPQrSTUVWXYZABCdefghiJ1k2LMNoPQRSTUVwxYZABCDEFGhij
    ... Server 2 ...
    ZYXWVUTSRqpoNnLKJiHGFEDCBAZYXwvutsrQ1p4ONMlKJIHGFEdcBAZYXWVUTsrq
    -----END CERTIFICATE-----
    

Creating an IBM Tivoli Netcool/Impact integration

To create an IBM Tivoli Netcool/Impact 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 IBM Tivoli Netcool/Impact 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 (Events).

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. You cannot use spaces or special characters in the display name. Use only alphanumeric characters.

   • GUI Server URLs of Impact endpoint: Enter the GUI URL or URLs for the endpoint. For high availability environments with multiple URLs, enter the URLs as a comma-separated list. For example, https://impact-1, https://impact-2.

   • Backend Server URLs of Impact endpoint: Enter the backend URL or URLs for the endpoint. For high availability environments with multiple URLs, enter the URLs as a comma-separated list. For example, https://impact-1, https://impact-2.

   • User ID: Enter the user ID for the IBM Tivoli Netcool/Impact administrator (example: impactadmin) for connecting to the IBM Tivoli Netcool/Impact endpoint.

   • Password: Enter the password for the IBM Tivoli Netcool/Impact administrator for connecting to the IBM Tivoli Netcool/Impact endpoint.

   • Impact Certificates: Enter the valid set of CA certificates for IBM Tivoli Netcool/Impact to use for verifying the SSL/TLS connection to the REST services for IBM Tivoli Netcool/Impact.

   • Deployment options: This is where the integration connector is deployed, not the location of IBM Tivoli Netcool/Impact. Select one of the options, Local or Remote. Local deploys the integration in the same cluster and project (namespace) where IBM Cloud Pak for AIOps is installed. Alternatively, Remote deploys the integration in your chosen location, such as a different network region, on SaaS, or a remote on-premises VM, cluster, or container.

7. Click Done.

8. If you selected Remote, you are presented with an Install Cloud Pak for AIOps remote integration window.

   1. Click Download shell script and copy the bootstrap script to a remote VM.

      The bootstrap script requires Podman to run. You can either run it as root or non-root.

      Note: To run Podman as non-root, see the Podman installation.

   2. Run the bootstrap script on the remote VM to complete the deployment.

9. You are redirected to the IBM Tivoli Netcool/Impact page for the integration.

   Your new integration is listed in the table on the page. The integration has an intial status of Initializing. After a few minutes, the status changes to Running if your integration is successful. With your integration successful and running, you now need to configure the integration in IBM Tivoli Netcool/Impact.

10. Configure the integration in IBM Tivoli Netcool/Impact.

To complete the integration, you need to edit the RESTful DSA data source in IBM Tivoli Netcool/Impact.

Editing an IBM Tivoli Netcool/Impact integration

After you create your integration, you can edit the integration. For example, if you want to add or change the listed GUI or backend URLs for the Impact endpoint, or to update the User ID or password. 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 IBM Tivoli Netcool/Impact integration type on the Manage integrations tab of the Integrations page.

4. On the IBM Tivoli Netcool/Impact 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 as required. Click Save when you are done editing.

Your integration is now edited.

Deleting an IBM Tivoli Netcool/Impact integration

If you no longer need your integration and want to delete it entirely, you can delete the integration from the console.

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 IBM Tivoli Netcool/Impact integration type on the Manage integrations tab of the Integrations page.

4. On the IBM Tivoli Netcool/Impact integrations page, click the Delete icon for the integration that you want to delete.

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

   Your integration is deleted in IBM Cloud Pak for AIOps. To fully remove the integration, log into the IBM Tivoli Netcool/Impact GUI and delete the IBM Cloud Pak for AIOps data source and policies from IBM Tivoli Netcool/Impact.

Enriching an incident by using IBM Tivoli Netcool/Impact policy

Cloud Pak for AIOps ingests data from many sources and is a central source of truth for a site reliability engineer (SRE) to manage all their disparate systems. You might need to automatically enrich Cloud Pak for AIOps incidents with data from external systems, such as state, ticket number or priority. The additional data gives more insight for an SRE to manage and resolve an incident.

To enrich incidents with data from external systems, use the following steps:

1. Create IBM Tivoli Netcool/Impact policy, which uses the Cloud Pak for AIOps API to enrich the incidents.
2. Create Cloud Pak for AIOps policy to send new incidents to IBM Tivoli Netcool/Impact and invoke the IBM Tivoli Netcool/Impact policy.

Log(
  'Enriching Incident(' + EventContainer.incident.id +
  ') with ticket number from external ITSM system'
);

// This is the DSA created when you create the Netcool/Impact integration with AIOps
var dsa = 'AIOps-jaunpuri1-f243ea05-c344-4d51-9e47-ec7e5031dfea';  

// The experimental API being utilised
var AIOPS_INCIDENT_PATH = 'api/issue-resolution/v1alpha1/incidents/'; 

// The incoming Incident ID from AIOps
var incidentId = EventContainer.incident.id; 
var path = AIOPS_INCIDENT_PATH + incidentId;

// In practice this would be a function call to get the URL from the external ITSM system
var ticketLink='https://github.com/oneill/myproject/issues/1489';  

// Like ticketLink, this would be a function call. Hardcoded here to simplify
var ticketNumber = '1489';

// Like ticketLink. Hardcoded here to simplify.
var priority = 2;

var incidentUpdateRequest = {
  priority: priority,
  insights: [
    {
      id: String(JavaCall('java.util.UUID', null, 'randomUUID', [])),
      type: 'aiops.ibm.com/insight-type/itsm/metadata',
      source: 'myGithubProject',
      details: {
        id: String(JavaCall('java.util.UUID', null, 'randomUUID', [])),
        name: 'Github',
        type: 'aiops.ibm.com/insight-type/metadata',
        permalink: ticketLink,
        ticket_num: ticketNumber
      }
   }
  ]
};

// Call the experimental API to enrich the AIOps incident
result = RESTfulAPIPATCH(dsa, path, { 
  Data: JSON.stringify(incidentUpdateRequest)
});

Log('Enrich Result: ' + result);
if (result.status > 202) {
  throw new Error(
    'Error ' + result.status + ' patching incident ' + id + '\n' +
    result.statusText
  );
}

Create Cloud Pak for AIOps policy

Create Cloud Pak for AIOps policy to invoke your IBM Tivoli Netcool/Impact when new incidents are created in Cloud Pak for AIOps.

Policy triggers and policy actions within Cloud Pak for AIOps can resemble the following examples:

When new incidents are created in Cloud Pak for AIOps, the incidents automatically invoke your IBM Tivoli Netcool/Impact policy and the incident is updated with the ticket number and any other edits you decided to make to state, priority, or owner.

Note: You can also create further Cloud Pak for AIOps policies to invoke extra IBM Tivoli Netcool/Impact policies when edits are made to the incidents in Cloud Pak for AIOps. For example, if you change the priority or state in Cloud Pak for AIOps and want to write that back to the external ticketing system. For this scenario, in the Trigger entity type field in the Policy details tab, select After an incident has been updated.

var insights = EventContainer.incident.insights;

for (var i = 0; i < insights.length; i++) {
  var thisInsight = insights[i];

  if (thisInsight.type === 'aiops.ibm.com/insight-type/itsm/metadata') {
    Log("Insight: "+thisInsight.details.ticket_num);
  }
}