Metrics

Purpose of Metrics

Metrics in the Timvero platform are used to calculate business indicators for entities such as application participants (Participant), collaterals (Collateral), and other objects implementing the HasMetric interface. The results of these calculations are used in the following scenarios:

• Participant or application assessment

  For example, calculating disposable income, debt-to-income ratio, age, and other derived values.

• Usage in business logic

  Metrics are integrated into decision-making rules, offer calculation (OfferEngine), covenant checks, and UI display.

• Centralization and logic reuse

  A metric is defined once and can be reused across multiple parts of the system without duplication.

• Flexible configuration

  Metrics are configured through the UI. The calculation logic is written in JavaScript and linked to a specific entity type.

• Transparency and control

  All metrics can be viewed, edited, and tested through the interface. The result of execution can be checked using the Evaluate button.

Metrics are a key element for building transparent and scalable decision-making logic in TimveroOS.

Creating a Metric in the Interface

To add a new metric, follow these steps:

1. Navigate to the Metric section

In the navigation menu, open the Metric section. Click the Create button or the “+” icon in the list of metrics.

2. Define the main parameters

• Metric Name – a unique name for the metric. It is used for referencing the metric (e.g., metrics.get(...)).

• Entity Type – select the type of entity for which the metric will be calculated (e.g., Participant, Collateral, etc.).

3. Write the metric script

In the editor, use JavaScript to define the calculation logic. The following are supported:

• Access to values defined in Field Mapping via features.get(...)

• Access to the entity itself via entity

• Platform utilities like Math, Temporal, etc.

Example script:

function calcDisposableIncome() {
    const income = entity.totalIncome;
    const outgoings = entity.totalOutgoings;
    return income - outgoings;
}
calcDisposableIncome();

Example of a Configured Metric in the UI

4. Configure data sources (Field Mapping)

If the metric uses features.get(...), you need to define the mapping between model fields and logical names:

• Go to the Field Mapping tab

• Open the data source (e.g., Application Data Source)

• Add field mappings, for example:

totalIncome     →     participant.totalIncome  
totalOutgoings  →     participant.totalOutgoings

Screenshot of a Field Mapping Configuration Example

Example Metric Script

function calcDisposableIncome() {
    const income = features.get("applicationDataSource", "totalIncome");
    const outgoings = features.get("applicationDataSource", "totalOutgoings");
    return income - outgoings;
}
calcDisposableIncome();

Screenshot of a Configured Metric

5. Test the Metric

Click the Evaluate button to run the metric on test data and verify that the calculation works correctly.

6. Save the Metric

Click Save to store the metric and make it available for use in other components of the platform.

Data Sources and Metric Evaluation

Data Sources

Metric logic in Timvero is written in JavaScript and executed in the context of a specific business entity. The following data sources are available during execution:

1. features.get(...)

Allows you to retrieve values explicitly mapped via Field Mapping.

const income = features.get("applicationDataSource", "totalIncome");

• The first argument (applicationDataSource) is the name of the data source (e.g., the application participant).

• The second argument (totalIncome) is the logical field name defined in the Field Mapping section of the UI.

features.get(...) is used to isolate the script from model changes and enables flexible reuse of metric logic.

2. Entity parameters (entity)

The metric script also has access to the entity itself (e.g., participant, collateral) and its fields.

Example:

return entity.totalIncome - entity.totalOutgoings;

Example Use Case: disposableIncome in Offer Calculation

The disposableIncome metric (available income) is used in business rules during offer generation in the Offer Engine module.

Example of a script used in an Offer Engine rule:

const disposableIncome = metrics.get("disposableIncome");

• disposableIncome — the result of a metric calculation

  When the rule is executed:

  • The platform retrieves the value of the disposableIncome metric

  • The result is used in the formula to calculate the available credit limit

  • The calculated value is stored within the rule execution and influences the final offer

  📌 Note: Using metrics.get("disposableIncome") allows a single calculation to be reused across all products and applications without duplicating logic.

✅ Testing a Metric Script Using the Evaluate Button

The metric editor in Timvero allows you to test a script before saving it using the Evaluate button.

How to Test a Script

1. Select the entity type in the Entity Type field — for example, Participant, Collateral, Credit, etc.

2. In the Test data section, find the specific entity you want to test the metric on.

   You can start typing its ID or other parts of its description — such as application status or name — and the system will suggest available options.

3. Write the script in JavaScript in the editor.

4. Click the Evaluate button to the right of the editor.

5. The result of execution will appear in the Output section at the bottom, including:

   • Timestamp of execution

   • Result of the calculation (number, string, object, etc.)

What is Available in the Script

The following variables are available inside the metric script:

Example

features.get("applicationDataSource", "totalIncome");

Output:

19:41:05:
60 000

HasMetric Interface

All entities for which a metric can be calculated must implement the HasMetric interface. This is a marker interface that allows the platform to identify objects that support metric evaluation.

Interface Signature

public interface HasMetric extends Serializable {
    Long getId();
    EntityType getEntityType();
}

• getId() — the unique identifier of the entity.

• getEntityType() — the type of the entity (e.g., PARTICIPANT, COLLATERAL). This is used to match the Entity Type parameter in the metric UI.

Example Implementations

• Application Participant (Participant):

public class Participant implements HasMetric {
    private Long id;
    private BigDecimal totalIncome;
    private BigDecimal totalOutgoings;
    private Integer age;


    @Override
    public Long getId() {
        return id;
    }


    @Override
    public EntityType getEntityType() {
        return EntityType.PARTICIPANT;
    }
}

Collateral:

public class Collateral implements HasMetric {
    private Long id;
    private MonetaryAmount marketValue;

    @Override
    public Long getId() {
        return id;
    }
    
    public MonetaryAmount getMarketValue() {
        return marketValue;
    }


    @Override
    public EntityType getEntityType() {
        return EntityType.COLLATERAL;
    }
}

Purpose

The HasMetric interface is used in the platform as a universal contract for all entities whose metrics can be calculated. This allows the system to centrally invoke the getMetric(...) method without knowing the exact class of the object.

Metric Display Tabs

To display calculated metrics for entities such as Participant, Collateral, etc., the platform uses specialized UI tabs. These are implemented through the HasMetricAnchoredMetricTab abstraction.

Purpose

The tabs are designed to:

• Display calculated metrics for a specific entity

• Trigger recalculation if needed

• Provide a clear and transparent interface for working with metrics

Base Interface: HasMetricAnchoredMetricTab

public interface HasMetricAnchoredMetricTab<T extends HasMetric> extends EntityElementTab<T> {
    @Override
    default String getTabLabel() {
        return "Metrics";
    }


    @Override
    default TabLocation getTabLocation() {
        return TabLocation.RIGHT;
    }
}

• The interface requires the implementation of a tab for entity T, which must implement HasMetric.

  Example Implementations

For an application participant: ParticipantAnchoredMetricTab

@RequestMapping("/anchored-metrics")
@Controller
@Order(3500)
public class ParticipantAnchoredMetricTab extends HasMetricAnchoredMetricTab<Participant> {

}

For collateral: CollateralAnchoredMetricTab

@RequestMapping("/anchored-metrics")
@Controller
@Order(3500)
public class CollateralAnchoredMetricTab extends HasMetricAnchoredMetricTab<Collateral> {

}

UI Behavior

The tab is automatically displayed on the entity’s detail page if it implements HasMetric.

Users can view a list of all calculated metrics and their values.

Values are updated when a calculation is performed or after a manual recalculation.