Margin Shortfall Agent (Reference)

The Margin Shortfall Agent identifies customers from transactions with significant revenue but suboptimal margins, also called margin shortfall.

List of Required Fields

The following table lists the set of transaction fields required for the Margin Shortfall Agent to compute its metrics and detection rules. Ensure these fields or equivalent are available and consistently populated in your source Transaction Datamart before deploying the Agent. Those exact field names are not required, but a similar fields with that data is required.

Definition

Series (1 Revenue and Margin by Customer and Product Group)

Group By

Measures

Filters

The filter configuration constrains the dataset to recent transactions and to those whose aggregated prices surpass a defined minimum level.

• Retains only transactions with an invoice date within a recent, configurable period.

• Excludes records with zero or missing invoice price, margin, product group, or quantity.

• Ensures that only transactions with complete and meaningful data are analyzed, supporting accurate and consistent results.

Example

(Invoice Date >= custom N months ago 3 (08/09/2025)) AND (Invoice Price > 0) AND (Margin is not null) AND (Product Group is not null) AND (Quantity > 0) 

Summary Table

• Customer Id – The top-level grouping dimension selected in the Group By definition.

• Customer Name – The customer name shown for readability within each grouped row.

• Product Group – A grouping dimension from the Transaction Datamart used to organize rows by product hierarchy.

• Customer Segment – Customer Segment is included as the Level 4 grouping dimension.

• Revenue – The aggregated sum of invoice price for all included transactions (per the relevant period/series).

• Profit – The aggregated gross margin (difference between realized price and cost).

• Avg Margin % – The weighted gross margin rate.

• Revenue Rank – The customer’s position when customers are sorted by revenue contribution within the selected group.

• Margin Rank – The customer’s position when customers are sorted by margin rate or margin contribution within the selected group.

Series 2 (Avg Margin by Product Group)

Group By

Measures

Filters

Example

(Invoice Date >= custom N months ago 3 (08/09/2025)) AND (Invoice Price > 0) AND (Margin is not null) AND (Product Group is not null) AND (Quantity > 0)

Summary Table

Join Series (Join Series)

Definition

Set up the relationship between the series by mapping the matching data columns/dimensions that you would like to include in the definition.

Summary Table

• Margin Variance – The difference between a customer’s average margin percentage and the relevant benchmark.

• Margin Lift Potential – The potential profit uplift per customer and product group if their margin rate were improved to the midpoint between their current margin percentage and the product group average.

• Margin Lift Potential Pct – The potential profit uplift (percentage) per customer and product group if their margin rate were raised to the product group average.

• Suggested Margin Rate – The recommended target margin percentage for a customer and product group, calculated as the midpoint between the customer’s current average margin percentage and the product group average margin percentage.

• Reference Margin Rate – The benchmark margin percentage for a product group, calculated as the weighted average gross margin rate across all transactions within that product group for the selected period.

• Revenue Uplift – The potential profit uplift per customer and product group if their margin rate were improved to the midpoint between their current average margin percentage and the product group average margin percentage.

Detection Rules

Detection Rules defines the Agent’s alert conditions and includes scheduling. When conditions are met, actions are triggered during the next Agent run.

This Detection Rule defines a minimum‑margin policy. It flags any evaluated row in the selected series where the weighted gross margin rate falls below a configured threshold, indicating margin underperformance.

Default thresholds are flexible, adjust as necessary.

Example

(RevenueRank > 0.8) AND (MarginRank < 0.2) AND (MarginLiftPotentialPct > 0.05) AND (MarginLiftPotential > 0)

Schedule

Set the preferred start date and frequency that you want the Agent to run.

Example

Start Date – The date when the scheduled task will run for the first time.
Period – Period which represents the offset between each run.
Interval – Interval which represents the number of repetitions in a selected period. Allowed characters are 0-9. 0 means one-off run.

Action Definition

Example

Similar Case Handling

• Period – Defines the time period between potential similar action. Similar case will not be recreated before the defined period. Time unit for the duplicate-prevention window.

• Interval – Number of periods between similar actions. Similar case will not be recreated before the defined interval. Prevents creating a very similar case for the same context within the defined interval.

Example

Prevents creating a very similar case for the same context within a 3-month period.

Impact Calculation

You can define specific metrics to compute the foreseen impact of the actions. Please only use total absolute value (and not relative values) as those metrics will be aggregated.

Impact Definition

Summary

Review the setup of the Agent, here you can see all the set parameters in one place.

If you are happy with the setup, click Submit for Approval. Once the Agent is approved, it becomes active and starts monitoring your data based on the schedule.