Information Model Schema Documentation

Type: object

Represents the structure of a single analytics algorithm within CMD's information model.

Each field below is pointing to a specific key, with the information about the purpose and possible values. Click on a given section to learn more.

Refer to this wiki page to learn more about the general purpose of information model and to see the concreate examples.

root name

Name

Type: string

Name under which given algorithm will be referenced within information model file. Same name cannot be repeated within one file!

In most cases it can be equal to path field. There are places, where it's handy to alias same function multiple times (with different inputs), example:

[
    {
        "name": "StartupsAverage",
        "path": "Statistics",
        "inputs": [
          {
            "type": "constant",
            "inputName": "function",
            "dataType": "stringArray",
            "values": [
              "Average"
            ]
          },
          "rest of the fields is not displayed"
        ],
        "dependencies": [
          "InherentAvailabilityDay"
        ],
        "schedule": "day",
        "retention": "default"
      },
      {
        "name": "StartupsMedian",
        "path": "Statistics",
        "inputs": [
          {
            "type": "constant",
            "inputName": "function",
            "dataType": "stringArray",
            "values": [
              "Median"
            ]
          },
          "rest of the fields is not displayed"
        ],
        "dependencies": [
          "InherentAvailabilityDay"
        ],
        "schedule": "day",
        "retention": "default"
    }
]

root path

Path

Type: string

Actual analytics azure function name, which shall be executed by the given algorithm.

Note that in order for the function to be visible by the CMD backend (and information model), docker container with the function code needs to be uploaded to the CMD's container registry.

In practice, it means that code with azure function needs to be merged to the master branch of the CMDFunctions repository.

root inputs

Inputs

Type: array

Representation of the actual algorithm inputs. Shall be provided as an array of objects (dicts); order is not important.

Objects are associated with actual function input by inputName; input type selection is done by type field.

No Additional Items

Each item of this array must be:

root inputs inputs items

root inputs inputs items oneOf Constant
Type: object

Simple constant value passed as an algorithm input with given data type. Example:

{
    "type": "constant",
    "dataType": "integer",
    "inputName": "temperatureReference",
    "value": 40
}

root inputs inputs items oneOf Constant inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf Constant optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf Constant type

Type

Type: const

Must be one of:

  • "constant"
Specific value: "constant"

root inputs inputs items oneOf Constant dataType
Type: enum (of string) Default: null

Requested value data type. If this filed is not provided, the value data type will be inferred.

Must be one of:

  • "string"
  • "stringArray"
  • "integer"
  • "double"

root inputs inputs items oneOf Constant value

Value

Default: null

Required when datatype field is NOT stringArray. Example:

{
    "type": "constant",
    "dataType": "string",
    "inputName": "trendName",
    "value": "PowerTrend"
}

root inputs inputs items oneOf Constant values

Values

Default: null

Required when datatype field IS stringArray. Example:

{
    "type": "constant",
    "datatype": "stringArray",
    "inputName": "functions",
    "values": [
      "min",
      "max",
      "rms",
      "delta",
      "std",
      "mean"
    ]
}

root inputs inputs items oneOf Constant values anyOf item 0
Type: array of string
No Additional Items

Each item of this array must be:

root inputs inputs items oneOf Constant values anyOf item 0 item 0 items
Type: string
root inputs inputs items oneOf Constant values anyOf item 1
Type: null
root inputs inputs items oneOf Calculated
Type: object

Returns value which is calculated by the CMD - refer to specific implementation (defined by calculation field) for more details. Example:

{
    "type": "calculated",
    "inputName": "commissioningDate",
    "calculation": "FanLifetimeStartDate"
}

root inputs inputs items oneOf Calculated inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf Calculated optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf Calculated type

Type

Type: const

Must be one of:

  • "calculated"
Specific value: "calculated"

root inputs inputs items oneOf Calculated calculation
Type: string

Defines actual calculation which will be performed. Actual code can be found here.

root inputs inputs items oneOf Calculated calculation oneOf CapacitorLifetimeStartDate

CapacitorLifetimeStartDate

Type: const

Returns capacitor component start date.

Technically, start date for each component is created in CMD's Cosmos DB (docType="ComponentLifetime") at first run of calculation for a given drive. It is determined based on the following logic:

  1. If drive has associated CbmConfig document, start date is taken from algorithm's startDate field. In this case, start date was previously set by old CBM (maintained by Analytics team), using this logic.
  2. If associated CbmConfig document was not found, data from DriveRegistrationInfo document will be used. If exists, field startUpDate will be used; otherwise warrantyStart.
Specific value: "CapacitorLifetimeStartDate"
root inputs inputs items oneOf Calculated calculation oneOf FanLifetimeStartDate

FanLifetimeStartDate

Type: const

Returns fan component start date.

Technically, start date for each component is created in CMD's Cosmos DB (docType="ComponentLifetime") at first run of calculation for a given drive. It is determined based on the following logic:

  1. If drive has associated CbmConfig document, start date is taken from algorithm's startDate field. In this case, start date was previously set by old CBM (maintained by Analytics team), using this logic.
  2. If associated CbmConfig document was not found, data from DriveRegistrationInfo document will be used. If exists, field startUpDate will be used; otherwise warrantyStart.
Specific value: "FanLifetimeStartDate"
root inputs inputs items oneOf Calculated calculation oneOf IgbtLifetimeStartDate

IgbtLifetimeStartDate

Type: const

Returns IGBT component start date.

Technically, start date for each component is created in CMD's Cosmos DB (docType="ComponentLifetime") at first run of calculation for a given drive. It is determined based on the following logic:

  1. If drive has associated CbmConfig document, start date is taken from algorithm's startDate field. In this case, start date was previously set by old CBM (maintained by Analytics team), using this logic.
  2. If associated CbmConfig document was not found, data from DriveRegistrationInfo document will be used. If exists, field startUpDate will be used; otherwise warrantyStart.
Specific value: "IgbtLifetimeStartDate"
root inputs inputs items oneOf Calculated calculation oneOf NominalCurrentFromLookUpTable

NominalCurrentFromLookUpTable

Type: const

Returns drive's nominal current taken from CMD's DriveDimensionMap document (field: maximumContinuousCurrentA), based on the drive's type code (shortTypeCode field in DriveRegistrationInfo document).

This method can be used for ACS800 drives - other drive types are not included in lookup table.

DriveDimensionMap document has following form:

{
    "id": "2E35FA40-CE65-4F17-98E0-8AAD445ED613",
    "partitionKey": "global",
    "docType": "DriveDimensionMap",
    "rules": [
        {
            "typeCode": "ACS800-01-0001-2",
            "maximumContinuousCurrentA": "5.1",
            "maximumCurrentA": "6.5",
            "maximumContinousPowerKw": "1.1",
            "frameSize": "R2",
            "driveType": "SingleDrive"
        },
        {
            "typeCode": "ACS800-01-0002-2",
            "maximumContinuousCurrentA": "6.5",
            "maximumCurrentA": "8.2",
            "maximumContinousPowerKw": "1.5",
            "frameSize": "R2",
            "driveType": "SingleDrive"
        }
        "skipped remaining entries"
    ]
}
Specific value: "NominalCurrentFromLookUpTable"
root inputs inputs items oneOf Calculated calculation oneOf NominalCurrentFromTypeCode

NominalCurrentFromTypeCode

Type: const

Returns drive's nominal current taken from the drive type code. Type code is taken from CMD's DriveRegistrationInfo document, field: shortTypeCode. Can be used for newer drives, e.g. ACS880 - older drives don't have current encoded in type code, thous this method will not work.

For example, for following type code: "ACS880-01-032A-3", returned value will be equal to 32.

Specific value: "NominalCurrentFromTypeCode"
root inputs inputs items oneOf Signal
Type: object

Returns internal drive signal (timeseries), referenced by symbolic_name. Signal will be truncated based on the algorithm schedule, e.g. if hourly schedule is requested, input signal will be starting at the beginning of the given hour and spawning to the end of the hour.

Example:

{
    "type": "signal",
    "inputName": "temperature",
    "symbolicName": "ctrl_board_temp",
}

There are cases where it is possible (and allowed) that input signal will be missing. For example, when algorithm is expecting multiple signals, and, based on the signal availability, final signal, which will be passed to the calculations, is selected. In this case, optional flag is necessary; otherwise error will be raised in case of missing signal.

root inputs inputs items oneOf Signal inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf Signal optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf Signal type

Type

Type: const

Must be one of:

  • "signal"
Specific value: "signal"

root inputs inputs items oneOf Signal symbolicName

Symbolicname

Type: string

Selects the actual drive timeseries signal which will be feed to the algorithm. Signal mapping and list of all available drive signals is located within abb.drives.{drive_type}.{type_id}.json file, section variables (stored in information model repo). Provided symbolicName shall match symbolicName field defined in this file.

Example snipped from drive signal mapping file:

{
    "skipped beginning sections",
    "variables": {
        "01_02": {
          "description": "SPEED (rpm)",
          "unit": "rpm",
          "dataType": "number",
          "symbolicName": "motor_speed",
          "textKey": "ABB.CMD.Backend.KPI.Parameters.acs800_asxr_as7r.01_02"
        },
        "01_03": {
          "description": "FREQUENCY (Hz)",
          "unit": "Hz",
          "dataType": "number",
          "symbolicName": "frequency_hz",
          "textKey": "ABB.CMD.Backend.KPI.Parameters.acs800.Frequency"
        },
        "skipped rest of the mapping and end sections"
    }
}
root inputs inputs items oneOf SignalSensor
Type: object

Returns external sensor signal (timeseries), referenced by symbolic_name. Signal will be truncated based on the algorithm schedule, e.g. if hourly schedule is requested, input signal will be starting at the beginning of the given hour and spawning to the end of the hour.

In practice, the used sensor will be a Yocto-Meteo device, which supports the following signals:

  • temperature
  • humidity
  • pressure

Example:

{
    "type": "signalSensor",
    "inputName": "sensorTemperature",
    "symbolicName": "temperature",
}

Since not all drives have an external sensor mounted, the optional flag is especially important for the sensor signal. Refer to the optional field description for more information.

root inputs inputs items oneOf SignalSensor inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf SignalSensor optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf SignalSensor type

Type

Type: const

Must be one of:

  • "signalSensor"
Specific value: "signalSensor"

root inputs inputs items oneOf SignalSensor symbolicName

Symbolicname

Type: string

Selects the actual sensor timeseries signal which will be feed to the algorithm. Signal mapping and list of all available sensor signals is located within abb.drives.sensor.json file, section variables.

In practice, for external sensor, following values are supported for symbolicName:

  • temperature
  • humidity
  • pressure
root inputs inputs items oneOf Events
Type: object

root inputs inputs items oneOf Events inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf Events optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf Events type

Type

Type: const

Must be one of:

  • "events"
Specific value: "events"
root inputs inputs items oneOf AlgorithmOutput
Type: object

Returns output from the other algorithm, defined in the information model file. This way, we can chain algorithms into sequences, where one algorithm output is an input for a different algorithm.

timeRange field controls the amount of the results which will be provided to the algorithm. Note that algorithms are referenced by name, not path field (actual azure function name).

Examples:

{
    "type": "AlgorithmOutput",
    "inputName": "consumedLifetimesHourly",
    "algorithm": "CapacitorLifetimeConsumptionHour",
    "property": "consumedLifetime",
    "timeRange": "day"
}

{
    "type": "AlgorithmOutput",
    "inputName": "remainingStack",
    "algorithm": "IgbtPowerCycleHour",
    "property": "remainingValues",
    "timerange": "previousHourSameDay",
    "optional": true
}

root inputs inputs items oneOf AlgorithmOutput inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf AlgorithmOutput optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf AlgorithmOutput type

Type

Type: const

Must be one of:

  • "AlgorithmOutput"
Specific value: "AlgorithmOutput"

root inputs inputs items oneOf AlgorithmOutput algorithm

Algorithm

Type: string

name of the algorithm which will be a source of the results. Algorithm definition with name shall be defined within information model file.

root inputs inputs items oneOf AlgorithmOutput property

Property

Type: string Default: null

Selects the provided key in algorithm output dictionary.

Expected response from analytics azure function has the following form:

{
    "details": {
        "key 1": 1,
        "key 2": "value 2"
    },
    "status": "response status",
    "message": "response message if exists",
    "version": "azure function version"
}

property allows to select key from the details dictionary. For example, by setting property="key 2", "value 2" will be passed to the azure function input.

If property is not provided, whole details dictionary will be passed as an input to the azure function.

root inputs inputs items oneOf AlgorithmOutput timeRange
Type: string

Allows to select results from the required time range, and passing them as an algorithm input. For more information, refer to the description of the specific value.

root inputs inputs items oneOf AlgorithmOutput timeRange oneOf all

all

Type: const

Be careful with using this setting - in most cases it is not necessary!

Selects ALL results which are available in CMD's database for a given algorithm.

Currently this setting is NOT used by any algorithm.

Specific value: "all"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf default

default

Type: const

Same as day - see day description.

Specific value: "default"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf previousHourSameDay

previousHourSameDay

Type: const

Returns result from previous hour on the same day. If previous hour has no result, latest hour with results will be used instead.

Note that this setting make sense for algorithms, which are working on hourly schedule (to select previous calculation result).

Example:

[
    {
        "name": "IgbtPowerCycleHour",
        "path": "IgbtPowerCycleHour",
        "inputs": [
          {
            "type": "signal",
            "inputName": "temperature",
            "symbolicName": "igbt_junction_temp",
          },
          {
            "type": "constant",
            "datatype": "integer",
            "inputName": "preventiveLifetimeYears",
            "value": 25
          },
          {
            "type": "constant",
            "inputName": "igbtType",
            "dataType": "string",
            "value": "Infineon_IGBT3"
          },
          {
            "type": "AlgorithmOutput",
            "inputName": "remainingStack",
            "algorithm": "IgbtPowerCycleHour",
            "property": "remainingValues",
            "timerange": "previousHourSameDay",
            "optional": true
          }
        ],
        "dependencies": [],
        "schedule": "hour",
        "retention": "sevenDays"
    }
]

remainingStack input is set to previousHourSameDay to also use results from previous algorithm execution. Note that optional flag is also used - without it, first execution of the day would produce an error since previous result is not yet present (and in consequence, this error will be propagated to next executions also).

Specific value: "previousHourSameDay"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf day

day

Type: const

Returns the results from the current day, when the algorithm calculations where requested.

Consider the following example:

[
    {
        "name": "AggregateLifetimeDailyFan",
        "path": "AggregateLifetimeDaily",
        "inputs": [
          {
            "type": "AlgorithmOutput",
            "inputName": "consumedLifetimesHourly",
            "algorithm": "FanLifetimeConsumptionHour",
            "property": "consumedLifetime",
            "timeRange": "day"
          },
          {
            "type": "calculated",
            "inputName": "commissioningDate",
            "calculation": "FanLifetimeStartDate"
          },
          {
            "type": "constant",
            "datatype": "string",
            "inputName": "algorithm",
            "value": "FanLifetimeConsumptionHour"
          }
        ],
        "dependencies": [],
        "schedule": "day",
        "retention": "unlimited"
      },
      {
        "name": "FanLifetimeConsumptionHour",
        "path": "FanLifetimeConsumptionHour",
        "inputs": [
          "inputs are skipped"
        ],
        "dependencies": [],
        "schedule": "hour",
        "retention": "sevenDays"
      }
]

AggregateLifetimeDailyFan is using daily results from FanLifetimeConsumptionHour, which is scheduled to be executed every hour. As a result, array of 24 floats will be passed to consumedLifetimesHourly input (note that we are also using property selector and format is not set):

[0.23, 0.52, 0.23, "remaining values skipped"]
Specific value: "day"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf previousDay

previousDay

Type: const

Works similarly as day, but selects results from the previous day (compared to when algorithm execution was requested).

For example if algorithm execution was requested on 10-01-2023 12:13, previousDay setting will select the results from 09-01-2023 00:00 to 09-01-2023 23:59.

Specific value: "previousDay"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf thirtyDays

thirtyDays

Type: const

Returns results from the last 30 days. Example:

[
      {
        "name": "ThermalAnomalyThirtyDaysAverage",
        "path": "Statistics",
        "inputs": [
          {
            "type": "constant",
            "datatype": "string",
            "inputName": "function",
            "value": "Average"
          },
          {
            "type": "AlgorithmOutput",
            "inputName": "data",
            "algorithm": "ThermalAnomalyDay",
            "property": "anomalyDrThermalCPA",
            "timeRange": "thirtyDays"
          }
        ],
        "dependencies": [
          "ThermalAnomalyDay"
        ],
        "schedule": "day",
        "retention": "default"
      },
      {
        "name": "ThermalAnomalyDay",
        "path": "ThermalAnomalyDay",
        "inputs": [
            "inputs are skipped"
        ],
        "dependencies": [],
        "schedule": "day",
        "retention": "default"
      }
]

For data input of ThermalAnomalyThirtyDaysAverage algorithm, we are passing results of ThermalAnomalyDay algorithm from the last 30 days. Since ThermalAnomalyDay is scheduled to be executed daily, data input will be an array of 30 floats.

Specific value: "thirtyDays"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf calendarMonth

calendarMonth

Type: const

Returns the algorithm results from the current month (compared to when algorithm execution was requested).

For example if algorithm execution was requested on 10-01-2023 12:13, calendarMonth setting will select the results from 01-01-2023 00:00 to 31-01-2023 23:59.

Specific value: "calendarMonth"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf dailySinceCapacitorLifetimeStart

dailySinceCapacitorLifetimeStart

Type: const

Returns results between CBM algorithm startDate (see inputs -> Calculated -> calculation -> FanLifetimeStartDate to learn how startDate is determined) and the end of the current (when algorithm execution was requested) day.

Currently, this time range is used only for CBM's GraphPoints algorithm, example:

{
    "name": "GraphPoints_Capacitor",
    "path": "GraphPoints",
    "outputFormat": "GraphPointArray",
    "inputs": [
      {
        "type": "calculated",
        "inputName": "commissioningDate",
        "calculation": "CapacitorLifetimeStartDate"
      },
      {
        "type": "AlgorithmOutput",
        "inputName": "stress",
        "algorithm": "AggregateLifetimeDailyCapacitor",
        "property": "consumedLifetime",
        "timeRange": "dailySinceCapacitorLifetimeStart",
        "format": "dateAndValue"
      }
    ],
    "dependencies": [
      "AggregateLifetimeDailyCapacitor"
    ],
    "schedule": "day",
    "retention": "latest"
}
Specific value: "dailySinceCapacitorLifetimeStart"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf dailySinceFanLifetimeStart

dailySinceFanLifetimeStart

Type: const

Returns results between CBM algorithm startDate (see inputs -> Calculated -> calculation -> FanLifetimeStartDate to learn how startDate is determined) and the end of the current (when algorithm execution was requested) day.

Currently, this time range is used only for CBM's GraphPoints algorithm, example:

{
    "name": "GraphPoints_Capacitor",
    "path": "GraphPoints",
    "outputFormat": "GraphPointArray",
    "inputs": [
      {
        "type": "calculated",
        "inputName": "commissioningDate",
        "calculation": "CapacitorLifetimeStartDate"
      },
      {
        "type": "AlgorithmOutput",
        "inputName": "stress",
        "algorithm": "AggregateLifetimeDailyCapacitor",
        "property": "consumedLifetime",
        "timeRange": "dailySinceCapacitorLifetimeStart",
        "format": "dateAndValue"
      }
    ],
    "dependencies": [
      "AggregateLifetimeDailyCapacitor"
    ],
    "schedule": "day",
    "retention": "latest"
}
Specific value: "dailySinceFanLifetimeStart"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf dailySinceIgbtLifetimeStart

dailySinceIgbtLifetimeStart

Type: const

Returns results between CBM algorithm startDate (see inputs -> Calculated -> calculation -> FanLifetimeStartDate to learn how startDate is determined) and the end of the current (when algorithm execution was requested) day.

Currently, this time range is used only for CBM's GraphPoints algorithm, example:

{
    "name": "GraphPoints_Capacitor",
    "path": "GraphPoints",
    "outputFormat": "GraphPointArray",
    "inputs": [
      {
        "type": "calculated",
        "inputName": "commissioningDate",
        "calculation": "CapacitorLifetimeStartDate"
      },
      {
        "type": "AlgorithmOutput",
        "inputName": "stress",
        "algorithm": "AggregateLifetimeDailyCapacitor",
        "property": "consumedLifetime",
        "timeRange": "dailySinceCapacitorLifetimeStart",
        "format": "dateAndValue"
      }
    ],
    "dependencies": [
      "AggregateLifetimeDailyCapacitor"
    ],
    "schedule": "day",
    "retention": "latest"
}
Specific value: "dailySinceIgbtLifetimeStart"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf latestValue

latestValue

Type: const

Returns the latest result before the day for which algorithm calculation was requested.

For example if algorithm execution was requested on 10-01-2023 12:13, latestValue setting will select last available algorithm result before 09-01-2023 23:59.

Currently, no algorithm is using this setting.

Specific value: "latestValue"
root inputs inputs items oneOf AlgorithmOutput timeRange oneOf maintainancePlan

maintainancePlan

Type: const

Functionality used in next level CBM.

Returns maintenance plan associated with the given drive. algorithm input is not important in this case, but still needs to be present.

Example definition in information model:

{
    "name": "GraphPointsPMKits",
    "path": "GraphPointsPMKits",
    "inputs": [
        {
            "type": "AlgorithmOutput",
            "inputName": "extensionFactors",
            "algorithm": "LifetimeExtensionFactorMonthly",
            "property": "extension_factor",
            "format": "dateAndValue",
            "timerange": "all"
        },
        {
            "type": "AlgorithmOutput",
            "inputName": "maintenancePlan",
            "algorithm": "maintenancePlan",
            "timeRange": "maintainancePlan"
        }
    ],
    "dependencies": ["LifetimeExtensionFactorMonthly"],
    "schedule": "day",
    "retention": "latest"
}

Output structure:

{
    "SerialNumber": "1140102007",
    "ManufacturingDate": "2013-12-30T00:00:00+00:00",
    "DeliveryDate": "2014-01-02T00:00:00+00:00",
    "CommissioningDate": null,
    "ServiceRecommended":
    [
        {
            "Name": "PM9",
            "Date": "2023-01-02T00:00:00+00:00",
            "IsServiceDone": false,
            "ServiceDone": null
        },
        {
            "Name": "PM12",
            "Date": "2026-01-02T00:00:00+00:00",
            "IsServiceDone": false,
            "ServiceDone": null
        },
        {
            "Name": "PM18",
            "Date": "2032-01-02T00:00:00+00:00",
            "IsServiceDone": false,
            "ServiceDone": null
        }
    ],
    "ServiceEvents":
    [
        {
            "Date": "2019-06-06T11:40:26.847+00:00",
            "Type": "Site update"
        },
        {
            "Date": "2016-06-10T15:05:21.043+00:00",
            "Type": "Drive QR code data"
        }
    ]
}
Specific value: "maintainancePlan"

root inputs inputs items oneOf AlgorithmOutput format
Type: string Default: "default"

Specifies the desired format of the AlgorithmOutput input.

root inputs inputs items oneOf AlgorithmOutput format oneOf default

default

Type: const

Results will be passed as a list of objects (dictionaries) without any additional transformation. If this is the desired behaviour, format field shall not be specified.

Example:

{
    "type": "AlgorithmOutput",
    "inputName": "consumedLifetimesHourly",
    "algorithm": "IgbtThermalCycleHour",
    "property": "consumedLifetime",
    "timeRange": "day"
}

Will fetch the consumedLifetime key from each result within this day and form the following input:

[0.032, 0.022, 0.012, "remaining values skipped"]
Specific value: "default"
root inputs inputs items oneOf AlgorithmOutput format oneOf dateAndValue

dateAndValue

Type: const

Will attach the date to each result value, creating the input in the following form:

[{"date": "date in 'yyyy-MM-dd'", "value": "actual value"},  {"..."}]

For example:

[{"date": "2022-01-12", "value": 0.0304},  {"date": "2022-01-13", "value": 0.045}, {"..."}]

Used currently in GraphPoints algorithms, example:

{
    "name": "GraphPoints_Fan",
    "path": "GraphPoints",
    "outputFormat": "GraphPointArray",
    "inputs": [
      {
        "type": "calculated",
        "inputName": "commissioningDate",
        "calculation": "FanLifetimeStartDate"
      },
      {
        "type": "AlgorithmOutput",
        "inputName": "stress",
        "algorithm": "AggregateLifetimeDailyFan",
        "property": "consumedLifetime",
        "timeRange": "dailySinceFanLifetimeStart",
        "format": "dateAndValue"
      }
    ],
    "dependencies": [
      "AggregateLifetimeDailyFan"
    ],
    "schedule": "day",
    "retention": "latest"
}
Specific value: "dateAndValue"

root inputs inputs items oneOf AlgorithmOutput recalculate

Recalculate

Type: boolean Default: false
root inputs inputs items oneOf AlgorithmOutputStatus
Type: object

root inputs inputs items oneOf AlgorithmOutputStatus inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf AlgorithmOutputStatus optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf AlgorithmOutputStatus type

Type

Type: const

Must be one of:

  • "AlgorithmOutputStatus"
Specific value: "AlgorithmOutputStatus"

root inputs inputs items oneOf AlgorithmOutputStatus timeRange
Type: string

Allows to select results from the required time range, and passing them as an algorithm input. For more information, refer to the description of the specific value.

root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf all

all

Type: const

Be careful with using this setting - in most cases it is not necessary!

Selects ALL results which are available in CMD's database for a given algorithm.

Currently this setting is NOT used by any algorithm.

Specific value: "all"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf default

default

Type: const

Same as day - see day description.

Specific value: "default"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf previousHourSameDay

previousHourSameDay

Type: const

Returns result from previous hour on the same day. If previous hour has no result, latest hour with results will be used instead.

Note that this setting make sense for algorithms, which are working on hourly schedule (to select previous calculation result).

Example:

[
    {
        "name": "IgbtPowerCycleHour",
        "path": "IgbtPowerCycleHour",
        "inputs": [
          {
            "type": "signal",
            "inputName": "temperature",
            "symbolicName": "igbt_junction_temp",
          },
          {
            "type": "constant",
            "datatype": "integer",
            "inputName": "preventiveLifetimeYears",
            "value": 25
          },
          {
            "type": "constant",
            "inputName": "igbtType",
            "dataType": "string",
            "value": "Infineon_IGBT3"
          },
          {
            "type": "AlgorithmOutput",
            "inputName": "remainingStack",
            "algorithm": "IgbtPowerCycleHour",
            "property": "remainingValues",
            "timerange": "previousHourSameDay",
            "optional": true
          }
        ],
        "dependencies": [],
        "schedule": "hour",
        "retention": "sevenDays"
    }
]

remainingStack input is set to previousHourSameDay to also use results from previous algorithm execution. Note that optional flag is also used - without it, first execution of the day would produce an error since previous result is not yet present (and in consequence, this error will be propagated to next executions also).

Specific value: "previousHourSameDay"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf day

day

Type: const

Returns the results from the current day, when the algorithm calculations where requested.

Consider the following example:

[
    {
        "name": "AggregateLifetimeDailyFan",
        "path": "AggregateLifetimeDaily",
        "inputs": [
          {
            "type": "AlgorithmOutput",
            "inputName": "consumedLifetimesHourly",
            "algorithm": "FanLifetimeConsumptionHour",
            "property": "consumedLifetime",
            "timeRange": "day"
          },
          {
            "type": "calculated",
            "inputName": "commissioningDate",
            "calculation": "FanLifetimeStartDate"
          },
          {
            "type": "constant",
            "datatype": "string",
            "inputName": "algorithm",
            "value": "FanLifetimeConsumptionHour"
          }
        ],
        "dependencies": [],
        "schedule": "day",
        "retention": "unlimited"
      },
      {
        "name": "FanLifetimeConsumptionHour",
        "path": "FanLifetimeConsumptionHour",
        "inputs": [
          "inputs are skipped"
        ],
        "dependencies": [],
        "schedule": "hour",
        "retention": "sevenDays"
      }
]

AggregateLifetimeDailyFan is using daily results from FanLifetimeConsumptionHour, which is scheduled to be executed every hour. As a result, array of 24 floats will be passed to consumedLifetimesHourly input (note that we are also using property selector and format is not set):

[0.23, 0.52, 0.23, "remaining values skipped"]
Specific value: "day"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf previousDay

previousDay

Type: const

Works similarly as day, but selects results from the previous day (compared to when algorithm execution was requested).

For example if algorithm execution was requested on 10-01-2023 12:13, previousDay setting will select the results from 09-01-2023 00:00 to 09-01-2023 23:59.

Specific value: "previousDay"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf thirtyDays

thirtyDays

Type: const

Returns results from the last 30 days. Example:

[
      {
        "name": "ThermalAnomalyThirtyDaysAverage",
        "path": "Statistics",
        "inputs": [
          {
            "type": "constant",
            "datatype": "string",
            "inputName": "function",
            "value": "Average"
          },
          {
            "type": "AlgorithmOutput",
            "inputName": "data",
            "algorithm": "ThermalAnomalyDay",
            "property": "anomalyDrThermalCPA",
            "timeRange": "thirtyDays"
          }
        ],
        "dependencies": [
          "ThermalAnomalyDay"
        ],
        "schedule": "day",
        "retention": "default"
      },
      {
        "name": "ThermalAnomalyDay",
        "path": "ThermalAnomalyDay",
        "inputs": [
            "inputs are skipped"
        ],
        "dependencies": [],
        "schedule": "day",
        "retention": "default"
      }
]

For data input of ThermalAnomalyThirtyDaysAverage algorithm, we are passing results of ThermalAnomalyDay algorithm from the last 30 days. Since ThermalAnomalyDay is scheduled to be executed daily, data input will be an array of 30 floats.

Specific value: "thirtyDays"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf calendarMonth

calendarMonth

Type: const

Returns the algorithm results from the current month (compared to when algorithm execution was requested).

For example if algorithm execution was requested on 10-01-2023 12:13, calendarMonth setting will select the results from 01-01-2023 00:00 to 31-01-2023 23:59.

Specific value: "calendarMonth"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf dailySinceCapacitorLifetimeStart

dailySinceCapacitorLifetimeStart

Type: const

Returns results between CBM algorithm startDate (see inputs -> Calculated -> calculation -> FanLifetimeStartDate to learn how startDate is determined) and the end of the current (when algorithm execution was requested) day.

Currently, this time range is used only for CBM's GraphPoints algorithm, example:

{
    "name": "GraphPoints_Capacitor",
    "path": "GraphPoints",
    "outputFormat": "GraphPointArray",
    "inputs": [
      {
        "type": "calculated",
        "inputName": "commissioningDate",
        "calculation": "CapacitorLifetimeStartDate"
      },
      {
        "type": "AlgorithmOutput",
        "inputName": "stress",
        "algorithm": "AggregateLifetimeDailyCapacitor",
        "property": "consumedLifetime",
        "timeRange": "dailySinceCapacitorLifetimeStart",
        "format": "dateAndValue"
      }
    ],
    "dependencies": [
      "AggregateLifetimeDailyCapacitor"
    ],
    "schedule": "day",
    "retention": "latest"
}
Specific value: "dailySinceCapacitorLifetimeStart"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf dailySinceFanLifetimeStart

dailySinceFanLifetimeStart

Type: const

Returns results between CBM algorithm startDate (see inputs -> Calculated -> calculation -> FanLifetimeStartDate to learn how startDate is determined) and the end of the current (when algorithm execution was requested) day.

Currently, this time range is used only for CBM's GraphPoints algorithm, example:

{
    "name": "GraphPoints_Capacitor",
    "path": "GraphPoints",
    "outputFormat": "GraphPointArray",
    "inputs": [
      {
        "type": "calculated",
        "inputName": "commissioningDate",
        "calculation": "CapacitorLifetimeStartDate"
      },
      {
        "type": "AlgorithmOutput",
        "inputName": "stress",
        "algorithm": "AggregateLifetimeDailyCapacitor",
        "property": "consumedLifetime",
        "timeRange": "dailySinceCapacitorLifetimeStart",
        "format": "dateAndValue"
      }
    ],
    "dependencies": [
      "AggregateLifetimeDailyCapacitor"
    ],
    "schedule": "day",
    "retention": "latest"
}
Specific value: "dailySinceFanLifetimeStart"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf dailySinceIgbtLifetimeStart

dailySinceIgbtLifetimeStart

Type: const

Returns results between CBM algorithm startDate (see inputs -> Calculated -> calculation -> FanLifetimeStartDate to learn how startDate is determined) and the end of the current (when algorithm execution was requested) day.

Currently, this time range is used only for CBM's GraphPoints algorithm, example:

{
    "name": "GraphPoints_Capacitor",
    "path": "GraphPoints",
    "outputFormat": "GraphPointArray",
    "inputs": [
      {
        "type": "calculated",
        "inputName": "commissioningDate",
        "calculation": "CapacitorLifetimeStartDate"
      },
      {
        "type": "AlgorithmOutput",
        "inputName": "stress",
        "algorithm": "AggregateLifetimeDailyCapacitor",
        "property": "consumedLifetime",
        "timeRange": "dailySinceCapacitorLifetimeStart",
        "format": "dateAndValue"
      }
    ],
    "dependencies": [
      "AggregateLifetimeDailyCapacitor"
    ],
    "schedule": "day",
    "retention": "latest"
}
Specific value: "dailySinceIgbtLifetimeStart"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf latestValue

latestValue

Type: const

Returns the latest result before the day for which algorithm calculation was requested.

For example if algorithm execution was requested on 10-01-2023 12:13, latestValue setting will select last available algorithm result before 09-01-2023 23:59.

Currently, no algorithm is using this setting.

Specific value: "latestValue"
root inputs inputs items oneOf AlgorithmOutputStatus timeRange oneOf maintainancePlan

maintainancePlan

Type: const

Functionality used in next level CBM.

Returns maintenance plan associated with the given drive. algorithm input is not important in this case, but still needs to be present.

Example definition in information model:

{
    "name": "GraphPointsPMKits",
    "path": "GraphPointsPMKits",
    "inputs": [
        {
            "type": "AlgorithmOutput",
            "inputName": "extensionFactors",
            "algorithm": "LifetimeExtensionFactorMonthly",
            "property": "extension_factor",
            "format": "dateAndValue",
            "timerange": "all"
        },
        {
            "type": "AlgorithmOutput",
            "inputName": "maintenancePlan",
            "algorithm": "maintenancePlan",
            "timeRange": "maintainancePlan"
        }
    ],
    "dependencies": ["LifetimeExtensionFactorMonthly"],
    "schedule": "day",
    "retention": "latest"
}

Output structure:

{
    "SerialNumber": "1140102007",
    "ManufacturingDate": "2013-12-30T00:00:00+00:00",
    "DeliveryDate": "2014-01-02T00:00:00+00:00",
    "CommissioningDate": null,
    "ServiceRecommended":
    [
        {
            "Name": "PM9",
            "Date": "2023-01-02T00:00:00+00:00",
            "IsServiceDone": false,
            "ServiceDone": null
        },
        {
            "Name": "PM12",
            "Date": "2026-01-02T00:00:00+00:00",
            "IsServiceDone": false,
            "ServiceDone": null
        },
        {
            "Name": "PM18",
            "Date": "2032-01-02T00:00:00+00:00",
            "IsServiceDone": false,
            "ServiceDone": null
        }
    ],
    "ServiceEvents":
    [
        {
            "Date": "2019-06-06T11:40:26.847+00:00",
            "Type": "Site update"
        },
        {
            "Date": "2016-06-10T15:05:21.043+00:00",
            "Type": "Drive QR code data"
        }
    ]
}
Specific value: "maintainancePlan"
root inputs inputs items oneOf Value
Type: object

Returns value from drive's parameter backup file.

Example parameter backup file:

[NETA-21 DDCS Report File]
2022-04-30T22:00:11+00:00

ACS 800 KR1620_SC1 {0}{1}

Application, Properties

DDCS adapter version 3.28.0.0
Name        AMAR7320
Version     AMXR7320

Parameters, 01: ACTUAL SIGNALS

NAME        VALUE   MINIMUM MAXIMUM
01.01: MOTOR SPEED FILT [rpm]       478.415405
01.02: SPEED ESTIMATED [rpm]        479.998474
01.03: SPEED MEASURED [rpm] 0.000000        -9999.998047    9999.996094
01.04: MOTOR SPEED [rpm]    479.842346
01.05: FREQUENCY [Hz]       24.008690       -500.000000     499.999939
(skipped rest of the file)

symbolicName will select the proper parameter and, after dispatching to actual id of the parameter, associated VALUE will be returned. For example, for symbolicName="motor_speed", which dispatches to id="01.04", value 479.842346 will be returned.

root inputs inputs items oneOf Value inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf Value optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf Value type

Type

Type: const

Must be one of:

  • "value"
Specific value: "value"

root inputs inputs items oneOf Value symbolicName

Symbolicname

Type: string

Selects the actual drive parameter which will be feed to the algorithm. Parameter mapping is located within abb.drives.{drive_type}.{type_id}.json file, section variables (stored in information model repo). Provided symbolicName shall match symbolicName field defined in this file.

Example snipped from drive signal mapping file:

{
    "skipped beginning sections",
    "variables": {
        "01_02": {
          "description": "SPEED (rpm)",
          "unit": "rpm",
          "dataType": "number",
          "symbolicName": "motor_speed",
          "textKey": "ABB.CMD.Backend.KPI.Parameters.acs800_asxr_as7r.01_02"
        },
        "01_03": {
          "description": "FREQUENCY (Hz)",
          "unit": "Hz",
          "dataType": "number",
          "symbolicName": "frequency_hz",
          "textKey": "ABB.CMD.Backend.KPI.Parameters.acs800.Frequency"
        },
        "skipped rest of the mapping and end sections"
    }
}
root inputs inputs items oneOf DCVoltage
Type: object

root inputs inputs items oneOf DCVoltage inputName

Inputname

Type: string

Associates input with actual azure function input. inputName shall be provided in camelCase notation. Example:

{
    "inputName": "preventiveLifetimeYears",
    "type": "actual input type",
    "other fields are depending on the input type"
}

root inputs inputs items oneOf DCVoltage optional

Optional

Type: boolean Default: false

Boolean flag which indicates if the input shall be optional. If set to false (default), and if given input is missing (eg. requested drive signal cannot be found), CMD will generate error at payload preparation stage. This is, in most cases, the desired behaviour.

There are scenarios, however, when setting optional flag to true is beneficial. For example, for the following algorithm definition: 

{
    "name": "CapacitorLifetimeConsumptionHour",
    "path": "CapacitorLifetimeConsumptionHour",
    "inputs": [
      {
        "type": "signalSensor",
        "inputName": "sensorTemperature",
        "symbolicName": "temperature",
        "optional": true
      },
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      "remaining inputs omitted"
    ],
    "dependencies": [],
    "schedule": "...",
    "retention": "..."
}

We are using external sensor temperature, "inputName": "sensorTemperature", with the optional flag. It means that even if drive doesn't have external sensor mounted, and therefore, requested signal doesn't exist, function will still be called with sensorTemperature = null.

If, however, ctrl_board_temp signal cannot be found, the analytics function will NOT be called - CMD will generate an error during payload preparation.

root inputs inputs items oneOf DCVoltage type

Type

Type: const

Must be one of:

  • "DCVoltage"
Specific value: "DCVoltage"

root outputFormat
Default: null

root outputFormat anyOf OutputFormat
Type: string

ToDo Defines the output format for the analytics library

root outputFormat anyOf OutputFormat oneOf GraphPointArray

GraphPointArray

Type: const
Specific value: "GraphPointArray"
root outputFormat anyOf OutputFormat oneOf EventGroup

EventGroup

Type: const
Specific value: "EventGroup"
root outputFormat anyOf item 1
Type: null

root dependencies

Dependencies

Type: array of string

Defines which algorithms need to be executed BEFORE running this algorithm. Proper use of dependencies allows you to guarantee the correct execution order within algorithms that are running on the same schedule (e.g. daily). If the algorithm needs results from the current execution of a different algorithm, then dependencies shall be used.

Consider the following case, where dependencies are necessary to guarantee proper execution order:

[
    {
        "name": "ThermalAnomalyThirtyDaysAverage",
        "path": "Statistics",
        "inputs":
        [
            {
                "type": "constant",
                "datatype": "string",
                "inputName": "function",
                "value": "Average"
            },
            {
                "type": "AlgorithmOutput",
                "inputName": "data",
                "algorithm": "ThermalAnomalyDay",
                "property": "anomalyDrThermalCPA",
                "timeRange": "thirtyDays"
            }
        ],
        "dependencies":
        [
            "ThermalAnomalyDay"
        ],
        "schedule": "day",
        "retention": "default"
    },
    {
        "name": "ThermalAnomalyDay",
        "path": "ThermalAnomalyDay",
        "inputs":
        [
            "inputs skipped"
        ],
        "dependencies": [],
        "schedule": "day",
        "retention": "default"
    }
]

ThermalAnomalyThirtyDaysAverage consumes current result of ThermalAnomalyDay execution - we need to ensure that ThermalAnomalyDay will be executed first and its results will be ready when ThermalAnomalyThirtyDaysAverage will be executed. Therefore, it's necessary to set dependencies of ThermalAnomalyThirtyDaysAverage to ["ThermalAnomalyDay"].

Dependencies, however, should not be used to describe the relationship between the algorithms. In other words, if one algorithm is expecting the results from the other algorithm as input, it doesn't always mean that adding this information as dependencies is necessary. In the following cases dependencies shall NOT be used:

  • when algorithms are running on a different schedule - in this case the problem of guaranteeing the order of execution is not present, because algorithms are run in different execution batches (e.g. hourly or daily):
[
    {
        "name": "AggregateLifetimeDailyCapacitor",
        "path": "AggregateLifetimeDaily",
        "inputs":
        [
            {
                "type": "AlgorithmOutput",
                "inputName": "consumedLifetimesHourly",
                "algorithm": "CapacitorLifetimeConsumptionHour",
                "property": "consumedLifetime",
                "timeRange": "day"
            },
            "other inputs skipped"
        ],
        "dependencies": [],
        "schedule": "day",
        "retention": "unlimited"
    },
    {
        "name": "CapacitorLifetimeConsumptionHour",
        "path": "CapacitorLifetimeConsumptionHour",
        "inputs":
        [
            "inputs skipped"
        ],
        "dependencies": [],
        "schedule": "hour",
        "retention": "sevenDays"
    }
]
  • algorithms are running on the same schedule, but top level algorithm is NOT using the results from the current round of execution. An example of such a situation is algorithm self-referencing, when the algorithm uses results from its previous execution. In that case, necessary results are already existing in the database, so usage of dependencies is not needed: 
{
    "name": "IgbtPowerCycleHour",
    "path": "IgbtPowerCycleHour",
    "inputs":
    [
        {
            "type": "AlgorithmOutput",
            "inputName": "remainingStack",
            "algorithm": "IgbtPowerCycleHour",
            "property": "remainingValues",
            "timerange": "previousHourSameDay",
            "optional": true
        },
        "other inputs skipped"
    ],
    "dependencies": [],
    "schedule": "hour",
    "retention": "sevenDays"
}
No Additional Items

Each item of this array must be:

root dependencies dependencies items
Type: string

root schedule
Type: enum (of string)

Requested algorithm schedule - interval between the consecutive runs of the same algorithm for the same drive. Decides how often algorithm will be run, but also which snipped of the timeseries signal (internal or external) will be passed to the algorithm if requested.

For example, in the following case:

{
    "name": "EnvironmentalAir",
    "path": "EnvironmentalAir",
    "inputs": [
      {
        "type": "signal",
        "inputName": "temperature",
        "symbolicName": "ctrl_board_temp"
      },
      {
        "type": "signal",
        "inputName": "igbtCaseTemperature",
        "symbolicName": "igbt_case_temp"
      }
    ],
    "dependencies": [],
    "schedule": "hour",
    "retention": "default"
}

Algorithm is running on hourly schedule. If algorithm execution is requested at 10-01-2023 14:48, signals passed as an inputs will be truncated to the range: <10-01-2023 14:00; 10-01-2023 14:59>. Actual number of samples which will be passed to the input depends on the sampling rate and cannot be set/modified by the algorithm.

Must be one of:

  • "hour"
  • "day"

root retention
Type: string

Defines the lifetime of a Cosmos DB document with algorithm results. In the vast majority of cases, retention shall be set to default. Known exceptions are:

  • CBM daily algorithms - see unlimited and latest
  • aggregations, where intermediate results are not needed - see sevenDays

root retention oneOf default

default

Type: const

This value shall be used in majority of the algorithms. CMD will manage the document in this case - for reporting purposes, this is the desired behaviour.

Specific value: "default"
root retention oneOf unlimited

unlimited

Type: const

Results will be kept forever, for an unlimited amount of time. This setting shall be used only when you are sure that results will be used also in the future.

Currently, the only example where this behavior is desired is daily lifetime calculations for CBM - in order to calculate the CBM graph (using the GraphPoints algorithm) ALL daily results are taken into account. Example:

[
    {
        &#34;name&#34;: &#34;AggregateLifetimeDailyCapacitor&#34;,
        &#34;path&#34;: &#34;AggregateLifetimeDaily&#34;,
        &#34;inputs&#34;: [
            &#34;inputs are skipped&#34;
        ],
        &#34;dependencies&#34;: [],
        &#34;schedule&#34;: &#34;day&#34;,
        &#34;retention&#34;: &#34;unlimited&#34;
    },
    {
        &#34;name&#34;: &#34;GraphPoints_Capacitor&#34;,
        &#34;path&#34;: &#34;GraphPoints&#34;,
        &#34;outputFormat&#34;: &#34;GraphPointArray&#34;,
        &#34;inputs&#34;: [
          {
            &#34;type&#34;: &#34;calculated&#34;,
            &#34;inputName&#34;: &#34;commissioningDate&#34;,
            &#34;calculation&#34;: &#34;CapacitorLifetimeStartDate&#34;
          },
          {
            &#34;type&#34;: &#34;AlgorithmOutput&#34;,
            &#34;inputName&#34;: &#34;stress&#34;,
            &#34;algorithm&#34;: &#34;AggregateLifetimeDailyCapacitor&#34;,
            &#34;property&#34;: &#34;consumedLifetime&#34;,
            &#34;timeRange&#34;: &#34;dailySinceCapacitorLifetimeStart&#34;,
            &#34;format&#34;: &#34;dateAndValue&#34;
          }
        ],
        &#34;dependencies&#34;: [
          &#34;AggregateLifetimeDailyCapacitor&#34;
        ],
        &#34;schedule&#34;: &#34;day&#34;,
        &#34;retention&#34;: &#34;latest&#34;
      }
]
Specific value: "unlimited"
root retention oneOf unlimitedPerMonth

unlimitedPerMonth

Type: const

Functionality used in next level CBM.

Only one result will be kept for the algorithm per calendar month - new calculations will NOT create new database document, but update existing document (result) for this calendar month.

Consider following algorithm:

{
    &#34;name&#34;: &#34;AggregatePMKitsHistogramsMonthly&#34;,
    &#34;path&#34;: &#34;AggregatePMKitsHistograms&#34;,
    &#34;inputs&#34;: [
        {
            &#34;type&#34;: &#34;AlgorithmOutput&#34;,
            &#34;inputName&#34;: &#34;histograms&#34;,
            &#34;algorithm&#34;: &#34;PreventiveMaintenanceKitsHistogramDaily&#34;,
            &#34;property&#34;: &#34;histogram&#34;,
            &#34;timerange&#34;: &#34;calendarMonth&#34;
        }
    ],
    &#34;dependencies&#34;: [&#34;PreventiveMaintenanceKitsHistogramDaily&#34;],
    &#34;schedule&#34;: &#34;day&#34;,
    &#34;retention&#34;: &#34;unlimitedPerMonth&#34;
}

Algorith is scheduled to be executed every day, so each day new result will be calculated. At each point in time, however, only one result will be stored in the database per calendar month. So, at first day of the month, new document with the results will be created. During that month each execution of the algorithm will update mentioned document - which also means that previous result (for this month) will be lost.

Specific value: "unlimitedPerMonth"
root retention oneOf latest

latest

Type: const

Only most recent algorithm result document will be kept for a given drive. This behaviour is desired when only most recent result is important, and previous can be removed.

Currently, this setting is used for GraphPoints algorithms - in this case we are every day updating graph results by taking into account new daily component lifetime. Once new graph points are computed, previous are not needed anymore. Example:

[
    {
        &#34;name&#34;: &#34;AggregateLifetimeDailyCapacitor&#34;,
        &#34;path&#34;: &#34;AggregateLifetimeDaily&#34;,
        &#34;inputs&#34;: [
            &#34;inputs are skipped&#34;
        ],
        &#34;dependencies&#34;: [],
        &#34;schedule&#34;: &#34;day&#34;,
        &#34;retention&#34;: &#34;unlimited&#34;
    },
    {
        &#34;name&#34;: &#34;GraphPoints_Capacitor&#34;,
        &#34;path&#34;: &#34;GraphPoints&#34;,
        &#34;outputFormat&#34;: &#34;GraphPointArray&#34;,
        &#34;inputs&#34;: [
          {
            &#34;type&#34;: &#34;calculated&#34;,
            &#34;inputName&#34;: &#34;commissioningDate&#34;,
            &#34;calculation&#34;: &#34;CapacitorLifetimeStartDate&#34;
          },
          {
            &#34;type&#34;: &#34;AlgorithmOutput&#34;,
            &#34;inputName&#34;: &#34;stress&#34;,
            &#34;algorithm&#34;: &#34;AggregateLifetimeDailyCapacitor&#34;,
            &#34;property&#34;: &#34;consumedLifetime&#34;,
            &#34;timeRange&#34;: &#34;dailySinceCapacitorLifetimeStart&#34;,
            &#34;format&#34;: &#34;dateAndValue&#34;
          }
        ],
        &#34;dependencies&#34;: [
          &#34;AggregateLifetimeDailyCapacitor&#34;
        ],
        &#34;schedule&#34;: &#34;day&#34;,
        &#34;retention&#34;: &#34;latest&#34;
      }
]
Specific value: "latest"
root retention oneOf sevenDays

sevenDays

Type: const

Result document will be kept for 7 days, after that period it will be removed. This setting can be used in case of aggregations - where intermediate results (e.g. hourly) are not needed once aggregate (e.g. daily) is calculated.

Example of such behaviour is daily lifetime aggregate for CBM. Consider the following example:

[
    {
        &#34;name&#34;: &#34;AggregateLifetimeDailyFan&#34;,
        &#34;path&#34;: &#34;AggregateLifetimeDaily&#34;,
        &#34;inputs&#34;: [
              {
                &#34;type&#34;: &#34;AlgorithmOutput&#34;,
                &#34;inputName&#34;: &#34;consumedLifetimesHourly&#34;,
                &#34;algorithm&#34;: &#34;FanLifetimeConsumptionHour&#34;,
                &#34;property&#34;: &#34;consumedLifetime&#34;,
                &#34;timeRange&#34;: &#34;day&#34;
              },
              {
                &#34;type&#34;: &#34;calculated&#34;,
                &#34;inputName&#34;: &#34;commissioningDate&#34;,
                &#34;calculation&#34;: &#34;FanLifetimeStartDate&#34;
              },
              {
                &#34;type&#34;: &#34;constant&#34;,
                &#34;datatype&#34;: &#34;string&#34;,
                &#34;inputName&#34;: &#34;algorithm&#34;,
                &#34;value&#34;: &#34;FanLifetimeConsumptionHour&#34;
              }
        ],
        &#34;dependencies&#34;: [],
        &#34;schedule&#34;: &#34;day&#34;,
        &#34;retention&#34;: &#34;unlimited&#34;
    },
    {
        &#34;name&#34;: &#34;FanLifetimeConsumptionHour&#34;,
        &#34;path&#34;: &#34;FanLifetimeConsumptionHour&#34;,
        &#34;inputs&#34;: [
          &#34;inputs skipped&#34;
        ],
        &#34;dependencies&#34;: [],
        &#34;schedule&#34;: &#34;hour&#34;,
        &#34;retention&#34;: &#34;sevenDays&#34;
    }
]

FanLifetimeConsumptionHour results are needed only as AggregateLifetimeDailyFan input - therefore retention can be set to sevenDays. Notice that in this case you won't have access for hourly results, even for report purposes.

Specific value: "sevenDays"