ACM ships with pre-made reports covering many different data topics. Custom reports can be created that are specific to your organization’s needs. This page will show how to create a new custom report and where to save it for users to access.
Caution on Creating Reports
Custom reports interact with the ACM database directly, and misconfigured reports can modify or delete contents from the ACM database which may cause issues. See Reports Tab on how to configure the reporting account to a read-only SQL user/account.
Instructions
- Create a new file with the .XML extension.
- Paste in the sample File Format shown on this page.
- Enter a Name and Description for the report. Assign a unique name. This is the display name that will appear in report listings. The description is supporting text to explain what the report provides.
- Enter the SQL for the report:
SQL Query method.
Example: <!-- SELECT * FROM TblObjects ORDER BY ObjectId -->
Stored Procedure method.
Example: <!–EXECUTE dbo.asi_spProcedureName '@Parameter' -->
- Create one or more parameters as needed. If no parameters are needed, leave the parameters node empty. See Parameters section for details and examples.
- Save the file to the File Location shown below. The Report Service will include the new report the next time the listing is loaded or refreshed. There is no need to restart the Report Service.
File Location
Reports are located in the Communication Manager system files folder under the Reports sub directory. The Report Server generates the listing from the files located here. The folder location is configured in the System Files tab of the ACM Monitor.
File Format
Reports are XML files with the following schema:
<?xml version="1.0" encoding="utf-8" ?>
<report>
<name>Name</name>
<description>Description</description>
<sql>
<!-- SQL -->
</sql>
<parameters>
<parameter type="Type" name="Name" description="Description" default="DefaultValue" />
</parameters>
</report>
Parameters
Parameters are optional modifiers for the SQL. Based on the type of parameter, the report viewing interface will display an input to allow report users to assign a value.
Parameters consist of the following elements:
- Type (Determines the user entry method such as checkbox or drop-down listing and its choices)
- Name (The label for the parameter and the token used in the SQL statement to resolve the value when executing.
- Description (Helpful description shown to guide user.)
- Default (Default value for parameter. Can be Custom Default for Date/DateTime types only.)
- Min/Max (If applicable, include the minimum and maximum range the value can be.)
No Parameters Example
<parameters>
</parameters>
One or More Parameters Example
<parameters>
<parameter type="Boolean" name="OnlyEnabled" description="Enabled Devices Only" default="true" />
<parameter type="Integer" name="Missing" description="Missing Record Count" default="0" min="-1" max="100"/>
<parameter type="Boolean" name="IncludeStation" description="Include Station Meters" default="false" />
<parameter type="Device" name="DeviceName" description="Device" default="0" />
</parameters>
Supported Parameter Types
| Type | Description |
|---|---|
DateTime Date | A value representing a datetime. Modifiers can be used to set a default. Uses the default attribute of the parameter node. See Supported Custom Defaults below. |
| Boolean | A value representing a choice of True or False. The UI will display a toggle or checkbox control. |
| Integer | A value representing a generic number such as a number of days or hours. The UI will display a number entry control. |
| Device | A value representing a device object number. The UI will display a listing of protocol devices to choose from. |
| Object | A value representing an object number. The UI will display a listing of objects to choose from. |
| Meter | A value representing a meter object number. The UI will display a listing of meters to choose from. |
| Archive | A value representing an archive object number. The UI will display a listing of archives to choose from. |
| Publisher | A value representing a publisher object number. The UI will display a listing of publishers to choose from. |
| Filter | A value representing an archive filter object number. The UI will display a listing of archive filters to choose from. |
Supported Custom Defaults
| Type | Description |
|---|---|
| Current | The current date and time as of executing the SQL. |
| TopHour | The current top of hour as of executing the SQL. Example: Current Time=12:30PM, TopHour=12:00PM |
| StartDay | The current date as of executing the SQL. |
| EndDay | The current date plus 1 day as of executing the SQL. |
| Yesterday | The current date minus 1 day as of executing the SQL. |
| PriorHour | The last top hour minus 1 hour from current date and time as of executing the SQL. Example: Current Time=12:30PM, PriorHour=11:00AM |
| NextHour | The next top of hour plus 1 hour from current date and time as of executing the SQL. Example: Current Time=12:30PM, NextHour=1:00PM |
| StartMonth | The date of the first day of the current month as of executing the SQL. |
Examples
Archive Hourly Summary (Stored Procedure Method)
<?xml version="1.0" encoding="utf-8" ?>
<report>
<name>Archive Hourly Summary Report</name>
<description>Returns the Archive Hourly Summary. Use the Missing Record Count parameter to control the minimum number of records a device must be missing to be included in the report.</description>
<sql>
<!-- EXECUTE asi_spHourlyArchiveStatus '@onlyEnabled', '@iMissing', @includeStation -->
</sql>
<parameters>
<parameter type="Boolean" name="onlyEnabled" description="Enabled Devices Only" default="true" />
<parameter type="Integer" name="iMissing" description="Missing Record Count" default="0" min="-1" max="100"/>
<parameter type="Boolean" name="includeStation" description="Include Station Meters" default="false" />
</parameters>
</report>
Note: Stored Procedure Parameters are preceded by the "@" character. The matches the name of the corresponding parameter.
GC Write Request Audit Last N Days (SQL Method)
<?xml version="1.0" encoding="utf-8" ?>
<report>
<name>GC Write Request Audit Last N Days</name>
<description>This report displays all audited GC write requests from the specified date.</description>
<sql>
<!-- SELECT tblGcWritePendingAudit.DeviceName As [Device], tblObjects.ObjectName As [Meter], tblGcWritePendingAudit.GcWriteTime As [WriteTime], tblGcWriteResultLookup.Description As [Result]
FROM tblGcWritePendingAudit, tblObjects, tblGcWriteResultLookup
WHERE tblGcWritePendingAudit.MeterId = tblObjects.ObjectId
AND tblGcWritePendingAudit.GcWriteResultId = tblGcWriteResultLookup.Id
AND tblGcWritePendingAudit.GcWriteTime > getdate() - @Age
ORDER BY tblGcWritePendingAudit.GcWriteTime -->
</sql>
<parameters>
<parameter type="Integer" name="Age" description="Age (in days)" default="30" min="0" max="730"/>
</parameters>
</report>
Note: SQL Parameters are preceded by the "@" character. The matches the name of the corresponding parameter.
Missing Daily Archive Records (Stored Procedure Method)
<?xml version="1.0" encoding="utf-8" ?>
<report>
<name>Missing Daily Archive Records</name>
<description>Identifies missing daily records, using the Archive Management process.</description>
<sql>
<!-- EXECUTE asi_spMissingDailyRecords '@startDate', '@endDate', '@enabled' -->
</sql>
<parameters>
<parameter type="Date" name="startDate" description="Start Date" default="StartMonth" />
<parameter type="Date" name="endDate" description="End Date" default="StartDay" />
<parameter type="Boolean" name="enabled" description="Enabled Devices Only" default="true" />
</parameters>
</report>
Note: Both parameters Start Date and End Date make use of custom defaults.
Related articles