Skip to content

Valuedef

<Value Definition>

The ValueDefinition defines a signal in DataPlatform by configuring a unique identifier (signal key), a reference to i18n label message key and units key. A ValueDefinition key can be referenced in the parsing definition of CAN-messages.

Note

It is highly advisable to use the Proemion DataPortal Signal Catalog for comparison and unifying the value definition. This enables you to seamlessly analyze machine data across the entire fleet.

Signal Catalog integration

For newly created signals or adapted signals from the Signal Catalog that need to be referenced in the PDC, you must add the following attribute to the <ValueDefinition> element:

managedByDataPlatform="true"

Example:

<ValueDefinition key="value.common.cu.hours.operation" managedByDataPlatform="true"/>

For ValueDefinition elements with managedByDataPlatform="true", no additional child elements or attributes are allowed except key and managedByDataPlatform. Adding local metadata will result in a validation error during upload to the DataPlatform.

You can find a PDC template including all required elements in PDC Introduction.

ValueDefinition elements without this attribute will be rejected during upload.

For migrating existing signals to the Signal Catalog, see Migration Guide for the Signal Catalog.

Note

If you do not need to define signals, ValueDefinitions may be left empty. It must not be omitted. <ValueDefinitions/> is a valid element.

ValueDefinitions XML example (DataPlatform and local definitions) (click to view) 
<ValueDefinitions>
<!-- Data Platform-managed signal: reference only, no local definition allowed -->
<ValueDefinition key="value.common.cu.hours.operation" managedByDataPlatform="true"/>
    <!-- Locally defined signal -->
    <ValueDefinition key="value.common.cu.battery.cyclecount" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.cu.battery.cyclecount"/>
      <unit>predefined.unit.NUMBER</unit>
    </ValueDefinition>
    <ValueDefinition key="value.common.machine.hours.fullload" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.machine.hours.fullload"/>
      <unit>predefined.unit.time.HOUR</unit>
    </ValueDefinition>
    <ValueDefinition key="value.common.engine.fuel.efficiency.total" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.engine.fuel.efficiency.total"/>
      <unit>predefined.unit.flow.LITER_PER_HOUR</unit>
      <format>%.2f</format>
    </ValueDefinition>
    <ValueDefinition key="value.common.engine.speed" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.engine.speed"/>
      <unit>predefined.unit.rotation.RPM</unit>
    </ValueDefinition>
    <ValueDefinition key="value.common.machine.distance.total" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.machine.distance.total"/>
      <unit>predefined.unit.length.KILOMETER</unit>
      <format>%.0f</format>
      <categories>
           <category xsi:type="Counter"/>
        </categories>
    </ValueDefinition>
    <ValueDefinition key="value.common.engine.def.level" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.engine.def.level"/>
      <unit>predefined.unit.PERCENT</unit>
    </ValueDefinition>
    <ValueDefinition key="value.common.engine.fuel.level" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.engine.fuel.level"/>
      <unit>predefined.unit.PERCENT</unit>
      <format>%1.0f</format>
      <minValue>0</minValue>
      <maxValue>100</maxValue>
    </ValueDefinition>
    <ValueDefinition key="value.common.model.fuel.efficiency.total" boundTo="model" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.model.fuel.efficiency.total"/>
      <unit>predefined.unit.flow.LITER_PER_HOUR</unit>
      <format>%.2f</format>
    </ValueDefinition>
    <ValueDefinition key="value.common.machine.hours.operation.total" managedByDataPlatform="false">
      <description xsi:type="MessageReference"
            value="label.value.common.machine.hours.operation.total"/>
      <unit>predefined.unit.time.HOUR</unit>
      <format>%1.1f</format>
      <categories>
        <category xsi:type="Counter" decreasing="false"/>
      </categories>
    </ValueDefinition>
    <ValueDefinition key="value.EngineHighTemp" managedByDataPlatform="false">
            <description xsi:type="MessageReference"
            value="label.value.EngineHighTemp"/>
            <unit>unit.state</unit>
            <categories>
                <category xsi:type="StateSignal" subType="boolean" machineError="true">
                    <state>
                        <description xsi:type="MessageReference"
            value="label.value.EngineHighTemp.On"/>
                        <aempCautionCode>
                            <Identifier>ISO 7000-1167</Identifier>
                            <Description>Transmission oil-pressure</Description>
                        </aempCautionCode>
                    </state>
                    <state value="0" inactive="true">
                        <description xsi:type="MessageReference"
            value="label.value.EngineHighTemp.Off"/>
                    </state>
                </category>
            </categories>
        </ValueDefinition>
        <ValueDefinition key="value.EngineLowTemp" managedByDataPlatform="false">
            <description xsi:type="MessageReference"
            value="label.value.EngineLowTemp"/>
            <unit>unit.state</unit>
            <categories>
                <category xsi:type="StateSignal" subType="enumeration" machineError="true">
                    <state value="1" inactive="true" >
                        <description xsi:type="MessageReference"
            value="label.value.EngineLowTemp.State_1"/>
                    </state>
                    <state value="2">
                        <description xsi:type="MessageReference"
            value="label.value.EngineLowTemp.State_2"/>
                    </state>
                    <state value="3">
                        <description xsi:type="MessageReference"
            value="label.value.EngineLowTemp.State_3"/>
                    </state>
                </category>
            </categories>
        </ValueDefinition>
  </ValueDefinitions>
Declaration Description
<ValueDefinition> Collector for a "ValueDefinition”
<ValueDefinition>.key Defines the signal key
<ValueDefinition>.managedByDataPlatform If value is true, the value definition from the DataPlatform Signal Catalog is used. The attribute must be added to the <ValueDefinition> element. Only key and managedByDataPlatform are allowed.
<description> Defines the label
<description>.value References the key of a from the used as label
<unit> Assigns the signal to a custom Unit or a predefined Unit.
<format> Optional. Defines the formatting of the values displayed in the DataPortal.
This setting applies if no settings are made in the DataPortal. The system saves all numerical values as high-precision floating point numbers.

Example: %1.2f ("f" stands for float and 1.2 defines the representation with 1 pre-decimal place and 2 decimal places). The definition of the digits before the decimal point is optional. If no pre-decimal places are defined, all pre-decimal places are displayed (example: %.0f).

In case that the representation of the predefined.unit.time.HOUR needs to be switched from HH:MM:SS to HH, the format <format>%1.0f</format> must be defined. Otherwise, the default format HH:MM:SS will be used.
<minValue> The ability to define the minimum value of a signal and therefore correctly scale visualizations, such as plots.
<maxValue> The ability to define the maximum value of a signal therefore correctly scale visualizations, such as plots.
<categories> The tag is the container for the <category>.
<category> The properties of the signal can be defined using <category>.
<category>.type The attribute "xsi:type" defines the type of signal. Two values are currently supported:
"Counter": The delta query can then be used in the data portal and on the REST-API for signals that contain these attributes. Counter signal only has the *decreasing
"StateSignal": Allows the definition of caution codes on the AEMP interface (<aempCautionCode>). Can select from 2 subtypes "boolean"(0,1) and "enumeration" (0,1,2,3...).
<category>.subType The attribute "xsi:subType" defines the sub type for state signals. Two values are currently supported:
"boolean": Allows to define a mapping for a signal with two states
"enumeration": Allows to define a mapping for a signal with multiple states
<category>.machineError
"true": Values of this signal will be part of the AEMP caution code endpoint. The signal value will be used as caution code identifier. The label as caution code description.
"false": Values of this signal will NOT be part of the AEMP caution code endpoint.
<category>.<aempCautionCode> Container for <Description> and <Identifier>.

Is used as a source for the standard metrics CautionMessages, see Caution Codes.
If <aempCautionCode> is absent, then the <state>.value and <state>.description are used.
<Identifier> refers to the caution code reference number ISO 7000 or IEC 60417 which represents the registration number of the symbol displayed on the machine indicating a system problem that occurred at a specific data and time.
In turn, the symbol registration number refers to "ISO 6405-1" and "ISO 6405-2".
The <Identifier> is optional and is a string with unbounded length.
Defining this element allows to use a standard regarding alerts.
<category>.<state> Allows the definition of a state per value.
<state>.value The signal value representing a specific state
<state>.inactive
"true": Non-error state, will NOT be part of AEMP caution code endpoint.
false": Error state, will be part of AEMP caution code endpoint.
<state>.<description> Defines the label, see above.
<ValueDefinition>.boundTo If signals do not specifically belong to a machine, but are determined based on a model, the boundTo attribute should be used. This indicates that a signal is provided by the model of a machine and not directly by the machine itself. You can choose between the "machine" and "model" key, with machine being the default case.

NOTE: The signal is not automatically filled when creating the value definition. In many cases special scripts are required to fill the signals with values. To do so, you will have to contact Proemion.

NOTE: If boundTo = "model" is used, the value definition key must contain the following syntax: value [common\|custom].model.\.*.