Calculate Follow-Up Status Business Logic

This document describes how the CalculateFollowUpStatusRule currently calculates:

• Next Appointment
• appointment-level PAI Status
• Overall PAI Status
• Overall PAI Status Summary

It is written for business review. The section Business decisions to confirm identifies points where the current implementation and the intended business behavior may differ.

#Appointment data

Each appointment is read from the configured SERVICES MultiChoice column. The rule uses these appointment fields:

The appointment type is taken from the configured appointment-type field. If that field is empty, the rule uses the service group name as a fallback.

#Interval configuration

Each configured appointment type is mapped to a whiteboard column containing a month interval.

Example:

Appointment type 89.50 -> HF_PAI_ECODIAGRAM_SCHEDULE -> 12-18

The interval format is:

minimum months - maximum months

For an interval of 12-18, the next qualifying appointment should be at least 12 months and at most 18 months after the reference appointment.

Valid intervals must:

• contain exactly two numbers;
• use a hyphen as the separator;
• have a minimum of zero or greater;
• have a maximum greater than or equal to the minimum.

If the configured interval column is missing, empty, or invalid, that appointment type has no active interval for the current row.

The configured status values default to:

The status values are configurable. For example, a system can use Done, Confirmed, and Scheduled instead of the defaults.

Appointments with unsupported statuses are not included in any calculation and do not cause output cells to be created.

Appointments are grouped by appointment type, case-insensitively.

Appointments of different types never affect one another. For example, a cardiology appointment cannot be the next appointment for an echocardiogram appointment.

Within each type, appointments are ordered by booking time.

#Current algorithm

For a Completed or Accepted appointment, the rule searches for the earliest later appointment of the same type whose status is one of the allowed statuses:

• Completed
• Accepted
• Booked

The result is written to the appointment's NextAppointment field.

For a Booked appointment, NextAppointment is always empty.

For an unsupported status, the appointment is ignored.

#Example of the current algorithm

Given these appointments of the same type:

The current NextAppointment chain is:

PAI is calculated independently for each appointment type, using the configured interval for that type.

#5.1 Completed or Accepted with a next appointment

For a Completed or Accepted appointment with a next appointment, the rule compares:

current appointment date + configured interval

with the next appointment date.

The interval boundaries are inclusive.

Example with interval 3-6:

#5.2 Completed or Accepted without a next appointment

If there is no next appointment, the rule compares the current date with the minimum follow-up date:

current appointment date + minimum interval

This means that a recent completed appointment can remain OK while there is still time to arrange the follow-up appointment.

Example with interval 3-6 and no next appointment:

#5.3 Booked appointment

For a Booked appointment, the rule looks backwards for the latest earlier appointment of the same type with status Completed or Accepted.

If no previous qualifying appointment exists:

• PAI Status is empty;
• Next Appointment is empty.

If a previous qualifying appointment exists, the booked date is compared with the previous appointment date and interval using the same rules:

• before the minimum: Too early;
• within the inclusive interval: OK;
• after the maximum: Too late.

This allows a future Booked appointment to be assessed against the previous clinical appointment.

#5.4 Appointment type without an interval

If the appointment type has no valid interval value in the current patient row:

• appointment-level PAI Status is empty;
• the appointment is excluded from overall PAI calculations;
• the appointment type is excluded from the overall summary.

This is different from Not booked. Empty means that no configured interval was available for evaluation.

#Purpose

Overall PAI Status gives one patient-level result across all configured appointment types.

#Which appointment types participate

Only appointment types that satisfy both conditions participate:

1. The appointment type has a configured mapping.
2. The mapped interval column contains a valid interval for the current patient row.

Unconfigured appointment types and appointment types with missing or invalid intervals are excluded.

If no appointment type participates, the overall value is empty.

#Which appointment represents each type

For each participating appointment type, the rule selects the latest appointment by booking time, regardless of status.

The PAI status already calculated for that latest appointment is used.

This means the latest appointment may be:

• Completed;
• Accepted;
• Booked.

#Overall result

The overall result is:

An empty appointment-level PAI status is not equal to OK, so it causes the overall result to be not-OK when that appointment type is included. In normal processing, types without intervals are excluded before this decision.

#Purpose

The summary gives one entry for each participating appointment type, making it possible to see which type caused the overall result.

The format is:

appointment type - PAI status, appointment type - PAI status

Example:

89.01.03 - Too early, 89.50 - OK

#Selection and ordering

The summary uses the same participating appointment types and the same latest appointment per type as Overall PAI Status.

Entries are ordered by the latest appointment booking time, from oldest to newest.

#Empty PAI values in the summary

If the selected latest appointment has an empty PAI status, the summary displays the configured Not booked value instead of an empty value.

Assume:

Appointment type: 89.50
Configured interval: 12-18 months

Appointments:

Under the current implementation:

The latest appointment for type 89.50 is the Booked appointment on 26.07.2026. Therefore:

Overall PAI Status: Not OK
Overall PAI Status Summary: 89.50 - Too early

#Decision A: Should Booked be a Next Appointment?

The current implementation includes Booked when finding the next appointment for a Completed or Accepted appointment.

Alternative business interpretation:

• NextAppointment should identify the next Completed or Accepted appointment only;
• Booked should not replace a future clinical appointment in the chain;
• a Booked appointment should be assessed separately against the previous Completed or Accepted appointment.

This decision changes both NextAppointment and the PAI status of preceding appointments.

#Decision B: Should Booked appointments have a PAI status?

The current implementation calculates PAI for a Booked appointment when a previous Completed or Accepted appointment exists.

Alternative behavior:

• always leave PAI empty for Booked appointments; or
• show OK, Too early, or Too late based on the previous clinical appointment.

The current implementation uses the second behavior.

#Decision C: What should happen when there is no next appointment?

The current implementation is time-aware:

• before the minimum follow-up date: OK;
• on or after the minimum follow-up date: Not booked.

Alternative behavior would be to show Not booked immediately whenever no next appointment exists.

#Decision D: Which appointment should drive the overall result?

The current implementation selects the latest appointment by date for each type, including a Booked appointment.

The business should confirm whether the latest appointment should instead mean:

• latest appointment of any allowed status;
• latest Completed or Accepted appointment only;
• latest appointment with a calculated PAI status;
• latest appointment excluding Booked.

This decision directly affects both overall fields.

#Decision E: How should missing interval configuration be represented?

The current behavior is:

• appointment-level PAI is empty;
• the type is excluded from both overall fields;
• no configured type results in empty overall fields.

This keeps “not configured” separate from “not booked,” but it should be confirmed with the business.

To avoid mixing separate concepts, agree on the rules in this order:

1. Which statuses are valid?
2. Which statuses can be a NextAppointment?
3. Which statuses can receive PAI?
4. What is the reference appointment for a Booked appointment?
5. What happens when there is no next appointment?
6. Which appointment is latest for overall calculations?
7. How should missing interval configuration be represented?
8. What exact display text should be used for each result?

Once these decisions are confirmed, the implementation and tests can be aligned to the agreed business behavior.

• CalculateFollowUpStatusRule.cs
• When_Validating_Arguments.cs