Integrate CA Automic

CA Digital Experience Insights / UIM combined with Automic Service Orchestration offers predictive analytics to help solve complex IT problems like performance, capacity, configuration issues to be detected proactively (before they impact users) and remediated automatically. 
uim902-9-0-2
HID_Automic_Integration
CA Digital Experience Insights / UIM combined with Automic Service Orchestration offers predictive analytics to help solve complex IT problems like performance, capacity, configuration issues to be detected proactively (before they impact users) and remediated automatically. 
The CA UIM-CA Automic integration is achieved using the messagegtw probe which publishes UIM alarms to an Automic endpoint that is configured in the messagegtw probe, using webhooks.
When CA UIM raises an alarm for disk full warning, the message is passed on to Automic where a specific job is run to clear the cache for the disk directory. You can also define/ configure other parameters from CA UIM to be sent as part of the message/ alarm that is sent to Automic. 
The CA Unified Infrastructure Management messagegtw (Message Gateway) probe is used to publish CA UIM alarms to an external application using webhooks. A webhook is a simple notification message using an HTTP POST to an external application. In CA UIM, a webhook is triggered based on the occurrence of an alarm.
 
Basic workflow to configure messagegtw for an endpoint
 
Configure messagegtw
Configure messagegtw
 
Contents:
 
 
 
4
 
 
Overview
When an event occurs in nas, it publishes to a queue on the hub. The messagegtw probe listens to the messages and alarms from nas through a queue that you create on the hub. You also need to configure the same queue on the messagegtw probe. The messagegtw probe makes an HTTP request to the URL configured for the webhook and posts the message to the configured webhook. 
You can deploy the probe on a primary hub, secondary hub, or a robot. You can choose to configure multiple webhooks to receive the message and alarms from messagegtw.
The nas auto operator GUI is now enhanced to support webhooks. The new action type “webhooks’ will work for running instances of the messagegtw and invokes a callback on that probe to see what webhooks or outbound rest integrations you have configured to allow you to create an Auto-Operator to point to a specific webhook.
The probe supports multiple instances of the messagegtw such that you can configure multiple probes across hubs and robots based on your environment. You can then create Auto-Operator profiles from nas for webhooks, filter the alarms, and publish to the specific instance of the messagegtw you want to publish to, by specifying the directory path of the robot or hub where the messagegtw probe is deployed.
You need to create an Auto-Operator profile in nas, using which you can filter the alarm and messages to be published through messagegtw. For more information, see the 'webhook' action type in nas auto-operator profiles.
The messagegtw probe GUI allows you to configure the webhook, and map nas and messagegtw fields. Messages that you add are sent to the webhook. In the messagegtw GUI, listeners are the webhooks listening to messagegtw probe. You can create multiple profiles under listeners. All the listener profiles that you create listen to messagegtw probe.
Prerequisites 
  • Deploy nas on the Primary Hub.
    You need to deploy the nas auto-operator for webhook on the primary hub, to configure webhook auto operator profile. This is required to be done on the primary hub, because data_engine probe is on the primary hub.
Create a Hub Attach Queue
CA UIM components use queues to pass messages. Create an attach queue in the hub to publish messages from messagegtw to the webhooks you configure.
 
Follow these steps:
 
  1. On the robot, open the hub probe configuration and go to 
    Queue List
    .
  2. In the Queue List Configuration table, select 
    New
    .
  3. Specify the following required information:
    •  
      Queue Name
       - Enter a unique and descriptive name. For usability, use a name similar or identical to the subject. You specify the queue name when configuring the webhook in the mesagegtw probe.
       Ensure that the queue name you specify while creating the attach queue, is the same as the queue name you specify in the 
      messagegtw configuration
      webhook, queue name
       field.
    •  
      Active
       - Select 
      active
       for the queue to be available immediately.
    •  
      Type
       - Select 
      attach
      .
    •  
      Hub Address
       (get queues) - Address of the hub that has the corresponding attach queue.
    •  
      Subject
       (attach queues) - Enter the subject probe_messagegtw.
 A dialog prompting you to restart the probe to enable the changes is displayed. Select Yes to restart the hub probe.
Configure messagegtw Probe
After you install the probe, configure the probe setup using the messagegtw probe Admin Console.
 
Follow these steps:
 
  1. Deploy the 
    messagegtw
     probe on a Primary or Secondary hub, or a robot.
  2. Select the 
    messagegtw 
    probe from the Probes tab and select 
    Configure
    .
    The default probe information is displayed.
  3. (Optional) In the Probe Configuration section, specify Log level, and 
    Save
    . The default log level is 1.
    : Log as little as possible during normal operation to minimize disk consumption, and increase the amount of detail when debugging.
  4. Select 
    Webhook
    Options
    Clone
    . We recommend you to create a custom webhook configuration based on the default or sample configuration.
  5. Select 
    Submit
     and 
    Close
  6. In the 
    EndPoint  Details
     section, select 
    New
     to configure a new endpoint and specify the following fields:
    Sample values are displayed in the profile you have cloned.
    •  
      URL: 
      Specify the endpoint url of the webhook where messagegtw will post the messages. Obtain this URL from the external application API Token.
    •  
      AUTH_METHOD:
       Specify the authentication method. You may select Basic or None. messagegtw supports only Basic Authentication. If you want to post your Webhooks to a service requiring authentication, use Basic HTTP authentication by modifying your URL from https://my.example.com to https://username:[email protected].
    •  
      USER_NAME: 
      Specify a username for the endpoint.
    •  
      PASSWORD: 
      Specify a password for the endpoint.
    • (Optional) 
      respkey
       = 
      $.run_id. 
      Adding this key allows you to retreive the Job/Ticket ID and store it in the alarm.
  7. In the 
    Payload Mapping
     section, you can specify your own payload to add your own custom fields to the payload request. For a sample payload, view Sample Payload. For a complete list of alarm and computer system variables, view Alarm and System Variables. 
     The supported payload type is application/json
  8. Select 
    New
     to configure the payload mapping to specify the content you want to post to the webhook or the endpoint URL. Specify the Mapping_key and Mapping_value, as in the following sample:
    •  
      tags 
      – For example, "#alarm", "#cauim", "#${message.prid}"
    •  
      external user name
       – For example, "CA UIM"
    •  
      content 
      – For example, "[${message.udata.severity}] ${cs.name}(${cs.ip}).${ci.description}.${ci.name}: ${message.udata.message}"
  9. In the 
    Webhook
     section, default values are displayed. You can customize the following mandatory fields:
    •  
      webhook name 
      – Specify the webhook name.
    •  
      queue name
       – Specify the name of the queue you have created in the hub which messagegtw subscribes to.
    •  
      attach to queue 
      – Specify if True or False. Default is True. If True, the queue collects messages for forwarding to a get queue. 
       
    •  
      send exclusive
       – If True, this option publishes the messages to the first configured endpoint URL. When set to False, the messages are sent to all the webhook endpoints at once. Default value is True.
    •  
      alert on failure
       – Generates an alert if messagegtw is unable to publish to the webhook configured. Default value is True.
    •  
      bulk size
       – Specifies the max queue size that is processed by messagegtw. Default value is 10. 
    •  
      (Optional) hub_address 
      – If messagegtw is deployed in the secondary hub, specify the primary hub address. For example, 
      hub_add = /domain/primary_hub/robot/hub
       
  10. Delete the sample webhook configuration before restarting the probe. Navigate to 
    Webhook,
     
    Options,
     and select 
    Delete
    .
  11. After you have made the configuration changes, restart the probe.
    The messagegtw probe now publishes messages from nas to the webhooks you have configured.
Sample Payload
<payload>
content = "[${message.udata.severity}] ${cs.name}(${cs.ip}).${ci.description}.${ci.name}: ${message.udata.message}"
external_user_name = "CA_UIM"
tags = ["#alarm", "#cauim", "#${message.prid}"]
</payload>
Alarm and System Variables
You can specify your own payload to add your own custom fields to the payload request. Specify your own custom payload, using the following alarm and computer system variables.
Variable
Type
Meaning
rowid
Integer
Indicates the row ID. Example: 1
event_type
Integer
Indicates the event type. Example: 16
nimid
String
Indicates the alarm message-id. For example, YP39028984-19824
nimts
Integer
Indicates the message timestamp, when it was originally sent. For example, 1534444449
arrival
Integer
Indicates the timestamp when the Nimsoft Alarm Server received the alarm. For example, 1534444450
severity
String
Indicates the name of the severity level. For example, critical
level
Integer
Indicates the severity level of the alarm. For example, 5
prevlevel
Integer
Indicates the previous severity level of the alarm. For example, 5
subsys
String
Indicates the message text.ndicates the alarm subsystem. For example, Controller
message
String
Indicates the message text. For example, Test alarm from controller on computer-8462
source
String
Indicates the IP address of the system that sent the alarm. For example, 10.131.144.22
hostname
String
Indicates the hostname of the system that sent the alarm. For example, computer-8462
sid
String
Indicates the subsystem ID in the Nimsoft Alarm Server. For example, 1.2.2.1
domain
String
Indicates the name of the domain the Robot is in. For example, computer-8462_domain
hub
String
Indicates the Hub the robot belongs to. For example, computer-8462_hub
nas
String
Indicates the name of the Hub, nas belongs to. For example, computer-8462_hub
robot
String
Indicates the name of the Robot that sent the alarm. For example, computer-8462
origin
String
Indicates the system name of the hub in which the robot is present. For example, computer-8462_hub
prid
String
Indicates the probe ID. For example, controller
supp_key
String
Indicates the suppression key (often contains the checkpoint). For example, test_alarm
suppcount
Integer
Indicates the number of times this alarm has been suppressed. For example, 43
supptime
Integer
Indicates the timestamp of the last suppression of this message.For example, 1536050909.
tz_offset
String
Indicates the sending system time zone offset in seconds compared to UTC. For example, -19800
visible
Boolean
Indicates whether the alarm has been made invisible to account users.
dev_id
Text
The ID of the IP addressable device that is associated with the entity for which the alarm was created.
met_id
Text
The ID of the metric, if any, for which the alarm was created.
profile
Text
Indicates the nas Auto-Operator profile name.
aots
Integer
Indicates the Auto-Operator execution timestamp.
webhook
Text
Indicate the name of the webhook.
ci.caption
Text
Indicates the caption of the configurable item.
ci.name
Text
Indicates the name of the configurable item.
ci.type
Text
Indicates the type of the configurable item.
ci.description
Text
Indicates the description of the configurable item.
metric.description
Text
Indicates the description of the metric.
metric.unit
Text
Indicates the unit of the metric.
device.id
Text
Indicates the unique id of the device.
device.ip
Integer
Indicates IP address of the device.
device.name
Text
Indicates the name of the device.
device.probe
Text
Indicates the name of the probe on the device.
cs.id
Text
Indicates the unique ID of the Computer system.
cs.key
Text
Indicates the key for the computer system.
cs.dedicated
Text
Indicates whether the Computer system is Virtual or Physical.
cs.state
Text
Indicates the state of the Computer system. Active = 1; Inactive = 0
cs.name
Text
Indicates the name of the Computer system.
cs.domain
Text
Indicates the domain in which the Computer system resides.
cs.origin
Text
Indicates the origin / tenant details of the computer system.
cs.ip
Text
Indicates the IP Address of the Computer system.
cs.os_type
Text
Indicates the type of OS of the Computer system. For example, UNIX / Windows
cs.os_name
Text
Indicates the name of the Operating system of the Computer System. For example, Linux, Cent / Ubuntu for UNIX, Windows
cs.os_version
Text
Indicates the version of the Operating system of the computer system.
cs.os_description
Text
Indicates the description of the Operating system of the computer system.
cs.maintenance
Text
Indicates if the computer system is in maintenance.
 For Oracles databases, parameters with ci, and cs, should be capitalized. For example, ci.name should be CI.NAME in Oracle databases.
Define Profile in nas Auto-Operator
On the, nas IM config, 
Auto-Operator
 tab, it is possible to configure the auto-operator with profiles containing selection criteria for various fields, such as severity level(s), subsystem Id, message string etc. When an alarm event passes the selection criteria as well as the action time, an action is triggered. 
The Auto-Operator aids the administrator in managing alarms by matching rules (alarm severity, alarm message text, subsystem ID) to assign an alarm to a person or group, and to send messages (email or text) when a specific rule is met. Create and define a profile in Auto-Operator for webhook. Specify the instance of messagegtw to which the queue is posted.
 
Follow these steps:
 
  1. On the robot, open IM nas configuration, and go to Auto-Operator.
  2. Right-click 
    New
     to create a profile.
    Webhook_AO.png 
  3. Specify the following required fields:
    •  
      Action type
       - Select 
      webhook
       (Specifies that the auto-operator sends a message to the configured webhooks).
    •  
      Path to Messagegtw Probe
       - Specify the path of the hub or robot where the messagegtw probe is deployed and configured. The nas auto-operator profile publishes to the instance of the messagegtw probe that you specify here.
    •  
      Webhook Name
       - Select the webhook from the drop-down. The webhook is populated based on the webhooks that are configured in the selected instance of the messagegtw probe.
    •  
      Subject
       - Specifies the message queue name. This field is auto populated based on the webhook you select.
    •  
      More Properties
       - Specify any additional property or metadata that you want to send to the messagegtw.
 
 
 
Use case for CA UIM-Automic Integration
 
Use Case: Self Remediation through the UIM-Automic integration: Disk clean-up & thereby preventing a DB from crashing.
An alarm is configured, in CA UIM to indicate free disk space on the server has dropped below pre-configured threshold. Because of low disk space, applications and databases may stop functioning properly and even the OS may crash which will lead to service interruption. In response to such alarms, a cleanup of the disk is to be performed proactively before it affects the business by Automic.
 
Prerequisites:
 
  • The host machine is monitored by UIM and has Automic deployed for WA.
  • Create a new job object type in Automic to clear the cache for specified disk directory on the target system. 
 
 
A job is used to define processing steps in a target system. It can be used independently, in a group, or within a workflow. 
 
 
 
The script is processed in a specific way in the object type "Job". Depending on the JCL (Job Control Language) and the script elements, an executable job is generated for the respective target system and transmitted via file transfer.The AE Script (if existing) and the JCL lines are processed and subsequently, the JCL is sent to the target system. AE Script is never sent to the target system.
 
 
When CA UIM raises an alarm for disk full warning, the message is passed on to Automic where a specific job is run to clear the cache for the disk directory. You can also define/ configure other parameters from CA UIM to be sent as part of the message payload that is sent to Automic. When a disk full alarm is generated on CA UIM, messagegtw sends a POST request mapping the UIM variables that generated the alarm, to field names in Automic. An Automic Job ID is returned as response. CA UIM attaches this JOB ID to the alarm, using the USM Edit URL Actions. Execute the Launch URL action, from USM to trigger the JOB ID in Automic. Automic executes the job to clear the cache for the specified disk on the target system.
Example: URL and Payload to send Message to Automic
http://hostname-a15090:8088/ae/api/v1/100/executions
The following json format is accepted by Automic:
{
"object_name"
:"JOBP.DISK_SPACE",
"inputs"
:{
"DISK#"
:"C",
"DNSNAME#"
:"domain.name.xx",
"IP#"
:"10.0.0.1"
}
You would need to map the fields names in the Automic job object to the CA UIM variables:
CA Automic
CA UIM
 
DISK
Specify the disk directory.
 
ci.name
Indicates the name of the configurable item.
 
DNSNAME
Specify the Domain Name Server Name.
 
cs.name
Indicates the name of the Computer system.
 
IP
Specify the IP address of the target system whose disk space you are monitoring.
 
cs.ip
Indicates the IP Address of the Computer system.
Once you have mapped the filed/ variables, use the following sample payload 
<payload>
object_name = "JOBP.DISK_SPACE"
inputs = {"DISK#" : "${ci.name}", "DNSNAME#" : "${cs.name}", "IP#" : "${cs.ip}"}
</payload>
Expected Response are, 
Custom 1
 = 
url_field
 and 
Custom 2
run_id_field.
 These are appended to the messagegtw configuration on a successful POST request. 
To get the status of the job in Automic, if the run_id returned, follow these steps: 
 USM Actions.png 
  1. In USM, select the monitored device, 
    Actions,
     
    Edit URL Actions
    .
  2. By default, Custom_1 and Custom_2 fields return the the url_field and run_id_field. Specify a 
    Name
     for the new URL action and click 
    Save.
     
  3. Click the 
    Launch URL Action
     button (for the selected device) to check the status of the job in Automic.   
Sample response of the status for Job ID using Launch URL Action > Name specified during Edit URL Actions. 
{
"name" : "JOBP.DISK_SPACE",
"type" : "JOBP",
"run_id" : 1934790,
"status" : 1900,
"status_text" : "ENDED_OK - ended normally",
"runtime" : 0,
"activation_time" : "2018-09-24T22:42:59Z",
"start_time" : "2018-09-24T22:43:00Z",
"end_time" : "2018-09-24T22:43:00Z",
"parent" : 0,
"user" : "AUTOMIC/AUTOMIC",
"estimated_runtime" : 1,
"alias" : "JOBP.DISK_SPACE"
}