Create a New Metric

Metrics represent values, states, dates, locations, or calculated results used throughout INTERA.

Examples include:

• Current Balance;
• Monthly Revenue;
• Open Tickets;
• Service Availability;
• Payment Status;
• Current Position;
• Days Until Expiry;
• Product Health.

A Metric may receive data from one or more Integrations, use other Metrics as inputs, apply calculations or logical conditions, and produce a final value for dashboards, triggers, scripts, and reconciliation rules.

This chapter explains how to create and configure a new Metric.

Open the Metrics Page #

To create a new Metric:

1. Open Settings.
2. Select Metrics.
3. Click New or Create Metric.

The Metrics page shows the Metric definitions available in your INTERA environment.

Depending on your permissions, you may be able to:

• create new Metrics;
• edit existing Metrics;
• duplicate Metrics;
• review their data sources;
• configure thresholds;
• manage synchronization;
• disable or archive Metrics.

Set the Metric Name #

Enter a clear name that describes what the Metric represents.

Good examples include:

• Outstanding Balance;
• Monthly Sales;
• Average Ticket Resolution Time;
• Active Service Count;
• Last Position Update;
• Supplier Amount Due;
• Product Health.

Avoid names that are too broad or unclear.

Poor examples include:

• Value;
• Result;
• Total;
• Status;
• Data;
• Metric 1.

The name should remain meaningful when shown next to an Asset.

For example:

Acme Ltd — Outstanding Balance

is clearer than:

Acme Ltd — Amount

A Role package may later provide a different display name for the same Metric, but the main Metric name should still be clear and reusable.

Set the Metric Type #

Select the Metric Type.

The Metric Type determines:

• what kind of value the Metric returns;
• how the value is validated;
• how it can be displayed;
• which calculations are available;
• which settings are required;
• how widgets and rules can use it.

Common Metric Types include:

• Number;
• Currency;
• Percentage;
• Boolean;
• Status;
• Date;
• Date and Time;
• Duration;
• Text;
• Coordinates;
• Composite;
• Metric Health.

Choose the Type based on the meaning of the final result, not only the format of the source data.

For example:

• use Currency for a bank balance;
• use Percentage for service availability;
• use Duration for average response time;
• use Status for paid, unpaid, or overdue;
• use Coordinates for vessel position;
• use Metric Health for a normalized weighted health score.

Define the Metric #

A Metric can be defined in either:

• the visual designer;
• YAML.

Both methods configure the same underlying Metric definition.

Visual Designer #

The visual designer allows you to build the Metric step by step.

You can add elements such as:

• Integration data;
• other Metrics;
• calculations;
• filters;
• summary operations;
• logical operators;
• conditional branches;
• result formatting.

The visual designer is normally the easiest option for common Metric definitions.

It is useful when:

• the Metric has a simple or medium-complexity calculation;
• you want to inspect the flow visually;
• the Metric is maintained by non-developers;
• you want to reduce syntax errors.

YAML Definition #

YAML provides direct access to the complete Metric definition.

It is useful when:

• the Metric is complex;
• you need precise control;
• you want to copy or reuse configuration;
• the Metric is part of a Role package;
• you are comfortable working with structured configuration.

A simplified Metric definition may look like this:

name: Outstanding Balance
type: currency
currency: EUR

sources:
  - integration: accounting
    datasource: customer_invoices
    filters:
      payment_status:
        in:
          - unpaid
          - overdue
    result:
      field: outstanding_amount
      operation: sum

The exact YAML structure depends on the available Metric schema and installed Integration.

You can move between the visual designer and YAML where supported. Changes made in one view should be reviewed before saving in the other.

Add Auto-Synchronized Data from an Integration #

Most automatically updated Metrics receive data from an Integration.

To add Integration data:

1. Click Add Source.
2. Select Integration Data.
3. Choose the Integration.
4. Select a DataSource.
5. define the required filters;
6. choose the result field;
7. choose the operation or summary method;
8. review the expected result.

Select an Integration #

Choose the connected Integration that provides the required information.

Examples include:

• accounting system;
• billing platform;
• CRM;
• banking API;
• network platform;
• navigation system;
• ticketing system.

Only active Integrations available to your environment can be selected.

Select a DataSource #

An Integration may provide several DataSources.

For example, an accounting Integration may provide:

• invoices;
• payments;
• customers;
• suppliers;
• account balances.

A billing Integration may provide:

• active services;
• usage;
• charges;
• subscriptions;
• products.

Select the DataSource that contains the required data.

The DataSource defines:

• available fields;
• supported filters;
• supported time parameters;
• possible result types;
• synchronization behaviour.

Set Filters #

Filters restrict which records are included in the Metric calculation.

Examples include:

• unpaid invoices only;
• active services only;
• selected products;
• a specific customer;
• current billing period;
• invoices due before today;
• selected vessels;
• a particular region.

A filter may use:

• a fixed value;
• an Asset field;
• a dashboard context;
• a package Time Context;
• another Metric;
• a user-selected parameter.

For example:

filters:
  customer_id:
    from_asset_field: external_customer_id

  payment_status:
    in:
      - unpaid
      - overdue

  invoice_date:
    from_time_context: current_period

Use only filters supported by the selected DataSource.

Choose the Result Field #

Select the field that should be returned or summarized.

Examples include:

• invoice amount;
• outstanding amount;
• transaction count;
• service status;
• ticket duration;
• latitude;
• longitude;
• last update timestamp.

The result field must be compatible with the Metric Type.

For example:

• a Currency Metric should normally use a numeric monetary field;
• a Date Metric should use a date field;
• a Status Metric should use a status or mapped text field;
• a Coordinates Metric may require both latitude and longitude.

Choose an Operation or Summary #

When the DataSource returns multiple records, define how INTERA should produce one Metric value.

Common operations include:

• Sum;
• Count;
• Average;
• Minimum;
• Maximum;
• First;
• Last;
• Latest;
• Distinct Count;
• Percentage;
• Difference.

Examples:

• sum all unpaid invoice amounts;
• count all open tickets;
• calculate average resolution time;
• use the latest vessel position;
• find the oldest overdue date;
• count distinct active customers.

For example:

result:
  field: outstanding_amount
  operation: sum

Choose an operation that matches the business meaning of the Metric.

Do not use Sum only because the source field is numeric. Some numeric values should be averaged, counted, or selected by latest timestamp.

Add More Synchronized Data #

A Metric may use more than one Integration source.

For example, a cash availability Metric may use:

• bank balance from a Banking Integration;
• expected collections from Accounting;
• supplier liabilities from ERP.

To add another source:

1. Click Add Source.
2. Select the required Integration and DataSource.
3. configure filters and result settings;
4. assign a clear internal source name;
5. include the source in the final calculation.

Example:

sources:
  - id: bank_balance
    integration: banking
    datasource: accounts
    result:
      field: current_balance
      operation: sum

  - id: expected_collections
    integration: accounting
    datasource: invoices
    filters:
      status:
        in:
          - unpaid
          - overdue
    result:
      field: outstanding_amount
      operation: sum

Each source should represent one clear input.

Add Other Metrics #

A Metric may use existing Metrics as inputs.

This is useful for:

• derived Metrics;
• totals;
• ratios;
• comparisons;
• health calculations;
• reusable business logic.

For example:

Available Cash =
Bank Balance
+ Expected Collections
- Supplier Payments

Instead of rebuilding each source inside the new Metric, you may reuse the existing Metrics:

• Bank Balance;
• Expected Collections;
• Supplier Payments.

In YAML, this may appear as:

metrics:
  - id: bank_balance
    metric: bank_balance

  - id: expected_collections
    metric: expected_collections

  - id: supplier_payments
    metric: supplier_payments

Reusing Metrics makes configuration easier to maintain and keeps calculations consistent.

Do not reuse an existing Metric when its business meaning is different, even if the values appear similar.

Combine Integration Data and Other Metrics #

A single Metric may combine:

• synchronized data;
• existing Metrics;
• fixed values;
• Asset fields;
• time parameters;
• calculated expressions.

For example, a Product Risk Metric may use:

• current sales from billing;
• overdue collections from accounting;
• open support tickets from a ticketing Integration;
• target sales from an Asset field.

This allows a Metric to represent a broader operational result rather than one direct source field.

Use Mathematical Operations #

You can apply mathematical operations to source values and other Metrics.

Common operations include:

• addition;
• subtraction;
• multiplication;
• division;
• percentage calculation;
• absolute value;
• rounding;
• minimum;
• maximum.

Example:

formula:
  subtract:
    - metric: invoiced_amount
    - metric: collected_amount

Another example:

formula:
  divide:
    - metric: resolved_tickets
    - metric: total_tickets

When using division, define how INTERA should handle a zero denominator.

Use Logical Operators #

Logical operators allow the Metric to evaluate conditions and choose different results.

Common logical operators include:

• AND;
• OR;
• NOT;
• IF;
• ELSE;
• SWITCH;
• greater than;
• less than;
• equal to;
• not equal to;
• contains;
• is empty;
• is unavailable.

For example:

formula:
  if:
    condition:
      greater_than:
        - metric: total_amount
        - value: 100
    then:
      divide:
        - metric: total_amount
        - value: 3
    else:
      metric: total_amount

This definition means:

• if the total is greater than 100, divide it by 3;
• otherwise, use the original total.

AND and OR Conditions #

Use AND when all conditions must be true.

Example:

condition:
  and:
    - greater_than:
        - metric: overdue_amount
        - value: 50000
    - greater_than:
        - metric: overdue_days
        - value: 30

Use OR when any condition may be true.

Example:

condition:
  or:
    - equals:
        - metric: sync_status
        - value: error
    - equals:
        - metric: integration_status
        - value: disabled

Keep logical expressions as simple as possible.

If a definition becomes difficult to understand, split it into several reusable Metrics.

Use IF Conditions #

An IF condition returns one value when the condition is true and another when it is false.

Example:

formula:
  if:
    condition:
      less_than:
        - metric: service_availability
        - value: 99
    then:
      value: warning
    else:
      value: healthy

This is useful for:

• status classification;
• fallback values;
• conditional calculations;
• exception handling.

Use SWITCH Conditions #

A SWITCH condition is useful when several possible outcomes exist.

Example:

formula:
  switch:
    - when:
        less_than:
          - metric: health_score
          - value: 50
      result: critical

    - when:
        less_than:
          - metric: health_score
          - value: 80
      result: warning

    - default: healthy

Use SWITCH when there are several ordered conditions.

For simple ranges, Metric thresholds may be easier to maintain.

Set Synchronization Options #

By default, a Metric normally uses the synchronization settings defined by its Integration.

You may override these settings when the Metric requires different behaviour.

Possible synchronization options include:

• update frequency;
• synchronization schedule;
• manual-only refresh;
• live request;
• retry policy;
• timeout;
• stale-data limit;
• historical range;
• time zone;
• incremental or full synchronization.

To override the Integration default:

1. Open Synchronization Options.
2. Enable Use Custom Settings.
3. configure the required options;
4. save the Metric.

Update Frequency #

Choose how often the Metric should update.

Examples include:

• every 5 minutes;
• hourly;
• daily;
• once per billing period;
• manually;
• when requested.

Use a frequency appropriate for the data.

Examples:

• network availability may update frequently;
• accounting balances may update hourly or daily;
• monthly sales may update once per day;
• contract expiry dates may update daily.

More frequent updates may increase load on the Integration and external system.

Stale-Data Limit #

The stale-data limit defines how old a value can become before INTERA marks it as delayed or out of date.

For example:

sync:
  stale_after: 2h

A Metric may still show its last valid value while also displaying a stale-data status.

Set the limit according to the expected update frequency.

A daily Metric should not normally be marked stale after ten minutes.

Retry and Error Behaviour #

Depending on the Metric, you may configure:

• number of retries;
• retry interval;
• use of the previous valid value;
• error status;
• fallback result;
• notification behaviour.

For example, if synchronization fails, INTERA may:

• keep the previous value;
• mark the Metric with a synchronization warning;
• return no value;
• use a defined fallback;
• trigger an alert.

Error handling should be visible and should not make outdated data appear current.

Set Metric Thresholds #

Thresholds divide Metric values into named ranges or states.

They are commonly used to show:

• Healthy;
• Warning;
• Critical;
• Low;
• Normal;
• High;
• Overdue.

For example:

thresholds:
  - name: healthy
    min: 90

  - name: warning
    min: 70
    max: 89.99

  - name: critical
    max: 69.99

Thresholds can be used by:

• dashboard widgets;
• status indicators;
• triggers;
• scripts;
• notifications;
• health calculations.

Define Threshold Direction #

Some Metrics are better when the value is higher.

Examples:

• service availability;
• collection rate;
• completion percentage.

Other Metrics are better when the value is lower.

Examples:

• overdue amount;
• error count;
• response time;
• unresolved incidents.

Make sure the threshold direction reflects the business meaning.

For example, an availability value of 99.9% may be Healthy, while an overdue ratio of 99.9% would be Critical.

Avoid Overlapping Thresholds #

Threshold ranges should not overlap.

Poor example:

• Warning: 50–80;
• Critical: 70–100.

A value of 75 would match both ranges.

Use clear non-overlapping ranges and define behaviour for values outside them.

Thresholds for Status Metrics #

Status Metrics may map specific values instead of numeric ranges.

Example:

thresholds:
  - value: paid
    status: healthy

  - value: not_ready
    status: warning

  - value: not_paid
    status: critical

This allows widgets and triggers to treat status values consistently.

Metric Health #

The metric_health Type produces a normalized health score from one or more input Metrics.

It is typically represented on a scale such as:

0–100%

A Metric Health definition requires:

• input Metrics;
• normalization rules;
• weights;
• missing-data behaviour;
• final thresholds.

Set Normalization #

Normalization converts different input Metrics into a common health scale.

For example:

• Service Availability may already be a percentage;
• Open Ticket Count is a number;
• Overdue Amount is a currency;
• Sync Status is a status value.

Before combining them, each input must be converted into a comparable health score.

A normalized result normally uses:

• 100 for fully healthy;
• 0 for fully unhealthy;
• intermediate values for partial health.

Example:

normalization:
  service_availability:
    method: direct_percentage

  overdue_amount:
    method: range
    healthy_at: 0
    critical_at: 100000
    reverse: true

In this example:

• higher availability produces better health;
• higher overdue amount produces worse health.

Normalization Methods #

Possible normalization methods include:

Direct Percentage #

Use the source percentage directly.

Example:

• Availability: 98% becomes health 98.

Range #

Convert a value between a healthy and critical boundary.

Example:

• 0 open incidents = health 100;
• 20 open incidents = health 0;
• values between them are scaled.

Threshold Mapping #

Convert existing threshold states into health values.

Example:

• Healthy = 100;
• Warning = 60;
• Critical = 0.

Boolean Mapping #

Convert true and false into scores.

Example:

• backup completed = 100;
• backup not completed = 0.

Status Mapping #

Assign scores to named statuses.

Example:

• Paid = 100;
• Not Ready = 50;
• Not Paid = 0.

Set Weights #

Weights define how much each input Metric contributes to the final health score.

Example:

weights:
  service_availability: 0.50
  overdue_amount: 0.30
  open_tickets: 0.20

The total weight should normally equal:

1.00

or:

100%

Use higher weights for factors that have greater business importance.

Do not assign weights only based on the size or units of the source value. Weights represent importance, not magnitude.

Example Metric Health Definition #

name: Product Health
type: metric_health

inputs:
  - id: sales_performance
    metric: sales_performance
    weight: 0.40
    normalization:
      method: direct_percentage

  - id: overdue_collections
    metric: overdue_collections
    weight: 0.35
    normalization:
      method: range
      healthy_at: 0
      critical_at: 50000
      reverse: true

  - id: support_tickets
    metric: open_support_tickets
    weight: 0.25
    normalization:
      method: range
      healthy_at: 0
      critical_at: 20
      reverse: true

thresholds:
  - name: healthy
    min: 80

  - name: warning
    min: 50
    max: 79.99

  - name: critical
    max: 49.99

Missing Inputs in Metric Health #

Define what should happen when one input Metric is unavailable.

Possible options include:

• exclude the missing input and recalculate remaining weights;
• use the last valid value;
• assign a neutral score;
• assign a critical score;
• mark the entire Metric Health as unavailable.

Choose the behaviour based on the business risk.

For example, missing service-availability data may itself be a serious problem and should not automatically receive a neutral score.

Other Metric Type-Specific Settings #

Different Metric Types require different configuration.

Number #

For a Number Metric, you may configure:

• unit;
• decimal places;
• minimum and maximum allowed values;
• rounding;
• aggregation.

Examples:

• Active Customers;
• Open Tickets;
• Data Usage;
• Inventory Quantity.

Currency #

For a Currency Metric, configure:

• currency;
• decimal precision;
• exchange-rate behaviour;
• whether mixed currencies are allowed;
• rounding rules.

Do not sum values in different currencies unless a conversion rule is defined.

Percentage #

For a Percentage Metric, define:

• whether source values use 0–1 or 0–100;
• decimal precision;
• minimum and maximum;
• threshold direction.

For example, 0.95 may represent 95%, depending on the source format.

Boolean #

For a Boolean Metric, configure:

• true label;
• false label;
• optional icons;
• optional status mapping.

Example:

• True: Completed;
• False: Not Completed.

Status #

For a Status Metric, define the allowed values.

Example:

values:
  - ready
  - not_ready
  - blocked

You may also define:

• display names;
• order;
• status severity;
• icons;
• transitions.

Date and Date-Time #

For Date and Date-Time Metrics, configure:

• source time zone;
• display format;
• handling of missing dates;
• whether past or future values are expected.

These Metrics may also be converted into derived values such as:

• Days Until Expiry;
• Days Overdue;
• Time Since Last Update.

Duration #

For Duration Metrics, define:

• source unit;
• display unit;
• rounding;
• formatting.

For example, a source may return seconds while the dashboard displays hours and minutes.

Text #

For Text Metrics, configure:

• maximum length;
• fallback value;
• allowed values where appropriate;
• case handling;
• formatting.

Text Metrics should be used carefully because they are harder to aggregate and compare than structured Status Metrics.

Coordinates #

For Coordinates Metrics, define:

• latitude source;
• longitude source;
• coordinate system;
• validity range;
• timestamp source.

Coordinates may be displayed on maps and used for location-based rules.

Composite #

A Composite Metric contains several related values.

Examples include:

• Current, 30-day, and 60-day overdue balances;
• Minimum, Average, and Maximum response time;
• Actual, Target, and Variance.

For a Composite Metric, define each component separately:

components:
  - id: current
    type: currency

  - id: overdue_30
    type: currency

  - id: overdue_60
    type: currency

Use a Composite Metric when the values belong together and are normally displayed or processed as one result.

Manual Metrics #

A Metric may be configured for manual input.

For example:

• Commission Paid;
• Document Approved;
• Audit Completed;
• Operational Readiness.

For a manual Metric, configure:

• input Type;
• allowed values;
• default value;
• entry permissions;
• timestamp;
• optional comment;
• change history.

Manual Metrics may be displayed in widgets that open a data-entry form.

Link the Metric to Asset Types #

After defining the Metric, select the Asset Types to which it may apply.

Examples:

• Outstanding Balance linked to Customer;
• Current Balance linked to Bank Account;
• Fuel Consumption linked to Vessel;
• Monthly Sales linked to Product.

A Metric may be linked to more than one Asset Type only when the business meaning remains consistent.

The same Metric definition may then produce a separate value for each Asset.

Validate the Metric #

Before saving, use Validate, Preview, or Test where available.

Validation may check:

• YAML syntax;
• required fields;
• DataSource availability;
• filter validity;
• result-field compatibility;
• Metric Type compatibility;
• formula correctness;
• threshold ranges;
• circular Metric dependencies;
• synchronization settings.

A preview may show:

• returned source records;
• intermediate values;
• final result;
• threshold status;
• errors or warnings.

Avoid Circular Dependencies #

A Metric must not depend on itself, directly or indirectly.

For example:

Metric A uses Metric B
Metric B uses Metric A

This creates a circular dependency and cannot be calculated reliably.

When reusing several Metrics, review the dependency chain before saving.

Save the Metric #

After completing the configuration:

1. review the name and Type;
2. validate the data sources;
3. review formulas and logical operators;
4. check synchronization settings;
5. confirm thresholds;
6. confirm Asset Type links;
7. click Save.

The new Metric will then appear in the Metrics list.

Depending on its configuration, it may calculate immediately or wait for the next synchronization.

Review the First Result #

After saving the Metric, check:

• the returned value;
• the linked Asset;
• the timestamp;
• the data source;
• the threshold status;
• the synchronization status;
• the error state;
• any normalized or intermediate values.

If the result is incorrect, inspect each source and formula step separately.

Common Problems #

No Data Returned #

The filters may be too restrictive, the selected period may contain no records, or the Asset may not be mapped to the Integration.

Review:

• filters;
• time period;
• Asset identifiers;
• DataSource result preview.

Wrong Result #

Check:

• the selected result field;
• the operation;
• source units;
• currency;
• date range;
• mathematical formula.

Metric Does Not Update #

Check:

• Integration status;
• synchronization schedule;
• custom sync settings;
• DataSource availability;
• stale-data rules.

Threshold Status Is Incorrect #

Check:

• threshold direction;
• range boundaries;
• overlapping ranges;
• source scale.

For example, verify whether the Percentage source uses 0.95 or 95.

Metric Health Appears Too High or Too Low #

Review:

• normalization rules;
• reverse scoring;
• weights;
• missing-input behaviour;
• input Metric values.

YAML Cannot Be Saved #

Use validation to check:

• indentation;
• field names;
• unsupported operators;
• missing required values;
• invalid references.

Recommended Design Process #

When creating a Metric:

1. define the business meaning;
2. choose the final Metric Type;
3. identify the required data sources;
4. add filters and time context;
5. choose the correct result operation;
6. reuse existing Metrics where appropriate;
7. add calculations and logical conditions;
8. configure synchronization;
9. define thresholds;
10. configure Type-specific settings;
11. link the Metric to Asset Types;
12. validate and preview the result;
13. save and test with real data.

Start with the business question the Metric must answer.

Do not begin with an available database field and create a Metric only because the data exists.