Changed Device Data Report Templates
Changed Device Data report templates contain a ReportDefinition page and a ReportSheet page, to access the worksheets that together describe the reports you can produce. CygNet provides a sample report template file DeviceChangeTemplate.xlsx for reference. It is stored in the CygNet\Services\FMS\ReportTemplates\Samples folder on your host server.
The ReportDefinition sheet includes the following parameters to describe the type of report to build.
The ReportSheet sheet includes the following sections and corresponding tokens to describe the specific format of the report to build. Valid tokens will be replaced by the values they represent. You may also include additional information you wish to see in the report.
Displaying Additional (Non-Token) Values
You can enter additional (non-token) elements such as logos, labels, or text into reports. Elements that are not valid token values will be displayed as entered.
Note: This means that tokens with typographical errors, therefore not "valid" tokens, will also be displayed as entered.
Example
[NodeName] is a valid token. If you use [Name] (not a valid token) instead of [NodeName], the value will be displayed as "[Name]" instead of displaying the Node Name value desired, since [Name] is not a valid token.
|
[Name] |
Configuring the ReportDefinition
The ReportDefinition uses parameters to describe the type of report for the service to build. The following parameters determine the described characteristics of your report.
Changed Device Data Report: ReportParameters
Report parameters, which appear between #ReportParameters# and #End#, can be defined by the following values.
| Parameter | Description | Value |
|---|---|---|
|
ReportName |
The value defined in this cell will be used for the report name, as it will appear in drop-down menus in FMS Explorer and CygNet Explorer. See Using the Reports Control and Scheduling FMS Command Tasks in the MSS for more information. |
Enter a value to be used for the report name. Example Changed Device Data |
|
CommandName |
The value defined in this cell will be used by the service to determine which specific report command type to execute. See FMSClient Methods in the Scripting section for more information. |
Enter a value to specify the report command name. Example CHNGD Note: Maximum of 7 characters; letters and/or numbers only, no spaces. |
Changed Device Data Report: Worksheet Parameters
Changed Device Data report worksheet parameters, which appear between #Worksheet# and #End#, can be defined by the following values.
Note: A tolerance can be set using either percentage or absolute; if you set both percentage and absolute tolerances, the more restrictive tolerance will be used.
| Parameter | Description | Value |
|---|---|---|
|
ReportType |
The value defined in this cell will be used to represent the standard FMS report type you are configuring. |
Enter a value to be used to indicate the type of the report. Example Changed Device Data |
|
NullToken |
The value defined in this cell will be used to represent null values in your report. |
Enter a value to be used to indicate a "null value" cell in the report. Example - |
|
VolumeTolerancePercentage |
The value defined in this cell will be used to specify what percentage change in Volume data is required to include the change in your report. If used, the report will ignore changes whose % change is less than or equal to the specified % tolerance. |
Enter a numerical value (0 - 100) to indicate the percentage change in Volume value that must be exceeded, in order to be shown in the report. |
|
VolumeToleranceAbsolute |
The value defined in this cell will be used to specify what value change in Volume data (in units specified as a command parameter) is required to include the change in your report. If used, the report will ignore Volume changes whose value change is less than or equal to the specified tolerance. |
Enter a numerical value to indicate the absolute change in Volume value (in units as specified in the command parameter) that must be exceeded, in order to be shown in the report. |
|
EnergyTolerancePercentage |
The value defined in this cell will be used to specify what percentage change in Energy data is required to include the change in your report. If used, the report will ignore changes whose % change is less than or equal to the specified % tolerance. |
Enter a numerical value (0 - 100) to indicate the percentage change in Energy value that must be exceeded, in order to be shown in the report. |
|
EnergyToleranceAbsolute |
The value defined in this cell will be used to specify what value change in Energy data (in units specified as a command parameter) is required to include the change in your report. If used, the report will ignore Energy changes whose value change is less than or equal to the specified tolerance. |
Enter a numerical value to indicate the absolute change in Energy value (in units as specified in the command parameter) that must be exceeded, in order to be shown in the report. |
|
MassTolerancePercentage |
The value defined in this cell will be used to specify what percentage change in Mass data is required to include the change in your report. If used, the report will ignore Mass changes whose % change is less than or equal to the specified % tolerance. |
Enter a numerical value (0 - 100) to indicate the percentage change in Mass value that must be exceeded, in order to be shown in the report. |
|
MassToleranceAbsolute |
The value defined in this cell will be used to specify what value change in Mass data (in units specified as a command parameter) is required to include the change in your report. If used, the report will ignore Mass changes whose value change is less than or equal to the specified tolerance. |
Enter a numerical value to indicate the absolute change in Mass value (in units as specified in the command parameter) that must be exceeded, in order to be shown in the report. |
|
PageBreaks |
The value defined in this cell will be used to specify whether or not to use page breaks in your report. If used, will force a page break after each device within a group. |
Enter a value to indicate whether or not to use page breaks in the report. Options are Yes or No. Default value is Yes. |
|
The value defined in this cell will be used in your report to represent the value for the Group name or Group description fields when either of the following is true.
|
Enter a value to be used to indicate the Group name or Group description when the command was not run against a single group Node. Example [Invalid Group] |
|
|
NodeSortOrder |
The value defined in this cell will be used to specify the order in which to display Node results in the report. |
Enter one of the following options.
Default value is Name ascending. This parameter is optional. |
|
Note: Optional. The value defined in this cell will be used to specify whether or not to display the [ChangeDateTime] value on every line in the data table. |
If used, enter one of the following possible values to repeat the date/time on every line in the table.
Enter any other value (or leave blank) to only show the date/time on the first occurrence in the table (default behavior). |
|
|
RptStDate |
Note: Optional. If you use this parameter in your report template, the RptStDate parameter will no longer appear for configuration in FMS Explorer or CygNet Explorer. See Changed Device Data Report Definitions (FMS Explorer) or Reports: Changed Device Data (CygNet Explorer) for more information. |
If used, enter a valid start date value for the report. RptStDate and RptEndDate must be the same configuration parameter type. Notes: The report will display data in Device time (D), although the report command parameters are configured relative to Contract time (C). The report will only include records that exist entirely within the specified date range. See Selecting Date and Time for more information. This parameter is optional. |
|
RptEndDate |
Note: Optional. If you use this parameter in your report template, the RptEndDate parameter will no longer appear for configuration in FMS Explorer or CygNet Explorer. See Changed Device Data Report Definitions (FMS Explorer) or Reports: Changed Device Data (CygNet Explorer) for more information. |
If used, enter a valid end date value for the report. RptStDate and RptEndDate must be the same configuration parameter type. *Notes: The report will display data in Device time (D), although the report command parameters are configured relative to Contract time (C). The report will only include records that exist entirely within the specified date range. See Selecting Date and Time for more information. This parameter is optional. |
|
RptUnitSet |
Note: Optional. If you use this parameter in your report template, the RptUnitSet parameter will no longer appear for configuration in FMS Explorer or CygNet Explorer. See Changed Device Data Report Definitions (FMS Explorer) or Reports: Changed Device Data (CygNet Explorer) for more information. |
If used, enter a valid unit set value for the report. Valid unit set values defined in the service can be viewed through the Admin menu in FMS Explorer. See Configuring Unit Set Definitions for more information. This parameter is optional. |
Configuring the ReportSheet
The ReportSheet uses tokens to describe the format of the report you want to run. The following tokens determine the report content, and will retrieve the corresponding values for display in your report.
Note: Enter report tokens carefully, as the tokens are case sensitive. Typographical errors (therefore not "valid" tokens) will be handled as "additional values" and displayed as entered; the non-token value will appear in your report instead of the actual value(s) the correctly entered token would have retrieved. See Displaying Additional (Non-Token) Values above for more information.
Changed Device Data Report: Header Tokens
Changed Device Data report headers, which appear above #EndReportHdr#, can be described by the following tokens.
| Token | Description |
|---|---|
| [BeginDateTime] | The start date, in Contract day (C), of the requested time range for the report |
| [EndDateTime] | The end date, in Contract day (C), of the requested time range for the report |
| [GeneratedDateTime] | The time the report was generated, in Local time (L) |
| [TotalDeviceCount] | The total number of devices in the report |
Changed Device Data Report: SubReport Header Tokens
Changed Device Data report subreport headers, which appear between #SubSection# SubReportHeader and #End#, can be described by the following tokens.
| Token | Description |
|---|---|
| [=] | When used as the first three characters, turns the cell into a formula |
| [RowNumber] | The current row number |
| [CurrentDeviceCount] | The index of the device being displayed |
| [TotalDeviceCount] | The total number of devices in the report |
| [NodeContractHour] | The contract hour of the Node |
| [NodeDaysOfData] | The number of days for which the data source of the Node will retain data |
| [NodeDesc] | The Node description |
| [NodeId] | The Node ID |
| [NodeInstallDateTime] | The install date/time for the Node, in Device time (D) |
| [NodeName] | The Node name |
| [NodePollingFacilityId] | The polling facility ID of the Node |
| [NodePollingFacilityTag] | The polling facility tag of the Node |
| [NodePollingSiteService] | The polling Site.Service of the Node |
| [NodeReportingFacilityId] | The reporting facility ID of the Node |
| [NodeReportingSiteService] | The reporting Site.Service of the Node |
| [NodeSecurityApp] | The security application of the Node |
| [NodeSortPriority] | The sort priority of the Node |
| [NodeStationContribution] | For station meter Nodes, the station contribution value, whether receipt (+) or delivery (-) |
| [NodeTimezone] | The time zone configured for the Node |
| [NodeTimezoneUsingDst] | The daylight saving time status of the Node |
| [NodeType] | The Node type |
| [PollingFac_Attr0] - [PollingFac_Attr39] |
Polling facility indexed text attributes 0 through 39 (each a separate token) |
| [PollingFac_Category] |
Polling facility category |
| [PollingFac_Comment] |
Polling facility comment attribute |
| [PollingFac_Desc] |
Polling facility description |
| [PollingFac_Info0] |
Polling facility info attribute 0 Default attribute name is Facility Location |
| [PollingFac_Info1] |
Polling facility info attribute 1 Default attribute name is Facility Contact |
| [PollingFac_IsActive] |
Polling facility active flag |
| [PollingFac_Table0] - [PollingFac_Table59] |
Polling facility indexed table-driven attributes 0 through 59 (each a separate token) |
| [PollingFac_Type] |
Polling facility type |
| [PollingFac_YesNo0] - [PollingFac_YesNo19] |
Polling facility indexed Yes/No attributes 0 through 19 (each a separate token) |
| [RecordSpan] | The number of minutes in the record span |
Changed Device Data Report: Data Table Header Tokens
Changed Device Data report data table headers, which appear between #SubSection# DataTableHeader and #End#, can be described by the text you enter. Type the desired text into the cell, and format it as desired. Data Table Headers can also be described by the following tokens.
Note: In PDF format, reports containing tables that span multiple pages will repeat the data table header on each contiguous page.
| Token | Description |
|---|---|
| [=] | When used as the first three characters, turns the cell into a formula |
| [RowNumber] | The current row number |
| [CurrentDeviceCount] | The index of the device being displayed |
| [TotalDeviceCount] | The total number of devices in the report |
Changed Device Data Report: Data Table Tokens
Changed Device Data report data table parameters, which appear between #SubSection# DataTable (1 or 2) and #End#, can be described by the following tokens.
Note: When the value of the ChangeDateTimePerLine parameter is set to Yes or Y, the [ChangeDateTime] value will be repeated on each line of the data table. Optionally, you can place any listed Node or facility token on that same line, and it will also be repeated on each line of the table.
| Token | Description |
|---|---|
| [=] | When used as the first three characters, turns the cell into a formula |
| [FirstRow] | Used by a formula, as a pointer to the first row of data in a table |
| [LastRow] | Used by a formula, as a pointer to the last row of data in a table |
| [RowNumber] | The current row number |
| [ChangeDateTime] | The date/time, in Device time (D), of the data change
Note: When the value of the ChangeDateTimePerLine parameter is set to Yes or Y, the [ChangeDateTime] value will be repeated on each line of the table. Optionally, you can place any listed Node or facility token on that same line, and it will also be repeated on each line of the table. |
| [ChangeItem] | The data item for which the data was changed |
| [ChangeValueOld] | The old value, prior to the changed device data |
| [ChangeValueNew] | The new value, resulting from the changed device data |
| [ChangeValueUnits] | The units used for the changed device data value |
| [ChangeNewDQ] | The new data quality value, resulting from the changed device data |
| [ChangeAuditUserName] | The username associated with the change to the device data, for auditing purposes |
| [ChangeAuditDateTime] | The date/time associated with the change to the device data, for auditing purposes |
| [ChangeAuditComment] | The comment associated with the change to the device data, for auditing purposes |
| [ChangeAuditCategory] | The audit category associated with the change to the device data, for auditing purposes |
| [ChangeDataSource] | The data source associated with the device data change |
| [NodeContractHour] | The contract hour of the Node |
| [NodeDaysOfData] | The number of days for which the data source of the Node will retain data |
| [NodeDesc] | The Node description |
| [NodeId] | The Node ID |
| [NodeInstallDateTime] | The install date/time for the Node, in Device time (D) |
| [NodeName] | The Node name |
| [NodePollingFacilityId] | The polling facility ID of the Node |
| [NodePollingFacilityTag] | The polling facility tag of the Node |
| [NodePollingSiteService] | The polling Site.Service of the Node |
| [NodeReportingFacilityId] | The reporting facility ID of the Node |
| [NodeReportingSiteService] | The reporting Site.Service of the Node |
| [NodeSecurityApp] | The security application of the Node |
| [NodeSortPriority] | The sort priority of the Node |
| [NodeStationContribution] | For station meter Nodes, the station contribution value, whether receipt (+) or delivery (-) |
| [NodeTimezone] | The time zone configured for the Node |
| [NodeTimezoneUsingDst] | The daylight saving time status of the Node |
| [NodeType] | The Node type |
| [PollingFac_Attr0] - [PollingFac_Attr39] |
Polling facility indexed text attributes 0 through 39 (each a separate token) |
| [PollingFac_Category] |
Polling facility category |
| [PollingFac_Comment] |
Polling facility comment attribute |
| [PollingFac_Desc] |
Polling facility description |
| [PollingFac_Info0] |
Polling facility info attribute 0 Default attribute name is Facility Location |
| [PollingFac_Info1] |
Polling facility info attribute 1 Default attribute name is Facility Contact |
| [PollingFac_IsActive] |
Polling facility active flag |
| [PollingFac_Table0] - [PollingFac_Table59] |
Polling facility indexed table-driven attributes 0 through 59 (each a separate token) |
| [PollingFac_Type] |
Polling facility type |
| [PollingFac_YesNo0] - [PollingFac_YesNo19] |
Polling facility indexed Yes/No attributes 0 through 19 (each a separate token) |
Changed Device Data Report: SubReport Footer Tokens
Changed Device Data report subreport footers, which appear between #SubSection# SubReportFooter and #End#, can be described by the following tokens.
| Token | Description |
|---|---|
| [=] | When used as the first three characters, turns the cell into a formula |
| [FirstRow] | Used by a formula, as a pointer to the first row of data in a table |
| [LastRow] | Used by a formula, as a pointer to the last row of data in a table |
| [RowNumber] | The current row number |
| [CurrentDeviceCount] | The index of the device being displayed |
| [TotalDeviceCount] | The total number of devices in the report |
| [NodeContractHour] | The contract hour of the Node |
| [NodeDaysOfData] | The number of days for which the data source of the Node will retain data |
| [NodeDesc] | The Node description |
| [NodeId] | The Node ID |
| [NodeInstallDateTime] | The install date/time for the Node, in Device time (D) |
| [NodeName] | The Node name |
| [NodePollingFacilityId] | The polling facility ID of the Node |
| [NodePollingFacilityTag] | The polling facility tag of the Node |
| [NodePollingSiteService] | The polling Site.Service of the Node |
| [NodeReportingFacilityId] | The reporting facility ID of the Node |
| [NodeReportingSiteService] | The reporting Site.Service of the Node |
| [NodeSecurityApp] | The security application of the Node |
| [NodeSortPriority] | The sort priority of the Node |
| [NodeTimezone] | The time zone configured for the Node |
| [NodeTimezoneUsingDst] | The daylight saving time status of the Node |
| [NodeType] | The Node type |
| [PollingFac_Attr0] - [PollingFac_Attr39] |
Polling facility indexed text attributes 0 through 39 (each a separate token) |
| [PollingFac_Category] |
Polling facility category |
| [PollingFac_Comment] |
Polling facility comment attribute |
| [PollingFac_Desc] |
Polling facility description |
| [PollingFac_Info0] |
Polling facility info attribute 0 Default attribute name is Facility Location |
| [PollingFac_Info1] |
Polling facility info attribute 1 Default attribute name is Facility Contact |
| [PollingFac_IsActive] |
Polling facility active flag |
| [PollingFac_Table0] - [PollingFac_Table59] |
Polling facility indexed table-driven attributes 0 through 59 (each a separate token) |
| [PollingFac_Type] |
Polling facility type |
| [PollingFac_YesNo0] - [PollingFac_YesNo19] |
Polling facility indexed Yes/No attributes 0 through 19 (each a separate token) |
| [RecordSpan] | The number of minutes in the record span |
Changed Device Data Report: Report Footer
Changed Device Data report footers, which appear between #SubSection# ReportFooter and #End#, can be described by the text you enter. Type the desired text into the cell, and format it as desired.
