Hierarchical Value Service API  future
api index

ScaleStructure Object

since: 0.29
Defines the scale configuration and scale breaks used to compute scaled values during the evaluation process. The scale structure is associated with a particular Record in a table, and is used to scale values associated with that record. The actual scale is contained in ScaleBreak objects contained in the ScaleStructure.scale element of this structure.

Fields

type
0.29optional
string
The type of scale threshold contained in the scale breaks in this structure. There are three valid scale threshold types available, QUANTITY (default), VOLUME, and REVENUE.
  • The QUANTITY scale threshold type specifies that the threshold value in the associated scale breaks is a scalar value that will be compared against the supplied threshold value to determine the offsets to apply to the base value in order to obtain the scaled value. The threshold value to be compared should also be a scalar value, and the ScaleStructure.currency field and ScaleStructure.units field should not be set in the structure.
  • The VOLUME scale threshold type specifies that the threshold value in the associated scale breaks is a value with units that will be compared against the supplied threshold value to determine the offsets to apply to the base value in order to obtain the scaled value. If the threshold value to be compared has units, then the ScaleStructure.units should be set to a valid unit as well. The ScaleStructure.currency field should not be set.
  • The REVENUE scale threshold type specifies that the threshold value in the associated scale breaks is a value with a currency that will be compared against the supplied threshold value to determine the offsets to apply to the base value in order to obtain the scaled value. If the threshold value to be compared has a currency, then the ScaleStructure.currency should be set to a valid currency as well. The ScaleStructure.units field should not be set.
0.29 valid values:
  • QUANTITY
  • VOLUME
  • REVENUE
0.29 default value: QUANTITY
offsetType
0.29optional
string
The type of scale offset contained in the scale breaks in this structure. There are two valid scale offset types available, NUMERIC (default) and PERCENT.
  • The NUMERIC offset type specifies that the offset in the associated scale breaks is a numeric value that will be added directly to the base value in order to obtain the scaled value. If the base value to be transformed has a currency, then the ScaleStructure.offsetCurrency should be set to a valid currency as well.
  • The PERCENT offset type specifies that the offset in the associated scale breaks is a numeric percentage that will be multiplied by the base value in order to obtain the scaled value. The offset will be treated as a scalar value.
0.29 valid values:
  • NUMERIC
  • PERCENT
0.29 default value: NUMERIC
calcType
0.29optional
string
The type of calculation used to compute scaled values with this structure. There are two valid calculation types available, CUMULATIVE (default) and GRADUATED.
  • The CUMULATIVE calculation type specifies that the scale break that has a threshold value less than or equal to the specified threshold value is the only one used in the calculation of the scaled value.
  • The GRADUATED calculation type specifies that all scale breaks that have a threshold value less than or equal to the specified threshold value are used to compute the scaled value.
0.29 valid values:
  • CUMULATIVE
  • GRADUATED
0.29 default value: CUMULATIVE
units
0.29optional
string
The units used for the scale break thresholds in this structure, if applicable. This is only used if the ScaleStructure.type is VOLUME.
currency
0.29optional
string
The currency used for the scale break thresholds in this structure, if applicable. This is only used if the ScaleStructure.type is REVENUE.
offsetCurrency
0.29optional
string
The currency used for the scale break offsets in this structure, if applicable. This is only used if the ScaleStructure.offsetType is NUMERIC.
scale
0.29optional
array of ScaleBreak
The scale breaks contained in this scale structure as a list of ScaleBreak structures. If this list is empty or null, then the values are unscaled.
0.29 min length: 0

Related API Objects

Example - Example scale structure 1

    {
        "type": "QUANTITY",
        "offsetType": "NUMERIC",
        "calcType": "CUMULATIVE",
        "currency": "USD",
        "scale":[
            { "threshold": 0, "offset": 0 },
            { "threshold": 10, "offset": -10 },
            { "threshold": 20, "offset": -20 }
        ]
    }

Example - Example 1 with no defaults specified

    {
        "currency": "USD",
        "scale":[
            { },
            { "threshold": 10, "offset": -10 },
            { "threshold": 20, "offset": -20 }
        ]
    }

Example - Scale metadata

    {
        "type": "VOLUME",
        "offsetType": "PERCENT",
        "calcType": "GRADUATED"
    }