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.