Integrate Spike with BMC Control-M
Integrate Spike with BMC Control-M to receive real-time alerts via Phone calls, SMS, Slack, MS Teams, and more when batch jobs fail or run late.
Overview
BMC Control-M is a workflow orchestration platform for scheduling and monitoring batch jobs across servers and applications.
With Spike's Control-M integration, an alert raised by Control-M becomes a Spike incident, and closing the alert in Control-M resolves it. Control-M does not send webhooks itself. It runs an alerts listener script that you provide, and that script posts the alert to Spike.
How it works
idis the Control-M alert id. It stays the same across everyIandUdelivery about one alert, so Spike uses it to match them. It may be sent as a string or a number (0is an id), and Spike treats2193,"2193"and" 2193 "as the same id. An empty value, a template variable that Control-M did not expand ($id,$ID,${id},{{id}},%id%,%%ALERT_ID,<id>), or a word for no value (null,None,nil,undefined,NaN,n/a) is not an id.eventTypeisIfor a newly issued alert andUfor an update. Matching is case-insensitive. AnIdelivery opens an incident. AUdelivery never opens one: it joins the open incident with the sameid, and is dropped when none is open. Any other or missingeventTypeopens an incident.statusis0Not_Noticed (New),1Noticed (Reviewed) or2Handled (Closed).0opens onIand joins onU.1joins and never closes.2resolves the open incident with the sameid, and never opens one, whatever theeventType.statusmay be a string or a number;handledandclosedcount as2, andnoticedandreviewedas1, in any case. An unknownstatusnever resolves.Without a valid
id, Spike falls back to matching by title. Always sendid: an alert without one cannot be reliably resolved.Changes to
eventType,status,severity,user,updateTimeandnotesbetween deliveries do not create a new incident.The incident title is
{message}: {jobName} on {host}, for exampleEnded not OK: nightly-invoice-export on prod-batch-agent-02.messageis Control-M's own sentence with whitespace collapsed. A variable Control-M did not expand counts as missing.: {jobName}is dropped whenmessagealready names the job as a whole word, for exampleJob nightly-invoice-export failed on prod-batch-agent-02.on {host}usesserverwhenhostis empty. It is dropped whenmessagealready names it, or when neither is present.With an empty
messagethe title isControl-M alert: {jobName} on {host}, thenControl-M alert on {host}, thenControl-M alert with no details.The title is at most 200 characters. The message is cut at a word boundary with
...and the: {jobName} on {host}part is kept whole, unless that part alone is over 100 characters, in which case the title is cut plainly.I,U, Noticed and Handled deliveries of one alert give the same title.id, times,status,severityandnotesnever appear in it.
Set up instructions
Step 1: Create a Control-M integration in the Spike dashboard and copy the webhook URL.
Create integration and service on our dashboardStep 2: Configure the alerts listener in Control-M.
Enable external alerts for your Control-M environment and choose the alert types to send, as described in BMC's "Sending events to external monitoring tools" tutorial. Set
enableExternalAlertsto{"value": "true"}andexternalAlertTypesto{"value": "Alerts"}withctm config systemsettings::set, so that only job alerts are sent. Control-M system alerts use different status codes and have noid, so Spike does not support them: do not send them to this integration.Keep the default alert template. Control-M then passes each alert to the alerts listener script as arguments that use the field names in the table below (
eventType,id,status,message,jobName,hostand so on). Do not rename them.Save the listener script below on the machine that runs the alerts listener, and make it executable. Control-M starts it with
/bin/sh, so it is written in plain POSIX shell. ReplaceSPIKE_WEBHOOK_URLwith the URL from Step 1.BMC documents more than one argument format, depending on the Control-M version and the
useNewAlertFieldsFormatsetting. The script accepts all three: a field name and its value as two arguments ("id: "then"2193 "), one argument with no spaces ("id:2193"), and one argument with spaces around the colon ("id : 2193").An argument starts a new field only when the text before its first colon is a field name from the table below, or one of the template fields the script drops (
closedByControlM,ticketNumber). Any other text, including a value that contains or ends in a colon such asCause: disk full, is part of the current field's value.When no argument names a known field, the script posts nothing and exits with status
2. It also exits non-zero when the post to Spike fails.
Register the script with the alerts listener and start it:
ctm run alerts:listener:environment::set <environment>, thenctm run alerts:listener:script::set <path to the script>, thenctm run alerts:listener::start.Confirm the argument format your listener uses. Set the listener's
listenerLogLeveltodebug, raise a test alert and check the Alerts listener log in$HOME/.ctm/python-logs/: it records the script's exit status, and2means the script found no field it knows. To see the exact arguments, setARGS_LOGat the top of the script to a file path; the script then appends each argument it receives, one per line in brackets. ClearARGS_LOGagain once alerts arrive in Spike, because the file holds alert text.
The script needs jq and curl. A field with no value, such as user:, is sent as an empty string. Spaces around each name and value are trimmed.
The script produces this body for a newly issued alert:
When an operator handles (closes) the alert, the script sends the same alert with eventType U and status 2:
Fields
Send these fields and no others. All values are strings. id, eventType, status and message drive how alerts open and resolve; jobName, host and server build the title; severity sets the severity badge. The rest are kept on the incident.
eventType
call_type
Required. I = newly issued alert, U = update of an existing alert.
id
alert_id
Required. Unique key of the alert, the same across its I and U deliveries.
status
status
Required. 0 Not_Noticed, 1 Noticed, 2 Handled (Closed).
message
message
Required. The full text of the alert. It starts the incident title.
jobName
job_name
Job that raised the alert. Used in the title.
host
host_id
Agent host where the job ran. Used in the title.
server
data_center
Control-M/Server. Used in the title when host is empty.
severity
severity
V very urgent, U urgent, R regular. Sets the incident's severity badge: V → sev1, U → sev2, R → sev3. Never part of the title.
type
alert_type
R regular, B SLA (BIM). Kept only.
application
application
The job's application. Kept only.
subApplication
sub_application
The job's sub-application. Kept only.
fileName
memname
Job file name, often empty. Kept only.
runId
order_id
Order id of the job run. Kept only.
runNo
run_counter
Run counter of the job execution. Kept only.
runAs
run_as
OS user the job runs as. Kept only.
time
send_time
When the alert was issued, yyyymmddhhmmss. Kept only.
updateTime
last_time
When the alert was last modified. Changes on every U. Kept only.
user
last_user
The user who last changed the alert. Kept only.
notes
notes
Note text attached to the alert. Kept only.
On-premises Control-M/EM uses the older names in the "Control-M name" column (call_type, alert_id, data_center and so on). If your listener receives those, map them to the field names in the first column before posting.
Test the integration
Make a Control-M job end not OK so that it raises an alert, or run the listener script by hand the way Control-M does, for example
/bin/sh listener.sh "eventType: " "I " "id: " "2193 " "status: " "0 " "message: " "Ended not OK " "jobName: " "nightly-invoice-export " "host: " "prod-batch-agent-02 ". It posts the first body above, limited to the fields you pass.Verify a new incident titled
Ended not OK: nightly-invoice-export on prod-batch-agent-02is created in Spike.In Control-M, handle (close) the alert, or run the script again with
"eventType: " "U " "status: " "2 "and the sameid.Confirm Spike auto-resolves the incident for that
id.
Last updated

