Show a number with a metric block

Before you start

• Create a dashboard and choose who sees it

A metric block shows one value with a label, such as the number of open purchase orders. The value is a Smart ScriptSmart ScriptBeezr's scripting language (engine name Beezl) used in fields, rules, filters, workflow values and dashboards.Open glossary ↗, so you can count, add up or work out any figure the data allows. This page builds two metrics and shows how to keep them from breaking on an empty result.

Add a metric block

1. Open the dashboard in the Page builder.
2. Add a section if the page has none: click a layout, for example Thirds, under Sections.
3. Under Blocks, drag Metric into an empty cell, or click Add block in the section and choose Metric.
4. In the right panel, type the Label, for example Open purchase orders.
5. In Value, write the script. The next section shows two.
6. Click Run test to see the result.
7. Click Save.

○ ○ ○Beezr

×

Label is plain text, or a label key such as ${info.customers} that follows the viewer’s language.
Value is the Smart Script editor. It has line numbers and keeps long lines in view.
Run test runs the script now and shows what it returned.
Width is how many of the section’s columns the block spans.

The panel has two tabs. Content holds the label, the value and the width. Style holds the look.

How do I write the value script?

Four rules cover most mistakes. They come from how the script engine runs your code.

• The last expression is the value. End the script with total;.
• getCurrentValue() gives text. Even a number comes back as a string. Convert with parseFloat or parseInt before you add.
• Clauses start with WHERE and use the full table.field name, such as cm_purchase_orders.status.
• Loops use .forEach. The lists are Java lists, not plain arrays.

A count

This counts open purchase orders. evaluateCount returns text, and an empty text if the call fails, so the script converts it and falls back to 0.

var open = parseInt(FunctionManager.evaluateCount("cm_purchase_orders", "WHERE cm_purchase_orders.status = 'Open'"), 10);
isNaN(open) ? 0 : open;

A total, with a guard

This adds up the amount of every open purchase order. It checks the list before the loop, and each amount before the sum.

var orders = FunctionManager.loadRecordsByClause("cm_purchase_orders", "WHERE cm_purchase_orders.status = 'Open'");
var total = 0;
if (orders) {
  orders.forEach(function (order) {
    var amount = parseFloat(order.getFieldValueMap().get("total_amount").getCurrentValue());
    if (!isNaN(amount)) {
      total = total + amount;
    }
  });
}
total;

loadRecordsByClause returns null, not an empty list, when nothing matches. That is why if (orders) is there. Without it, an app with no open orders would show an error where a 0 belongs.

Tip from a Beezr Consultant

For sums and averages, use FunctionManager.evaluateSumFunction("total_amount", "cm_purchase_orders", "WHERE ...") or evaluateAverageFunction. They calculate on every matching record and return "0" when nothing matches.

Which helper should I use?

Press Ctrl + Space in the editor to suggest modules, fields and functions. Type FunctionManager. first to list the helpers.

○ ○ ○Beezr

×

The editor opens in a larger window from the expand button on the script box.
Suggestions list the helpers with their arguments.
Done closes the large editor. Your script is already saved to the block.

Helper	Returns
evaluateCount(module, clause)	The number of matching records, as text
evaluateSumFunction(field, module, clause)	The total of a field, as text, or "0"
evaluateAverageFunction(field, module, clause)	The average of a field, as text, or "0"
loadValueByClause(field, module, clause)	The field value of the first match, or an empty text
loadRecordsByClause(module, clause)	A list of records, or null
loadRecordsByClauseSortable(module, clause, orderField, orderType)	The same, in an order
getSubListFromContext(module, listField)	The rows of a list field on the current record

How do I test it?

Click Run test. The result appears under the button:

• “Returned 12 in 140 ms” means the script ran.
• “The script is empty. Write an expression that returns a value.” means Value has nothing in it.
• “The script didn’t run and would show as text. Check the module and field names.” means the engine handed your text back unchanged. Check the spelling of the module and field names.
• A red message with the engine’s own error means the script failed. Read it for the line and the reason.

How do I change how it looks?

On the Style tab, pick a Look: Card, Soft, Bee or Dark. Icon adds an image , and Custom colors and type opens the fine settings.

What did I get?

A metric on the dashboard that shows a live figure and a 0 when there is nothing to count. People see the new value the next time they open the dashboard.