Task #19897
Updated by Redmine Admin 3 months ago
An Air Clearing File is created in **DRAFT** status by default.
While the file is in **DRAFT**, users can continue preparing and updating it.
Once the operational work has been completed, the user can mark the file as **COMPLETED**.
A **COMPLETED** file means the operational work has been completed, but the file can still be amended if needed. However, if the user updates a Completed file, the system must automatically change the status back to **DRAFT**, because the file has been modified after completion and must be considered under preparation again.
Once the file is fully finalized and no further changes should be allowed, the user can mark the file as **CLOSED**.
If the file is no longer required or was created by mistake, the user can **CANCEL** it, provided cancellation is allowed.
# Status Definitions
| Status | Meaning |
|--------|---------|
| DRAFT | File is still being prepared and can be updated. |
| COMPLETED | File has been completed, but can still be updated. If updated, status returns to DRAFT. |
| CLOSED | File has been completed and closed. It should no longer be changed. |
| CANCELLED | File is no longer valid and should no longer be changed. |
# Important Billing Rule
A clearing file must **not be cancelled directly if a standard invoice has already been issued**.
Once a standard invoice exists, the clearing file is already linked to billing/accounting. Cancelling it directly may create inconsistencies in:
* Invoices
* Customer statements
* Revenue records
* Credit notes
* Accounting reports
Therefore, before cancelling the Air Clearing File, the system must check the billing/invoice status.
# Status Workflow
## Statuses Required
* DRAFT
* COMPLETED
* CLOSED
* CANCELLED
## ACTION Dropdown Values
The ACTION dropdown will contain the following actions, depending on current status and permission:
* COMPLETED
* CLOSE
* CANCEL
# Workflow Transitions
| Current Status | Available Action | Resulting Status |
|----------------|------------------|------------------|
| DRAFT | COMPLETED | COMPLETED |
| DRAFT | CANCEL | CANCELLED |
| COMPLETED | CLOSE | CLOSED |
| COMPLETED | CANCEL | CANCELLED, subject to invoice rules |
| COMPLETED | Update file | DRAFT |
| CLOSED | No action | CLOSED |
| CANCELLED | No action | CANCELLED |
# Important Rule – Updating a Completed File
If the file is in **COMPLETED** status and the user updates any editable information, the system must automatically change the status back to:
DRAFT
This is because once the completed file is amended, it is no longer considered finalized/completed.
Suggested Activity Log:
_\<username\> updated Air Clearing File \<CLEARING_REF\>; status changed from COMPLETED to DRAFT_
# Important UI Clarification
The existing Ocean Clearing screen has the **ACTION** button in two places:
1. At the **top** of the Clearing Add/Update screen
2. At the **bottom** of the Clearing Add/Update screen
The Air Clearing module must follow the same approach.
Both ACTION buttons must:
* Show the same available actions
* Follow the same permission rules
* Trigger the same workflow logic
* Update the same file status
* Create the same Activity Log entries
There must not be separate logic for the top and bottom ACTION buttons.
# Screen Area
The ACTION button must be displayed on the Air Clearing Add/Update screen.
## ACTION Button Placement
| Location | Placement |
|----------|-----------|
| Top ACTION button | Near the top Back button / header action area |
| Bottom ACTION button | Near the bottom Back button and Update Clearing File button |
# Functional Requirements
## 1 – Default Status on Creation
When a new Air Clearing File is created successfully, the system must set the status to:
DRAFT
This applies to all creation methods:
* From HAWB
* From MAWB
* From Quotation
* Manual / from scratch
## 2 – Display Current Status
The current status must be displayed clearly on:
* Air Clearing Retrieve/List screen
* Air Clearing Add/Update screen
The status should use the same badge/tag style as Ocean Clearing where possible.
## 3 – ACTION Button Visibility
The ACTION buttons should be displayed only after the Air Clearing File has been saved and a Clearing Reference has been generated.
Before first save:
* No status transition should be available.
* ACTION buttons may be hidden or disabled.
Suggested message if user attempts action before save:
_Please save the Air Clearing File first before performing workflow actions._
## 4 – ACTION Button Placement
The Air Clearing Add/Update screen must display the ACTION button in two locations:
1. Top of the screen
2. Bottom of the screen
Both ACTION buttons must show the same available actions based on:
* Current file status
* Logged-in user role
* User permissions
* Workflow rules
## 5 – ACTION Button Synchronisation
The top and bottom ACTION buttons must always be synchronized.
If the top ACTION button shows:
* COMPLETED
* CANCEL
then the bottom ACTION button must show the same actions.
If the top ACTION button shows:
* CLOSE
* CANCEL
then the bottom ACTION button must show the same actions.
If one button is hidden or disabled due to status or permission, the other must behave the same.
Both buttons must call the same workflow/action service.
## 6 – Complete Air Clearing File
When the file is in **DRAFT**, the user can select:
COMPLETED
When selected, the system should:
1. Ask for confirmation, same as existing Ocean behaviour.
2. Validate mandatory information.
3. Change status from DRAFT to COMPLETED.
4. Save the updated status.
5. Refresh the screen status display.
6. Update available ACTION button options.
7. Keep the file editable.
8. Add Activity Log entry.
Suggested Activity Log:
\<username\> changed clearing status from DRAFT to COMPLETED
## 7 – Mandatory Validation before Completion
Before the file can be marked as Completed, the system must validate required sections.
Minimum validation should include:
* Shipment Details completed
* Flight Information completed where mandatory
* Party Information completed based on Import/Export rule
* BOE information completed if business decides BOE is mandatory before completion
* No invalid Cost records
* No invalid Sales records
## 8 – Update Completed File and Revert to Draft
When an Air Clearing File is in **COMPLETED** status, users may still update it if they have permission.
However, after a successful update to any editable section, the system must automatically change the status from:
COMPLETED
to:
DRAFT
This applies when the user updates sections such as:
* Shipment Details
* Flight Information
* Party Information
* BOE
* Costs
* Sales
* Documents
Suggested Activity Log:
\<username\> updated Air Clearing File \<CLEARING_REF\>; status changed from COMPLETED to DRAFT
## 9 – Close Air Clearing File
When the file is in **COMPLETED** status, the user can select:
CLOSE
When selected, the system should:
1. Ask user to confirm closure.
2. Validate that the file is eligible for closure.
3. Change status from COMPLETED to CLOSED.
4. Save the updated status.
5. Make the Air Clearing File read-only.
6. Refresh the status display.
7. Disable or hide update-related actions.
8. Add Activity Log entry.
Suggested confirmation:
_Are you sure you want to close this Air Clearing File?_
Suggested Activity Log:
\<username\> changed clearing status from COMPLETED to CLOSED
## 10 – Cancel Air Clearing File
The user can select:
CANCEL
Cancellation should be available only when the file is eligible for cancellation.
Recommended eligibility:
| Current Status | Cancel Allowed? |
|----------------|-----------------|
| DRAFT | Yes, subject to invoice rules |
| COMPLETED | Yes, subject to invoice rules |
| CLOSED | No |
| CANCELLED | No |
When CANCEL is selected, the system should:
1. Check whether cancellation is allowed.
2. Check billing/invoice status.
3. Ask user to confirm cancellation.
4. Ask for cancellation reason.
5. Validate that cancellation reason is entered.
6. Change status to CANCELLED.
7. Save the updated status.
8. Make the Air Clearing File read-only.
9. Refresh the status display.
10. Disable or hide update-related actions.
11. Add Activity Log entry.
Cancellation reason is **mandatory** for Air Clearing.
Suggested confirmation:
_Are you sure you want to cancel this Air Clearing File?_
Suggested Activity Log:
\<username\> cancelled Air Clearing File \<CLEARING_REF\>. Reason: \<reason entered\>
# Billing / Invoice Rules for Cancellation
## 11 – Check Invoice Status before Cancellation
Before allowing cancellation, the system must check if any invoice exists for the Air Clearing File.
| Billing Status | Cancellation Rule |
|----------------|-------------------|
| No invoice exists | Allow cancellation |
| Draft invoice exists | Allow cancellation |
| Proforma invoice exists | Allow cancellation |
| Standard/final invoice issued | Block cancellation |
| Standard/final invoice fully reversed by credit note | Allow cancellation only if no active invoice remains |
| Payment already received | Require billing reversal/refund/reallocation process before cancellation |
## 12 – Block Cancellation if Standard Invoice Exists
If a **standard invoice** has already been issued for the Air Clearing File, the system must block cancellation.
Suggested message:
_This clearing file cannot be cancelled because a standard invoice has already been issued. Please cancel or reverse the invoice through the billing process first._
## 13 – Cancellation after Invoice Reversal
If the standard invoice has been cancelled/reversed through the proper billing process, for example by credit note, and no active invoice remains, then the system may allow cancellation.
Before allowing cancellation, the system should confirm that:
* No active standard invoice remains
* No unreversed invoice exists
* Any payment/refund/reallocation process has been handled if applicable
## 14 – Permission Control
Workflow actions must be controlled by user role and permission.
Suggested role logic:
| Role | Suggested Allowed Actions |
|------|---------------------------|
| Operations User | Create, Update, Complete if permitted, Cancel if permitted |
| Supervisor/Admin | All actions based on permission |
The exact permission mapping should follow existing MFreight User Management / Role Management logic.
If user does not have permission, display:
_You do not have permission to perform this action._
## 15 – Read-only / Editable Behaviour by Status
The Air Clearing File must behave according to status.
| Status | Screen Behaviour |
|--------|------------------|
| DRAFT | Editable |
| COMPLETED | Editable, but update changes status back to DRAFT |
| CLOSED | Read-only |
| CANCELLED | Read-only |
## 16 – Read-only Rules for Closed and Cancelled Files
For **CLOSED** and **CANCELLED** files:
* Update Clearing File button must be disabled or hidden.
* Add/Edit/Delete actions in BOE must be disabled or hidden.
* Add/Edit/Delete actions in Costs must be disabled or hidden.
* Add/Edit/Delete actions in Sales must be disabled or hidden.
* Upload/Delete actions in Documents must be disabled or hidden.
* View actions should remain available where applicable.
## 17 – Activity Log for Status Changes
Every status change must be recorded in the Activity Log section at the bottom of the Air Clearing Add/Update page.
The log must include:
* Activity Date & Time
* Activity By
* Activity Description
Example:
13-05-2026 10:42 | supervisor | supervisor changed clearing status from DRAFT to COMPLETED
The Activity Log is not a separate screen. It is displayed at the bottom of the Air Clearing page.
## 18 – Prevent Invalid Status Change
The system must prevent invalid workflow steps.
Examples:
* User should not change DRAFT directly to CLOSED.
* User should not change CLOSED back to DRAFT.
* User should not change CANCELLED back to DRAFT.
* User should not update a CLOSED file.
* User should not update a CANCELLED file.
* User should not cancel a file if a standard invoice is active.
Suggested message:
_This status change is not allowed._
## 19 – Refresh Screen after Status Change
After any successful status change, the screen must refresh or update dynamically to reflect:
* New status badge
* Updated ACTION button options at top and bottom
* Updated read-only/editable behaviour
* New Activity Log entry
# ACTION Button Availability by Status
| Status | ACTION Button Options |
|--------|-----------------------|
| DRAFT | COMPLETED, CANCEL |
| COMPLETED | CLOSE, CANCEL |
| CLOSED | No action |
| CANCELLED | No action |
# Validation Rules
| Scenario | Rule |
|----------|------|
| New file created | Status must be DRAFT |
| Complete file | Mandatory fields must be completed |
| Update completed file | Status must revert to DRAFT |
| Close file | File must be COMPLETED |
| Cancel file | Invoice/billing status must be checked |
| Cancellation reason | Mandatory |
| Standard invoice exists | Cancellation must be blocked |
| Closed file | No updates allowed |
| Cancelled file | No updates allowed |
| Invalid transition | Must be blocked |
| Top and bottom ACTION buttons | Must show same actions and trigger same logic |
# Error Messages
| Scenario | Suggested Message (**but can use same as ocean clearing module**) |
|----------|-------------------------------------------------------------------|
| Mandatory information missing before completion | Please complete all mandatory information before completing the Air Clearing File. |
| No permission | You do not have permission to perform this action. |
| Invalid transition | This status change is not allowed. |
| File not yet saved | Please save the Air Clearing File first before performing workflow actions. |
| Complete confirmation | Are you sure you want to mark this Air Clearing File as completed? |
| Close confirmation | Are you sure you want to close this Air Clearing File? |
| Cancel confirmation | Are you sure you want to cancel this Air Clearing File? |
| Missing cancellation reason | Please enter a cancellation reason. |
| Standard invoice exists | This clearing file cannot be cancelled because a standard invoice has already been issued. Please cancel or reverse the invoice through the billing process first. |
| Update closed file | This clearing file is closed and cannot be updated. |
| Update cancelled file | This clearing file is cancelled and cannot be updated. |
# Acceptance Criteria
## 1 – Default Status
Given I create a new Air Clearing File,\
When the file is saved successfully,\
Then the system should set the status to DRAFT.
## 2 – Display Status
Given an Air Clearing File exists,\
When I open the file,\
Then the current status should be clearly displayed on the screen.
## 3 – ACTION Buttons Displayed at Top and Bottom
Given an Air Clearing File has been saved,\
When I open the Air Clearing Add/Update screen,\
Then the system should display the ACTION button at both the top and bottom of the page.
## 4 – ACTION Buttons Not Active before First Save
Given I am creating a new Air Clearing File and it has not yet been saved,\
When the page is displayed,\
Then the system should not allow workflow transitions from the ACTION buttons.
## 5 – Same Actions in Top and Bottom ACTION Buttons
Given the file is in DRAFT,\
When I open the top ACTION button and the bottom ACTION button,\
Then both should display the same available actions:
* COMPLETED
* CANCEL
## 6 – Same Actions for Completed File
Given the file is in COMPLETED,\
When I open the top ACTION button and the bottom ACTION button,\
Then both should display the same available actions:
* CLOSE
* CANCEL
## 7 – Same Behaviour from Both ACTION Buttons
Given I select a workflow action from either the top or bottom ACTION button,\
When the action is confirmed,\
Then the system should apply the same validation, permission checks, status update, and Activity Log logic.
## 8 – Complete File Successfully
Given the file is in DRAFT and mandatory information is completed,\
When I select **COMPLETED**,\
Then the system should change the status to COMPLETED.
## 9 – Mandatory Validation before Completion
Given the file is in DRAFT and mandatory information is missing,\
When I select **COMPLETED**,\
Then the system should prevent the status change and display:
_Please complete all mandatory information before completing the Air Clearing File._
## 10 – Update Completed File Reverts to Draft
Given the file is in COMPLETED,\
When I update and save any editable section,\
Then the system should save the update and automatically change the status to DRAFT.
## 11 – Activity Log for Completed File Update
Given the file is in COMPLETED,\
When I update and save the file,\
Then the system should record in Activity Log that the file was updated and status changed from COMPLETED to DRAFT.
## 12 – Close File Successfully
Given the file is in COMPLETED,\
When I select **CLOSE** and confirm,\
Then the system should change the status to CLOSED and make the file read-only.
## 13 – Prevent Direct Close from Draft
Given the file is in DRAFT,\
When I attempt to close the file directly,\
Then the system should prevent the action and display:
_This status change is not allowed._
## 14 – Cancel File Successfully When No Standard Invoice Exists
Given the file is in DRAFT or COMPLETED,\
And no standard/final invoice exists,\
When I select **CANCEL**, enter a cancellation reason, and confirm,\
Then the system should change the status to CANCELLED.
## 15 – Cancellation Reason Mandatory
Given I select **CANCEL**,\
When I do not enter a cancellation reason,\
Then the system should prevent cancellation and display:
_Please enter a cancellation reason._
## 16 – Block Cancellation When Standard Invoice Exists
Given a standard invoice has already been issued for the Air Clearing File,\
When I select **CANCEL**,\
Then the system should prevent cancellation and display:
_This clearing file cannot be cancelled because a standard invoice has already been issued. Please cancel or reverse the invoice through the billing process first._
## 17 – Allow Cancellation after Invoice Reversal
Given a standard invoice was issued but has been fully reversed/cancelled through the billing process,\
And no active standard invoice remains,\
When I select **CANCEL**, enter a cancellation reason, and confirm,\
Then the system should allow cancellation if all other cancellation rules are satisfied.
## 18 – Prevent Update on Closed File
Given the file is CLOSED,\
When I try to update any section,\
Then the system should prevent the update and display:
_This clearing file is closed and cannot be updated._
## 19 – Prevent Update on Cancelled File
Given the file is CANCELLED,\
When I try to update any section,\
Then the system should prevent the update and display:
_This clearing file is cancelled and cannot be updated._
## 20 – Activity Log for Completion
Given the file is marked as Completed,\
When the status is changed,\
Then the system should record the status change in the Activity Log section.
## 21 – Activity Log for Closure
Given the file is closed,\
When the status is changed from COMPLETED to CLOSED,\
Then the system should record the closure in the Activity Log section.
## 22 – Activity Log for Cancellation
Given the file is cancelled,\
When the status is changed,\
Then the system should record the cancellation and cancellation reason in the Activity Log section.
## 23 – ACTION Buttons Refresh after Status Change
Given a status change has been completed,\
When the screen updates,\
Then both top and bottom ACTION buttons should display the correct options for the updated status.
For CLOSED or CANCELLED, no further workflow action should be available unless business permission allows otherwise.
**NOTE:** The user should be able to create a STANADARD invoice when the clearing status is either completed or closed.