Configuration properties

The Ratings cube is configured through Spring Boot configuration properties under the prefix atoti.solution.model.cubes.ratings. Default values are applied when a property is omitted. The data load source uses the prefix atoti.solution.data-load.ratings. Prerequisites: Familiarity with Spring Boot externalized configuration (application.yml or application.properties).

Ratings cube

Enables the counterparty scorecard model. Prefix: atoti.solution.model.cubes.ratings

Property	Type	Default	Description
`enabled`	`Boolean`	`true`	Enables or disables the Ratings cube. When `false`, neither the cube schema nor its data loading topics or aliases are registered. When `true`, the cube also needs at least one `rating-components` entry and a grading factory (`IGradingFactory`) the application registers, or startup fails. The cube is enabled by default when `ratings-cube-starter` is on the classpath; see Setup and start.
`rating-components`	`List`	`[]`	The rating components the cube runs. See Rating components.

Rating components

Configures the rating components the Ratings cube grades, aggregates and scores. The Internal Rating adds the score of every component, each multiplied by the total weight of that component. The solution ships no rating component and no grading factory: an application declares them, as in the example under How to add a rating component. Prefix: atoti.solution.model.cubes.ratings.rating-components

rating-components is empty unless an application configures it, and an empty list fails startup with “Ratings rating-components configuration is empty, so the cube rates nothing. Configure at least one rating component, or set atoti.solution.model.cubes.ratings.enabled to false.” The list is the whole rating methodology: a component is in the cube only if it is in the list.

rating-components is a list. Each entry configures one rating component:

Property	Type	Default	Description
`method`	`String`	(required)	The rating method a metric declares to be graded by this component. Names the component’s published measures, for example `Metric Rating (Acme.StewardshipGrading)`. Matched against the `RatingMethod` column of the `Metrics` extract; see Metrics.
`value`	`String`	`Ratings.PeriodAverage`	Plugin key of the `IMetricValueFactory` that reads the value the component grades. The solution provides two keys. `Ratings.PeriodAverage` grades the average of a metric’s observations in each reporting period, weighted across periods by period weight. `Ratings.LatestValue` grades the latest value on or before the Scorecard Date.
`grading`	`String`	(required)	Plugin key of the `IGradingFactory` that grades the component’s metrics. Several rating components can name the same `grading` key. Each has its own `method`, and they can differ in their `steps`.
`steps`	`List`	`[]`	The aggregation the component’s ratings run through, in order. An empty list selects the standard route. Metric ratings average by metric weight within a category. Category ratings then average by category weight within a scorecard.

Each entry of steps configures one step of the chain:

Property	Type	Default	Description
`stage`	`String`	(required)	Plugin key of the aggregation rule that runs the step, for example `Ratings.MetricAggregation` or `Ratings.CategoryAggregation`.
`weight`	`String`	(required)	Name of the measure the step’s weighted average weights by, for example `Aggregation Metric Weight` or `Category Weight`.
`levels`	`List\<String\>`	`[]`	The levels whose members the step averages over. At least one level is required; a step with an empty list fails startup. Each entry is a level description of the form `level@hierarchy@dimension`. Escape a literal `@` or `/` in a name with a leading `/`.

What does the standard aggregation route do?

A component that states no steps runs the standard two-step route. Written out explicitly, that route is:

steps:
  - stage: Ratings.MetricAggregation
    weight: Aggregation Metric Weight
    levels:
      - "Metric ID@Metric ID@Metric"
  - stage: Ratings.CategoryAggregation
    weight: Category Weight
    levels:
      - "Category@Category@Metric"

A component states its own steps when its ratings roll up differently. An application might average metric ratings directly to the scorecard level, weighted by metric weight, and skip the category step. The component’s score then takes its share of the Internal Rating from the metric weights. The CategoryWeight of a category still declares that share: the load warns where the metric weights of a category do not total its CategoryWeight, or where the category weights of a scorecard do not total 1.

How to add a rating component

To add a rating component, append an entry to the list. The following example declares two components. Acme.StewardshipGrading runs the standard route. Acme.AssessmentGrading reads the latest value and states its own single step. Both grading keys name factories that the example application registers:

atoti:
  solution:
    model:
      cubes:
        ratings:
          rating-components:
            - method: Acme.StewardshipGrading
              value: Ratings.PeriodAverage
              grading: Acme.StewardshipGrading
            - method: Acme.AssessmentGrading
              value: Ratings.LatestValue
              grading: Acme.AssessmentGrading
              steps:
                - stage: Ratings.MetricAggregation
                  weight: Aggregation Metric Weight
                  levels:
                    - "Scorecard@Scorecard@Ratings Attributes"
                    - "Metric ID@Metric ID@Metric"

Acme.StewardshipGrading states no steps, so it runs the standard route. Its value is the default, so the line could be left out. For the IGradingFactory implementation a grading key selects, the IMetricValueFactory a value key selects, and how to register them, see Rating components.

What does the cube validate?

A rating-components configuration is checked at two points: before the cube is built, and when data loads.

Before the cube is built. An empty rating-components list fails startup before the cube is built. A pre-flight check then validates every configured component. It checks that each component’s value key resolves to a registered IMetricValueFactory, and that each component’s grading key resolves to a registered factory. It checks that each step’s stage key resolves to a registered IAggregationStageFactory: the three shipped stages, Ratings.PeriodAggregation, Ratings.MetricAggregation and Ratings.CategoryAggregation, implement it, and a custom stage factory must implement it too. It checks that each step has at least one entry in levels, and that no two components declare the same method. It checks that each step’s levels entries resolve to one of the cube’s own levels. A level description parses without being checked for existence. A well-formed but wrong level is caught here, not silently ignored. Every problem across every component is reported together in one failure, naming the legal values beside it.
An unrecognized weight measure. This happens within the same pre-flight check, but never fails it: it only warns. A step’s weight names a measure resolved at build time, against whatever the cube ends up publishing. A client’s own stage can legitimately weight by a measure it publishes itself. The product cannot treat its own two weight measures as the only valid answers. A typo still shows up in the log, naming the solution’s weight measures.
At data load. A RatingMethod value that no configured component’s method matches produces a warning, naming the configured methods. Those metrics rate nothing. The rest of the scorecard still renders.
Lookup table rows at data load. The solution does not check the rows of a lookup table. An application that declares one checks its rows itself.
Lookup table declarations at startup. A lookup table declared through IRatingsConfigurer fails startup when it is declared twice, or named like a table already in the database or a topic of the Ratings cube. It also fails when its channel name is already taken by a channel of the Ratings cube or by another lookup table, such as Metric_Targets beside MetricTargets. It also fails when a field is named like a key field or declared twice, when publish names a field the table does not declare, when a vector field has no element, when inMetricCategory is set on a table not keyed on METRIC, or when map is given no mapper or no output type. See How to add a lookup table.
Weights at data load. The load logs a warning for each scorecard whose category weights do not total 1, and for each category whose metric weights do not total its CategoryWeight. It does not fail.
MetricWeight at data load. A metric with no MetricWeight while another metric of the same RatingMethod on the same scorecard has one produces a warning, since it counts with a weight of 1. The load does not fail.
Category at data load. On a scorecard, a category that holds metrics of more than one RatingMethod fails the load, since MIXED_RATING_METHODS is a fatal check. Every metric of that category is reported. Only metrics whose RatingMethod matches a configured component’s method are compared. The same category name on another scorecard can use another rating method.

Ratings data load source

Selects where the Ratings data is read from. Applies to the Ratings cube only. Prefix: atoti.solution.data-load.ratings

Property	Type	Default	Description
`type`	`DataLoadSourceType (CSV \| JDBC)`	`CSV`	Source the Ratings topics read from. `CSV` declares the solution’s extract topics and the `RATINGS_LOAD` and `RATINGS_UNLOAD` aliases over them. `JDBC` declares none of them, leaving the topics to the application; a request naming either alias skips it with a warning. The channels are declared either way, so an application targets them by name through `IRatingsCubeChannels`, including `lookupTable(tableName)` and `limitsTable(tableName)` for the tables an application declares. Any other value fails the startup rather than booting an application that silently loads nothing.

As-of-date data load

Controls what is loaded and unloaded for a single as-of date, and which dates are loaded on startup. The properties are available to an application that imports AsOfDateDataLoadConfiguration. Prefix: atoti.solution.data-load.as-of-date

Property	Type	Default	Description
`topics`	`List\<String\>`	`[]`	The topics each as-of-date request loads. Add `RATINGS_LOAD`, the alias this solution declares over the Ratings cube’s topics.
`unload-topics`	`List\<String\>`	unset	The topics each as-of-date request unloads. Add `RATINGS_UNLOAD`. No Ratings topic is as-of-date scoped: the historical series, the static referentials, the scorecard configuration and the counterparty set are all refreshed by wholesale reloads, and the unload condition of their channels never matches. A date unload therefore removes no Ratings data.
`initial-dates.enabled`	`Boolean`	`true`	When `true`, the application triggers a data load for each date in `initial-dates.dates` at startup.
`initial-dates.dates`	`Set\<LocalDate\>`	`[]`	Set of as-of dates to load on startup (ISO format, e.g. `2024-01-15`).
`controller.enabled`	`Boolean`	`true`	When `false`, the `/activeviam/as-of-date/rest/v1` REST endpoints are not registered.

For how these properties drive loading, see Data loading.

Limit methods

Configures the limit methods the Ratings cube publishes a capacity for. A limit method is a list of bounds, and the capacity under it is the smallest of them. The solution ships no limit method and no bound factory: an application declares them. Prefix: atoti.solution.model.cubes.ratings.limit-methods limit-methods is a list, empty by default. With an empty list the cube publishes no limit measure. Each entry configures one limit method:

Property	Type	Default	Description
`method`	`String`	(required)	The name of the limit method. Matched against the `LimitMethod` column of the `RelationshipTypes` extract; see Relationship types. Names the method’s published measures, for example `Limit Capacity (LineOnly)`.
`bounds`	`List\<String\>`	(required)	The bound keys the method is bounded by. Each is the plugin key of an `ILimitBoundFactory`. At least one is required. The capacity is the smallest of the bounds, and has no value if any bound has no value.

What do limit methods look like?

The following example declares two methods. LineOnly is bounded by a credit line reported per counterparty. CappedLine adds a ceiling set per relationship type, so one bound is shared by two methods:

atoti:
  solution:
    model:
      cubes:
        ratings:
          limit-methods:
            - method: LineOnly
              bounds: [Acme.CreditLine]
            - method: CappedLine
              bounds: [Acme.CreditLine, Acme.TypeCeiling]

For the bound factories, the limits tables they read and the measures the cube publishes, see Limit capacity.

What does the cube validate for limit methods?

Before the cube is built. Startup fails when a method has no name, when two methods have the same name, when a method declares no bounds, when a method repeats a bound, or when a bound key matches no ILimitBoundFactory registered globally or for the Ratings cube. Every problem is reported together, with the legal bound keys beside it.
When a limits table is declared. Startup fails when a table is declared twice, named like a table already in the database or a topic of the Ratings cube, or when its channel name is already taken. It also fails when a field is named like one of the table’s own dating fields (EffectiveDate for EFFECTIVE, ReportingDate or CounterpartyId for REPORTED) or declared twice.
At data load. With at least one method configured, the load logs a warning, and does not fail, for a LimitMethod value that names no configured method.
When a bound reads a limits table. The cube fails to start when the dating fields plus keys are not exactly the table’s key fields, or when the table has no such field.
When the limits date level is chosen. With readLimitsAt, startup fails when two configurers choose different levels, when the Ratings cube has no such level, when a field that is not a LocalDate feeds the level, or when no field feeds it, as for a computed or analysis hierarchy. See Choose the date limits tables are read at.
At query time. A bound that returns a value that is not a number fails the query with an error naming the bound key and the method.

Example configuration

The following example shows an application.yml configuration for the Ratings cube, loading from CSV extracts:

atoti:
  solution:
    model:
      cubes:
        ratings:
          rating-components:
            - method: Acme.StewardshipGrading
              value: Ratings.PeriodAverage
              grading: Acme.StewardshipGrading
    data-load:
      ratings:
        type: CSV
      as-of-date:
        topics:
          - RATINGS_LOAD
        unload-topics:
          - RATINGS_UNLOAD
        initial-dates:
          enabled: true
          dates:
            - 2024-01-15

Acme.StewardshipGrading is a grading factory that the application registers; see Rating components.

​Ratings cube

​Rating components

​What does the standard aggregation route do?

​How to add a rating component

​What does the cube validate?

​Ratings data load source

​As-of-date data load

​Limit methods

​What do limit methods look like?

​What does the cube validate for limit methods?

​Example configuration

​Related pages