Setting up Calculations

Calculations (historically called certificates) let Dataforce ASAP compute values for the products on an appointment - certificates created, energy saved, rebates, co-payments and similar figures - and optionally turn the result into a discount on the customer’s quote or invoice.

This guide explains how the calculator works, then walks through building a new calculation from scratch. Each step links to the detailed page for the screen involved.

How the calculator works

Every calculation is performed per product, per appointment. For each Calculation Type, each eligible product is processed as follows:

1. Start with the product’s base value. This comes from the product’s Calculations (Certificates) tab, using the Calculation Zone that matches the appointment’s suburb. A product with no base value configured starts at 0.

2. Apply each Modifier Group in priority order. For each group, the calculator works out which of the group’s Modifiers apply (see below), multiplies all of their multiplier values together, and adds all of their modifier values together. It then applies the group to the running result:

   result = result × (combined multiplier) + (combined modifier)
3. Repeat for the next group. Groups are applied sequentially, each to the output of the previous group - the calculator does not use mathematical order of operations. Brackets in a formula are represented by giving each bracket its own group and ordering the groups by priority.
4. Multiply by quantity. The per-unit result is multiplied by the product’s quantity.
5. Round and cap. Rounding configured on the calculation type is applied to the stored results (at activity, area or appointment level), and the calculation cap (if any) limits the final primary result.
6. Apply the discount (if the calculation type has a discount type set): the primary result is multiplied by the discount rate, and for Point of Sale discounts the amount is applied to the job balance.

A modifier only participates in a group when all of the following hold:

• It is picked up for the appointment - either its group is Mandatory, or the modifier is linked to a question answer that was selected on the appointment.
• Its zone restriction (if set) matches the zone used for the product’s base value.
• Its customer type restriction (if set) matches the job’s customer.
• The appointment’s activity date falls inside its Valid From / Valid To range (if set).
• Every attached Modifier Condition passes.

The building blocks

What makes a calculation appear on an appointment

Before any figures show on the job calculations tab, all of these must be true:

1. A product is attached to the appointment (or linked automatically through question answers).
2. The product’s activity is linked to the calculation type on the Activities screen (Step 5). This is the master switch - if the activity is not linked, the calculation is skipped entirely for that product.
3. The property’s suburb resolves to a calculation zone that is valid for the calculation type (or the type has a global zone).
4. The product has a base value for that type and zone - or a base value of 0 plus at least one modifier that adds a value (a multiplier alone cannot produce a result from a base of 0).
5. The relevant modifiers are picked up - through a Mandatory group or a selected question answer.

The troubleshooting section below turns this into a checklist.

Step-by-step setup

Step 1: Create the Calculation Type

Create the type on the Calculation Types screen. Decide up front:

• Calculation Run Order - determines both list ordering and the order the calculator processes types. If this calculation will read another calculation’s result (see advanced topics), it must have a higher run order than the calculation it reads.
• Dual Calculation - tick it if you need a secondary result alongside the primary (e.g. primary = certificates, secondary = energy).
• Discount settings - discount type (Point of Sale / Delayed / none), rate, GST and presentation options. These can be revisited later.

Step 2: Create the Zone Type and Zones

Zones let the same product carry different base values depending on where the property is (e.g. climate zones). Create a Calculation Zone Type, then create the Calculation Zones inside it.

Step 3: Link the zones to the Calculation Type

Either tick the zones in the calculation type’s Zone(s) field, or tick the calculation type in each zone’s Calculation Type(s) field - both edit the same link.

Step 4: Assign suburbs to zones

On the Suburbs screen, place each suburb in the correct zone. A suburb can hold one zone of each zone type. Skip this step for global zones.

Step 5: Link the Activity to the Calculation Type

1. Navigate to (Configuration icon) Activities.
2. Open the activity whose products should be calculated.
3. In Calculation Zone Type(s), tick the entry for your calculation type / zone type combination.
4. Save the activity.

Products take part in calculations through their activity, so this is the step that switches the calculation on. Only one zone type can be selected per calculation type on an activity.

Step 6: Set the product base values

On the Product Register, open each product and use its Calculations (Certificates) tab to enter the base value for each zone. The grid shows a column for every zone in the zone type selected in Step 5.

Products with no value entered use a base value of 0 - this is normal when the whole result is built up by modifiers, but remember that at least one modifier must add a value in that case.

Step 7: Create the Modifier Groups

Create the Modifier Groups and link each one to the calculation type. Think of each group as one bracket of the formula:

• Priority sets the order the brackets are applied.
• Valid for Product Category restricts a group to products in specific categories - leave it empty to apply to every product.
• Mandatory applies every modifier in the group automatically, without question answer links.
• Min/Max multiplier and modifier, Max Count and Rounding Method put guard rails around the group’s combined values.

Step 8: Create the Modifiers

Create the Modifiers inside each group. For each one choose:

• Where its multiplier and modifier values come from - a fixed value, a question answer, a product attribute, the product quantity, or another calculation’s result.
• The operation - multiplication or division, addition or subtraction.
• Whether it affects the primary, secondary or both results (Modifier Type).
• Any restrictions: zone, customer type, valid dates, and conditions.

Step 9 (optional): Create Modifier Conditions

If a modifier should only apply in certain circumstances (an answer above a threshold, a product attribute in a range, another calculation’s result over a limit), create the rules on the Calculation Modifier Conditions screen and attach them to the modifier under Additional Condition(s). Every attached condition must pass.

Step 10: Link modifiers to question answers

For every modifier that is not in a mandatory group, attach it to the question answer(s) that should trigger it. When that answer is selected on an appointment, the modifier joins the calculation. An answer can trigger several modifiers.

Step 11: Test the calculation

1. Create a test job/appointment in a suburb belonging to one of your zones.
2. Attach a product from the linked activity (answer the linking questions, or add it manually).
3. Save the questions, then open the job’s Calculations tab.
4. Use the calculation breakdown to drill into each product - it shows exactly which modifier groups and modifiers were applied and with what values, which makes configuration mistakes easy to spot.

Making rule changes over time

When a scheme changes its factors from a given date, do not edit modifier values in place - that would change the result of historical appointments the next time they recalculate. Instead:

1. Set Valid To on the outgoing modifiers to the day before the change.
2. Create replacement modifiers with Valid From set to the changeover date.

The calculator picks modifiers using the appointment’s activity date (its expected installation date, falling back to the scheduled date), so appointments before the changeover keep using the old factors and later appointments use the new ones - even when recalculated.

Advanced topics

Dual calculations

Ticking Dual Calculation on the calculation type adds a secondary result with its own name, units, term and format. Each modifier’s Modifier Type controls which result it affects: Base applies to both, Primary Calculation / Secondary Calculation to one only. Only the primary result drives discounts.

Using one calculation’s result in another

A modifier’s value (or a condition’s test) can come from another calculation type’s result:

• By Product - the other calculation’s per-unit result for the same product.
• By Area - the other calculation’s subtotal for the same question block/area.
• By Appointment - the other calculation’s total for the whole appointment.

The referenced calculation must run before the one using it - give it a lower Calculation Run Order on the Calculation Types screen.

Rounding and caps

Rounding exists at two levels:

• Modifier group rounding rounds the group’s combined multiplier and modifier before they are applied.
• Calculation type rounding rounds the stored result (per activity, per area or for the whole appointment depending on configuration).

The Calculation Cap on the type limits the final primary result, and can be overridden per job from the calculations tab. Calculation Limit is separate - it does not change the result, it makes Runabout warn (soft) or block completion (hard) when the result exceeds the limit.

Customer types

Modifiers can be restricted to Residential or Business customers. Combined with valid dates and zones this often removes the need for duplicate modifier groups.

Troubleshooting

No calculation appears on the appointment at all:

1. Is the product’s activity linked to the calculation type? (Configuration Activities, Calculation Zone Type(s) - see Step 5.)
2. Is the property’s suburb assigned to a zone of that zone type (Suburbs), or is there a global zone?
3. Is the zone linked to the calculation type (Calculation Zones)?
4. Has the appointment been recalculated since the configuration change? (Save the questions or use Recalculate.)

A calculation appears but the value is wrong or zero:

1. Open the calculation breakdown and check which modifier groups and modifiers actually applied.
2. If a modifier is missing: check its question answer link, group Mandatory flag, zone, customer type, valid dates and conditions.
3. If everything multiplies out to 0: the base value is probably 0 with no additive modifier - see Step 6.
4. If the value is unexpectedly capped or rounded: check the group’s min/max limits and rounding, and the calculation type’s cap and rounding method.
5. If a modifier that reads another calculation returns 0: check the run order of the two calculation types.

Where to Next?