Skip to content

MK Commercial, Inbound, Outbound And Booking — Operator Runbook

Purpose

  • Status: SOURCE-RECONCILED OPERATOR DRAFT / CURRENT WIKI AND TARGET-ROLE REVIEW REQUIRED - Audience: MK Commercial/Office, Receiving, Shipping/Booking, Inventory/Allocation, Scale, Manager and Support - Scope: core order-first work from Commercial Agreement through Inbound Pur

Who does this

Whoever owns this job.

Before you start

  • You have the right account (see Permissions and Access).
  • The record and date you are working on are correct.

  • Words you do not know are in the Glossary.

  • Status: SOURCE-RECONCILED OPERATOR DRAFT / CURRENT WIKI AND TARGET-ROLE REVIEW REQUIRED

  • Audience: MK Commercial/Office, Receiving, Shipping/Booking, Inventory/Allocation, Scale, Manager and Support
  • Scope: core order-first work from Commercial Agreement through Inbound Purchase, Outbound Sales and Booking
  • Process source: MK_ORDER_FIRST_CORE_RECONCILIATION.md
  • Rebuild source: MK_ORDER_FIRST_CORE_CAPABILITY_REBUILD_PACKET.md
  • Important: this repository Runbook does not authorize operational writes, role changes, DB changes, Wiki publication or Production effects. Current menu labels, permissions and exact UI wording must be verified before publication.

1. Core Operating Rule

MK is order-first, but an order record does not prove every later child completed.

Commercial Agreement
!= Inbound/Outbound execution
!= Receipt/Shipment completion
!= Inventory Lot
!= Allocation
!= Booking
!= Scale
!= Packing/Document output

Every operator action ends with an exact reread of the owning record and any child that the action is expected to affect.

Do not use:

  • a success toast;
  • a list row disappearing;
  • a header COMPLETED label;
  • an Outbound readiness badge;
  • a Booking flag;
  • a printed page;

as proof that a different child process completed.

2. Before Starting Any MK Order Work

Confirm:

  • correct MK tenant/profile;
  • personal account and intended role;
  • current date/range and filters;
  • exact Purchase/Sales/PO/SO/Booking/reference/container identity;
  • existing record search before create;
  • current child links and states;
  • whether another operator is editing the same record;
  • whether a previous request has an unknown or partial result;
  • which optional children actually apply.

Stop and escalate when:

  • the same business work may already exist under a different date/filter;
  • tenant/counterparty/commodity/Booking/container identity is unclear;
  • a record shows child progress that conflicts with the intended edit/delete;
  • a prior Booking Save may have changed Order/Inventory/Allocation children;
  • a Scale ticket is complete but receipt finalization is unknown;
  • an allocation or lot balance is ambiguous.

3. Commercial Agreement

3.1 Search before create

  1. Open the normal MK Commercial Orders entry.
  2. Set a date range broad enough to include the intended agreement.
  3. Search by Purchase/Sales type, agreement number, reference, counterparty and commodity.
  4. Open every plausible match.
  5. Confirm no existing agreement represents the same commercial terms.

Do not create a duplicate because the default list filter did not show an older row.

3.2 Create a Purchase or Sales agreement

  1. Select Purchase or Sales.
  2. Select the current tenant counterparty.
  3. Review contract date and shipping period.
  4. Enter terms, ports, currency, packaging, allowances and required documents as applicable.
  5. Add at least one valid commodity line.
  6. Review quantity, UOM and rate precision.
  7. Review container plan and signatures where used.
  8. Save once.
  9. Search the exact generated agreement number/reference.
  10. Reopen Detail.
  11. Compare every header field and line with the intended agreement.

3.3 Create or verify the Purchase-to-Sales relation

  1. Create or identify both agreements first.
  2. Reopen the Purchase agreement through the current normal entry.
  3. Select the intended Sales agreement in the current linked-SO control when required.
  4. Save once.
  5. Reopen Purchase Detail and verify the stored link.
  6. Open Sales Detail/list and verify the reverse linked-Purchase projection.

Do not assume the relation is one-to-one, status-restricted or automatically execution-safe until the approved policy is documented.

3.4 Update before execution

Before changing lines:

  • inspect the execution section;
  • inspect known Inbound/Outbound references;
  • confirm no item-level execution pointer exists when the UI shows an empty header-level execution list;
  • understand whether current Save replaces the full line set and changes line IDs.

After Save:

  • reopen Detail;
  • compare every line ID/value;
  • verify linked execution references still point to the intended commercial line or have an explicit disposition.

3.5 Update after execution exists

Current behavior blocks or preserves selected type/item changes but does not define the full safe header edit policy.

Do not:

  • change Purchase to Sales or Sales to Purchase;
  • replace execution-used lines;
  • delete the agreement;
  • change material terms merely because the form allows it.

Record the intended field, existing execution IDs and business reason, then use the approved correction/amendment decision.

3.6 Status labels

Current values are manual labels.

DRAFT
OPEN
PARTIAL
FULFILLED
CANCELLED

Do not infer:

PARTIAL = execution quantity partly received/shipped
FULFILLED = all child orders complete
CANCELLED = agreement deleted or all children cancelled

until the process owner approves that policy.

3.7 Commercial timeout/unknown result

If create/update/relation/delete response is missing:

  1. do not repeat the same whole request;
  2. search by exact number/reference/date/counterparty;
  3. open Detail and compare header, lines, relation and execution references;
  4. use the committed result when correct;
  5. retry only a clearly absent command;
  6. stop and escalate partial or conflicting results.

4. Inbound Purchase

4.1 Search and create scheduled work

  1. Open MK Inbound Orders through the normal menu.
  2. Search by PO, reference, load, date and commodity.
  3. Open plausible matches.
  4. Select the intended Commercial Purchase and line when applicable.
  5. Enter header references, parties, timing and at least one item.
  6. Review commodity, quantity, UOM and net weight.
  7. Save once.
  8. Reopen exact Detail and verify header, all items and Commercial pointers.

A Commercial prefill is proposed input. It is not receipt evidence.

4.2 Scheduled edit through the shared editor

For an existing scheduled order:

  1. reopen complete Detail;
  2. verify no receipt/Scale/lot/allocation progress;
  3. edit the header and complete intended item set;
  4. stage only intended deletions;
  5. save once through the normal atomic-save flow;
  6. reread the complete header and all items.

If one validation fails, the intended atomic request should roll back. Do not split recovery into unrelated header/item writes without rereading the whole order.

4.3 Physical Scale receipt

The normal evidence chain is:

Scale check-in/Gross
-> Scale check-out/Tare
-> separate Inbound finalize
-> item and transload receipt state
-> exact Inventory Lot

Procedure:

  1. identify the exact Inbound order and items at Scale;
  2. complete the required Gross and Tare stages;
  3. confirm the Scale ticket is complete;
  4. do not treat ticket checkout as receipt completion;
  5. run the separate Purchase Inbound finalize command;
  6. reread:
  7. Scale ticket;
  8. Inbound header;
  9. every item;
  10. source transload(s);
  11. created/updated Inventory Lot(s);
  12. warehouse placement when applicable.

4.4 Scale complete, finalize failed

Possible state:

Scale ticket completed
+ Inbound items still scheduled or inconsistent
+ Inventory Lot absent

Recovery:

  1. preserve the ticket;
  2. reread exact order/items/transload/lot;
  3. correct only the finalize blocker;
  4. retry finalize only when the logical receipt is absent;
  5. do not repeat Scale checkout;
  6. do not manually create a second lot.

4.5 Complete without Scale

Use only when the current accepted eligibility applies.

Before submission verify:

  • intended order type/current policy;
  • no conflicting Scale or transload progress;
  • scheduled active item(s);
  • positive item net weight;
  • current source/cardinality supports exact lot materialization.

After submission reread:

  • no Scale ticket was created;
  • item state;
  • transload state;
  • exact lot and source identity;
  • balance and placement.

4.6 Next-work intent

Current choices may include:

WAREHOUSE_ONLY
DIRECT_OUTBOUND
MIXED

The current choice primarily controls the returned next page and is not a proven durable business state.

If the response/browser state is lost:

  • do not infer the choice from the received lot;
  • confirm the intended next action with the operator;
  • open Inventory or Allocation explicitly.

4.7 Post-receipt correction

Before any received-item edit/delete, inspect:

  • Scale evidence;
  • transload state;
  • Inventory Lot quantity, weight and remaining balance;
  • active allocations;
  • ledger/reversal history;
  • warehouse placement.

Do not change source quantity/weight through a normal item editor if it would reset remaining balance or bypass allocation/ledger history.

Use only an approved inventory-aware correction/reversal path.

4.8 Inbound unknown result

For create/save/finalize/no-scale/delete response loss:

  1. reread the order and all items;
  2. reread Scale ticket where applicable;
  3. reread transload and lot;
  4. classify not committed, committed, partial/conflict;
  5. repeat only the missing owner command;
  6. retain exact IDs for escalation.

5. Outbound Sales

5.1 Search and create requested demand

  1. Open MK Outbound Orders.
  2. Search by SO, reference, Booking, container and date.
  3. Open possible matches.
  4. Select Commercial Sales when applicable.
  5. Enter Ocean/Local fields, parties, Booking/container/size where applicable and requested lines.
  6. Save once.
  7. Reopen exact Detail.
  8. Verify header, all lines, Commercial/Booking references and equipment bridge.

5.2 Understand direct Save

Direct Outbound Save creates requested demand. It does not prove inventory allocation.

Outbound item exists
!= T_LOAD_ALLOCATION exists
!= Inventory Lot balance changed

A current UNMAPPED item means the demand has not been linked to an accepted source allocation.

5.3 Allocate inventory

  1. open Allocation Workbench through its normal entry;
  2. select the exact Outbound item/demand;
  3. inspect eligible source lots and current remaining quantity/weight;
  4. enter the intended allocation once;
  5. reread the allocation row;
  6. reread source lot remaining balance;
  7. return to Outbound Detail and verify the derived allocation projection.

Do not edit Outbound requested weight merely to make the allocation projection look complete.

5.4 Booking and equipment bridge

Before linking or changing Booking/container/size:

  • identify the exact Booking and Outbound Sales;
  • inspect existing equipment/equipment-load bridge;
  • inspect Scale/Delivery/Transload/Packing progress;
  • confirm the bridge is not execution-locked.

After link/save:

  • reread Outbound Detail;
  • reread Booking Detail;
  • confirm both sides show the intended relation;
  • confirm no unrelated bridge/container was remapped.

5.5 Readiness

Treat readiness as information only.

READY_FOR_FINAL_EXECUTION
!= allocated
!= packed
!= scale complete
!= delivered
!= Commercial Sales fulfilled

Open the owning child for completion evidence.

5.6 Edit allocated or progressed work

Before editing an allocated item or progressed bridge:

  • read all allocations and source lot balances;
  • read Scale, Delivery, Packing and Cost children;
  • identify whether the proposed field is safe metadata or changes business quantity/weight/source.

Do not use normal item update for allocation-affecting correction. Use an approved allocation-aware correction/unallocate/reallocate path.

5.7 Delete

Delete only an accepted unprogressed order.

Check:

  • Scale execution;
  • Delivery;
  • Allocation;
  • Transload linkage;
  • Outbound Cost;
  • Booking reverse pointer;
  • equipment bridge.

After delete:

  • verify the order/items are absent from active reads;
  • verify Booking pointer disposition;
  • verify no child was left pointing to deleted demand.

5.8 Outbound unknown result

Reread:

  • order header and items;
  • Booking and equipment bridge;
  • allocations and lot balances;
  • Scale/Delivery/Packing/Cost children.

Retry only the missing command. Never repeat allocation or physical work from an Outbound editor response alone.

6. Booking

6.1 Search before create

  1. open the normal MK Booking List;
  2. search by Booking number, invoice/order reference and date;
  3. include inactive records where the current surface permits exact review;
  4. open possible matches before create.

6.2 Create

  1. enter Booking Number, Shipping Line, Booking Type and required shipper/party information;
  2. review ports, cutoffs, vessel, terminals and planned container quantities;
  3. review independent flags;
  4. select the exact Outbound Sales link when required;
  5. save once;
  6. reopen exact Booking Detail;
  7. verify invoice number, header, flags and Sales link;
  8. inspect every child/handoff that current compatibility logic may have affected.

6.3 Current compatibility warning

Current Booking Save may run compatibility work beyond the Booking row.

Possible affected children include:

execution order
order items
inventory lots
allocations
linked transload-derived state

Therefore:

Booking success
!= every child synchronized correctly

When a Booking Save changes unexpected child data or logs an internal sync error:

  • preserve Booking and all child IDs;
  • stop dependent allocation/financial/output work;
  • reread each child owner;
  • do not submit Booking Save repeatedly as a repair.

6.4 Update

Before update:

  • reopen current Detail;
  • verify Sales link and active children;
  • identify exactly which Booking-owned fields should change.

After update:

  • reread Booking-owned fields;
  • reread Sales link on both sides;
  • inspect current compatibility child disposition;
  • treat any partial/unknown child result separately.

6.5 Clone

Current clone can carry selected header values and flags but does not prove child containers/files were cloned.

Procedure:

  1. review the source Booking carefully;
  2. confirm intended clone count;
  3. submit once;
  4. search every expected generated suffix/number;
  5. open every clone;
  6. review invoice, flags, inactive state and Sales link;
  7. verify containers/files/allocations were not assumed to exist;
  8. on response loss, search before retry.

6.6 Mark inactive

NOT_IN_USE is a manual marker.

Before changing it:

  • inspect linked Sales order;
  • inspect container/equipment and output children;
  • understand current list/clone/edit behavior.

After changing it:

  • reread the flag;
  • record remaining active children;
  • do not report cancellation or cleanup unless separate owner commands completed.

6.7 Booking unknown result

  1. search exact Booking/invoice number;
  2. open Booking Detail;
  3. reread linked Sales order;
  4. reread affected order/item/lot/allocation children;
  5. classify Booking commit and each child result separately;
  6. repeat only a clearly missing owner command;
  7. escalate partial or unknown compatibility results.

7. Order-First Daily Reconciliation

For each active logical work set, record only applicable children.

Child Required evidence Disposition
Commercial exact agreement/lines and accepted status/relation Complete/Pending/Not applicable/Conflict
Inbound scheduled or received order/items Complete/Pending/Conflict
Scale ticket/stage evidence when physical Scale applies Complete/Pending/Not applicable
Inventory Lot exact source lot and balance after receipt Complete/Pending/Conflict
Outbound requested demand and child references Complete/Pending/Conflict
Allocation exact allocation and source balance when required Complete/Pending/Not applicable/Conflict
Booking exact Booking/link/flags when required Complete/Pending/Not applicable/Conflict
Physical/output children owning evidence only Complete/Pending/Not applicable/Conflict

Composite close is a review result, not one stored state.

8. Common Recovery Matrix

Symptom Possible committed result Reread first Safe next action Do not repeat
Commercial create timeout agreement/lines may exist number/reference/date/counterparty/detail use existing or create only when absent full create blindly
Commercial update conflict newer line/header may exist full detail + execution refs reconcile one intended change stale line set
Scale checkout done/finalize absent ticket exists, receipt absent ticket + order/items/transload/lot finalize only checkout
Inbound lot conflict item/transload/lot disagree exact source chain owner reconciliation manual second lot
Outbound direct Save shows no allocation demand exists only item + allocations + lot use Allocation Workbench Outbound Save
Allocated item edit conflict demand/allocation/lot can diverge all three approved allocation-aware correction generic item update
Booking Save timeout Booking and some child changes may exist Booking + linked Sales/order/item/lot/allocation continue only missing owner command Booking Save
Clone timeout clones may exist request/base/suffix/detail use exact existing clones clone batch
Delete leaves pointer source deleted, relation stale both sides explicit link reconciliation raw pointer edit

Universal rule:

Reread the owning record and every expected child before repeating a business or physical action.

9. Escalation Packet

Include:

tenant/profile
operator and role
page/action
request ID or timestamp
Commercial agreement and line IDs
Inbound/Outbound order and item IDs
Booking ID/number
Scale ticket ID
Transload ID
Inventory Lot ID and current balance
Allocation ID
Equipment/Equipment Load ID
before/after status and values
which action may have committed
which child is missing or inconsistent
what has already been retried
screenshots without credentials or restricted data

Do not include passwords, access tokens, provider secrets or raw restricted customer data in repository documentation.

10. Stable Wiki Topics

mk-operations
mk-dashboard
mk-commercial-orders
mk-inbound-orders
mk-outbound-orders
mk-booking
mk-schedule-allocation
mk-scale
mk-documents

The future React/Next.js route may change. The operator topic should remain stable where practical.

11. Current Limitations Requiring Review

  • exact target-role menu/page/API matrix;
  • Commercial status/relation/post-execution policy;
  • multi-line receipt and lot policy;
  • no-scale eligibility and branch-intent persistence;
  • post-receipt inventory-aware correction;
  • allocated outbound correction/unallocate;
  • Booking/Sales pointer cleanup;
  • Booking clone/inactive policy;
  • hidden Booking compatibility side effects;
  • current Wiki content/screenshots and field acceptance.

---

Source: docs/runbooks/MK_COMMERCIAL_INBOUND_OUTBOUND_BOOKING_OPERATOR_RUNBOOK.md — ctc repository · Rewritten from the source document as a first-time operator guide. The source remains the record of identifiers, file paths and code symbols.