AlertMagic Expression Functions (am_*)

AlertMagic lets you write NCalc expressions in your configuration - in Alert Studio, in Integration / Alert Management System (AMS) and Issue Management System (IMS) actions, and in problem spec calculations and comments. Alongside the general-purpose NCalc functions (see NCalc 101), AlertMagic adds a small family of functions - all prefixed am_ - that read from and write to your connected remote systems.

This page documents the AlertMagic-specific remote-system functions, and am_triggerBot for starting ReportMagic schedules. Every remote-system function takes a systemType as its first argument, which selects which connected system to talk to:

systemType	Meaning
'ams'	The Alert Management System connected to the integration (e.g. LogicMonitor, Meraki).
'ims'	The Issue Management System connected to the integration (e.g. Jira, ServiceNow, AutoTask, SolarWinds Service Desk).

Note: any other systemType value raises an error. The table and criteria arguments are system-dependent: each connected system decides which tables/objects it supports and how it interprets the criteria string.

Function index

Function	Purpose	Arguments
am_lookup	Look up a single item in a remote system and return a field from it (or the whole item).	3-6
am_queryCount	Count the items in a remote system that match a query.	3
am_setProperties	Set one or more properties on a matched remote-system object.	5+
am_merakiEvidence	Ask Merlin for live Meraki evidence about an alert, as text for an assessment.	1-2

AlertMagic also provides general-purpose functions, including am_calculate, am_http, am_sha256, am_isGuid, am_log, am_extractSubstring, am_delimitJql, am_sqlSanitizedString and am_nullableDateTimeOffset. All am_ functions work only in AlertMagic expressions. They are not part of NCalc 101 and cannot be evaluated there.

Note: not every connected system supports every function. Where a system does not support a function, or a table value, the expression raises an error that says so.

am_lookup

Looks up a single item in a remote system and returns either a chosen field or the whole item. This is how a rule answers questions like “is there already an open incident for this problem?”.

am_lookup(systemType, table, criteria, [property], [subField], [failureValue])

#	Argument	Required	Description
1	systemType	Yes	'ims' or 'ams' (see above).
2	table	Yes	The system's table/object name to search. Which values are valid depends on the system - e.g. SolarWinds Service Desk supports activeIncidents.
3	criteria	Yes	A system-dependent query string that selects the item - e.g. 'title[]=' + {{P_Sig}} for SolarWinds Service Desk.
4	property	No	The field to return from the matched item. If omitted or null, the whole item is returned, where the connected system allows it. Some lookups require a property: a LogicMonitor 'alert' lookup, for example.
5	subField	No	A sub-field of property to drill into. If omitted or null, the property itself is returned. Not every system supports sub-fields.
6	failureValue	No	Controls what happens when the lookup does not match exactly one item - see below.

Success and failure behaviour

A lookup “succeeds” only when it matches exactly one item. For zero matches or more than one match:

• If you supply failureValue, that value is returned.
• If you omit failureValue, the expression throws an error.

Tip: pass a failureValue (for example -1 or '') when “no match” is a normal, expected outcome you want to branch on. Omit it when a missing/ambiguous match genuinely indicates a misconfiguration you want surfaced loudly.

Example - is there an active incident for this problem?

am_lookup(
    'ims',                   // Look up on the Issue Management System
    'activeIncidents',       // SolarWinds Service Desk: only active incidents
    'title[]=' + {{P_Sig}},  // Match incidents whose title is the problem signature
    'id',                    // Return the incident's id...
    null,                    // ...with no sub-field
    -1)                      // ...or -1 if there isn't exactly one match

This returns the id of the single active incident whose title matches the problem signature, or -1 if there is no such incident (or more than one). A common pattern is to test the result to decide whether to create a new incident or update the existing one.

am_queryCount

Returns the number of items in a remote system that match a query - useful for threshold logic without pulling back the items themselves.

Availability: am_queryCount is currently supported only by the LogicMonitor Alert Management System, for the 'appliesTo' object type. Other connected systems raise an error.

am_queryCount(systemType, objectType, queryString)

#	Argument	Description
1	systemType	'ims' or 'ams'.
2	objectType	The object type to count. LogicMonitor supports 'appliesTo'.
3	queryString	For 'appliesTo', a LogicMonitor AppliesTo expression, e.g. displayName == "PDL-DEV-01". The result is the number of resources it matches.

am_setProperties

Sets one or more properties on the remote-system object(s) matched by the criteria - for example acknowledging an alert or adding a comment to a ticket.

am_setProperties(systemType, table, criteria, propertyName1, propertyValue1, [propertyName2, propertyValue2, ...])

#	Argument	Description
1	systemType	'ims' or 'ams'.
2	table	The table/object to update.
3	criteria	A system-dependent query selecting the object to update.
4+	propertyName / propertyValue pairs	One or more name/value pairs to set. At least one pair is required.

Example - acknowledge an alert with a comment:

am_setProperties('ams', 'alert', alert_internalId, 'ack', 'Acknowledged by AlertMagic')

am_triggerBot

Starts a run of one of your ReportMagic report schedules and returns the new batch job ID. Use it to have an alert kick off a ReportMagic “bot”: a schedule that investigates or acts on the alert, using the variables you pass it.

am_triggerBot(reportScheduleId, variables)

#	Argument	Description
1	reportScheduleId	The ID of the report schedule to run. It must be a positive whole number, and the schedule must belong to the same tenant as the integration.
2	variables	The batch variables to pass to the run: a dictionary(...), a JSON object string, or null for none. Each value must be a string, number, boolean or null.

AlertMagic connects to ReportMagic with its own credentials, so you never put an API key or a URL in your configuration. The run is recorded as triggered by AlertMagic and names the integration.

The call raises an error if the schedule does not exist, or belongs to another tenant, or if the integration has not been enabled for bot triggers. For security, these cases all give the same error. In the Alert Studio Testing tab the function returns 0 and starts nothing.

Example - start the investigation bot for this alert:

am_triggerBot(
    1234,
    dictionary(
        'alertId', alert_id,
        'deviceId', alert_resource_id,
        'actionCode', 'WINCPU_BUSY_PERCENT'))

am_merakiEvidence

Asks Merlin to gather live evidence from your Meraki network about an alert, and returns what it found as text. Use it ahead of am_aiThoughts so that the assessment of an alert can draw on what is happening in Meraki now, rather than on the alert text alone. A rule opts in by calling it: alerts from rules that do not call it are not affected.

am_merakiEvidence(question, [networkId])

#	Argument	Required	Description
1	question	Yes	The question for Merlin, in plain English, between 1 and 500 characters. Name the device or site and what you want to know.
2	networkId	No	The Meraki network the alert is about. Letters, digits, underscores and hyphens only.

Merlin only reads: it can never change a network. It works as your Tenant, using your Tenant's Meraki Connection, and AlertMagic connects with its own credentials, so you never put an API key or a URL in your configuration. The function takes at most 4 rounds of queries and about a minute. Each request costs model time, so your organisation may make a limited number of them a day (200 unless Panoramic Data has set it otherwise).

The function never stops an alert being assessed. If Merlin cannot finish, a limit or the daily allowance is reached, or Meraki or the service is unavailable, the function returns an empty string and the alert is assessed exactly as it would have been without it. The evidence is cut to 4000 characters.

Example - assess a Meraki alert with live evidence:

am_aiThoughts(
    'Assess this alert and say what is likely to have caused it. Live evidence: '
    + am_merakiEvidence(
        'Why did the access point at the Hull depot go offline?',
        'N_123456789'))

Note: the question must be text of 500 characters or fewer, and the function takes no destination or credential. Anything else raises an error.

See also

• NCalc 101 - the general-purpose expression functions and operators. The am_ functions on this page are not available there.
• Configuring your Issue Management System (IMS) and Configuring your Alert Management System (AMS) - which table and criteria values each connected system supports.