Connecting to External Systems

You need to connect ReportMagic (and other apps, such as AlertMagic) to the systems whose data you wish to report on.

To do this, you will need:

The remote system's URL (e.g. http://mycompany.logicmonitor.com)
Relevant redentials, such as a user name and password, or an API token
In some cases, additional configuration information

You can add Connections for any number of remote systems, including more than one of each type.

IP Address Range: If your security policy requires you to restrict incoming connections by IP address, connections will originate from the range 46.249.212.128/27. If this range is considered too broad, the IP Address of the Production ReportMagic server is the single IP Address: 46.249.212.140. This may be subject to change at short notice. If you require notice of such a change, please submit a support request via the Feedback form, and we will keep your contact details on file and let you know if this occurs.

Adding a Connection

Choose the type of Connection below for specific instructions on how to set up a Connection:

When saving the Connection via the UI, if it is the first of this type of Connection, a Macro Parameter Default is automatically created which sets it as the default used by any macros that require it. This saves you specifying the connectionName in every relevant macro. You can also create a default manually, if you are a Tenant Admin.

With Connections in place, you can use relevant macros for those systems - such as AutoTask, Jira, LogicMonitor, ServiceNow, etc. You can then copy the Help examples to Report Studio and amend them, or start using them in report document templates straight away.

Where available, version information is shown for each Connection. For example, LogicMonitor Connections indicates the LogicMonitor release version in the version column (accessible by going to the Admin => Connections page in ReportMagic, or the Connections menu in the Admin app).

Various Connection types (Cisco, Highlight, LogicMonitor and Meraki) may also show a 'graph icon' in the table, which when clicked on will open a pop-up with various statistics about the Connection. For example, the number of Devices and Websites in your LogicMonitor portal. More information is at the end of this document.

Read-Only Connections

When you create a Connection, depending on the type, you can set them to be read-only via the create / edit dialog. This means in the case of file-based Connections, writing anything to the destination folder is not possible. For other Connection types, this means that 'restricted macros' (that would cause a write operation such as an SQL CREATE command) will under no circumstances be allowed to use that Connection, and the macro will fail.

Multiple Connections with the Same Type

You can create more than one Connection for the same type - for example two LogicMonitor Connections pointing to different systems such as testing and production LogicMonitor portals. With one of the Connections defined as the default, you would interact with the non-default system in one of these ways:

Use the [Settings:] macro to override the default

Use the [Settings:] macro in an input document or Report Studio to override the Macro Parameter Default. For example, the following will use the non-default Connection, but only for LogicMonitor.Graph macros:

[Settings: LogicMonitor.Graph.connectionName=nonDefaultConnection]

This approach has the advantage that you can specify that it applies only to one particular type of macro throughout the report. Using this approach, [LogicMonitor.LastMeasurement:] macros in the same report would not be affected, and in this example would still use the LogicMonitor Connection that has been setup as the default.

[XXX.Connection:] macros

Use a [XXX.Connection:] macro to override the macro parameter default in a report, for example:

[LogicMonitor.Connection:name=nonDefaultConnection]

This approach has the advantage that all following [LogicMonitor:] macros are affected, until another [LogicMonitor.Connection:] macro is reached, or you use the per-macro override approach.

Per-Macro Override

Use the connectionName parameter within an individual macro to override the macro parameter default as a one-off. For example:

[LogicMonitor.Graph:connectionName=nonDefaultConnection]

This approach has the advantage that you can use it as a one-off. No other macros in the report will be affected.

Changing the Macro Default (Tenant Admins only)

For a one-off interaction with the non-default system, a Tenant Admin could change the Macro Default while running a report, then change it back again afterwards. All relevant macros in the report will use the changed default. Use caution with this approach - any other users who are running reports at the same time may get unexpected results!

SuperAdmin Locked Connections

Super Admins and Uber Admins can lock a Connection to protect it from a Tenant Admin. This includes ensuring a Tenant Admin cannot edit / clone / delete a Connection. Only Super Admins and Uber Admins can create this locked Connection. Tenant Admins do not have the ability to set this up.

When Might a Connection Fail?

Connections may fail if since the Connection was created:

The credentials or account used to create the Connection have changed or been removed
The URL on the target system has changed, for example, the URL for web connection authentication
The Configuration field is being use but contains invalid item(s) or a value which has now changed, for example, the port on a database
The target system is not reachable, for example due to an outage
The Windows Agent needs to be restarted
The default Connection has been deleted (this will present as a failure to run relevant macros rather than a broken Connection, assuming that Connection name is not set on the macro)

Viewing a Connection's Status

To help identify which Connections are 'valid' (and which might be incorrectly configured), each Connection showns an icon on the Connections page (in both the Admin app and in ReportMagic via the Admin => Connections menu) in the 'Status' column of the table to indicate if they are valid - a green check for OK or a red cross otherwise.

Viewing Statistics about a Connection

Some Connection types also enable you to view a pop-up of statistics on the Connections page, to indicate various items collected via the respective endpoints. This can be useful to get a quick glance of data about each Connection.

The supported Connection types are:

Cisco - shows support for various product types, e.g. Eox, Hello, Software Suggestion, and more
Git - lists the branches and tags for the repository - from version 3.25
Highlight - displays the number of folders - from version 3.25
Meraki - lists each Organization and shows data such as the number of sensors, access points, smart cameras, and switches
LogicMonitor - displays a wealth of statistics about resources, alerts and maps, users and roles, and thresholds and datapoints

Each relevant Connection shows a bar chart icon in the Connection table's "Stats" column. Clicking that opens a pop-up presenting the data in tabular form.

Note that the statistics / details are collected automatically by Magic Suite on a regular interval behind the scenes, so that they are ready to view straight away. The pop-up indicates in the top-right corner when the last collection time was. You can press the "Update" button in the pop-up footer to perform an immediate refresh.