External Alerts Fields and Templates

The following topics describe the fields in external alerts that are sent from Helix Control-M to external tools, such as an event management system, and how you can control these fields through the use of templates that you provide when you run the run alerts:stream:template::set command:

External Alerts Default Fields: Describes the default combination of fields in external alerts.
Setting Fields Using a Template: Describes how to use a template to customize fields in external alerts.
Changing Field Names After Migrating from Control-M: Describes how to use a template to set pre-migration names for fields in external alerts.
Restoring All Default Fields: Describes how to use a template to revert to the default combination of fields in external alerts.

External Alerts Default Fields

Helix Control-M provides default fields for the external alerts. The default combination of fields depends on the alert type:

Job Processing Alerts Default Fields
System Alerts Default Fields

You can override the default combination of fields to use a subset of fields with modified names and in a different order, as described in Setting Fields Using a Template.

Job Processing Alerts Default Fields

The following table lists the default alert fields provided by Helix Control-M for alerts from Control-M job processing. It also includes the names of the corresponding fields in Control-M, for a migration from Control-M to Helix Control-M.

Helix Control-M Field Name	Control-M Field Name	Description
eventType	call_type	Determines the type of event that triggered the alert: I: newly issued alert U: update of an existing alert
id	alert_id	Indicates a numeric value that uniquely identifies the alert (also known as the key or index).
server	data_center	Indicates the name of the Control-M/Server associated with the job. Example: IN01
fileName	memname	Indicates the filename of the job (previously known as the member name).
runId	order_id	Indicates a numeric value that uniquely identifies the job run.
severity	severity	Determines the severity of the alert: V: Very urgent U: Urgent R: Regular
status	status	Determines the status of alert handling: 0: Not_Noticed (New) 1: Noticed (Reviewed) 2: Handled (Closed)
time	send_time	Indicates the time and date that the alert was issued. Format: yyyymmddhhmmss
user	last_user	Indicates the name of the user who last modified the status or text of the alert.
updateTime	last_time	Indicates the time and date that the alert was last modified by the user. Format: yyyymmddhhmmss
message	message	Indicates the full text of the alert.
runAs	run_as	Indicates the Run As user set as owner of the job.
subApplication	sub_application	Indicates the Sub Application of the job (previously known as group).
application	application	Indicates the Application of the job.
jobName	job_name	Indicates the name of the job.
host	host_id	Indicates the node or host where the job is run.
type	alert_type	Determines the Alert type: R: Regular B: SLA Default: R
closedByControlM	closed_from_em	(Deprecated in Helix Control-M)* Determines whether a ticket was closed from Control-M/EM. Values: Y (yes) or N (no)
ticketNumber	ticket_number	(Deprecated in Helix Control-M*) Indicates a ticket number associated with the alert.
runNo	run_counter	Indicates a numeric value that uniquely identifies the job execution instance. This counter is relevant for jobs that run more than once on a scheduling day.
notes	notes	Indicates the note text associated with the alert.

* In the case of a migration from Control-M to Helix Control-M, backward compatibility for this field enables you to continue using the same scripts for external alert handling.

System Alerts Default Fields

The following table lists the default alert fields provided by Helix Control-M for system alerts (also known as exception alerts or xAlerts), which are triggered by system failures in Control-M components or the Control-M communication network.

This type of alert is especially useful if you have self-hosted Control-M/Servers connected to Helix Control-M.

Field Name	Description
eventType	Indicates the type of event that triggered the system alert. The value for system alerts is always I (Insert), that is, a newly issued alert.
serial	Indicates a sequential numeric value that uniquely identifies the system alert (also known as the key or index) from the specific Control-M component.
component_type	Indicates a number that identifies the type of component in the Control-M environment.
component_machine	Indicates the hostname of the machine where the Control-M component resides.
component_name	Indicates the name of the Control-M component with the problem.
message_id	Indicates a string that uniquely identifies the message associated with the system alert.
xseverity	Determines the severity of the system alert: V: Very urgent U: Urgent R: Regular
xtime	Indicates the time and date that the system alert was issued. Format: yyyymmddhhmmss
xtime_of_last	Indicates the time and date that the system alert was last modified by the user. Format: yyyymmddhhmmss
counter	Indicates the number of times that the same system alert was received. The value is always 1 (a newly issued alert).
status	Determines the status of system alert handling: 0: Undefined 1: Not Handled 2: Handled
note	Indicates the note text associated with the system alert.
message	Indicates the full text of the system alert.
alert_key1	Indicates a first reserved field for future developments.
alert_key2	Indicates a second reserved field for future developments.
alert_key3	Indicates a third reserved field for future developments.
alert_key4	Indicates a fourth reserved field for future developments.
alert_key5	Indicates a fifth reserved field for future developments.

Setting Fields Using a Template

This procedure describes how to use a template to customize fields in external alerts and override the default combination of fields provided by Helix Control-M. In your template you control which fields to include in an alert (a subset of the default fields), the names of the fields, and the order of their appearance.

Begin

Create a template in JSON format with your combination of fields for external alerts.

The content of the template differs according to the type of alert, as described in the following samples:

Job Processing Alerts Template: The following sample template sets a group of five fields of alert details. Of these five fields, three fields are renamed and two fields remain with their original names.

Copy

{
    "alertFields":
    [
        {"id":"alertId"},
        {"application":"businessUnit"},
        {"message":"message"},
        {"time":"date_and_time"},
        {"jobName":"jobName"}
    ]
}

System Alerts Template: The following sample template sets a group of five fields of system alert (xAlert) details. Of these five fields, four fields are renamed and one field remains with its original name.

Copy

{
    "alertType":"systemAlerts",
    "fields":
    [
        {"component_type":"component"},
        {"xseverity":"severity"},
        {"xtime":"time"},
        {"message_id":"messageCode},       
        {"message":"message"}   
    ]
}

Run the run alerts:stream:template::set command to submit your template.

The following alerts include the fields defined in the submitted sample templates, in the same order of appearance:

Job Processing Alert:

Copy

{
    "fields":
    [
        {"alertId":"650"},
        {"businessUnit":"ACCT"},
        {"message":"SHOUT TO Alertscript FAILED Shout to Destination Alertscript failed."},
        {"date_and_time":"20220120070014"},
        {"jobName":"J1"}
    ]
}

System Alert:

Copy

{
    "alertFields":
    [
        {"component": "CMS dba-server"},
        {"severity": "Urgent"},
        {"time": 20231101130000},
        {"messageCode": "CTM_5936"},
        {"message":"System failure"}
    ]
}

Changing Field Names After Migrating from Control-M

This procedure describes how to use a template to change the names of all fields in external alerts to their pre-migration names in Control-M. Use this template if you have migrated from Control-M to Helix Control-M and want to continue using your existing scripts to handle external alerts.

Begin

Create a template in JSON format to rename all fields in job processing alerts to their previous names in Control-M:

Copy

{
  "fields":
  [
    {"eventType":"call_type"},
    {"id":"alert_id"},
    {"server":"data_center"},
    {"fileName":"memname"},
    {"runId":"order_id"},
    {"severity":"severity"},
    {"status":"status"},
    {"time":"send_time"},
    {"user":"last_user"},
    {"updateTime":"last_time"},
    {"message":"message"},
    {"runAs":"run_as"},
    {"subApplication":"sub_application"},
    {"application":"application"},
    {"jobName":"job_name"},
    {"host":"host_id"},
    {"type":"alert_type"},
    {"closedByControlM":"closed_from_em"},
    {"ticketNumber":"ticket_number"},
    {"runNo":"run_counter"},
    {"notes":"notes"}
  ]
}

Run the run alerts:stream:template::set command to submit your template.

Restoring All Default Fields

This procedure describes how to use a template to revert to the default combination of fields in external alerts after you have customized the fields (as described in Setting Fields Using a Template).

Begin

Create a template in JSON format to reset the default fields.

The content of the template differs according to the type of alert:

Job Processing Alerts Template:

Copy

{    
    "fields": [
        {"eventType": "eventType"},
        {"id": "id"},
        {"server": "server"},
        {"fileName": "fileName"},
        {"runId": "runId"},
        {"severity": "severity"},
        {"status": "status"},
        {"time": "time"},
        {"user": "user"},
        {"updateTime": "updateTime"},
        {"message": "message"},
        {"runAs": "runAs"},
        {"subApplication": "subApplication"},
        {"application": "application"},
        {"jobName": "jobName"},
        {"host": "host"},
        {"type": "type"},
        {"closedByControlM": "closedByControlM"},
        {"ticketNumber": "ticketNumber"},
        {"runNo": "runNo"},
        {"notes": "notes"}    
    ] 
}

System Alerts Template:

Copy

{
    "alertType": "systemAlerts",
    "fields": [
        {"eventType": "eventType"},
        {"serial": "serial"},
        {"component_type": "component_type"},
        {"component_machine": "component_machine"},
        {"component_name": "component_name"},
        {"message_id": "message_id"},
        {"xseverity": "xseverity"},
        {"xtime": "xtime"},
        {"xtime_of_last": "xtime_of_last"},
        {"counter": "counter"},
        {"status": "status"},
        {"note": "note"},
        {"message": "message"},
        {"alert_key1": "alert_key1"},
        {"alert_key2": "alert_key2"},
        {"alert_key3": "alert_key3"},
        {"alert_key4": "alert_key4"},
        {"alert_key5": "alert_key5"}
    ]    
}

Run the run alerts:stream:template::set command to submit your template.

External alerts fields are restored to the default combination, as described in External Alerts Default Fields.