> 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.158.md).

# Version 0.158

Client Delivery V0.158 is a fix-focused release covering three items: the default value of the Billable Participant Note flag, an Appointment finalisation issue when multiple Resources are involved in a Check-Out, and a map display issue on the Quick Complete screen.

{% hint style="warning" %}
The Billable Participant Note default value fix requires a post-install data correction step. See **Post-Install Steps** at the bottom of this page.
{% 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**: <a href="https://login.salesforce.com/packaging/installPackage.apexp?p0=04tQp000000n7YDIAY" class="button primary">Production URL</a>

**Sandbox & Scratch Orgs:** <a href="https://test.salesforce.com/packaging/installPackage.apexp?p0=04tQp000000n7YDIAY" class="button secondary">Sandbox URL</a>

{% 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              |
| --------------------------------------------------------------- | ---- | ----------------- |
| **Billable Participant Note Default Value**                     | Fix  | Participant Notes |
| **Check-Out: Appointment Finalisation with Multiple Resources** | Fix  | Appointments      |
| **Quick Complete: Map Display**                                 | Fix  | Appointments      |

## Fixes

### Billable Participant Note Default Value

**Reference:** CC-705

We have refined the default value of the **Billable Participant Note** flag on Participant Notes so that non-billable notes are no longer flagged as billable.

**What's changed**

The default value of the **Billable Participant Note** flag is now determined as follows:

* On Participant Notes created in-Appointment, the flag defaults to **FALSE**.
* On Participant Notes created outside an Appointment context, the default is driven by whether the user has the **Create Billable Participant Notes** permission. Users with the permission see the flag default to **TRUE** and can adjust it; users without the permission see the flag default to **FALSE** and cannot edit it.
* The flag is only set to **TRUE** when the user actively selects a Participant, nominates an Appointment Service, and either explicitly sets **Billable Participant Note = TRUE** or has the field set by an in-Appointment workflow that captures billable activity.

Reports and extracts that filter on **Billable Participant Note** now return the correct set of records for Participant Notes created from this release forward. A one-time post-install data correction script is provided to reset the flag on existing notes that were incorrectly stored as billable under the previous default. See **Post-Install Steps** at the bottom of this page.

{% hint style="warning" %}
**Post-install steps required.** See [Billable Participant Note Data Correction](#billable-participant-note-data-correction) under Post-Install Steps.
{% endhint %}

**Example scenarios**

* ✅ A Support Worker creates a non-billable in-Appointment Participant Note → the note saves with **Billable Participant Note = FALSE**.
* ✅ A user with the Create Billable Participant Notes permission opens the New Participant Note dialog from outside an Appointment context → the flag defaults to **TRUE** and the user can adjust it before saving.
* ✅ A user without the Create Billable Participant Notes permission opens the same dialog → the flag defaults to **FALSE** and is not editable.

### Check-Out: Appointment Finalisation with Multiple Resources

**Reference:** CC-714

We have refined the Check-Out logic so that an Appointment is only finalised once all Accepted Resources on the Appointment have completed their Check-Out.

**What's changed**

When a Resource Checks Out of an Appointment, Maica evaluates whether any other Accepted Resources on the Appointment are still working. The Appointment is only finalised (moved to **Completed** or **Under Review**) once no other Accepted Resources remain in a state where Check-Out is still expected. Resources in a non-Accepted status (for example, Withdrawn or Declined) are correctly excluded from this evaluation.

**Example scenarios**

* ✅ An Appointment has two Accepted Resources. The first Resource Checks Out while the second has not yet Checked In → the Appointment remains in its in-progress state and waits for the second Resource's Check-Out.
* ✅ The second Resource Checks Out → the Appointment is finalised to **Completed** or **Under Review** as appropriate.
* ✅ An Appointment has one Accepted Resource and one Withdrawn Resource. The Accepted Resource Checks Out → the Appointment is finalised; the Withdrawn Resource is not considered.

### Quick Complete: Map Display

**Reference:** CC-713

We have updated the Quick Complete Appointment screen so that the map component renders reliably and remains visible for the duration of the Quick Complete flow.

**What's changed**

The map component on the Quick Complete Appointment screen now renders consistently when the screen loads, and remains visible while the rest of the screen data populates.

**Example scenarios**

* ✅ A Care Worker opens Quick Complete on an Appointment → the map renders and remains visible after the rest of the screen data loads.
* ✅ A Care Worker navigates between Appointments using Quick Complete → the map renders correctly for each Appointment.

## Post-Install Steps

### Billable Participant Note Data Correction

#### Prerequisites

* Maica Client Delivery package version **0.158** or later installed
* System Administrator profile with the Maica Client Care permission sets assigned
* Access to the Salesforce Developer Console or Apex Anonymous Window

#### About this script

This script resets the **Billable Participant Note** flag to **FALSE** on existing Participant Notes that were stored as billable under the previous default value but carry no billing evidence. A Participant Note is treated as having billing evidence only if its Appointment has at least one Delivery Activity with a Billing Status of **Requested**, **Generated**, **Processed**, **Review**, or **Rejected**. These statuses are set by the New Participant Note flow when a user explicitly creates a billable note. All other notes flagged as billable, including notes without an Appointment, are reset to FALSE.

The script is idempotent and processes up to 9,900 records per execution. Re-run it until the debug output reports `Remaining: 0`.

{% stepper %}
{% step %}

#### Open the Developer Console and Execute Anonymous Window

1. Open the **Developer Console** in your Salesforce org
2. Open the **Execute Anonymous Window** (`Debug → Open Execute Anonymous Window`)
3. Paste the following Apex script:

```apex
/**
 * Billable Participant Note data correction (post-installation step)
 *
 * Run as:  System Administrator (with the Maica Client Care permission sets assigned),
 *          via Developer Console or `sf apex run`, after upgrading to the package
 *          version containing this fix.
 *
 * What:    Sets maica__Billable_Client_Note__c = FALSE on existing notes that are
 *          flagged billable but carry NO billing evidence. Billing evidence = the
 *          note's Appointment has at least one Delivery Activity with Billing Status
 *          of Requested / Generated / Processed / Review / Rejected. Notes without
 *          an Appointment are reset too, as they cannot have been billed.
 *
 * Safety:  - Idempotent: corrected records drop out of the selection on subsequent
 *            runs.
 *          - Processes up to 9,900 records per execution to stay inside anonymous
 *            Apex governor limits. RE-RUN the script until the debug output reports
 *            'Remaining: 0'.
 *          - Partial-success DML: rows rejected by org-specific automation or
 *            validation rules are logged to the debug log and skipped; the rest
 *            still commits.
 */
try {
    final Set<String> BILLING_EVIDENCE_STATUSES = new Set<String>{
            'Requested', 'Generated', 'Processed', 'Review', 'Rejected'
    };

    List<maica__Client_Note__c> notesToFlip = [
            SELECT Id
            FROM maica__Client_Note__c
            WHERE maica__Billable_Client_Note__c = TRUE
            AND maica__Appointment__c NOT IN (
                    SELECT maica__Appointment__c
                    FROM maica__Delivery_Activity__c
                    WHERE maica__Billing_Status__c IN :BILLING_EVIDENCE_STATUSES
                    AND maica__Appointment__c != NULL
            )
            LIMIT 9900
    ];

    for (maica__Client_Note__c noteToFlip : notesToFlip) {
        noteToFlip.maica__Billable_Client_Note__c = false;
    }

    Integer flippedCount = 0;
    Integer failedCount = 0;
    List<Database.SaveResult> saveResults = notesToFlip.isEmpty()
            ? new List<Database.SaveResult>()
            : Database.update(notesToFlip, false);
    for (Integer i = 0; i < saveResults.size(); i++) {
        if (saveResults[i].isSuccess()) {
            flippedCount++;
        } else {
            failedCount++;
            System.debug(LoggingLevel.ERROR, 'Billable Participant Note correction: failed to update ' + notesToFlip[i].Id + ': ' + saveResults[i].getErrors());
        }
    }

    Integer remainingCount = [
            SELECT COUNT()
            FROM maica__Client_Note__c
            WHERE maica__Billable_Client_Note__c = TRUE
            AND maica__Appointment__c NOT IN (
                    SELECT maica__Appointment__c
                    FROM maica__Delivery_Activity__c
                    WHERE maica__Billing_Status__c IN :BILLING_EVIDENCE_STATUSES
                    AND maica__Appointment__c != NULL
            )
            LIMIT 10000
    ];

    System.debug(LoggingLevel.INFO, 'Billable Participant Note correction: Flipped: ' + flippedCount
            + ', Failed: ' + failedCount
            + ', Remaining: ' + remainingCount
            + (remainingCount > 0 ? '. RE-RUN THIS SCRIPT until Remaining: 0.' : '. COMPLETE.'));
} catch (Exception scriptException) {
    System.debug(LoggingLevel.ERROR, 'Billable Participant Note correction: script failed: ' + scriptException.getMessage()
            + '\n' + scriptException.getStackTraceString());
}
```

4. Click **Execute**
5. Review the debug log to confirm the **Flipped**, **Failed**, and **Remaining** counts
6. Re-run the script until the debug log reports `Remaining: 0`. Each execution processes up to 9,900 records.

{% hint style="info" %}
The 9,900-record limit per execution is in place to keep each transaction within Salesforce governor limits. The script is idempotent: records already corrected on a previous run will not be selected again.
{% endhint %}
{% endstep %}

{% step %}

#### Confirm Completion

Once the debug log reports `Remaining: 0`, the data correction is complete. No further action is required.

To verify the correction at any point, the following SOQL query returns the count of remaining incorrectly billable Participant Notes:

```sql
SELECT COUNT()
FROM maica__Client_Note__c
WHERE maica__Billable_Client_Note__c = TRUE
AND maica__Appointment__c NOT IN (
    SELECT maica__Appointment__c
    FROM maica__Delivery_Activity__c
    WHERE maica__Billing_Status__c IN ('Requested', 'Generated', 'Processed', 'Review', 'Rejected')
    AND maica__Appointment__c != NULL
)
```

A return value of `0` confirms the correction is complete.
{% endstep %}
{% endstepper %}

## Verification Checklist

After completing the post-install steps above, verify the data correction is complete.

* [ ] The verification SOQL query returns a count of `0`
* [ ] A test billable Participant Note created via the in-Appointment workflow (with an Appointment Service nominated and a Delivery Activity with Billing Status of `Requested`) is correctly stored as **Billable Participant Note = TRUE**
* [ ] A test non-billable in-Appointment Participant Note is correctly stored as **Billable Participant Note = FALSE**
* [ ] Reports and extracts filtering on **Billable Participant Note = TRUE** return the expected set of records