Produces a list of list of instances of a given DataSource on a given Device.
Compatibility
The macro can be used in all input document types and in Report Studio.
Usage
When specifying deviceGroup(s) and dataSource(s) / dataSourceName(s), only the property type 'Spec' is supported. Spec is defined as the Device DataSource Instance's Device ID, it's DataSource ID, and it's ID.
Updates
One year ago · July 2025
Fixed issue where the macro would not work in Normal Mode. Normal Mode properties 'ResourceDataSourceId', 'ResourceId', and 'ResourceDisplayName' are now used instead of 'DeviceDataSourceId', 'DeviceId', and 'DeviceDisplayName'. You may still request those properties, but in the output JObject, they will use the new names.
Parameters(122)
Behaviour(3)11 additional
Parameter
Type
Presence
Purpose
Options
Default
maxAttempts
Int32
Optional
The maximum number of attempts when requesting data via the LogicMonitor API.
From 1 to 2147483647
N/A
recurseDeviceGroups
Boolean
Optional
Whether to recurse Device Groups when the deviceGroups parameter is specified.
true
false
true
waitDuringUpgrades
Boolean
Optional
Whether to wait during LogicMonitor upgrades (i.e. execution essentially pauses).
true
false
N/A
Additional (11)
Parameter
Type
Presence
Purpose
Options
Default
calculate
String
Optional
Post processing formula. Use {value} to substitute the macro's output into the formula as text, e.g. {value}/1024, or the bare word value to use the output itself, e.g. jPath(value, 'id') to read a property from an object. If the result is fractional it is shown to two decimal places unless you also set format, e.g. format=G to show it in full; a value kept by storeAs always retains its full precision.
N/A
N/A
desiredExecutionResult
List<ExecutionResult>
Optional
If specified, asserts the expected execution result of the macro. Accepts a single value or a semicolon-separated list of acceptable values (e.g. 'Success;Warning'). The macro executes normally; if the actual result matches any of the desired values, the result is converted to Success. If the actual result does not match, the result is converted to MacroError with a descriptive message. This is primarily used for testing and diagnostic purposes. Valid values are: 'Unknown', 'Success', 'MacroError', 'WorkerStopped', 'Running', 'Warning', 'NeverRun', 'Cancelled', 'Pending', 'Paused', 'SystemError', 'Deferred' and 'Stopped'.
Cancelled
Deferred
MacroError
NeverRun
Paused
Pending
Running
Stopped
Success
SystemError
Warning
WorkerStopped
N/A
errorOnOverflow
Boolean
Optional
Should NCalc expression evaluation throw error on Overflow
true
false
true
expectedType
String
Optional
If specified, asserts the expected output type of the macro result. The macro executes normally; if the actual type does not match, a macro error is generated. Requires 'storeAs', 'storeAsHidden', or 'storeFormattedValueAs' to be set for typed validation. Valid types include CLR names (e.g. Int32, Int64, Single, Double, Boolean, String, JArray, JObject) and C# keyword aliases (e.g. int, long, float, double, bool, string, uint, ulong, short, ushort, byte, sbyte, decimal, char, object). The special value 'Number' matches any numeric type.
N/A
N/A
expectedValue
String
Optional
If specified, asserts the expected output value of the macro result. The macro executes normally; if the actual value does not match, a macro error is generated. When 'storeAs' or 'storeAsHidden' is set, the stored variable value is compared. Otherwise, the document output text is compared.
N/A
N/A
hidden
Boolean
Optional
Whether to hide the macro output.
true
false
false
if
String
Optional
The condition that must be true in order for the macro to be executed/evaluated. Must either evaluate to true or false, for example: "3+5=8" or "contains('abcd', 'z')".
N/A
true
mode
MacroMode
Optional
The mode in which variables are stored. In legacy mode (default for Schedules), the variable created is a string and formatted. In normal mode (default for Report Studio), the output variable is stored as a strongly-typed object, e.g. an Int32 or a JArray etc., rather than a formatted string.
Legacy
Normal
Legacy
obfuscation
ObfuscationType
Optional
Obfuscation type. Use obfuscation to write reports where sensitive data is hidden. When used, ReportMagic guarantees that the same input string will map to the same output string for the whole of the report (but the next time the report runs, it will most likely map to a different value). If you use obfuscation, the property in your macro will not show up and instead, you will see a fake item of the obfuscation type chosen.
None
UkTown
DeviceName
Company
IpAddress
PrivateIpAddress
None
redact
Boolean
Optional
Whether substituted variables are hidden from macro results (and the word 'REDACTED' will appear in progress screens and elsewhere in the web UI).
true
false
false
warning
String
Optional
If specified, adds a warning message for this macro. This is processed as an NCalc, and the warning message will ALWAYS be present and will be the value of the evaluated NCalc expression.
N/A
N/A
Colours(21)
Parameter
Type
Presence
Purpose
Options
Default
colorTableCell
Boolean
Optional
Whether to color table cells if thresholds are breached, rather than color the text.
true
false
true
criticalFontBackgroundColor
Color
Optional
The critical font background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
criticalFontColor
Color
Optional
The critical font color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
criticalTableCellBackgroundColor
Color
Optional
The critical table cell background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
errorFontBackgroundColor
Color
Optional
The error font background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
errorFontColor
Color
Optional
The error font color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
errorTableCellBackgroundColor
Color
Optional
The error table cell background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
fatalFontBackgroundColor
Color
Optional
The fatal font background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
fatalFontColor
Color
Optional
The fatal font color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
fatalTableCellBackgroundColor
Color
Optional
The fatal table cell background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
fontBackgroundColor
Color
Optional
The font background color to use.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
fontColor
Color
Optional
The font color to use.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
infoFontBackgroundColor
Color
Optional
The info font background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
infoFontColor
Color
Optional
The info font color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
infoTableCellBackgroundColor
Color
Optional
The info table cell background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
normalFontBackgroundColor
Color
Optional
The normal font background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
normalFontColor
Color
Optional
The normal font color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
normalTableCellBackgroundColor
Color
Optional
The normal table cell background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
warningFontBackgroundColor
Color
Optional
The warning font background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
warningFontColor
Color
Optional
The warning font color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
warningTableCellBackgroundColor
Color
Optional
The warning table cell background color to use. If omitted, no change is made.
A named color or an HTML-encoded color .Note that 'transparent' is a valid color that you can use in any macro parameter that expects a color.
N/A
Formatting(15)
Parameter
Type
Presence
Purpose
Options
Default
criticalFontBold
Boolean
Optional
Change the critical font weight (true=strong, false=normal). If omitted, no change is made.
true
false
N/A
criticalFontSize
Double
Optional
Change the critical font size in points. If omitted, no change is made.
From 2 to 200
N/A
errorFontBold
Boolean
Optional
Change the error font weight (true=strong, false=normal). If omitted, no change is made.
true
false
N/A
errorFontSize
Double
Optional
Change the error font size in points. If omitted, no change is made.
From 2 to 200
N/A
fatalFontBold
Boolean
Optional
Change the fatal font weight (true=strong, false=normal). If omitted, no change is made.
true
false
N/A
fatalFontSize
Double
Optional
Change the fatal font size in points. If omitted, no change is made.
From 2 to 200
N/A
fontBold
Boolean
Optional
Change the font weight (true=strong, false=normal). If omitted, no change is made.
true
false
N/A
fontSize
Double
Optional
Change the font size in points. If omitted, no change is made.
From 2 to 200
N/A
format
String
Optional
The formatting to use for numbers. You can also specify 'format=string' to force numbers to be treated as strings. For dates, C# date formats are supported, plus two special values (in any casing): 'format=dayOfWeek' for the day of the week as a number (Sunday = 0; use 'format=dddd' for the day name) and 'format=epoch' for the number of seconds since 1970-01-01 UTC.
N/A
N/A
infoFontBold
Boolean
Optional
Change the info font weight (true=strong, false=normal). If omitted, no change is made.
true
false
N/A
infoFontSize
Double
Optional
Change the info font size in points. If omitted, no change is made.
From 2 to 200
N/A
normalFontBold
Boolean
Optional
Change the normal font weight (true=strong, false=normal). If omitted, no change is made.
true
false
N/A
normalFontSize
Double
Optional
Change the normal font size in points. If omitted, no change is made.
From 2 to 200
N/A
warningFontBold
Boolean
Optional
Change the warning font weight (true=strong, false=normal). If omitted, no change is made.
true
false
N/A
warningFontSize
Double
Optional
Change the warning font size in points. If omitted, no change is made.
From 2 to 200
N/A
Conditional Formatting(35)
Parameter
Type
Presence
Purpose
Options
Default
criticalEq
String
Optional
The macro is considered 'critical' if the output is equal to this value.
N/A
N/A
criticalGe
String
Optional
The macro is considered 'critical' if the output is greater than or equal to this value.
N/A
N/A
criticalGt
String
Optional
The macro is considered 'critical' if the output is greater than this value.
N/A
N/A
criticalIf
String
Optional
The macro is considered 'critical' if the expression evaluates to true. Use 'value' as the macro output in the expression.
N/A
N/A
criticalLe
String
Optional
The macro is considered 'critical' if the output is less than or equal to this value.
N/A
N/A
criticalLt
String
Optional
The macro is considered 'critical' if the output is less than this value.
N/A
N/A
criticalNe
String
Optional
The macro is considered 'critical' if the output is not equal to this value.
N/A
N/A
errorEq
String
Optional
The macro is considered 'error' if the output is equal to this value.
N/A
N/A
errorGe
String
Optional
The macro is considered 'error' if the output is greater than or equal to this value.
N/A
N/A
errorGt
String
Optional
The macro is considered 'error' if the output is greater than this value.
N/A
N/A
errorIf
String
Optional
The macro is considered 'error' if the expression evaluates to true. Use 'value' as the macro output in the expression.
N/A
N/A
errorLe
String
Optional
The macro is considered 'error' if the output is less than or equal to this value.
N/A
N/A
errorLt
String
Optional
The macro is considered 'error' if the output is less than this value.
N/A
N/A
errorNe
String
Optional
The macro is considered 'error' if the output is not equal to this value.
N/A
N/A
fatalEq
String
Optional
The macro is considered 'fatal' if the output is equal to this value.
N/A
N/A
fatalGe
String
Optional
The macro is considered 'fatal' if the output is greater than or equal to this value.
N/A
N/A
fatalGt
String
Optional
The macro is considered 'fatal' if the output is greater than this value.
N/A
N/A
fatalIf
String
Optional
The macro is considered 'fatal' if the expression evaluates to true. Use 'value' as the macro output in the expression.
N/A
N/A
fatalLe
String
Optional
The macro is considered 'fatal' if the output is less than or equal to this value.
N/A
N/A
fatalLt
String
Optional
The macro is considered 'fatal' if the output is less than this value.
N/A
N/A
fatalNe
String
Optional
The macro is considered 'fatal' if the output is not equal to this value.
N/A
N/A
infoEq
String
Optional
The macro is considered 'info' if the output is equal to this value.
N/A
N/A
infoGe
String
Optional
The macro is considered 'info' if the output is greater than or equal to this value.
N/A
N/A
infoGt
String
Optional
The macro is considered 'info' if the output is greater than this value.
N/A
N/A
infoIf
String
Optional
The macro is considered 'info' if the expression evaluates to true. Use 'value' as the macro output in the expression.
N/A
N/A
infoLe
String
Optional
The macro is considered 'info' if the output is less than or equal to this value.
N/A
N/A
infoLt
String
Optional
The macro is considered 'info' if the output is less than this value.
N/A
N/A
infoNe
String
Optional
The macro is considered 'info' if the output is not equal to this value.
N/A
N/A
warningEq
String
Optional
The macro is considered 'warning' if the output is equal to this value.
N/A
N/A
warningGe
String
Optional
The macro is considered 'warning' if the output is greater than or equal to this value.
N/A
N/A
warningGt
String
Optional
The macro is considered 'warning' if the output is greater than this value.
N/A
N/A
warningIf
String
Optional
The macro is considered 'warning' if the expression evaluates to true. Use 'value' as the macro output in the expression.
N/A
N/A
warningLe
String
Optional
The macro is considered 'warning' if the output is less than or equal to this value.
N/A
N/A
warningLt
String
Optional
The macro is considered 'warning' if the output is less than this value.
N/A
N/A
warningNe
String
Optional
The macro is considered 'warning' if the output is not equal to this value.
N/A
N/A
Filtering & Sorting(1)
Parameter
Type
Presence
Purpose
Options
Default
selectDistinct
Boolean
Optional
Specify true to exclude repeated entries
true
false
true
Output(1)7 additional
Parameter
Type
Presence
Purpose
Options
Default
listDelimiter
Char
Optional
In Legacy Mode, the delimiter to use between multiple items in the output.
N/A
;
Additional (7)
Parameter
Type
Presence
Purpose
Options
Default
failureText
String
Optional
The text to display should the macro fail to execute. Note that a poorly-specified macro (e.g. omitting mandatory parameters) will still result in an error message.
N/A
N/A
failureVariable
String
Optional
The name of a variable to create should the macro fail to execute. The variable will be a text variable, and will contain either the failure text (only if the failureText parameter is set), otherwise it will contain the exception / failure message.
N/A
N/A
outputListsAsJarray
Normal mode
Boolean
Optional
Any macros that output lists can optionally (in Normal mode) output a jArray instead.
true
false
true
storeAs
String
Optional
The variable to store the result as. If the variable name ends 'Json' (any casing) its value is wrapped in json tags. That marks the value as JSON so it can be passed straight into a parameter that expects json content, and the RMScript editor also displays it with JSON highlighting. When several variables are stored at once each one is judged by its own name.
N/A
N/A
storeAsHidden
String
Optional
The variable to store the result as, while hiding the output. Equivalent to 'storeAs=ThisValue, hidden=true'.
N/A
N/A
storeAsVariableDelimiter
Char
Optional
The delimiter used by storeAs to split a TEXT value, when there are multiple stored variables. For example, in this macro, we indicate that the value to be stored should be split by the asterisk when being stored: [String:value=a*b*c*d, storeAs=var1;var2;var3;var4, storeAsVariableDelimiter=*]. If splitting on this delimiter does not produce one value per variable, the '^' character is tried instead; that applies whatever this parameter is set to, and is what allows a single variable to hold a value containing a ';'. Note this delimiter is only used for a TEXT value. A list or a JSON array is instead shared out one element per variable, and a JSON object by its property values in order, so storing jObject('a',1,'b',2) as two variables gives 1 and 2. Any other type cannot be split across several variables at all.
N/A
;
storeFormattedValueAs
String
Optional
The name of the STRING variable to store the result as and output (both will use the same format) into the report. Note that if you also use 'storeAsHidden' in the same macro, you should not expect the output to be hidden, as this parameter overrides that. As with 'storeAs', a name ending 'Json' has its value wrapped in json tags.
N/A
N/A
General(14)2 additional
Parameter
Type
Presence
Purpose
Options
Default
dataSource
List<String>
Conditional
The DataSource name or names. Either this or dataSourceId must be specified.
N/A
N/A
dataSourceIds
List<Int32>
Conditional
The DataSource Id(s). Either this or dataSourceNames must be specified.
N/A
N/A
deviceGroups
List<String>
Conditional
The Device Group (or semicolon-separated list of Device Groups). Either this parameter, deviceIds or the devices parameter must be specified. Use "/" or no value in the deviceGroups parameter to reference the root folder.
N/A
N/A
deviceIds
List<Int32>
Conditional
The Device (or semicolon-separated list of Devices). Either this parameter, devices or the deviceGroups parameter must be specified.
N/A
N/A
devices
List<String>
Conditional
The Device (or semicolon-separated list of Devices). Either this parameter, deviceIds or the deviceGroups parameter must be specified.
N/A
N/A
propertyRegexMatchesPattern
Regex
Conditional
Used with propertyRegexMatchesProperty to specify the instance-level pattern that must match for that property.
N/A
N/A
propertyRegexMatchesProperty
String
Conditional
Used with propertyRegexMatchesPattern to specify the instance-level property.
N/A
N/A
aliasRegexMatches
Regex
Optional
Only include instances where the alias matches a regular expression.
N/A
N/A
connectionName
String
Optional
The name of the LogicMonitor Connection.
N/A
N/A
dataSourceInstanceAlias
String
Optional
Filter by alias (only applies when property=alias is used). Multiple values can be used, separated by a semi-colon.
N/A
N/A
dataSourceInstanceGroupName
String
Optional
Filter by DataSource instance group name(s). Multiple values can be used, separated by a semi-colon.
N/A
N/A
dataSourceInstanceName
String
Optional
Acts as a filter on the returned instance name(s). Multiple values can be used, separated by a semi-colon.
N/A
N/A
descriptionRegexMatches
Regex
Optional
Only include instances where the description matches a regular expression.
N/A
N/A
property
DataSourceInstanceProperty
Optional
The property to insert. The 'Spec' property is not supported in Normal Mode. You can obtain the 'ResourceId','DataSourceId' and 'ResourceDataSourceId' properties separately.
Name
None
GroupId
DisplayName
Alias
LockDescription
DeviceId
DataSourceId
DeviceDataSourceId
WildValue
WildValue2
DisableAlerting
StopMonitoring
AlertStatus
SdtStatus
AlertDisableStatus
SdtAt
Id
AllAsJson
Description
GroupName
Type
DeviceDisplayName
Spec
AllAsJObject
ResourceDataSourceId
ResourceDisplayName
ResourceId
AlertDisabledOn
AlertStatusPriority
IsUNCInstance
CollectorId
CustomProperties
SystemProperties
AutoProperties
Name
Additional (2)
Parameter
Type
Presence
Purpose
Options
Default
comment
String
Optional
Add a comment to make your document template more readable. The comment is discarded in the output document.
N/A
N/A
singleValueList
Normal mode
Boolean
Optional
In Normal Mode and for macros that output JArrays only, whether to convert a JArray of single-property jObjects into a flat JArray of values.
true
false
false
Deprecated(12)
Parameter
Type
Preferred Parameter
Purpose
Options
Default
dataSourceId
List<Int32>
dataSourceIds
The DataSource Id(s). Either this or dataSourceNames must be specified.
N/A
N/A
dataSourceName
List<String>
dataSource
The DataSource name or names. Either this or dataSourceId must be specified.
N/A
N/A
dataSourceNames
List<String>
dataSource
The DataSource name or names. Either this or dataSourceId must be specified.
N/A
N/A
dataSources
List<String>
dataSource
The DataSource name or names. Either this or dataSourceId must be specified.
N/A
N/A
device
List<String>
devices
The Device (or semicolon-separated list of Devices). Either this parameter, deviceIds or the deviceGroups parameter must be specified.
N/A
N/A
deviceGroup
List<String>
deviceGroups
The Device Group (or semicolon-separated list of Device Groups). Either this parameter, deviceIds or the devices parameter must be specified. Use "/" or no value in the deviceGroups parameter to reference the root folder.
N/A
N/A
deviceId
List<Int32>
deviceIds
The Device (or semicolon-separated list of Devices). Either this parameter, devices or the deviceGroups parameter must be specified.
N/A
N/A
group
List<String>
deviceGroups
The Device Group (or semicolon-separated list of Device Groups). Either this parameter, deviceIds or the devices parameter must be specified. Use "/" or no value in the deviceGroups parameter to reference the root folder.
N/A
N/A
groups
List<String>
deviceGroups
The Device Group (or semicolon-separated list of Device Groups). Either this parameter, deviceIds or the devices parameter must be specified. Use "/" or no value in the deviceGroups parameter to reference the root folder.
N/A
N/A
host
List<String>
devices
The Device (or semicolon-separated list of Devices). Either this parameter, deviceIds or the deviceGroups parameter must be specified.
N/A
N/A
hosts
List<String>
devices
The Device (or semicolon-separated list of Devices). Either this parameter, deviceIds or the deviceGroups parameter must be specified.
N/A
N/A
delimiter
Char
listDelimiter
In Legacy Mode, the delimiter to use between multiple items in the output.