How to…

Expose Custom Measurements for Use in

Web Applications
StruxureWare Power Monitoring 7.0 / 7.0.1
Important Information
People responsible for the application, implementation and use of this document must make sure that all
necessary design considerations have been taken into account and that all laws, safety and performance
requirements, regulations, codes, and applicable standards have been obeyed to their full extent.

Schneider Electric provides the resources specified in this document. These resources can be used to minimize
engineering efforts, but the use, integration, configuration, and validation of the system is the user’s sole
responsibility. Said user must ensure the safety of the system as a whole, including the resources provided by
Schneider Electric through procedures that the user deems appropriate.

Notice
This document is not comprehensive for any systems using the given architecture and does not absolve users of
their duty to uphold the safety requirements for the equipment used in their systems, or compliance with both
national or international safety laws and regulations.

Readers are considered to already know how to use the products described in this document.

This document does not replace any specific product documentation.

Intention
This document is intended to describe how to expose your custom measurements for use in Web Applications
especially in energy-related Dashboard gadgets and reports

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

Table of Contents

1. Introduction 4
1.1. Purpose 4
1.2. Dashboard Gadgets and Custom Measurements 4
1.3. Before You Begin 5
1.4. About this Document 5

2. How to Configure Custom Measurements for Exposure in Web Applications 6

2.1. PART 1: How to Update Measurement Metadata 6
2.2. PART 2: How to Assign Unit of Measurement 12

3. Why is the Measurement not listed in the Web Applications? 15

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

1. Introduction

1.1. Purpose

StruxureWare Power Monitoring (SPM) 7.0 and 7.0.1 are installed with a default set of measurements. The
Customer’s application may require additional custom measurements to represent non-typical data, such as
energy price, energy costs, etc. Custom measurements are created using the Logical Device Type Editor tool.
These measurements are available throughout the application; however additional database configuration is
required to expose custom measurements to Dashboard Gadgets.

All measurements in SPM 7.0 and 7.0.1 are defined by an internal set of characteristics called metadata. This
metadata is used only by Web Applications and it describes:
• The measurement type;
• How the measurement is processed; and
• How the measurement is displayed.

When a custom measurement is created in the Logical Device Type Editor, it is defined with a default set of
metadata which requires manual definition to reflect the proper the measurement definition and to expose the
measurement to Dashboard Gadgets.

In SPM 7.0 or 7.0.1, this metadata is only accessible via a direct connection to the ApplicationModules database;
Users do not have access this data through the Application user interface.

The purpose of this document is to guide you through how to update the metadata for a custom measurement
so that it is available for use by energy-related Dashboard Gadgets.

1.2. Dashboard Gadgets and Custom Measurements

Dashboard Gadgets are designed to display data for specific applications. For example, the Period over Period
gadget is designed to display consumption totaled at specified intervals (daily, weekly, monthly) between two
similar time intervals (this week over last week, this month over last month, etc). With this design, only
measurements that are configured for the intended application are available for selection during gadget
configuration. In the Period over Period example, only measurements defined as consumption measurements
will be available for use in this gadget.

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

Immediately after you create a custom measurement for the Customer, the good thing is that these
measurements are already available for use in non-energy gadgets/reports without additional tweaking.

The only case where you must apply this document is when the custom measurement:
1. Should be exposed to energy gadgets/reports;
2. Will contain cumulative data;

In this case, you must define its metadata appropriately via data configuration directly in the system databases.
The background knowledge and instructions for configuring your custom measurements are described in this
document.

1.3. Before You Begin

To follow the instructions in this document, you must have knowledge and experience with the following:
• SQL Server Management Studio
• How to write T-SQL queries
• How to connect to the Application databases
• How to locate specific tables and view its data
• How to update records in these tables

It is strongly recommended that you backup the database before you implement any changes described in this
document.

1.4. About this Document

This document contains the information to configure custom measurements for proper use and exposure in
energy-related items in SPM Web Applications. It does not provide an explanation of the database structure or
how a measurement’s metadata configuration affects the how the measurement is handled by Web
Applications. The intention of this document is only to provide the steps to expose the custom measurement
to energy-related gadgets.

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

2. How to Configure Custom Measurements for Exposure in Web
Applications
When a new custom measurement is created in the Logical Device Type Editor, the measurement’s default
configuration is enough to make the measurement available to general Dashboard Gadgets, Tables and Reports.
Its configuration must be updated only if the measurement:
1. Contains cumulative data; and/or
2. Should be available in energy-specific gadgets or reports; and/or
3. You want to display a valid unit of measurement to be displayed along with the data.

The measurement configuration is divided into two parts:

1. Update Measurement Metadata
2. Update Measurement Unit

The steps involved in each part are outlined in the sections below.

2.1. PART 1: How to Update Measurement Metadata

To expose the custom measurement to energy-related dashboard gadgets, you need to change the
measurement’s metadata for the following two measurement characteristics:
1. Set APPLICATION to CONSUMPTION and
2. Set UTILITY to a value that is not N/A. For example: ELECTRICITY, GAS, etc.

To designate the custom measurement as a cumulative measurement, you need to change the measurement’s
Accumulation Type characteristic:
1. Set ACCUMULATION_TYPE to CUMULATIVE.

In order to change the custom measurement’s metadata, you will need to know three IDs for each characteristic
(Note: the MetadataValueId represents both the characteristic and metadata):
1. The measurement’s MetadataItemId;
2. The MetadataValueId for the measurement’s current metadata; and
3. The MetadataValueId for the target metadata.

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

At this time, a custom measurement’s metadata and Ids are only available via direct connection to the
ApplicationModules database. So to update metadata, you will need to have a basic understanding of how to
write/update SQL queries and also how to use SQL Server Management Studio.

This section provides steps that will guide you on how to get the Ids and update the metadata. Follow the step-
by-step instructions below.

Step 1: Connect to Database

Log onto the SQL Server instance and connect to the ApplicationModules database with read and write access
at minimum.

Step 2: Get the Measurement’s TopicId

First identify the Metadata currently assigned to your custom measurement by running the following query or
reviewing the CommonDataModel.TopicMetadataView view :

-- Show assigned metadata

SELECT *
FROM [ApplicationModules].[CommonDataModel].[TopicMetadataView]
WHERE [Description] LIKE '%<Custom Measurement Name>%'

You should see results similar to that in Figure 1 below.

Figure 1: TopicMetadataView

Take note of the measurement’s TopicId and MetadataItemId for use in following steps. Note: A negative
TopicId indicates a custom measurement. Measurements supplied by the factory have a positive TopicId
number.

Measurement TopicId

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

Step 3: Get the Measurement’s MetadataItemId and Current MetadataValueIds for each
Measurement Characteristic

To expose the custom measurement to energy-related dashboard gadgets, you need to change the metadata for
the APPLICATION and UTILITY characteristics and to designate the custom measurement as cumulative, you
need to change the measurement’s ACCUMULATION_TYPE characteristic. This step walks through how to get
the MetadataValueId for current metadata assigned to these characteristics.

To get the measurement’s MetadataItemId and current MetadataValueIds, run the following query in a new
Query window and replace the <TopicId> text with the number found in the previous step.

-- Show the Measurement's Metadata in a legible format

SELECT
B.[MetadataItemId]
, C.[DataSourceRepresentation] as MeasurementName
, A.[MetadataValueId]
, E.[Name] as MetadataName
, D.[Value] as MetadataValue
FROM [ApplicationModules].[Metadata].[MetadataItemValue] A
INNER JOIN [ApplicationModules].[Metadata].[MetadataItem] B
ON B.MetadataItemId = A.MetadataItemId
INNER JOIN [ApplicationModules].[DataSourceBus].[DataSourceTopic] C
ON C.TopicId = B.TargetId
INNER JOIN [ApplicationModules].[Metadata].[MetadataValue] D
ON D.MetadataValueId = A.MetadataValueId
INNER JOIN [ApplicationModules].[Metadata].[MetadataName] E
ON E.[MetadataNameId] = D.MetadataNameId
WHERE C.[TopicId] = <TopicId>
ORDER BY D.[MetadataNameId],A.[MetadataValueId]

You should see results similar to that in Figure 2 below.

Figure 2: Example Query Result Showing Assigned Metadata in a Legible Format

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

Note the MetadataItemId and the MetadataValueIds for APPLICATION, UTILITY and ACCUMULATION_TYPE.

Measurement MetadataValueId

APPLICATION MetadataValueId (Current)

UTILITY MetadataValueId (Current)

ACCUMULATION_TYPE MetadataValueId (Current)

Step 4: Find the Target MetadataValueIds for Target MetadataValues

To expose the custom measurement to energy dashboard gadgets, you will set:
1. APPLICATION to CONSUMPTION and
2. UTILITY to a value that is not N/A. For example: ELECTRICITY, GAS, etc.

For a cumulative measurement, you will set ACCUMULATION_TYPE to CUMULATIVE.

This step involves find the target MetadataValueIds for each of the new metadata assignments:

For the APPLICATION characteristic, run the following query to get the MetadataValueId for CONSUMPTION:
-- Find the MetadataValueId for CONSUMPTION
SELECT a.[MetadataValueId], a.[Value]
FROM [ApplicationModules].[Metadata].[MetadataValue] a
INNER JOIN [ApplicationModules].[Metadata].[MetadataName] b
ON b.[MetadataNameId] = a.[MetadataNameId]
WHERE b.[Name] = 'CDM.MdName.APPLICATION'
AND a.[Value] = 'CDM.MdValue.CONSUMPTION'

For the UTILITY characteristic, run the following query to get the MetadataValueIds for available utilities:
-- Find the MetadataValueId for desired UTILITY
SELECT a.[MetadataValueId], a.[Value]
FROM [ApplicationModules].[Metadata].[MetadataValue] a
INNER JOIN [ApplicationModules].[Metadata].[MetadataName] b
ON b.MetadataNameId = a.MetadataNameId
WHERE b.[Name] = 'CDM.MdName.UTILITY'
AND a.[Value] <> 'CDM.MdValue.N/A'
ORDER BY a.[Value]

You should see results similar to that in Figure 3 below perhaps with different MetadataValueIds. Select one
utility that best represents your custom measurement, and note the corresponding MetadataValueId.

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

Figure 3: Example Query Result to Show all non-N/A MetadataValues associated with the UTILITY Characteristic

For the ACCUMULATION_TYPE characteristic, run the following query to get the MetadataValueId for the
CUMULATIVE metadata:
-- Find the MetadataValueId for CUMULATIVE
SELECT a.[MetadataValueId], a.[Value]
FROM [ApplicationModules].[Metadata].[MetadataValue] a
INNER JOIN [ApplicationModules].[Metadata].[MetadataName] b
ON b.MetadataNameId = a.MetadataNameId
WHERE b.[Name] = 'CDM.MdName.ACCUMULATION_TYPE'
AND a.[Value] = 'CDM.MdValue.CUMULATIVE'

In the end, you should have 2 or 3 target MetadataValueIds depending on whether your custom measurement
represents cumulative data or not

APPLICATION MetadataValueId (Target)

UTILITY MetadataValueId (Target)

ACCUMULATION_TYPE MetadataValueId (Target)

Step 5: Update Metadata Assignments

With the necessary data gathered from the previous steps, update the necessary metadata assignments. Run
the following query once for each measurement characteristic that will change (APPLICATION, UTILITY, and
ACCUMULATION_TYPE):
-- Update Measurement metadata
UPDATE [ApplicationModules].[Metadata].[MetadataItemValue]
SET MetadataValueId = <Target MetadataValueId>
WHERE MetadataItemId = <Measurement MetadataItemId>
AND MetadataValueId = <Current MetadataValueId>

10

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

Example: Say you have the following information for the APPLICATION characteristic from the previous steps:

Measurement MetadataValueId 7456

APPLICATION MetadataValueId (Current) 1021

APPLICATION MetadataValueId (Target) 7

The query would be modified and run as follows:

-- Update Measurement metadata
UPDATE [ApplicationModules].[Metadata].[MetadataItemValue]
SET MetadataValueId = 7
WHERE MetadataItemId = 7456
AND MetadataValueId = 1021

Step 7: Review

Review a summary of the assigned metadata by re-running the query in Step 2. Ensure:
1. CDM.MdName.APPLICATION is set to CDM.MdValue.CONSUMPTION; and
2. CDM.MdName.UTILITY is set to a value that is not CDM.MdValue.N/A.
3. CDM.MdName.ACCUMULATION_TYPE is set to CDM.MdValue.CUMULATIVE, if the custom
measurement represents cumulative data.

Step 8: Done

11

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

2.2. PART 2: How to Assign Unit of Measurement

By default, a custom measurement is defined as DIMENSIONLESS (UnitId = 0). To ensure custom measurement
data is displayed with the proper unit of measurement, you need to update the UnitId field in two tables in the
ApplicationModules database with the proper UnitId for your measurement:
• DataSourceBus.DataSourceTopic, and
• CommonDataModel.Topic

Follow these steps to assign the proper unit of measurement to your custom measurement:
1. Log onto the SQL Server instance and connect to the ApplicationModules database with read and write
access at minimum, if not connected already.
2. Review the list of available units of measurement. Query the CommonDataModel.Unit table in a new
Query window. Note the UnitId of the appropriate unit of measurement.

SELECT * FROM [ApplicationModules].[CommonDataModel].[Unit]

You should see results similar to Figure 4 below.

Figure 4: Example Query Result from CommonDataModel.Unit

Note the UnitId of the desired unit of measurement.

Target UnitId

3. Update the assigned unit of measurement using your custom measurement’s TopicId (obtained in Part 1 –
Step 2). Run the following Update query in a new Query window:

12

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

 UPDATE [ApplicationModules].[DataSourceBus].[DataSourceTopic]
SET [UnitId] = <Selected UnitId>
WHERE [TopicId] = <TopicId>

UPDATE [ApplicationModules].[CommonDataModel].[Topic]
SET [UnitId] = <Selected UnitId>
WHERE [TopicId] = <TopicId>

4. Confirm the assignment. Run the following two queries using the measurement’s TopicId in a new Query
window.

Check the CommonDataModel.Topic table:

-- Check the CommonDataModel.Topic table
SELECT
cdm_t.TopicId
, cdm_t.Description
, cdm_t.UnitId
, cdm_u.UnitId AS Unit_UnitID
, cdm_u.BaseUnitId
, cdm_u.Name as UOM_Name
, cdm_u.Description AS UOM_Symbol
FROM [ApplicationModules].[CommonDataModel].[Unit] cdm_u
INNER JOIN [ApplicationModules].[CommonDataModel].[Topic] cdm_t ON cdm_u.UnitId =
cdm_t.UnitId
WHERE cdm_t.TopicId = <TopicId>

You should see results similar to Figure 5 below.

Figure 5: Example Query Result when Checking the CommonDataModel.Topic Table

Check the DataSourceBus.DataSourceTopic table:

-- Check the DataSourceBus.DataSourceTopic table
SELECT * FROM [ApplicationModules].[DataSourceBus].[DataSourceTopic]
WHERE TopicId = <TopicId>

You should see results similar to Figure 5 below.

Figure 6: Example Query Result when Checking the DataSourceBus.DataSourceTopic Table

13

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

5. Done.

14

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

3. Why is the Measurement not listed in the Web Applications?
It is important to note the conditions for your custom measurement to appear in the list of available
measurements. The following explanation was extracted from the Web Applications Help File under the section
titled “Where is my measurement?”

Figure 7: Location of "Where is my Measurement?" Link

If you do not see a measurement that you expect in the data series list, it is probably due to one of the
following:
• The cache needs to be updated. To view newly added measurements, click “Refresh List”.
• The measurement is not logged. Only logged measurements are available in the data series list.
• The measurement is an advanced measurement, and “Common Only” is selected in the Measurements
drop-down list.
o “Common Only” displays a selection of the most commonly used measurements.
o Select “All” in the Measurements drop-down list to display all available measurements.
• The measurement is not available for the utility selected in the Utility drop-down list.
o Select a different utility from the Utility drop-down list, and see if the measurement appears in
the data series list.
• The measurement type cannot be displayed in the selected gadget.
o For example, some gadgets only display consumption measurements, such as energy or volume.
o The data series list only displays measurement types available for the selected gadget.
o To find out which measurement types are available for a specific gadget, click the gadget help
icon.
• The measurement is a custom measurement for which the metadata is not set up correctly.
o The metadata defines the measurement type, as well as how a measurement is presented in the
Measurements and Utility drop-down lists.
o Metadata for a measurement supplied with the software is defined by the factory.
o Metadata for an application-specific measurement created in the field (i.e. a custom
measurement) must be defined by the person creating the custom measurement.

15

INTERNAL DISTRIBUTION ONLY © 2013 Schneider Electric All Rights Reserved

StruxureWare Power Monitoring is a trademark or registered trademark of Schneider Electric. Other trademarks
used herein are the property of their respective owners.

Due to evolution of standards and equipment,

characteristics indicated in texts and images in this
Schneider Electric Industries SAS
document are binding only after confirmation by our
Head Office departments.
35, rue Joseph Monier
92506 Rueil-Malmaison Cedex
FRANCE Print:

www.schneider-electric.com
Version 3.0.1 – Sep 2013