> For the complete documentation index, see [llms.txt](https://knowledge.maica.com.au/maica-release-notes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledge.maica.com.au/maica-release-notes/client-delivery/version-0.162.md).
# Version 0.162
Client Delivery V0.162 introduces two enhancements and six fixes. The headline changes are **Travel Quantities Committed at Two Decimal Places**, **The Kilometre Travel Cap Now Applies**, and **Leave Cancellation Only Cancels Work That Has Not Been Delivered or Billed**. The remaining fixes cover Support at Home units of measure, Check-Out without Check-In, Total Committed calculation, and Schedule End validation on recurring Appointments.
{% hint style="warning" %}
Three entries in this release require post-install steps: the kilometre travel cap, travel quantity rounding for orgs using the Unit Price ratio calculation base, and Support at Home units of measure. See [Post-Install Steps](#post-install-steps) before the upgrade reaches your users.
{% endhint %}
## Installation Information
Use the buttons below to install the latest version of **Maica Client Delivery** into the appropriate Salesforce org type. Select the link that matches your environment using the Buttons below.
{% hint style="info" %}
We always recommend installing the package into a **Sandbox** first to validate the release before deploying to **Production**. If you're unsure which option to select, please contact **Maica Support**.
{% endhint %}
**Production & Developer Edition Orgs**: Production URL
**Sandbox & Scratch Orgs:** Sandbox URL
{% hint style="success" %}
If you are on a Journey Agreement with us, your Account Manager will connect with you to organise the upgrade.
{% endhint %}
## At a glance
| Headline | Type | Area |
| ------------------------------------------------------------------------------ | ----------- | ------------------ |
| **Leave Cancellation Only Cancels Work That Has Not Been Delivered or Billed** | Enhancement | Service Agreements |
| **Total Committed Calculation Completes Reliably on Large Data Volumes** | Enhancement | Billing |
| **Travel Quantities Committed at Two Decimal Places** | Fix | Travel Management |
| **The Kilometre Travel Cap Now Applies** | Fix | Billing |
| **Support at Home Hours Now Calculate a Quantity** | Fix | Appointments |
| **Check-Out Only Available After Check-In** | Fix | Appointments |
| **End Agreement No Longer Recalculates Total Committed Across the Org** | Fix | Service Agreements |
| **Schedule End Validation No Longer Blocks Whole-Series Edits** | Fix | Appointments |
## Enhancements
### Leave Cancellation Only Cancels Work That Has Not Been Delivered or Billed
**Reference:** CC-761
We have updated Service Agreement Leave so that cancelling deliveries for a leave period only affects work that is still planned and unbilled. Previously, Delivery Activities that had already been delivered, were under review or had been billed could be swept up by the cancellation.
**What's changed**
* Only Delivery Activities with a status of **Planned**, a Billing Status other than **Generated**, and no Invoice Line Item are cancelled.
* Delivered, under review or billed work is left exactly as it is.
* Cancellation is limited to deliveries that belong to the leave's own Service Agreement, or that have not yet been costed against any Agreement Item.
* A leave's **End Date** now covers the whole of that day. Previously, deliveries scheduled later on the End Date were missed.
**Example scenarios**
* ✅ A Service Agreement has leave from Monday to Friday. A Planned, unbilled delivery on Wednesday → the delivery is cancelled.
* ✅ A delivery within the leave period has already been billed → it is left unchanged.
* ✅ A participant has two Service Agreements and leave is recorded against one → deliveries under the other Service Agreement are unaffected.
* ✅ A delivery is scheduled for the afternoon of the leave End Date → it is cancelled along with the rest of the leave period.
***
### Total Committed Calculation Completes Reliably on Large Data Volumes
**Reference:** CC-679
We have reworked how the Total Committed calculation saves its results so that large volumes of Agreement Items no longer cause Agreement Item triggers to fail partway through the scheduled job.
**What's changed**
* Agreement Item updates produced by the calculation are now saved in a lighter-weight way, in system mode, so the follow-on rollups stay within platform limits.
* The calculation no longer carries its full working list between processing chunks.
**Example scenarios**
* ✅ The scheduled Total Committed calculation runs against an org with a high volume of Agreement Items and Invoice Line Items → the job completes without trigger failures.
## Fixes
### Travel Quantities Committed at Two Decimal Places
**Reference:** CC-742
We have updated Travel Management so that billable travel quantities are committed to exactly two decimal places when the Delivery Activity is created. Previously, travel quantities were stored at full precision while displaying as two decimals, so an Invoice Line Item could show a quantity and unit price that did not multiply to the displayed line total.
**What's changed**
* Time-based and kilometre travel quantities are rounded to two decimal places once, from the unrounded total, using the same rounding the platform already applied to service quantities.
* A participant's share of travel that rounds to 0.00 no longer creates a Delivery Activity. For example, a one-minute leg split at a 10% share now produces no travel line.
* A pre-set Delivery Activity quantity, including one created by an integration or data load, is normalised to two decimal places when it is costed.
* Travel Delivery Activities now always store the participant's share as the **Quantity**, billed at the full unit price. This includes Agreement Items using the **Unit Price** ratio calculation base. The previous arrangement, which stored the whole trip as the Quantity and the participant's share as the Quantity Delivered, has been retired.
* Adding a participant to an existing Appointment no longer copies the travel line to them.
* Existing Delivery Activities and Invoice Line Items are not restated. Amounts already invoiced and claimed stay as they are.
**Example scenarios**
* ✅ A 20-minute travel leg → a Quantity of 0.33.
* ✅ A 40-minute combined travel charge → a Quantity of 0.67, and the Line Total reconciles to Quantity multiplied by Unit Price.
* ✅ 40 km of travel split across three participants → 13.34, 13.33 and 13.33, which total 40.00.
* ✅ A travel quantity of exactly 20.00 km against a 20.00 km cap → billed at 20.00 and no longer clamped by a hidden fraction.
{% hint style="warning" %}
**Post-install step required for orgs using the Unit Price ratio calculation base.** See [Travel Quantity Repair](#travel-quantity-repair) under Post-Install Steps.
{% endhint %}
***
### The Kilometre Travel Cap Now Applies
**Reference:** CC-749
We have updated the invoice flow so that a configured kilometre travel cap is enforced. Previously, the cap check could never match kilometre travel, so a participant could be billed beyond their kilometre cap with nothing to stop it and no warning. The time-based travel cap was not affected.
**What's changed**
* Both travel cap decisions in the invoice flow no longer depend on the Delivery Activity's claim type. The Time Based and Non Time Based checkboxes decide which cap applies.
* A blank travel cap now means the cap is off. An explicit cap of **0** means no travel is billable and the line is written at zero quantity.
* Travel lines above a configured cap now bill at the cap rather than at the full distance, from this release onwards.
**Example scenarios**
* ✅ A 10 km cap is configured and 12 km of travel is recorded → the line bills at 10.00 km.
* ✅ Exactly 10.00 km is recorded against a 10 km cap → billed in full.
* ✅ No travel cap is configured → travel bills in full.
* ✅ A service line that is not travel carries the travel claim type and exceeds the cap values → billed in full.
{% hint style="warning" %}
**Post-install step required.** See [Kilometre Travel Cap](#kilometre-travel-cap) under Post-Install Steps.
{% endhint %}
***
### Support at Home Hours Now Calculate a Quantity
**Reference:** CC-641
We have updated Appointment costing so that Support at Home units of measure are understood when calculating the Delivery Activity Quantity. Previously, an Appointment Service carrying the Support at Home unit **Hours** left the calculated Quantity at zero, and the Quantity had to be typed in by hand.
**What's changed**
* Support at Home units are mapped into the Appointment Service vocabulary: **Hours** is treated as **Hourly**, and **Item**, **Bill**, **Voucher**, **Meal** and **Trip** are treated as **Each**.
* The mapping is applied when quantities are calculated, when Support Item units roll up to the Appointment Service, in the Appointment service helper, and in the new client note steps.
* The Support Item **Quantity Unit Of Measure** field now includes the values Item, Hours, Bill, Voucher, Meal and Trip.
**Example scenarios**
* ✅ An Appointment Service uses the Support at Home unit **Hours** → the Delivery Activity Quantity is calculated from the Appointment duration.
* ✅ An Appointment Service uses **Meal** or **Trip** → it is treated as **Each**.
{% hint style="warning" %}
**Post-install steps required.** See [Support at Home Units of Measure](#support-at-home-units-of-measure) under Post-Install Steps.
{% endhint %}
***
### Check-Out Only Available After Check-In
**Reference:** CC-722
We have updated the Appointment Check-Out action so that a Resource must have checked in before they can check out. Previously, a Resource could check out without checking in, which meant their Appointment Resource record was never marked as checked out and the Appointment stayed **In Progress** permanently.
**What's changed**
* Check-Out is now offered for a Resource only when they have checked in and have not yet checked out.
* Users with the **Check In/Out on behalf of Others** permission can still check out other Resources.
* This applies to both the Appointment and the Planner.
**Example scenarios**
* ✅ A Resource has checked in → the Check-Out action is available, and the Appointment completes once every Resource has checked out.
* ✅ A Resource has not checked in → the Check-Out action is not offered.
***
### End Agreement No Longer Recalculates Total Committed Across the Org
**Reference:** CC-757
We have updated End Agreement so that the Total Committed calculation only runs for the Service Agreement being ended. Previously, ending a Service Agreement that had no Agreement Items caused the calculation to run across every Agreement Item in the org.
**What's changed**
* A calculation scoped to a Service Agreement or Agreement Items now processes nothing, rather than everything, when no matching Agreement Items are found.
**Example scenarios**
* ✅ A Service Agreement with no Agreement Items is ended → no org-wide recalculation is started.
* ✅ A Service Agreement with Agreement Items is ended → only its own Agreement Items are recalculated.
***
### Schedule End Validation No Longer Blocks Whole-Series Edits
**Reference:** CC-765
We have updated the recurring Appointment schedule so that the Schedule End date no longer blocks edits applied to the whole series.
**What's changed**
* When editing the master Appointment, the earliest selectable Schedule End is still the end of the Appointment.
* When editing any other Appointment in the series, the earliest selectable Schedule End is now the schedule's own Start Date.
**Example scenarios**
* ✅ A Coordinator edits a later occurrence of a recurring Appointment and applies the change to the whole series → the Schedule End date can be saved without a validation error.
## Post-Install Steps
### Kilometre Travel Cap
#### Prerequisites
* Client Delivery package version **0.162** or later installed
* System Administrator profile or equivalent permissions, with access to Flows in Setup
{% stepper %}
{% step %}
#### Update your own copy of the Invoice Flow
`Maica_Invoice_Flow` is shipped as a template, so every existing org runs its own copy and this fix does **not** reach it on upgrade. Without the steps below, the kilometre travel cap stays unenforced in your org.
Open your org's copy of the invoice flow and make the same four edits to it:
1. In the decision **Is Travel and over the Chargeable Travel Cap**, remove the condition that compares the Delivery Activity's **Claim Type** with the Travel Setting's **Travel Claim Type**.
2. In the time-based counterpart decision, remove the same Claim Type condition.
3. In both cap formulas, change the comparison to `>= 0`.
4. In both cap formulas, change the fallback value from `0` to `9999999`.
Save as a new version and activate it.
{% endstep %}
{% step %}
#### Check for travel caps set to exactly zero
Under this change, a travel cap of exactly **0** means no travel is billable, and the line is written at zero quantity with no error. If a cap of 0 was intended to mean unlimited, clear the field instead.
{% endstep %}
{% step %}
#### Tell customers with a configured kilometre cap
The kilometre cap begins to apply from this release. Travel lines above the cap will bill at the cap rather than at the full distance. It is worth checking whether any participant has previously been billed beyond a kilometre cap.
{% endstep %}
{% endstepper %}
***
### Travel Quantity Repair
#### Prerequisites
* Client Delivery package version **0.162** or later installed
* Required only for orgs where Agreement Items use the **Unit Price** ratio calculation base **and** unbilled travel Delivery Activities exist from before the upgrade
* System Administrator profile or equivalent permissions, with access to Execute Anonymous Apex
{% stepper %}
{% step %}
#### Understand what needs repairing
Before this release, travel on the Unit Price ratio calculation base stored the whole trip as the **Quantity** and the participant's share as the **Quantity Delivered**. From this release, travel always stores the share as the Quantity. Unbilled travel Delivery Activities created in the old arrangement are not rewritten by the upgrade. Until they are repaired, each bills at its stored Quantity, which is the whole trip, so repair them **before the next invoice run**.
Delivery Activities and Invoice Line Items that have already been billed are never restated.
{% endstep %}
{% step %}
#### Run the report script
Request the two repair scripts referenced to **CC-742** from Maica. Run the **report** script first in **Setup > Developer Console > Debug > Open Execute Anonymous Apex Window**. It changes nothing. It lists every unbilled travel row still in the old arrangement, with either a proposed rewritten quantity or the reason it needs a person to decide, such as a lone row, no chargeable travel remaining, or a group that does not fit the trip.
Review the list with the customer and record any quantities they want to override.
{% endstep %}
{% step %}
#### Run the fix script
The fix script rewrites the rows the report marked for rewrite, plus any overrides the customer chose, and writes a before and after CSV. Before running it:
1. Deactivate the validation rule **Prevent Quantity Update When Completed** on Delivery Activity for the duration of the run. The script names the rule and refuses to write while it is still active.
2. Make sure no invoice run or Total Committed job is running. The script will not run alongside either.
Both scripts run in chunks. Re-run each until its log reports that nothing remains. Reactivate the validation rule when finished.
{% endstep %}
{% endstepper %}
***
### Support at Home Units of Measure
#### Prerequisites
* Client Delivery package version **0.162** or later installed
* Required for every org using Support at Home
* System Administrator profile or equivalent permissions, with access to Setup and Execute Anonymous Apex
{% stepper %}
{% step %}
#### Add the Support at Home values to the Support Item picklist
New picklist values on a field that already exists in your org do not always arrive with a package upgrade. In **Setup > Object Manager > Support Item > Fields & Relationships > Quantity Unit Of Measure**, add any of these values that are missing, with the API name and label identical: **Item**, **Hours**, **Bill**, **Voucher**, **Meal**, **Trip**. Values your org already added by hand can stay as they are.
Do **not** add them to the Appointment Service picklist, which keeps the Maica values.
{% endstep %}
{% step %}
#### Export the current Appointment Service values
Before running the script, export the following so the previous values can be recovered:
```sql
SELECT Id, maica__Quantity_Unit_Of_Measure__c FROM maica__Appointment_Service__c WHERE maica__Quantity_Unit_Of_Measure__c IN ('Hours','Item','Bill','Voucher','Meal','Trip')
```
{% endstep %}
{% step %}
#### Correct existing Appointment Services
The upgrade corrects an Appointment Service only on its next Support Item change, so run this once in **Setup > Developer Console > Debug > Open Execute Anonymous Apex Window** to fix existing records now. It only changes recognised Support at Home values, so it is safe to re-run.
```apex
Integer ROW_CAP = 10000;
List toFix = [
SELECT Id, Name, maica__Quantity_Unit_Of_Measure__c
FROM maica__Appointment_Service__c
WHERE maica__Quantity_Unit_Of_Measure__c IN ('Hours', 'Item', 'Bill', 'Voucher', 'Meal', 'Trip')
LIMIT :ROW_CAP
];
Map unitMap = new Map{
'hours' => 'Hourly',
'item' => 'Each',
'meal' => 'Each',
'trip' => 'Each',
'voucher' => 'Each',
'bill' => 'Each'
};
List toUpdate = new List();
Integer skipped = 0;
for (maica__Appointment_Service__c svc : toFix) {
String current = svc.maica__Quantity_Unit_Of_Measure__c;
String mapped = String.isBlank(current) ? null : unitMap.get(current.trim().toLowerCase());
if (mapped == null || mapped == current) {
skipped++;
continue;
}
svc.maica__Quantity_Unit_Of_Measure__c = mapped;
toUpdate.add(svc);
}
Integer succeeded = 0;
Integer failed = 0;
if (!toUpdate.isEmpty()) {
for (Database.SaveResult sr : Database.update(toUpdate, false)) {
if (sr.isSuccess()) {
succeeded++;
} else {
failed++;
System.debug(LoggingLevel.ERROR, 'Update failed: ' + sr.getErrors()[0].getMessage());
}
}
}
System.debug('Selected=' + toFix.size() + ', Skipped=' + skipped + ', Succeeded=' + succeeded + ', Failed=' + failed);
if (toFix.size() == ROW_CAP) {
System.debug(LoggingLevel.WARN, 'Row cap reached. Re-run until nothing is selected.');
}
```
{% hint style="info" %}
To roll back, restore the affected records from the export taken in the previous step. Do not reverse by value, because **Hourly** and **Each** are also legitimate existing values.
{% endhint %}
{% endstep %}
{% step %}
#### Optional: reactivate the Support Item unit trigger handler
If your org deactivated the **SupportItemUnitOfMeasure\_MDTM** trigger handler under **Setup > Custom Metadata Types > Trigger Handler** as a workaround, you can reactivate it. First confirm no Appointment Service relies on a hand-set unit that differs from its Support Items, because the handler overwrites it with the most-used mapped unit on the next Support Item change. If left inactive, cost and quantity still calculate correctly. Only the automatic upkeep of the Appointment Service unit is lost.
{% endstep %}
{% endstepper %}
## Verification Checklist
After completing the post-install steps above, verify the setup is working as expected.
* [ ] The org's own copy of the invoice flow has the four cap edits applied and is active
* [ ] A travel line above a configured kilometre cap bills at the cap, and a line with no cap configured bills in full
* [ ] For Unit Price orgs, the report script shows no unbilled travel rows left in the old arrangement
* [ ] One billed travel Appointment: Quantity multiplied by Unit Price equals the line total to the cent
* [ ] The Support Item Quantity Unit Of Measure picklist includes Item, Hours, Bill, Voucher, Meal and Trip
* [ ] The Appointment Service remediation script reports Failed=0 and no row cap warning
* [ ] A Support at Home Appointment shows an Appointment Service of Hourly or Each, a Delivery Activity Quantity derived from the duration, and a non-zero cost