Freight ERP user manual

This manual describes the screens as they behave in this build. Each chapter names the sidebar link, the fields, the buttons, and the messages the application actually shows. Pictures were taken from the synthetic Nile Freight demo. A picture that was not taken is named in the chapter, with the reason, and again in the screenshot index.

How to find something: open the HTML copy and use the search box, or use the contents. Procedures are at the end of each chapter. Words used on the screens are in the glossary. The first screen for each role is in the quick start.

Counts from the coverage file, after the chapters were written:

What is not described as a working screen is the old two-factor page and its controls. That page is no longer part of the application, and the gaps report names it as a specification disagreement. The four acceptance scenarios that are not described are LIVE03–LIVE06, which wait for a live mail, tax, payment or hosting test. They were not run, and they are not marked passed.

828 manual test cases are in the workbook. All of them are Not run.

1. Getting started: sign-in, navigation, dashboard and search

This chapter explains how to sign in, how to find your way around the staff application, what the dashboard shows and how search works. It also lists, for every default role, which parts of the application the role unlocks. Every internal user needs it: Platform administrator, Security administrator, Company administrator, Branch manager, Sales representative, Sales manager, Pricing officer, Pricing manager, Operations coordinator, Operations manager, Documentation officer, Customs coordinator, Warehouse or dispatch user, AR accountant, AP accountant, Treasury user, Finance manager, Executive and Auditor. Customer and agent portal users (Customer viewer, Customer collaborator, Customer organization administrator, Agent viewer, Agent collaborator) use the same sign-in page but get the portal shell, which is described in the portal chapters.

Permission keys used in this chapter: dashboard.finance.view (financial position on the dashboard), operations.task.view, operations.alert.view, crm.enquiry.list, operations.shipment.view, operations.job.view, partners.partner.list (dashboard sections and search), system.health.view (health link). Every sidebar link is shown by a permission prefix (see The staff shell). The key dashboard.view is seeded on every internal role, but the code does not check it: any signed-in internal user can open the dashboard (see the gaps file).

References: Spec §19.1 (user lifecycle, MFA, reset), §19.2 (permission model: "UI menus only reflect access; they do not enforce it"), §19.3 (default roles), §20 (screens), §25 (security), §33.4 (portal roles). UML 02 (identity and authentication), UML 03 (scoped authorization).

How errors look. Most refusals in this application appear on one of two pages. When you open a page you may not see (HTTP 403) or a record that does not exist in the active company (HTTP 404), the message appears inside the normal application layout, in your language. When a form you submit is refused (any POST), a plain page shows the status number, a heading, the exact refusal message, a Return to the start page button and a "Reference" code. That plain page is always in English. Use the browser's Back button to return to your form. Quote the Reference code when you report a problem.

Sign in

How to open it: go to /login (staff) or /portal/login (portal users; same form). Any page you open without a valid session sends you here. The page uses the sign-in layout: a short pitch on the left ("Freight operations, finance and customer service in one place.", "Authorised users only. Activity is recorded.") and the form on the right. The left side is hidden on screens narrower than 1200 px. Arabic: Sign in (تسجيل الدخول).

The page shows the heading Sign in, the text "Use your work email and password.", the form, a Forgot password? link and a language button (العربية / English) at the top.

Fields

Actions

Rules and messages

• Wrong email or password, or an inactive account: "The email or password is not valid." (HTTP 401). The message does not say which part was wrong.
• After 5 failed attempts for the same email from the same IP address within 15 minutes: "Too many sign-in attempts. Try again later." (HTTP 429). The lock lifts when the 15-minute window passes. Each refused attempt is recorded in the audit log as a failed sign-in.
• The form carries a hidden form token. If the page was open too long or the token is missing, the post is refused with HTTP 419 "The form token is not valid. Reload the page and try again." on the plain error page, heading "Form expired".
• A successful sign-in records the audit event auth.login.

Role differences

None on this page. After sign-in, internal users get the staff shell; external (portal) users get the portal shell. A correct password opens the dashboard for every role. There is no code page.

Forgot password

How to open it: Forgot password? on the sign-in page, or /password/forgot. Arabic: Reset password (إعادة تعيين كلمة المرور).

The page shows "Reset password", the text "Enter the email address of your account.", the form and a Back to sign in link.

Fields

Actions

Rules and messages

After submitting, the page always reads: "If the account exists, a reset token was created. Reset emails are not sent by this installation yet, so the token is not sent and is not shown here. Ask an administrator to reset your password."

Known defect D8: reset emails are not sent. The token is created but no email goes out, so a user cannot finish a reset on their own. Ask an administrator.

Role differences

None.

Reset password

How to open it: /password/reset with a reset token in the link. Because reset emails are not sent (D8), a user normally never receives this link. Arabic: Choose a new password (اختر كلمة مرور جديدة).

Fields

Actions

Rules and messages

• "Use at least 12 characters with a letter and a number."
• "This reset link is not valid." (wrong, used or expired token; tokens expire after 30 minutes and work once).

Role differences

None.

The staff shell: sidebar, header and session

How to open it: every staff page after sign-in uses this shell (layouts/app). This is the staff application shell. Arabic labels for the sidebar groups: Workspace (مساحة العمل), Sales (المبيعات), Operations (العمليات), Finance (المالية), Master data (البيانات الرئيسية), Administration (الإدارة).

Numbered parts in the annotated shot: 1 company switcher, 2 sidebar navigation, 3 header search box, 4 language button, 5 alerts bell, 6 user menu.

Sidebar

The sidebar lists only the links you can use. A link is shown when you hold at least one allowed permission whose key starts with one of the prefixes below. Hiding a link never grants or removes access: the page itself checks permissions again, and a direct URL to a page you may not see returns "Not allowed". A group with no visible link is not shown.

Below the links the sidebar footer reads "Times shown in {tz}" (your display time zone). The page footer reads "Figures come from recorded data only."

Header

• Open navigation (فتح قائمة التنقل) button: shown only on narrow screens (below 992 px). It slides the sidebar in.
• Search box with the placeholder "Search jobs, shipments, customers…". Press Enter to open /search. Below 576 px the box is hidden and a search icon links to /search instead.
• Company name badge: shown on wide screens (992 px and up).
• Language button: shows العربية in English and English in Arabic. It opens /locale?lang=ar or /locale?lang=en.
• Alerts bell: shown only if you hold operations.alert.view. The red number counts open alerts that are assigned to you or not assigned to anyone, capped at 99.
• User menu: your initials and name. It shows "Signed in as" with your name and a Sign out (تسجيل الخروج) button. There are no other entries (no profile or password change page for staff).

Session timeout

Your session ends after 30 minutes without activity (setting security.session.idle_timeout, default 1800 seconds) and in any case 8 hours after sign-in (default 28800 seconds). Every page you open extends the idle time. Two minutes before the idle limit, a banner says "Your session will expire soon because of inactivity. Save your work." At the limit it says "Your session has expired. Sign in again to continue." The next page you open sends you to /login. A session also ends when an administrator revokes it, when your account is deactivated, or when your password is reset.

Fields

Actions

Rules and messages

• Choosing a company you are not a member of: HTTP 403 "That company is not in your memberships."
• If you have no active company, the first active membership is used when you sign in.
• Any form posted with a missing or old form token: HTTP 419 "The form token is not valid. Reload the page and try again."
• While a backup or restore is running, every form post is refused with the plain text "Writes are paused while a backup runs. Try again in a few minutes." (HTTP 503). Pages can still be read. Sign out is also blocked during that time (known defect D19).

Role differences

The sidebar content depends entirely on your roles; see Roles and what each role sees. The alerts bell is hidden without operations.alert.view.

Mobile and off-canvas navigation

On screens narrower than 992 px the sidebar is hidden off the edge of the screen. Tap Open navigation to slide it in; a dark backdrop covers the page. Tap the backdrop or press Escape to close it. Below 576 px the search box is replaced by a search icon and text labels next to header icons are hidden.

Arabic and right-to-left layout

Choose العربية in the header (or on the sign-in page). The whole page switches to right-to-left: the sidebar moves to the right, the right-to-left Bootstrap stylesheet is loaded and the off-canvas sidebar slides in from the right. Labels and messages come from the Arabic catalogue. Codes, references and numbers stay left-to-right inside the text. Two exceptions stay in English: the plain error page for refused form posts, and messages that have no Arabic translation (for example the heading "Form expired").

Staff dashboard

How to open it: sidebar Workspace > Dashboard, or /dashboard (also /). Arabic: Dashboard (لوحة المعلومات).

The subtitle reads "Recorded work and figures for the active company. Sections follow your permissions." Each section appears only if you hold the permission shown below. If you have no active company, the page shows "No active company" and "Choose a company in the sidebar to see its work and figures."

Fields

The dashboard has no forms.

Actions

Rules and messages

Figures are read from recorded data only. Financial figures are posted balances; drafts are not included.

Role differences

A Sales representative sees only Approvals waiting, Open enquiries and Partner profiles. An AR accountant sees Approvals waiting and Financial position. A Platform administrator sees Approvals waiting and the Open system health link. See the role table below.

Global search

How to open it: type in the header search box and press Enter, or open /search?q=…. Arabic: Search (بحث).

The page title is Search with the subtitle "Partners in the active company that match your search." It has one panel, Partners (الشركاء), with a count and the columns Code and Legal name. If nothing matches: "No partners matched this search in the active company."

Search covers partners only, although the header placeholder mentions jobs, shipments and customers. The search page itself has no search box: you search from the header. On phones (below 576 px) the header box is hidden, so you cannot type a new search there (see the gaps file).

Fields

Actions

Rules and messages

Results come only from the active company.

Role differences

Users without partners.partner.list (for example Pricing officer, AR accountant, Executive, Auditor) always get the empty result.

Error and message pages

How they appear: automatically, when a request is refused. This is the error/message page. Arabic: Not allowed (غير مسموح), Not found (غير موجود).

The page Module unavailable opens from /unavailable links: heading Not installed (غير مثبت), "This module is not installed yet. No sample data is shown." and Back to dashboard.

Fields

None.

Actions

Rules and messages

The Reference code on the plain page identifies the request in the technical log. Give it to support.

Role differences

Portal users get portal message pages instead: for a staff address they see "Not found" and "That page does not exist or is not shared with you." (HTTP 404).

Installer and portal layouts

Two more layouts exist. The installer layout (/install, title "Freight ERP · Installer") is used only before the application is installed, behind the setup secret; it is described in the administration chapter. The portal shell (/portal/* and the portal /dashboard) is used by external users: links Overview, Shipments, Enquiries, Notifications (with unread count), Invoices (only when billing is shared), Exports, Members (organization administrators), Switch organization (several organizations), Profile, Security, the language link and Sign out, which posts to /logout. The portal is described in the portal chapters.

Roles and what each role sees

The table lists the default roles as seeded (EssentialSeed::roleCatalog). Roles are editable templates, so your installation may differ. A person may hold several roles; the sidebar then shows the union. No role asks for a second sign-in code.

Notes:

• The Approvals link is shown to any role with an operations permission, but /approvals and the "Approvals waiting" KPI are open to every internal user. An Executive or AR accountant can open /approvals by URL and sees only requests their permissions allow them to decide.
• /commissions never returns Not allowed: users without commission rights see "You can read your own statement only." (chapter 3).
• /organization has no permission check (known defect D12): roles without an organization. permission do not see the link but can open the page by URL.

Procedures

Sign in

1. Open /login.
2. Enter your work email in Email and your password in Password.
3. Select Sign in.
4. The dashboard opens.

Change language

1. In the header, select العربية.
2. The current page reloads in Arabic, right to left.
3. To go back, select English in the header.

Switch company

1. In the sidebar, open the Company list.
2. Choose the company. The page changes to /dashboard for that company.
3. Check the company name in the header badge (wide screens).

Find a partner

1. Type part of the partner name or code in the header search box.
2. Press Enter.
3. Open the result you need from the Partners panel.

Sign out

1. Open the user menu (your initials, top right).
2. Select Sign out. The sign-in page opens.

Request a password reset

1. On the sign-in page select Forgot password?.
2. Enter your Email and select Request reset.
3. Read the notice. Because reset emails are not sent (D8), ask an administrator to reset your password.

Troubleshooting

2. My work: activities, tasks, alerts and approvals

The Workspace group collects the work that is waiting for you: sales follow-ups (My queue), operational tasks, alerts raised by the scheduled scan, and approval requests that need a second person. Sales representatives and Sales managers use My queue (crm.activity.manage). Operations coordinators, Operations managers, Customs coordinators, Branch managers, Documentation officers, Warehouse or dispatch users and Company administrators use Tasks (operations.task.view, operations.task.manage). Operations roles, Branch managers and Company administrators use Alerts (operations.alert.view, operations.alert.manage). Anyone who holds a decide permission for an approval type uses Approvals: Operations manager (operations.release.approve, operations.exception.approve, operations.cost_estimate.approve, operations.commitment.approve), Company administrator (operations.cost_estimate.approve) and Finance manager (finance.claim.approve, finance.disbursement.approve).

References: Spec §5.1 and §5.2 (activities), §12 (milestones, tasks, exceptions and approvals), §19.2 (maker-checker). UML 07 (CRM activities), UML 12 (tasks), UML 03 (approvals), UML 38 (queue task lifecycle).

When a form post is refused, a plain English page shows the status, the heading "The request could not be completed" (409 or 422) or "Not allowed" (403), the exact message and a Reference code. Use the browser's Back button to return. Successful posts return to the list without a success message; check the row's new status.

My queue

How to open it: sidebar Workspace > My queue, route /activities. Customer 360 also has a My queue button. Arabic: My queue (قائمة أعمالي).

The page title is My queue, subtitle "Follow-ups and tasks assigned to you." Three KPIs count your activities: Open (مفتوح), Overdue (متأخر, open with a due date before today, UTC) and Due today (مستحقة اليوم). Selecting a KPI opens that view.

The Queue view tabs (عرض القائمة) are Open (/activities?view=open), Overdue (?view=overdue) and Closed (?view=done, done or cancelled). The table columns are Due, Kind, Subject, Customer, From and Status. Status values: open (to do), done (completed, with the outcome), cancelled. A second list, Assigned by me (أسندتها أنا), shows open activities you created for other people.

Fields

New activity form (posts to /activities):

Row forms on open activities:

Actions

Rules and messages

• "Choose a follow-up, task, call, meeting or note."
• "Subject is required (up to 200 characters)."
• "Due date must be a date."
• "A follow-up or task needs a due date."
• "Notes are limited to 2000 characters."
• "The outcome is limited to 500 characters."
• "Activities can only be assigned to active internal members of this company." (422)
• "Customer was not found." / "The related record was not found." (404, when a customer or record link is wrong)
• "Activity was not found." (404)
• "Only the assignee or the person who created this activity can change it." (403)
• "This activity is already closed." (409)

Role differences

Without crm.activity.manage the sidebar hides My queue and /activities shows "Not allowed". Only the assignee or the creator can complete or reassign; other users get the 403 message above.

Tasks

How to open it: sidebar Workspace > Tasks, route /tasks. The dashboard link Open queue also leads here. Arabic: Tasks (المهام).

Subtitle: "Open tasks from milestones, templates and manual entry. Overdue tasks are highlighted." Tasks come from milestone templates, task templates and manual entry on a job (see the jobs chapter). The Task scope tabs (نطاق المهام) are Mine and my teams (/tasks?scope=mine: tasks you own, plus tasks with no individual owner whose team is one of your teams) and All open (/tasks?scope=all). A header link Templates opens /task-templates (jobs chapter).

The task table partial has the columns Task, Job, Owner or team, Due, Priority (normal or high), Checklist (done/total) and Status. Overdue rows are highlighted. Empty list: "No tasks." Only open tasks are listed.

Fields

The list has no form.

Actions

Rules and messages

Without operations.task.view, /tasks shows "Not allowed".

Role differences

Sales, pricing, finance (except where an operations permission is held), Executive and Auditor roles do not see Tasks.

Task detail

How to open it: select a task title in Tasks, or a task on a job; route /tasks/{id}. Arabic: Checklist (قائمة التحقق), Cancel task (إلغاء المهمة).

Numbered parts in the annotated shot: 1 summary, 2 checklist, 3 comments, 4 Complete, 5 Reassign, 6 Cancel task.

The summary shows Job, Owner, Due, Priority and Status. Status values: open, done, cancelled. If the task depends on another task, a notice says "Depends on {task}; it cannot be completed first." A cancelled task shows its cancel notice. Then come the Description, the Checklist (each item is a toggle button; items marked "(optional)" do not block completion) and Comments.

Fields

Actions

The routes above are grouped in the fact pack as /tasks/{id}/(complete|cancel|reassign|comment).

Rules and messages

• "Only an open task can be completed." (409)
• "Complete the task this one depends on first." (409)
• "Tick the required checklist items first." (409)
• "Only an open task can be cancelled." (409)
• "Choose an owner or a team." (422)
• "Only an open task can be reassigned." (409)
• "The owner must be an active internal user of this company."
• "Reason is required." / "Reason is too long."
• "Comment is required." / "Comment is too long."
• "Team is too long."
• "Checklist item was not found." (404) / "The task is closed." (409)
• "Task was not found." (404)

Role differences

The Complete, Reassign, Cancel and Comment controls are shown to anyone who can open the task. Users with operations.task.view but without operations.task.manage (none of the default roles) would get "You do not have permission for this action." when they press them.

Alerts

How to open it: sidebar Workspace > Alerts (with the open count), the header bell, or the dashboard link All alerts; route /alerts. Arabic: Alerts (التنبيهات), Alert status (حالة التنبيهات).

Subtitle: "Alerts are raised by the scheduled scan (overdue tasks and pickups, approvals waiting too long, completed jobs not invoiced, customs holds). Each rule raises at most one alert per entity per window." The scan runs from the scheduled cron task (Developer-assisted to trigger). Rules and severities: task overdue (warning), pickup overdue (critical), approval waiting over 24 hours (warning), completed job not fully billed (warning), customs hold or inspection (critical). An alert still open (not acknowledged) 24 hours after it was raised is escalated once: its severity becomes critical and the row shows "escalated". When a snooze time passes, the next scan sets the alert back to open.

Scope buttons: Mine and unowned (/alerts?scope=mine, default) and All (?scope=all). The Alert status tabs: Active (default: everything not resolved), Open, Acknowledged, Snoozed and Resolved (&status=active|open|acknowledged|snoozed|resolved). Columns: Alert (title and rule key), Severity (and "escalated"), Job, Owner ("Unowned" if none), Raised, Status (with "until …" for snoozed and the resolution note for resolved) and Action.

Status meanings: open (new), acknowledged (someone has seen it), snoozed (hidden from attention until the time shown), resolved (closed with a note).

Fields

Actions

These are grouped in the fact pack as /alerts/{id}/(acknowledge|snooze|resolve). After each action you return to /alerts.

Rules and messages

• "Snooze until a time within the next 14 days."
• "Snooze until must be a UTC date and time."
• "Resolution note is required."
• "Alert was not found." (404)
• "This alert cannot move to {to} from {status}." (409, for example resolving an already resolved alert from an old page)

Role differences

Without operations.alert.view the Alerts link and the header bell are hidden and /alerts shows "Not allowed". The action buttons are not hidden for viewers without operations.alert.manage; the server refuses them.

Approvals

How to open it: sidebar Workspace > Approvals, or the dashboard link Open approvals; route /approvals. The sidebar link is shown only to roles with an operations permission, but the page opens for every internal user. Arabic: Approvals (الموافقات), Waiting for your decision (بانتظار قرارك), Your requests (طلباتك).

Subtitle: "Each request is fixed to the exact facts it was raised for. You cannot approve your own request, and an approved request is used once; if the facts change before it is used, it becomes stale."

Requests are raised from other screens (jobs, consolidations, customs, claims). The types are:

Waiting for your decision lists pending requests of the types you may decide, raised by someone else. Columns: Request (number, label and amount), Job, Requested by, Reason, Facts (the fixed details), Expires and Decision. Empty: "Nothing is waiting for you."

Your requests lists your own last 50 requests: Request, Job, Status, Decided by, Note and Used. Status values: pending (waiting), approved (may be used once), rejected, expired (not decided in time), consumed (used by the action it authorised). When the facts changed before use, the action refuses with "The situation changed after the approval. Ask for a new approval of the current details." Empty: "No requests."

Fields

Actions

Rules and messages

• "Approval request was not found." (404)
• "This approval action is no longer configured." (409)
• "Decision note is required." (when rejecting) / "Decision note is too long."
• "This request is not waiting for a decision." (409)
• "The requester cannot decide their own request." (409)
• "This request expired before it was decided. Ask for a new one." (409; the request is marked expired)
• "You do not have permission for this action." (403, no decide permission for the type)

Role differences

Each user sees only the types they may decide. A Pricing officer, Executive or AR accountant normally sees "Nothing is waiting for you."

Your own requests never appear in your decision list.

Procedures

Add a follow-up for yourself

1. Open Workspace > My queue.
2. In New activity, choose Kind Follow-up.
3. Enter the Subject and a Due on date.
4. Leave Assign to on your name and select Add.
5. The activity appears under Open.

Close a follow-up

1. Open My queue, tab Open.
2. In the row, type what happened in Outcome.
3. Select Done. The row moves to Closed.

Complete a task with a checklist

1. Open Workspace > Tasks and select the task title.
2. Select each required checklist item to mark it done.
3. Optionally add a comment in Add a comment and select Comment.
4. Select Complete. The status becomes done.

Hand a task to a team

1. Open the task.
2. In Reassign, choose "No individual owner" in New owner and type the team in Team.
3. Select Reassign.

Snooze an alert until tomorrow morning

1. Open Workspace > Alerts.
2. In the alert row, enter a time in Snooze until (UTC). Remember it is UTC, not your local time.
3. Select Snooze. The alert moves to the Snoozed tab.

Decide an approval request

1. Open Workspace > Approvals.
2. Read Reason and Facts in the row.
3. Type your Decision note.
4. Select Approve, or Reject and confirm "Reject this request?".

Troubleshooting

3. Sales and CRM: enquiries, leads, customers, rates and commissions

This chapter covers the commercial front end: capturing leads and enquiries, the customer list and the Customer 360 page with credit control, the rates and tariffs workbench (rate search, charge calculation, selling suggestion, chargeable-weight policies and margin rules), and sales commissions.

Who uses it:

• Sales representative: enquiries and leads (crm.enquiry.list, crm.enquiry.create), customers (crm.customer.view), activities (crm.activity.manage), selling tariffs (pricing.sell_rate.view), selling suggestions (pricing.quotation.create) and their own commission statement (sales.commission.view).
• Sales manager: as Sales representative, plus account owners and customer financials (crm.customer.manage, crm.customer.financials.view), commission rules and settlements (sales.commission.manage, sales.commission.approve) and margin rule approval (pricing.margin.approve).
• Pricing officer: tariffs and buy rates (pricing.sell_rate.view, pricing.sell_rate.configure, pricing.buy_rate.view, pricing.buy_rate.configure); reads enquiries (crm.enquiry.list).
• Pricing manager: as Pricing officer, plus margin rules (pricing.margin.configure, pricing.margin.approve).
• AR accountant: customers with financials and the credit limit (crm.customer.view, crm.customer.financials.view, crm.credit.manage).
• Finance manager: as AR accountant, plus credit override decisions (crm.credit.approve); holds sales.commission.approve but cannot reach the commission screens (see the gaps file).
• Company administrator: enquiries, leads, customers and owners, selling tariffs and policies.

References: Spec §5.1 (leads and opportunities), §5.2 (customer management), §5.3 (commercial handoff and commission rules), §4.1 and §15 (credit limits and exposure), §6.1 (buying rates), §6.2 (pricing engine). UML 07 (CRM pursuit), UML 08 (rate contracts, tariffs and pricing), UML 04 (partners and commercial profiles). Acceptance scenarios A02 (hidden buy cost), A06 (chargeable weight example), A25 (CSV formula safety).

When a form post is refused, a plain English page shows the status, the heading "The request could not be completed" (409 or 422) or "Not allowed" (403), the exact message and a Reference code. Use the browser's Back button to return; the values you typed may be lost. A successful post returns to the page without a success message.

Enquiries and leads

How to open it: sidebar Sales > Enquiries and leads, route /enquiries. Arabic: Leads and enquiries (العملاء المحتملون والاستفسارات).

The page title is Leads and enquiries, subtitle "Open enquiries are company records. No sample pipeline is shown." The left column has two lists; the right column has two forms.

• Enquiries: Reference (for example E-…), Customer, Route (origin to destination) and Status, with a "Filter this page…" box that filters the rows already shown. Statuses: pricing (recorded directly or accepted from booking intake, waiting for a quotation) and qualification (converted from a lead). Enquiry rows have no detail page. Empty: "No enquiries recorded."
• Leads: Reference (L-YYYY-000001), Company and Status, with row buttons. Statuses: new, assigned, contacted, qualified, disqualified and converted. The screen offers Qualify (for new, assigned and contacted leads) and Convert (for qualified leads). There are no buttons for assigned, contacted or disqualified. Empty: "No leads recorded."

Fields

New enquiry (posts to /enquiries):

New lead (posts to /leads). The lead fields are generated from one list in the template (fact pack label $label [$name]); each is shown below by its label and submitted name:

Row form on a qualified lead:

Actions

Rules and messages

• "Customer profile was not found." (404, customer missing or inactive)
• "Origin is not valid." / "Destination is not valid."
• "Commodity is required." / "Requirements is required." (also shown when the text is longer than 1000 characters)
• "Source is required." / "Company name is required."
• "Email is not valid."
• "A lead with this email already exists: {reference}." (409)
• "That lead transition is not allowed."
• "Only a qualified lead can be converted." (409)
• "Origin is required." / "Destination is required." / "Commodity is required." when converting a lead saved without them.
• "Lead was not found." (404)

Role differences

• Without crm.enquiry.list (for example Branch manager, Operations roles, AR accountant) the link is hidden and /enquiries shows "Not allowed".
• Pricing officer and Pricing manager can see both lists and both forms but hold no crm.enquiry.create; saving, qualifying or converting ends in "You do not have permission for this action."

Customers

How to open it: sidebar Sales > Customers, route /customers. Arabic: Customers (العملاء).

Subtitle: "Company customer profiles. Open one for contacts, quotations, bookings, jobs, activities and, with financial permission, balances and credit." Empty search: "No customers match." / "Try a different name or code."

The header has the buttons Commissions and My queue. The search form filters by name or code and shows "{n} shown". Columns: Customer (link to Customer 360), Code, Status, Payment terms and Account owner ("Not assigned" when empty). At most 200 rows are shown.

Fields

Actions

Rules and messages

Without crm.customer.view, /customers shows "Not allowed".

Role differences

Pricing officers, Pricing managers, operations roles, AP accountant, Treasury user, Executive and Auditor do not see the list.

Customer 360

How to open it: select a customer in Customers; route /customers/{id}. Arabic: Credit control (مراقبة الائتمان).

Numbered parts:

1. Overview, with the Set account owner form.
2. Credit control: Limit, Exposure and Available, the exposure components and the overrides table.
3. The credit limit form (Save limit).
4. The override request form (Request override).
5. Recent activity, with the Add activity form.

The title is the customer's legal name (with the Arabic name under it if recorded) and its status. The Sections tabs jump within the page: Overview, Credit control and Receivables ageing (only with financial access), Commercial, Jobs and Recent activity.

• Overview: Code, Payment terms ("not set"), Account owner and Collections owner ("not assigned").
• Credit control (financial access only): with no limit, "No credit limit is set. Bookings and invoices are not credit-checked for this customer." With a limit: KPIs Limit ("Plus approved overrides {amount}"), Exposure and Available ("Within limit" or "Limit exceeded"), and a table of exposure components: Open posted receivables, Draft invoices, Unbilled job sell lines, Open bookings without job sell lines, Less unapplied receipts. "Other currencies are converted through the base currency at the latest company rate on or before {date}." Then the overrides table: Override, Valid until, Reason, Requested by, Status (pending, approved, rejected; "by {name}"), Actions.
• Receivables ageing (financial access only): a total per currency and the open invoices with Invoice, Date, Days and Open amount ("No open receivables.").
• Commercial: Contacts, Open quotations ("Revision {n}", "valid until {date}") and Bookings.
• Jobs: jobs for this customer in your scope ("None in your scope.").
• Recent activity: the latest activities and an add form.

Fields

Set account owner (posts to /customers/{id}/owner):

Credit limit (posts to /customers/{id}/credit-limit):

Credit override request (posts to /customers/{id}/credit-overrides; shown only once the customer has a limit):

Add activity (posts to /activities; same rules as My queue in chapter 2, and the activity is linked to this customer):

Actions

Rules and messages

• "Customer was not found." (404; also for a customer of another company)
• "The account owner must be an active internal member of this company." (422)
• "Reason is required (up to 500 characters)."
• "Credit limit is not a valid amount." / "Credit limit cannot be negative."
• "Credit limit currency is not an active currency." (422)
• "Override amount must be greater than zero."
• "Valid until must be a date." / "Valid until cannot be in the past." (422)
• "Set a credit limit before requesting an override." (409)
• "Credit override was not found." (404)
• "This override was already decided." (409)
• "Another person must decide a credit override you requested." (409)

Credit limits and overrides take effect at booking and invoicing (chapter 4 and the receivables chapter). The policy for which customers get which limit is an open question (OPEN_QUESTIONS Q14); the system does not set one.

Role differences

• Without crm.customer.financials.view (Sales representative, Company administrator), Credit control and Receivables ageing are not shown and the limit is removed from the server response.
• Sales manager sees credit figures but cannot change the limit (no crm.credit.manage).
• AR accountant can change the limit and request overrides, but cannot decide them.
• Finance manager can change limits, request overrides and decide overrides requested by someone else.
• The owner form appears only with crm.customer.manage; the activity form only with crm.activity.manage.

Rates and tariffs

How to open it: sidebar Sales > Rates and tariffs, route /tariffs. The Quotations page has a Selling tariffs button that leads here. The page title is Tariffs (التعريفات). Arabic: Find rates (البحث عن الأسعار), Chargeable-weight policies (سياسات الوزن المحتسب), Margin rules (قواعد الهامش).

Numbered parts:

1. Find rates.
2. Calculate a charge.
3. Selling suggestion.
4. The Selling tariffs and Buy rates tables, with their add forms.
5. Chargeable-weight policies.
6. Margin rules.

Subtitle: "Selling tariffs are stored separately from buying rates. Overlapping matches stay listed with priority and explanation; the engine does not choose one." The Sections tabs are Find rates, Calculate, Selling suggestion (only with pricing.quotation.create), Rates, Chargeable-weight policies and Margin rules.

• Find rates shows, for Selling tariffs (and Buy rates if you may see them), one of: "No rate covers this lane, mode and date.", "One rate covers this lane, mode and date." or, when several overlap, "Several rates overlap at the same top priority. Choose one explicitly." / "Several rates overlap. Priorities and explanations are listed; choose one explicitly." Each candidate shows "#{id}, priority {priority}", the basis, amount, breaks and explanation.
• Calculate a charge saves a calculation and shows "Calculation {id} ({kind} rate)" with the volume, volumetric and chargeable weight, "Billable {quantity}, unit rate {rate}", any "{limit} applied" (minimum or maximum) and the Amount. The calculation id can be linked to a quotation (chapter 4).
• Selling suggestion: "Uses the buy rate for the lane and the approved margin rule. Cost is shown only to users who may see buy rates." The result shows "Suggested sell … for {n} billable unit(s), calculation {id}.", the rule ("Rule: {rule} (minimum margin {margin}%).") and, for buy-rate viewers only, "Cost {amount} {currency} from buy rate {id}." If several buy rates match, they are listed and you must give a buy rate number.
• Selling tariffs and Buy rates tables: #, Provider (buy only), Lane, Mode, Basis, Rate, Min / max, Breaks, Validity, Priority and Explanation. Expandable forms Add selling tariff and Add buy rate appear for users who may configure them.
• Chargeable-weight policies (one per mode): "Per mode. Nothing is assumed: a chargeable-kg or revenue-ton rate cannot be calculated until its mode has a policy." Columns Mode, Measure, Divisor, Volume factor, Method, Rounding, Pivot and Explanation.
• Margin rules: Scope (mode or "any mode", charge or "any charge"), Markup, Minimum margin, Priority, Status and Explanation. Statuses: proposed (waiting for approval), active (used for suggestions and the margin floor), retired.

Fields

Find rates (GET /tariffs/match):

Calculate a charge (POST /tariffs/calculate):

Selling suggestion (POST /tariffs/suggest): Origin, Destination, Mode, Service date and Date basis as in Find rates, the shipment fields as in Calculate, and:

Add selling tariff / Add buy rate (POST /tariffs/sell or /tariffs/buy; not listed in the fact pack coverage):

Chargeable-weight policy (POST /tariffs/policies; saving a mode that already has a policy replaces it):

Margin rule (POST /margin-rules):

Actions

The fact pack groups the last two as /margin-rules/{id}/(approve|retire).

Rules and messages

• "Origin is not valid." / "Destination is not valid." / "Mode is not valid." / "Service date must be a date." / "Date basis must be booking date or departure date." (Find rates errors appear on the plain error page.)
• "Rate kind must be buy or sell."
• "Rate was not found." (404)
• "Each dimension line must be "pieces x length x width x height" in cm."
• "No chargeable-weight policy is configured for mode {mode}." (409)
• "The mode policy measure does not match the rate basis." (409)
• "Dimensions or volume are required for this basis." / "Gross weight is required for this basis." / "Pieces are required for this basis." / "Quantity is required for this basis."
• "The chosen buy rate does not cover this lane, mode and date."
• "No approved margin rule covers this charge and mode." (409)
• "Two approved margin rules apply equally. Adjust their priorities." (409)
• Rates: "Charge basis is not supported.", "Currency is not valid.", "Unit is not in reference data.", "Minimum is above maximum.", "Valid to is before valid from.", "Priority must be at least 1.", "Each break line must be "from quantity:rate".", "A flat charge cannot have breaks.", "Break quantities must be unique.", "Charge code is not available.", "{label} is not a valid number.", "{label} must be greater than zero.", "{label} is required (500 characters at most)."
• Policies: "Measure must be weight or revenue ton.", "Method must be aggregate or per piece.", "A revenue ton policy needs kg per revenue ton in the divisor.", "A weight policy needs a divisor or a volume factor."
• Margin rules: "Markup is not a valid percentage." / "Markup is out of range.", "The markup gives a margin below the minimum margin.", "Priority must be at least 1.", "Only a proposed rule can be approved.", "The person who proposed a margin rule cannot approve it.", "The rule is already retired.", "Margin rule was not found." (404)

Role differences

• Sales representatives see Selling tariffs, policies and margin rules (read only), can calculate selling tariffs and get selling suggestions without cost or markup. The Buy rates panel is not shown.
• Pricing officers add tariffs, buy rates and policies and see buy costs; they cannot propose margin rules.
• Pricing managers propose and retire margin rules and approve rules proposed by someone else. Sales managers can approve margin rules but not propose or retire them.
• Company administrators add selling tariffs and policies but cannot see or add buy rates.

Commissions

How to open it: sidebar Sales > Commissions, route /commissions, or the Commissions button on Customers. Arabic: Commissions (العمولات), Statement (الكشف), Settlements (التسويات).

Subtitle: "Commission accrues when an invoice posts, on its net amount, at the salesperson's approved rule; credit notes reverse it. It becomes payable once the invoice is fully collected. Accruals are a subledger and are not posted to the ledger."

• Statement filter: Salesperson, From (default 1 January of this year), To (default today) and Show statement.
• With a statement: the heading "Statement: {name}, {from} to {to}", Download CSV, a totals table per currency (Accrued, Awaiting collection, Eligible, In settlement, Settled) and the Accruals table: Date, Source (invoice, credit or debit note), Invoice, Customer, Basis, Rate %, Commission and State. State values: awaiting_collection (invoice still open), eligible (invoice fully collected, not yet settled), in_settlement (in a proposed settlement), settled (settlement approved). Empty: "No accruals in this range."
• Settlements: #, Up to, Total, Proposed by, Status (proposed, approved, rejected; "by {name}") and Actions.
• Rules (managers only): the propose form and the table Salesperson, Basis, Rate %, Valid ("{from} to {to}", "open"), Status (proposed, active, retired), Proposed by and Actions. Empty: "No commission rules recorded."
• Users who may not read the chosen statement see "You can read your own statement only."

Fields

Statement filter (GET /commissions):

Propose settlement (managers, POST /commissions/settlements):

Propose rule (managers, POST /commissions/rules):

Actions

The fact pack groups rule actions as /commissions/rules/{id}/(approve|retire).

Rules and messages

• Opening another salesperson's statement or CSV link without sales.commission.manage shows the page with "You can read your own statement only." and no file. The service message "You can only read your own commission statement." (403) is not reached from this screen.
• "From must be a date." / "To must be a date." / "The end date is before the start date." (422)
• "The rate must be above 0 and at most 100 percent." (422)
• "Valid to is before valid from." (422)
• "The salesperson must be an active internal member of this company." (422)
• "Commission rule was not found." (404) / "Only a proposed rule can be approved." (409) / "This rule is already retired." (409)
• "A commission rule is approved by someone other than its proposer and the salesperson." (409)
• "Another active rule for this salesperson overlaps these dates. Retire it first." (409)
• "There is no collected, unsettled commission to settle." (409)
• "Settlement was not found." (404) / "This settlement was already decided." (409)
• "A salesperson cannot approve their own commission settlement, and the proposer cannot decide it." (409)

Role differences

• Sales representative: own statement and CSV only; the Salesperson list is disabled; no Rules panel or settlement controls.
• Sales manager: any salesperson's statement, rules and settlements; approves rules and settlements proposed by someone else for someone else.
• Finance manager: holds sales.commission.approve but no view or manage right, so the page shows only "You can read your own statement only." and no approval buttons.
• /commissions never returns "Not allowed": any internal user can open it and sees the notice.

Procedures

Record an enquiry for an existing customer

1. Open Sales > Enquiries and leads.
2. In New enquiry, choose the Customer.
3. Enter Origin and Destination codes (for example EGALY and DEHAM), Commodity and Requirements.
4. Select Save enquiry. The enquiry appears at the top of Enquiries with status pricing.

Capture, qualify and convert a lead

1. In New lead, enter Source and Company, plus Origin, Destination and Commodity (needed to convert later).
2. Select Save lead. The lead shows status new.
3. When the lead is qualified, select Qualify in its row.
4. Choose the customer profile in the row's list and select Convert. A new enquiry with status qualification appears.

Set or change a customer's credit limit

1. Open Sales > Customers and select the customer.
2. Select Credit control in the section tabs.
3. Enter Limit and Currency (leave Limit blank to remove it) and the Reason for the change.
4. Select Save limit and confirm "Change the credit limit for this customer?".

Request and approve a temporary credit override

1. As AR accountant, open the customer's Credit control.
2. Enter Extra {currency}, Valid until and Why the exception is needed; select Request override.
3. As Finance manager, open the same customer. In the override row select Approve and confirm.
4. The Limit KPI shows "Plus approved overrides {amount}".

Calculate an air charge

1. Make sure the air mode has a chargeable-weight policy (Chargeable-weight policies).
2. In Calculate a charge, choose Rate Selling tariff and enter the Rate number.
3. Enter Dimensions (cm), one line per size, for example 2 x 120 x 80 x 100, and Gross kg.
4. Select Calculate. Note the calculation number to link it on a quotation.

Propose and approve a margin rule

1. As Pricing manager, in Margin rules enter Markup %, Minimum margin %, Priority and Why; select Propose rule.
2. As a different user with pricing.margin.approve (another Pricing manager or a Sales manager), select Approve and confirm "Approve this margin rule?".

Settle commission

1. As Sales manager, open Commissions, choose the Salesperson and dates, select Show statement.
2. Check the Eligible total, set Currency and Period end, select Propose settlement of eligible commission and confirm.
3. A different user with sales.commission.approve (and Commissions access) selects Approve in Settlements and confirms.

Troubleshooting

4. Quotations, bookings and booking intake

This chapter covers turning an enquiry into a quotation, issuing and revising it, recording the customer's acceptance, creating a booking from the acceptance, opening a job from the booking, and reviewing booking requests that arrive by email or through the customer API.

Who uses it:

• Sales representative: quotations (pricing.quotation.view, pricing.quotation.create, pricing.quotation.issue, pricing.quotation.accept, pricing.quotation.print), bookings (bookings.booking.view, bookings.booking.create) and the intake queue (bookings.intake.review).
• Sales manager: as Sales representative, plus intake API tokens (bookings.intake.configure) and issuing below the margin floor (pricing.margin.approve).
• Pricing officer: prepares and prints quotations with buy estimates (pricing.quotation.create, pricing.quotation.print, pricing.buy_rate.configure); cannot issue.
• Pricing manager: as Pricing officer, plus issuing and margin approval (pricing.quotation.issue, pricing.margin.approve).
• Operations coordinator, Operations manager, Branch manager and Customs coordinator: read bookings (bookings.booking.view) and open jobs from them (operations.job.create).
• Company administrator: everything in this chapter except margin approval and buy estimates.

References: Spec §5.3 (commercial handoff), §6.2 (pricing engine and margin floor), §6.3 (quotation behaviour), §7.1 (booking intake), §7.2 (job creation), §15 (credit exposure) and §24 (APIs and integrations). UML 09 (quotation revision, acceptance and bookings), UML 31 (quotation revision lifecycle), UML 32 (booking lifecycle), UML 23 (API clients and tokens). Acceptance scenarios A02 (customer outputs carry no buy cost or margin), A04 (no double booking of accepted quantities), A05 (a revision after acceptance leaves the booking snapshot unchanged) and A29 (Arabic quotation output).

When a form post is refused, a plain English page shows the status, the heading ("The request could not be completed" for 409 and 422, "Not allowed" for 403, "Not found" for 404), the exact message and a Reference code. Use Back to return. A successful post returns to the page without a success message.

Quotations

How to open it: sidebar Sales > Quotations, route /quotations. Arabic: Recorded quotations (عروض الأسعار المسجلة), New quotation (عرض سعر جديد).

Subtitle: "Selling amounts are entered by the user. Matching tariffs are suggestions and are not applied automatically." The header button Selling tariffs opens /tariffs (chapter 3).

• Recorded quotations: Reference (Q-…), Enquiry, Route and Latest status (the status of the newest revision), with "Filter this page…". Empty: "No quotations recorded." / "Create a draft from an enquiry with the form below."
• Revision statuses: draft (being prepared, not visible to the customer), issued (sent to the customer, cannot be edited), accepted (the customer accepted at least part of a line), expired (an acceptance was attempted after Valid until).
• New quotation: "Creates a draft with one charge line. Further lines and options are added on the quotation." The quotation page has no control to add lines or options (see the gaps file), so a quotation created here has exactly one line.

Fields

Fieldset Enquiry and charge:

Fieldset Terms:

Actions

Rules and messages

• "Valid until must be a date."
• "Service scope is required." / "Exclusions is required." (also over 1000 characters)
• "Incoterm is not valid." / "Incoterm is not in reference data."
• "Unit is not valid." / "Unit is not in reference data."
• "Quantity is not a valid amount." / "Quantity must be greater than zero."
• "Sell amount currency is not valid." / "Currency is not in reference data." / "Sell amount must be greater than zero."
• "Buy estimate currency is not valid." / "Buy estimate must be greater than zero."
• "Charge code is not available."
• "Pricing calculation was not found."
• "Enquiry was not found." (404)

Role differences

• Without pricing.quotation.view (operations, finance and administration roles other than Company administrator) the link is hidden and the page shows "Not allowed".
• Sales users and Company administrators do not see Buy estimate or Buy currency.

Quotation detail

How to open it: select a reference in Recorded quotations; route /quotations/{id}. Arabic: Issue revision (إصدار المراجعة), New revision (مراجعة جديدة).

Numbered parts:

1. Header actions: Customer copy, PDF (English), PDF (العربية).
2. The revision's terms: Valid until, Service scope and Exclusions.
3. The accept row under a line.
4. New revision on the latest issued or accepted revision.

The page shows one panel per revision, newest first ("Revision {n}" with its status; older revisions are greyed). Each panel shows Valid until, Service scope and Exclusions, then the charge lines: Charge, Quantity, Sell and, for users with pricing.buy_rate.view, Buy estimate. "Issued below the margin floor with approval" marks a revision issued with a margin exception. Acceptances show "Accepted {date}".

Fields

Issue form (draft revision, with pricing.quotation.issue):

Accept row (under each line of an issued or accepted revision, with pricing.quotation.accept):

Hidden: version_id and line_id identify the revision and line.

Create booking (under an acceptance, with bookings.booking.create):

Actions

Rules and messages

• Issue: "Only a draft revision can be issued." (409), "A quotation needs at least one line." (422), "A line is below the approved margin floor. A pricing approver other than the preparer must issue it with a note." (409).
• New revision: "A new revision can be opened from an issued or accepted revision." (409), "The issued terms could not be read." (409).
• Accept: "Accepted quantity is not a valid amount." / "Accepted quantity must be greater than zero.", "Acceptance evidence is required.", "There is no issued revision to accept." (409), "This revision is past its validity date." (409; the revision is marked expired), "Quotation line was not found on the issued revision." (404), "Accepted quantity exceeds the remaining quoted quantity." (409).
• Book: "Acceptance was not found." (404), "The accepted revision is missing.", "The acceptance has no quantities.", "An accepted line is missing.", "Accepted quantity is already allocated." (409), "This would take the customer over the credit limit ({currency} {limit}, available {available}). Ask for an approved credit override." (409, audited), "Credit exposure needs a {currency} exchange rate on or before {date}." (409).
• PDF: "Language must be English or Arabic.", "No issued revision is available for the customer copy." (409), "The stored document belongs to different quotation lines." (409).
• "Quotation was not found." (404; also for another company's quotation).

The margin floor applies only to lines with a buy estimate in the same currency as the sell amount (chapter 3, Margin rules).

Role differences

• Pricing officers see buy estimates and the PDF links but no Issue form, accept rows or Create booking.
• Sales representatives issue, accept and book but do not see buy estimates; a margin breach must be issued by a Sales manager or Pricing manager other than the preparer.
• Without pricing.quotation.print the PDF links are hidden.

Customer copy

How to open it: Customer copy on the quotation; route /quotations/{id}/customer. Arabic: Customer copy (نسخة العميل).

Title "Customer copy {reference}", subtitle "This copy omits buying estimates, margin, and approval notes. It is not a PDF." It shows the latest issued or accepted revision: Revision, Valid until, Scope, Exclusions and Exchange, then per option the Charge, Quantity and Amount. Print uses the browser's print dialog.

Fields

None.

Actions

Rules and messages

• "No issued revision is available for the customer copy." (409) when only a draft exists.

Role differences

Any user with pricing.quotation.view sees the same copy; buy estimates are never shown here (A02).

Bookings

How to open it: sidebar Sales > Bookings, route /bookings. Arabic: Bookings (الحجوزات).

Subtitle: "A booking stays in draft until carrier and customer confirmation are recorded. Those confirmations are not installed." Columns Reference, Customer reference and Status. Every booking created by the system is in draft; there is no step that confirms it. Empty: "No bookings recorded." / "A booking is created when a customer accepts a quotation."

Fields

None.

Actions

Rules and messages

Without bookings.booking.view the page shows "Not allowed".

Role differences

Sales, Sales manager, Company administrator and the operations roles (Operations coordinator, Operations manager, Branch manager, Customs coordinator) see the list.

Booking detail

How to open it: select a booking, or after Create booking; route /bookings/{id}. Arabic: Accepted snapshot (اللقطة المقبولة), Open a job (فتح ملف).

Subtitle: "This is the accepted quotation snapshot. A later quotation revision does not change it."

• Accepted snapshot: Quotation, Revision, Snapshot taken, Evidence, Scope and Exclusions.
• Accepted charges: Charge, Accepted quantity and Sell. Empty: "No charges in this snapshot."
• Job: a "Job {reference}" button when a job exists and you may view jobs; otherwise the Open a job form for users who may create jobs ("Add an active branch before opening a job." when there is no branch); otherwise "No job is linked to this booking."

Fields

Hidden: category_name is always forwarding.

Actions

Rules and messages

• "Booking was not found." (404)
• "Branch was not found." (404)
• "Mode is not valid." / "Direction is not valid." / "Category is not valid."
• "The booking snapshot has no lines." (409)
• "This booking is already allocated to a job." (409)
• "The booking needs a distinct origin and destination." (422)

Role differences

• Operations roles and Company administrators open jobs and see the job link.
• Sales users see the snapshot but never the job link (they lack operations.job.view), so the panel always says "No job is linked to this booking." even when a job exists (see gaps).

Booking intake

How to open it: sidebar Sales > Booking intake, route /intake. Arabic: Booking intake (استقبال الحجوزات), Intake status (حالة الاستقبال), API tokens (رموز الواجهة البرمجية).

Subtitle: "Booking requests received by email and by the customer API. Each one waits here for review: accepting opens an enquiry, rejecting records why. No booking or job is created from a message."

• Intake status tabs: Pending (default), Accepted, Rejected and All (/intake?status=pending|accepted|rejected|all).
• Queue columns: Received, Channel (email or api), From ("Ref {reference}" for API requests), Subject ("(no subject)"), Customer ("Not matched" when the sender is not linked to a customer) and Status (with the enquiry reference once accepted). Empty: "Nothing here."
• Mailboxes: Mailbox, Last poll ("never"), Outcome, Last message uid and Detail. With no polls: "No intake mailbox has been polled for this company. Mailboxes are configured in the private config file under {key} and read by the scheduled cron task." Mailbox setup is Developer-assisted.
• API tokens (only with bookings.intake.configure): explains that each token belongs to one customer and requests go to POST /api/v1/intake/bookings with a Bearer token, a JSON body with client_reference, origin, destination and commodity, and an optional Idempotency-Key header. Table: Name, Customer, Prefix (fit_xxxxxxxx_…), Status (active or revoked), Last used ("never") and Actions. Empty: "No tokens issued."

Fields

Actions

Do not refresh the page after Issue token: the browser offers to send the form again, and doing so issues a second token.

Rules and messages

• "Name the token (3 to 128 characters)." (422)
• "Customer profile was not found." (404)
• "The token was not found." (404)

API callers (not this screen) receive: "client_reference is required: 1 to 128 letters, digits, dot, dash, underscore or slash.", "ready_date must be YYYY-MM-DD.", "Idempotency-Key must be 1 to 255 visible ASCII characters.", "This client_reference was already used for a different request." and "This Idempotency-Key was already used for a different request." (409). A repeated identical request returns the original message instead of a new one.

Role differences

• Sales representatives review the queue but do not see API tokens.
• Sales managers and Company administrators also issue and revoke tokens.
• Other roles get "Not allowed".

Intake message

How to open it: select a subject in the queue; route /intake/{id}. Arabic: Accept into an enquiry (القبول كاستفسار).

Picture not taken (04-intake-message-annotated). The demo has no intake message. The reason is in the screenshot index.

Numbered parts:

1. The Message panel.
2. The Accept into an enquiry form.
3. The Reject form.

The title is the subject. Message shows Received, Channel, From, Client reference, Customer ("Not matched. Choose one when accepting." when unknown), Message id and the body. A reviewed message shows "Accepted by {name} on {date}. Enquiry {reference} was opened for {customer}." with Open enquiries, or "Rejected by {name} on {date}: {reason}", and no forms.

Fields

Accept into an enquiry ("Check the details read from the message. They are saved only when you accept."):

Reject:

Hidden: version detects changes made by someone else since you opened the page.

Actions

Rules and messages

• "The intake message was not found." (404)
• "This message was already reviewed." (409)
• "This message changed since you opened it. Reload and try again." (409)
• "This message already belongs to a customer and cannot be moved to another." (409)
• "Choose the customer for this message." (422)
• "Give a reason of 3 to 500 characters." (422)
• Enquiry rules from chapter 3: "Origin is not valid.", "Destination is not valid.", "Commodity is required.", "Customer profile was not found."
• Failed accept or reject attempts are audited as failures.

Role differences

Without crm.enquiry.create the accept form is replaced by "You can reject this message. Accepting it needs permission to create enquiries."

Procedures

Prepare and issue a quotation

1. Open Sales > Quotations.
2. In New quotation choose the Enquiry and Charge, enter Quantity, Unit, Sell amount and Currency.
3. Enter Valid until, Service scope and Exclusions; optionally Incoterm and Pricing calculation.
4. Select Save draft. The quotation opens with Revision 1 in draft.
5. Select Issue revision and confirm. Revision 1 shows issued.

Issue a quotation below the margin floor

1. The preparer (for example a Pricing officer) saves the draft with a Buy estimate in the sell currency.
2. If issuing shows "A line is below the approved margin floor…", a Pricing manager or Sales manager who did not prepare it opens the quotation.
3. They enter the Margin exception note and select Issue revision. The revision shows "Issued below the margin floor with approval".

Record acceptance and create a booking

1. Open the issued quotation.
2. In the accept row under the line, enter Accepted quantity and Acceptance evidence; select Accept.
3. Under "Accepted {date}", enter the Customer reference if given and select Create booking.
4. The booking opens in draft with the accepted snapshot.

Revise an issued quotation

1. Open the quotation and select New revision; confirm.
2. A new draft revision appears with the same lines. It cannot be edited on screen; issue it as it is, or record a new quotation.

Open a job from a booking

1. As an operations user, open the booking.
2. In Open a job choose Branch, Mode and Direction; select Open job and confirm.
3. The new job opens (chapter 5).

Review a booking request

1. Open Sales > Booking intake (tab Pending) and select the subject.
2. Check Origin, Destination, Commodity and Requirements; choose the Customer if not matched.
3. Select Accept and open enquiry, or enter a Reason and select Reject.

Issue an API token for a customer

Staging only: test tokens against a staging company first. A token gives the customer's system the ability to create intake messages.

1. As Sales manager, open Booking intake and go to API tokens.
2. Choose the Customer, enter a Token name and select Issue token.
3. Select Copy and pass the token to the customer's IT contact through a secure channel. It is not shown again.

Troubleshooting

5. Jobs and the job workspace

A job is the operational file for one shipment. It is opened from a confirmed booking (chapter 4) and then carries the shipment, its cargo, milestones, holds, costing, the house bill draft and the request for financial close. A job keeps four states apart: Operations (open or completed), Documents, Billing and Finance (open, under review, closed, reopened). Completing operations does not close finance.

Who uses it:

Sales, pricing, treasury, executive and auditor roles have no operations.* keys and do not see the Operations group.

Spec references: §7 (bookings and operations jobs), §12 (milestones, tasks, exceptions and approvals), §13 (communication), §14 (job costing). UML: 10, 12, 16, 17, 32, 33, 53.

Jobs list

Open it from the sidebar: Operations > Jobs and shipments (الملفات والشحنات). Route: /jobs. The page title is Jobs (الملفات). It needs operations.job.view.

The list shows the newest jobs first, 100 per page. Columns: Reference, Branch, Movement (mode icon, mode and direction), Operations, Billing, Finance. Each state is a coloured badge:

• Operations: open (work in progress), completed (operations finished; may be reopened).
• Billing: starts as not_ready.
• Finance: open, under_review (financial close requested), closed, reopened.

The Consolidations button in the page header opens /consolidations (chapter 6).

Fields

Actions

Rules and messages

• An empty company shows "No jobs recorded."
• A search with no match shows "No job reference contains that text."

Role differences

• Roles without operations.job.view (for example AR accountant, Sales representative) do not see the sidebar link; typing /jobs returns 403 "You do not have permission for this action."
• Jobs belong to the signed-in company. A job id of another company returns 404 "Job was not found."

Job workspace (Overview)

Open a job from the jobs list, or from any job link. Route: /jobs/{id}. The page title is the job reference; the badge next to it is the operations state. Section tabs appear below the header (see "Job section tabs").

Numbered areas in the annotated shot: 1 summary header, 2 Cargo, 3 Milestones, 4 House bill, 5 Estimated margin, 6 Financial close.

Summary header. Mode, Direction, Customer, Branch, Shipment, Operations, Documents, Billing, Finance and Credit check. The note under it explains that the credit check records the customer's credit standing when the job was opened; the credit gate is the booking confirmation, and this value does not approve or block the job.

Cargo (البضاعة). One row per cargo line with Quoted, Booked, Measured and Final quantities. When the measured quantity differs from the booked one, a warning says "No charge revision was created, and the final quantity stays empty." Users with operations.cargo.measure see a Measured quantity box and Record measurement.

Milestones (المراحل). The milestone plan for the job's mode and direction. Statuses: pending (not yet recorded), recorded, superseded (replaced by a correction). If the job has no plan yet, Apply milestone plan creates it. The plans configured in the system are:

Ocean and air domestic or cross-trade jobs have no plan; Apply milestone plan then answers "No milestone template is configured for this mode and direction."

Only the next pending milestone can be recorded. Its form has Occurred (UTC) and Evidence for {milestone} (the milestone name is filled in), and the button Record milestone. Two milestones have their own forms:

• departed – when the next milestone is departed, the form asks for Pieces, Occurred (UTC) and Departure evidence and the button is Record departure quantity. A partial quantity is recorded but does not mark the lot departed.
• destination_handoff – when the first leg has no arrival yet, the form asks for Pieces, Occurred (UTC) and Arrival evidence and the button is Record arrival quantity.

For air and road jobs, departures and arrivals normally come from flight events (chapter 6) and trip stops (chapter 6).

House bill (بوليصة الشحن الفرعية), anchor #house-bill. For an ocean shipment without a house bill, users with operations.transport_document.draft see the draft form. A draft shows Revise draft and Request release. Issue of the bill happens on the Documents tab (chapter 7).

Customer invoices (needs finance.invoice.view). Lists invoices created from this job. Users with finance.invoice.draft see a Tax select and the button Create invoice draft from {n} approved line(s), which opens the new draft at /invoices/{id} (chapter 8).

Estimated margin (الهامش المقدّر), anchor #estimated-margin (needs operations.job_costing.manage). Sell lines with status estimated (entered, not yet billable) or approved (approved for billing). Totals, margin notices and Recognised in the ledger (base currency). The sell estimate form adds new lines.

Financial close (الإقفال المالي), anchor #financial-close (shown to users with operations.job.complete or finance.job.close). Shows Finance state: and the findings that block an ordinary close. Finding codes: cost_missing, cost_unapproved, allocation_stale, unbilled_sell, accrual_unmatched, recognition_pending. When there are none: "No open cost or billing findings." The notes say that open customer receivables do not block financial close. A history table lists each request (Requested, By, Outcome, Decided by, Reason, Reopened).

Right column. Parties, Lots and legs, Holds (الإيقافات) and Operations (العمليات).

Hold statuses: active (blocks operational completion and, for its scope, release) and released. Hold types: general, document, finance, customs, claim. Hold scopes: all, cargo, documents.

Fields

Measure cargo (/jobs/{id}/cargo/{id}/measure):

Record milestone (/jobs/{id}/milestones/record):

Record departure quantity (/jobs/{id}/departure):

Record arrival quantity (/jobs/{id}/arrival):

Open house bill draft (/jobs/{id}/house-bill):

Create invoice draft (/jobs/{id}/invoice-draft):

Record sell estimate (/jobs/{id}/sell-estimates):

Financial close decision (/jobs/{id}/close/(approve|return|reopen): /jobs/{id}/close/approve, /jobs/{id}/close/return, /jobs/{id}/close/reopen):

Holds (/jobs/{id}/holds, /holds/{id}/release):

Actions

Staging only: approving, closing by exception and reopening a financial close change the finance state other users rely on. Run these tests on a staging copy.

Rules and messages

Milestones and quantities:

• "No milestone template is configured for this mode and direction."
• "This milestone is not waiting to be recorded." / "Record earlier milestones first."
• "A partial departure does not record the whole lot as departed." / "A partial arrival does not record destination handoff."
• "Destination handoff cannot occur before arrival."
• "Departure quantity must be a decimal." / "Departure quantity must be greater than zero." / "Departure is not waiting on this shipment." / "Departure quantity is larger than the remaining lot."
• "Arrival quantity must be a decimal." / "Arrival quantity must be greater than zero." / "Record departure before arrival." / "Arrival is not waiting on this shipment." / "Arrival cannot occur before departure." / "Arrival quantity is larger than the remaining lot."
• "The shipment has no lot."
• Correction route: "Record the milestone before correcting it."
• Measurement: "Cargo was not found."

House bill:

• "A house bill draft is for an ocean shipment."
• "This shipment already has a house bill draft."
• "Freight terms must be prepaid or collect." / "Shipper is required." / "Consignee is required."
• Request release on a draft: "A draft cannot be released. Original-document and financial holds are separate, and this draft clears neither." On an issued bill: "Release the original documents from the job release page, which checks document and finance holds."

Costing and invoice draft:

• "Quantity and rate must be decimals." / "Quantity and rate must be greater than zero." / "Charge, unit, and currency must be active records."
• "The job is under review for financial close; reopen it before adding charges."
• "Only an estimated sell line can be approved." / "The person who entered a sell estimate cannot approve it." / "Sell estimate was not found."
• "There are no approved, unbilled sell lines on this job." / "All sell lines on one invoice must share a currency. Approve the lines in one currency per invoice." / "The customer profile must be active before it can be invoiced."

Operations and financial close:

• "Only an open job can be operationally completed." / "An active hold blocks operational completion." / "Every leg of a multimodal job must arrive before operational completion."
• "Only a completed job can be reopened." / "Reason is required." / "Financial close is under review; finance must return or reopen it first."
• "Operations must be completed before financial close is requested." / "Financial close is already …" (under review or closed).
• "The job has open findings: …" (ordinary approve with findings).
• "An exception needs a reason of 10 to 500 characters." / "A close exception is approved by a user other than the requester."
• "The job is not under close review." / "A reason of 3 to 500 characters is required." / "Only a financially closed job is reopened."

Holds:

• "Hold type or scope is not valid." / "Reopen the job before placing a hold." / "Hold reason is required."
• "Hold was not found." / "This hold is already released." / "Release reason is required."

Role differences

• Operations coordinator: sees Cargo, Milestones, House bill, Holds, Operations and the Request financial close button, but not Estimated margin (no operations.job_costing.manage) and not the close decision forms.
• Operations manager and Company administrator: also see Estimated margin and Approve for billing.
• Finance manager: sees the close decision forms (Approve financial close, Close as approved exception, Return for remediation, Reopen financial close) but no milestone, measure or hold controls.
• A user with finance.job.close but without finance.job.close_exception sees Exception reason and Close as approved exception disabled, with "Clear the findings, or ask a user who may approve a close exception."
• Documentation officer and Warehouse or dispatch user: read-only overview (they lack operations.job.complete and operations.milestone.record).
• AR accountant: 403 on /jobs/{id} (no operations.job.view).

Job section tabs

Below the header of every job page there is a row of section tabs (the job tabs partial) (aria label Job sections, أقسام العمل): Overview (نظرة عامة) /jobs/{id}, Air (جوي) /jobs/{id}/air, Routing legs (مراحل المسار) /jobs/{id}/legs, Tasks (المهام) /jobs/{id}/tasks, Customs (الجمارك) /jobs/{id}/customs, Custody (الحيازة) /jobs/{id}/custody, Documents (المستندات) /jobs/{id}/documents, Release (الإفراج) /jobs/{id}/release, Communication (المراسلات) /jobs/{id}/communication, Purchase orders (أوامر الشراء) /jobs/{id}/purchase-orders, Claims (المطالبات) /jobs/{id}/claims.

All tabs are shown to everyone who can open the job, for every mode. A tab the user may not open returns 403. The Air tab also opens for an ocean or road job; its forms then refuse with "Air waybills are only for air jobs." or "Flights are only booked for air jobs." Air is described in chapter 6; Customs, Custody, Documents and Release in chapter 7.

Routing legs

Open: job page > Routing legs tab. Route: /jobs/{id}/legs. Needs operations.shipment.view. This is the job legs screen. Page title Routing legs (مراحل المسار).

Picture not taken (05-job-legs). The demo has no multimodal job. The reason is in the screenshot index.

Legs run in sequence. A leg departs only after the previous leg has arrived, unless an approved exception covers that leg. The Legs table has #, Mode, Route, Provider, Reference, Status and Exceptions. Leg statuses: planned, departed, arrived. The Exceptions column lists exception approvals with their status and "(used)" once consumed. The Leg events timeline lists departures, arrivals and estimates.

The first leg moves with the mode's own records (ocean milestones, flights, trips). Its Departed and Arrived buttons are still shown but the server refuses them.

Picture not taken (05-legs-add-form). The demo has no multimodal job. The reason is in the screenshot index.

Fields

Depart / arrive / exception (row controls):

Set estimate:

Add leg:

Actions

The routes are documented together as /legs/{id}/(exception|depart|arrive).

Rules and messages

• "Origin and destination must differ." / "Legs are added to open jobs only." / "Provider is not valid." / "… must be a location code of 3 to 10 letters or digits."
• "Enter an estimated departure or arrival." / "Estimated arrival cannot be before estimated departure."
• "The first leg moves with its flights, trips or ocean milestones."
• "This leg has already departed." / "Only a departed leg can arrive." / "Arrival cannot be before departure."
• "The previous leg has not arrived. An approved exception is needed to start this leg."
• "The previous leg has arrived. No exception is needed."
• Approval consumption: "The exception is not approved.", "The approval expired. Ask for a new one.", "The approval is for a different action or record." A leg exception approval expires after 72 hours.

Role differences

• Without operations.leg.manage: no Add leg panel and no Request exception.
• Without operations.milestone.record: no Departed, Arrived or Set estimate controls.
• The requester cannot decide their own exception: "The requester cannot decide their own request."

Job tasks

Open: job page > Tasks tab. Route: /jobs/{id}/tasks. Needs operations.task.view. Page title Job tasks (مهام العمل).

Milestones create tasks from the matching templates. Overdue open tasks raise an alert for the owner. The Tasks table lists the job's tasks (status open, done or cancelled); opening a task leads to /tasks/{id} (chapter 2).

Fields

Add a task:

Actions

Rules and messages

• "A task can have at most 30 checklist items."
• "The task it depends on was not found."
• "The owner must be an active internal user of this company."

Role differences

• The add form is shown to everyone who can open the tab. Users without operations.task.manage get 403 on submit.

Task templates

Open: sidebar Workspace > Tasks, then the Templates button. Route: /task-templates. Page title Task templates (قوالب المهام). Viewing needs operations.task.view.

When a milestone is recorded, every active template matching its code, mode and direction creates one task. Company templates come first; global defaults also apply. The Templates table has Title, Scope (Global default or Company), Mode, Direction, Milestone, Due after, Team, Checklist and Status. Active company templates have a Retire button.

Fields

Add a company template:

Actions

Rules and messages

• "Trigger must be a milestone code."
• "Due offset must be between 0 and 1440 hours."
• "Only a company template can be retired. Global defaults are replaced by adding company templates."

Role differences

• The add form and Retire are shown to every viewer; only users with operations.task.configure (Operations manager, Company administrator) can save. Others get 403.

Job communication

Open: job page > Communication tab. Route: /jobs/{id}/communication. Needs operations.job.view and operations.communication.send. Page title Job communication (مراسلات العمل).

Messages are built from approved templates using shipment facts only; costs, margins and internal notes cannot be placed in a template. Messages are queued and sent by the scheduled job. No mail provider is configured, so queued messages stay queued and none is reported as delivered.

Compose builds a preview. Preview (template version {version}) shows the subject and body with the shipment facts filled in, and Queue message puts it in the outbox. The Messages table has Subject, To, Queued, Template, Status, Attempts and Detail. Message statuses: queued (waiting for the scheduled job), provider_accepted (a provider took the message), failed (gave up after the maximum attempts), cancelled.

Fields

Compose:

Cancel a queued message:

Actions

Rules and messages

• "Recipient email is not valid."
• "Email template was not found."
• "Message was not found." / "Only a queued message can be cancelled."
• Delivery is done by cron with retries after 5, 15, 60 and 240 minutes, at most 5 attempts (Developer-assisted to observe). Without a provider profile messages remain queued.

Role differences

• Coordinator and manager roles have operations.communication.send. Finance manager can open the job but gets 403 on this tab.

Email templates

Open: job page > Communication tab > Manage templates. Route: /email-templates. Viewing needs operations.communication.send. Page title Email templates (قوالب البريد الإلكتروني).

Saving a template creates a new version; messages keep the version they were built from. The Allowed placeholders notice lists the only placeholders a template may use: recipient_name, sender_name, shipment_reference, job_reference, origin, destination, status, message. Any other placeholder is refused, so costs, margins and internal notes cannot be sent. The Templates table has Key, Language, Scope, Version, Subject and Body. The seeded global templates (shipment_update, document_request) exist in English only.

Fields

Save a company template:

Actions

Rules and messages

• "Template key must be lower case letters, digits and underscores."
• "Placeholder {{x}} is not allowed. Allowed: …"

Role differences

• The save form is shown to every viewer. Only Operations manager and Company administrator (operations.communication.configure) can save; others get 403.

Purchase orders

Open: job page > Purchase orders tab. Route: /jobs/{id}/purchase-orders. Needs operations.commitment.view. Page title Purchase orders (أوامر الشراء).

A purchase order commits cost to a supplier. It counts as committed cost once approved by someone other than the requester. It posts nothing to the ledger; the supplier's bill does. Each order shows Supplier, Total, the Supplier reference once confirmed, its lines and an approval timeline. Statuses:

• draft – created, not yet submitted.
• submitted – waiting for an approval in Workspace > Approvals (decided by operations.commitment.approve).
• approved – approval applied; the cost is committed.
• confirmed – the supplier confirmed it.
• cancelled – cancelled with a reason.

Fields

Raise a purchase order:

Row controls:

Actions

The routes are documented together as /purchase-orders/{id}/(submit|activate|confirm|cancel).

Rules and messages

• "Add at least one line." / "Supplier and currency must be active records in this company." / "Each line needs an active buy charge and a unit."
• Line checks: "Quantity on line n must be …", "Description on line n is required."
• "Only a draft purchase order can be submitted." / "Submit the purchase order for approval first." / "Only an approved purchase order can be confirmed." / "This purchase order is already …" (cancelled or closed).
• Approval: "The exception is not approved." (not yet decided), "The approval expired. Ask for a new one." (168 hours), "The requester cannot decide their own request."

Role differences

• Without operations.commitment.manage the create form and row buttons are hidden.

Claims and insurance

Open: job page > Claims tab. Route: /jobs/{id}/claims. Needs operations.claim.view. Page title Claims and insurance (المطالبات والتأمين).

Reserves and settlements need finance approval and post no ledger entry here. Claim effect on this job shows, per currency, Reserved, Settled, Recovered and Net (a management figure). Each claim (reference prefix CLM) shows its type, the party, incident time, amounts, policy and an event timeline. Claim statuses:

• open – recorded; a reserve or settlement may be requested.
• reserved – an approved reserve was applied.
• settled – an approved settlement was applied; recoveries can be recorded.
• closed – closed after settlement.
• rejected – rejected from open or reserved (a rejected claim is closed).

Fields

Claim footer forms:

Open a claim:

Insurance references:

Actions

The routes are documented together as /jobs/{id}/(claims|insurance) and /claims/{id}/(note|request|apply|recovery|close).

Rules and messages

• "Currency is not valid." / "Insurance reference is not on this job." / "Cover ends before it starts."
• "This claim is …" (wrong status for the action) / "Approval request was not found." / "Recoveries are recorded on settled claims."
• "Only a settled claim is closed." / "Only an open or reserved claim is rejected."
• Approval consumption: "The exception is not approved.", "The approval expired. Ask for a new one.", "The situation changed after the approval. Ask for a new approval of the current details."

Role differences

• Operations coordinator and Finance manager have operations.claim.view only: they see claims but no forms.
• Operations manager and Company administrator manage claims. The Finance manager decides the approval requests.

Procedures

Record the milestones of an ocean export job

1. Open Operations > Jobs and shipments and click the job reference.
2. In Milestones, click Apply milestone plan if the list is empty.
3. For the next pending milestone, enter Occurred (UTC) and Evidence for {milestone}, then click Record milestone.
4. Repeat for each milestone in order.
5. At departed, enter Pieces, Occurred (UTC) and Departure evidence, then click Record departure quantity. Enter the full lot to record the milestone.
6. Open Tasks to see tasks created by task templates for the recorded milestones.

Measure cargo

1. On the job page, in Cargo, type the Measured quantity for the line.
2. Click Record measurement.
3. If a warning says the quantity differs from booked, tell the person who manages charges; no charge revision is created.

Place and release a hold

1. In Holds, choose Hold type and Hold scope, type the Hold reason, click Place hold.
2. To lift it, type the Release reason next to the hold and click Release hold, then confirm "Release this hold?".

Add a sell estimate and approve it for billing (maker-checker)

1. Signed in as the Operations manager, in Estimated margin, choose Sell charge, type Quantity, choose Unit, type Unit rate, choose Currency, click Record sell estimate.
2. Sign in as a different user with operations.sell_line.approve and click Approve for billing on the line; confirm.
3. A user with finance.invoice.draft (for example browser-staff) chooses Tax and clicks Create invoice draft from {n} approved line(s).

Complete operations and request financial close

1. Release every active hold and make sure every leg of a multimodal job has arrived.
2. In Operations, click Complete operations and confirm.
3. In Financial close, review the findings and click Request financial close; confirm.
4. A Finance manager opens the job, reviews the findings and clicks Approve financial close (no findings) or types an Exception reason of at least 10 characters and clicks Close as approved exception. The approver must not be the requester.
5. To send it back, the Finance manager types a Return reason and clicks Return for remediation.

Reopen operations

1. If finance is under review, ask finance to return or reopen it first.
2. In Operations, type the Reopen reason and click Reopen; confirm.

Add a leg and depart it early under an exception

1. Open Routing legs. In Add leg, choose Mode, type Origin code and Destination code, optionally Carrier reference and Service scope, click Add leg.
2. On leg 2 or later, type the reason and click Request exception.
3. A user with operations.exception.approve approves it in Workspace > Approvals.
4. Back on Routing legs, enter Departed at (UTC) and the evidence and click Depart under exception.

Send a shipment update

1. Open Communication. Choose the Template, type Recipient name, Recipient email and optionally Message.
2. Click Preview and check the text.
3. Click Queue message. The message appears as queued.

Raise and approve a purchase order

1. Open Purchase orders. Choose Supplier and Currency, fill at least Line 1, click Create draft order.
2. Type the reason and click Submit for approval.
3. Another user with operations.commitment.approve approves it in Workspace > Approvals.
4. Click Apply approval, then when the supplier confirms type the reference and click Supplier confirmed.

Handle a claim

1. Open Claims. Fill Open a claim and click Open claim.
2. Choose Request = Reserve, type Amount and Reason, click Request approval.
3. A Finance manager approves it in Workspace > Approvals.
4. Click Apply approval #{id} and confirm. Repeat with Settlement.
5. On a settled claim, record recoveries, then type a Closing note and click Close.

Troubleshooting

6. Air, road and consolidated movements

This chapter covers the mode-specific work on a job and the shared movements that carry several jobs: the Air tab of a job (waybills, flights, bookings, screening and dangerous goods), the master air waybill page, consolidations (lots, declared pieces, carrier estimates, cost splits, approvals and accrual) and road trips (stops, cargo assignment, dispatch, proof of delivery, failed delivery and redelivery). Ocean jobs have no separate tab: ocean progress is recorded with the ocean milestone plan and the house bill on the job overview (chapter 5), and the house bill is issued from the Documents tab (chapter 7).

Who uses it:

Spec references: §8 (ocean), §9 (air), §10 (road and multimodal), §14.2 (allocation). UML: 11, 17, 55. Acceptance: A06 (air chargeable weight), A07 (shared master cost split), A08 (shipment split over two flights).

Air (job tab)

Open: job page > Air tab (جوي). Route: /jobs/{id}/air. Needs operations.air.view. Page title Air; a Dangerous goods badge appears in the header when the shipment is flagged.

Numbered areas: 1 summary, 2 Air waybill, 3 Flights and lot bookings, 4 Screening and dangerous goods, 5 Flight events.

Summary. Shipment, Movement, Dangerous goods (yes/no), Lot pieces, Booked on open flights, Departed, Arrived. A part shipment is not marked departed or arrived until every piece has moved.

Air waybill (بوليصة الشحن الجوي). If no air chargeable-weight policy is configured, a warning says a pricing manager must set one before a waybill can be drafted, and the draft form is hidden. The table has AWB, Type (direct, house, master), Master, Pieces, Gross kg, Volume kg, Chargeable kg, Status and Action. Waybill statuses: draft (editable record, not sent to the airline), issued (fixed; a fingerprint is shown), cancelled. Chargeable weight is calculated with the company's air policy. The draft form appears when the shipment has no active direct waybill.

Flights and lot bookings (الرحلات الجوية وحجوزات الدفعات). One row per booking: Flight, Date, Route, Booked, Departed, Arrived, Offloaded, Missing, Damaged, Status. Booking statuses: booked, partially_departed, departed, partially_arrived, arrived, offloaded, cancelled. Under each booking an event form records departure, arrival, offload, missing or damaged pieces. Departure and arrival events also record the job's departed and destination milestones when the earlier milestones are recorded and the whole lot has moved.

Screening and dangerous goods (الفحص الأمني والبضائع الخطرة). A timeline of reviews (security screening or dangerous goods; outcome passed or failed). Export departure needs a passed security screening; dangerous goods also need a passed review. A passed security screening records the security_screened milestone when it is next in sequence. The button Flag as dangerous goods / Clear dangerous goods flag switches the flag.

Flight events. Occurred, Flight, Event, Pieces, Evidence.

Fields

Draft a waybill:

Waybill row controls:

Flight event (per booking):

Book pieces on a flight:

Add a flight:

Record a review:

Actions

The waybill routes are documented together as /air/waybills/{id}/(issue|cancel|reconcile).

Rules and messages

Waybills:

• "Air waybills are only for air jobs." / "Choose an open master air waybill." / "Add this shipment to the master consolidation before issuing a house waybill under it." / "This shipment already has an active air waybill. Cancel it before creating another."
• "An airline waybill number has 11 digits…" / "The waybill check digit does not match (the 7-digit serial modulo 7)."
• "Currency is not valid."
• Issue: "Only a draft waybill can be issued." / "Correct the validation errors before issuing." / "Dangerous goods need a passed review by a trained person before issue."
• Cancel: "This waybill is already cancelled." / "Cancel the house waybills under this master first."

Flights and bookings:

• "Enter a carrier code and flight number, for example MS 777." / "Origin and destination airports must differ."
• "Flights are only booked for air jobs." / "Pieces can only be booked on a scheduled flight." / "Booked pieces would exceed the lot. …" / "Only offloaded pieces of this shipment can be rebooked."
• Events: "Flight booking was not found." / "Only … pieces …" (more pieces than can take the event) / "Only pieces that have not departed can be offloaded. …" / "Arrival cannot be before the flight departed." / "Only departed pieces that have not arrived can be reported missing." / "Only arrived pieces can be reported damaged." / "Export air cargo needs a passed security screening before departure."

Reviews:

• "A dangerous-goods review needs the reviewer to confirm current training."
• "Enter the UN number (UN1234) and hazard class (for example 3 or 2.1)." / "Packing group must be I, II or III."
• "A dangerous-goods review is recorded. The flag stays on." (clearing the flag after a review)

Role differences

• Operations coordinator: sees Issue and Cancel (they are shown without a permission check) but gets 403 "You do not have permission for this action." because they need operations.air.issue.
• Operations coordinator: sees Flag as dangerous goods (shown with operations.air.manage) but the service needs operations.handling.review; result 403. The Record review form is shown only with operations.handling.review.
• Documentation officer: read-only (no draft, booking or flight forms).
• The flight event form is shown to operations.air.manage; posting needs operations.milestone.record (both are in the coordinator and manager roles).

Master air waybill

Open: consolidation page > Master air waybill panel > the AWB number link. Route: /air/masters/{id}. Needs operations.air.view. Page title Master AWB {number}.

Picture not taken (06-air-master). The demo has no air master. The reason is in the screenshot index.

The summary shows Consolidation, Route, Status, Reconciliation, Master pieces, Gross weight, Chargeable weight, Houses (count, pieces and kg) and Pieces assigned to the consolidation. When the master and its houses differ, a warning "Master and houses do not reconcile:" lists the differences. House waybills (البوالص الفرعية) lists House AWB, Shipment, Pieces, Gross kg, Chargeable kg, Status.

Reconciliation statuses: empty (not reconciled yet), reconciled (master totals match the houses), discrepancy_accepted (differences accepted with a note). A master is issued only after one of these two.

Fields

Actions

Rules and messages

• "Master air waybill was not found."
• "Only a master waybill is reconciled." / "Only a draft master is reconciled."
• "Master totals differ from the houses: … Accept the discrepancy with a note or correct the waybills."
• "Reconcile the master with its houses before issuing it."

Role differences

• The reconciliation form and Issue master are shown to every viewer; users without operations.air.manage (reconcile) or operations.air.issue (issue) get 403.

Consolidations

Open: sidebar Operations > Consolidations (التجميعات), or the Consolidations button on the jobs list. Route: /consolidations. Needs operations.consolidation.view.

The operating company is the signed-in company. A consolidation holds shipment lots. It does not allocate carrier cost and it does not post finance. The table has Reference, Mode, Master reference and Status. Consolidation statuses: open (declared pieces match the assigned lots, or nothing declared) and review (declared pieces differ from the assigned lots and wait for review). Each road trip opens its own road consolidation with the trip reference as master reference.

Fields

Open consolidation:

Actions

Rules and messages

• "Master reference is too long." / "Choose an active branch." / "Mode is not valid."

Role differences

• Without operations.consolidation.manage the open form is hidden and the list takes the full width.

Consolidation detail

Open: a reference on the consolidations list, or the Consolidation link on a trip or master AWB. Route: /consolidations/{id}. Page title is the consolidation reference.

Numbered areas: 1 summary, 2 Assigned lots, 3 Carrier cost estimate, 4 Proposed split, 5 Master air waybill.

The subtitle states the rules: the master reference is not a master bill; a carrier amount is an estimate until it is accrued; a split by pieces, gross weight or chargeable weight is a proposal until approved; approving the split freezes it; approving an estimate needs an approved split, a different approver from the person who recorded the estimate, and declared pieces that match; accrual posts the approved amount to freight expense and accrued freight payable and does not create a supplier bill or customer invoice; assigned pieces, weight and volume cannot exceed the lot that remains.

Summary. Mode, Status, Master reference, Active pieces, Active volume, Declared pieces. In status review a warning says "The declared pieces do not match the assigned lots. The difference is waiting for review. The carrier estimate was not rewritten."

Assigned lots (الدفعات المخصصة). Job, Shipment, Pieces, Volume, Status (active or released). Releasing a lot does not allocate cost.

Carrier cost estimate (تقدير تكلفة الناقل) (shown with operations.consolidation.manage). Charge, Payee, Quantity, Rate, Amount, Status; revisions show "(revision n)" and adjustments "Adjustment of line {id}: {reason}". Estimate statuses:

• estimated – recorded, not approved; can be split, revised and approved.
• approved – approved against an approved split; can be accrued.
• accrued – posted to freight expense and accrued freight payable.
• matched – matched to a supplier bill (chapter 9).
• superseded – replaced by a revision.

Proposed split (التوزيع المقترح). Each line is one lot's share of the estimate, split by the chosen basis: pieces, gross weight or chargeable weight. The shares add up to that estimate once. For each revision the panel shows "Revision {n} for {charge}", the status, Basis and Denominator, and per lot Job, Lot, Basis, Amount, Exact share and Residue (rounding residue). Split statuses: proposed, approved (frozen), superseded. A stale proposal (lots changed) shows "The lots have changed since this proposal. It was not rewritten. Propose the split again before approving it."; a stale approved split says to use Revise split. A revision of an accrued split says "This revises the accrued split of batch {id}. Approving it posts an accrual adjustment that moves cost between the jobs; the total stays the same."

Master air waybill (بوليصة الشحن الجوي الرئيسية) (air consolidations only). Lists the master with status and reconciliation; without one, the Draft master AWB form is shown.

Fields

Assign lot and declare total:

Record estimate:

Estimate row controls:

Draft master AWB:

Actions

Staging only: Accrue cost and Approve split revision post journals. Run them on staging, and use a consolidation nobody else is testing.

Rules and messages

Lots and declaration:

• "Assigned pieces must be a decimal." / "Assigned pieces must be greater than zero." / "Job was not found." / "The job mode does not match the consolidation." / "The job has no shipment." / "The shipment has no lot and leg to assign." / "The assignment is larger than the remaining lot."
• "Declared pieces must be a decimal." / "Declared pieces cannot be negative."
• "Allocation was not found." / "This assignment is already released."

Estimates and splits:

• "Quantity and rate must be decimals." / "Quantity and rate must be greater than zero." / "Charge, unit, currency, and payee must be active records in this company."
• "Split basis is not valid." / "Only an estimate can be split, and the split stays unapproved." / "Assign at least one lot before proposing a split." / "An approved split stays as it is. Use Revise split to propose a new version." / "A proposed split already matches these lots."
• "A lot has no gross weight, so the split cannot use weight." / "Every lot needs a house air waybill with chargeable weight before the split can use it."
• "Allocation proposal was not found." / "Only a proposed split can be approved." / "The lots changed after this split was proposed. Propose the split again before approving it." / "The stored split does not match its denominator. It was not approved."
• Approve estimate: "Only an estimated cost can be approved." / "The person who recorded this estimate cannot approve it." / "Declared pieces must match the assigned lots before a cost is approved." / "Approve the split before approving the estimate." / "The lots changed after the split was approved. Revise the split before this estimate can be approved."
• Accrue: "This carrier cost is already accrued." / "Only an approved carrier estimate can be accrued." / "Accrual needs the company base currency. No exchange rate is configured." / "Declared pieces must match the assigned lots before this cost is accrued." / "The lots changed after the split was approved. Revise the split before accruing."
• Revise: "The revision does not change the estimate." / "The revision does not change the accrued cost." / "This cost is already accrued. Record the lower amount on the supplier bill; matching posts the variance, or ask the supplier for a credit note." / "This cost line was already superseded. Revise the newest revision."
• Revise split: "Only an approved or accrued cost has a split to revise. Propose a split for an estimate instead." / "The approved split still matches the lots. Nothing to revise."
• Approve split revision: "Split revision was not found." / "Only a proposed split revision can be approved." / "The cost changed after this revision was proposed. Revise the split again." / "The person who proposed this split cannot approve it." / "The lots changed again after this revision was proposed. Revise the split again." / "The revised split does not total the accrued cost. Nothing was posted."
• "An estimate is not a posted payable and it does not create an invoice."

Master AWB:

• "Consolidation was not found." / "A master air waybill needs an air consolidation." / "This consolidation already has an active master air waybill."

Role differences

• Users without operations.consolidation.manage see only the summary, assigned lots and master AWB; the estimate and split panels are hidden.
• Approve estimate and Approve split revision appear only with operations.cost_estimate.approve (Operations manager, Company administrator). Approve allocation needs only operations.consolidation.manage.
• Accrue cost appears only to a user who has both operations.consolidation.manage (to see the panel) and finance.accrual.post, for example the Company administrator or browser-staff. AP accountant and Finance manager hold finance.accrual.post but get 403 on the page.

Road trips

Open: sidebar Operations > Road trips (الرحلات البرية). Route: /trips. Needs operations.trip.view.

Each trip carries its own road consolidation, so shared trip costs split across the jobs on it. The Trips table has Trip, Service (FTL or LTL), Vehicle, Planned start, Stops, Jobs and Status. Trip statuses: planned (stops and cargo can be added), dispatched (stops are worked), completed (all cargo delivered).

Fields

Plan a trip:

Actions

Rules and messages

• "Haulier is not valid."
• Field length and decimal checks name the field, e.g. "Weight capacity …", "Planned start …".

Role differences

• Without operations.trip.manage the Plan a trip panel is hidden (Warehouse or dispatch user sees the list only).

Trip detail

Open: a trip on the trips list. Route: /trips/{id}. Page title Trip {ref} (الرحلة {ref}).

Numbered areas: 1 header buttons, 2 summary, 3 Stops, 4 Jobs on this trip.

Header buttons: Dispatch trip (planned trips) and Complete trip (dispatched trips). Summary: Service, Vehicle, Haulier ("own fleet" when none), Status, Consolidation (link), Weight and Volume ("{load} of {capacity}"), Pieces. The consolidation holds the shared trip costs.

Stops (المحطات): #, Type (pickup, delivery, border; "(redelivery)" for a redelivery stop), Location, Window, Status, Arrived, Completed, Detail (POD reference and signer, or failure reason). Stop statuses: pending, arrived, completed, failed. Stop controls appear only while the trip is dispatched.

• Loading a pickup stop records the departure of the assigned pieces on each job (road departed milestone when the whole lot leaves).
• Delivering a delivery stop records the arrival and the delivered milestone, with "POD {reference}" as evidence.
• A failed delivery keeps the cargo loaded (assignment status failed) and creates a high-priority task "Arrange redelivery: {trip} stop {n}", due in 4 hours, for the trip owner. Scheduling a redelivery adds a new delivery stop at the same place, moves the cargo to it and marks that task done.

Jobs on this trip (الأعمال على هذه الرحلة): Job, Pieces, Weight kg, Pickup stop, Delivery stop, Status (assignment statuses planned, loaded, delivered, failed). Capacity overrides lists every over-capacity assignment with its reason, measure and user.

Fields

Add stop:

Assign cargo:

Stop controls (dispatched trip):

Actions

The routes are documented together as /trips/{id}/(stops|assign|dispatch|complete) and /trip-stops/{id}/(arrive|pickup|deliver|fail|redeliver).

Rules and messages

• "Trip was not found." / "Stop was not found." / "The stop is not on this trip."
• "The time window ends before it starts." / "Stops are added to planned or dispatched trips only."
• "Cargo is assigned while the trip is planned." / "Choose a pickup stop and a later delivery stop of this trip." / "Only road jobs go on a trip."
• "This load exceeds the trip weight capacity (… planned, … available). Give an override reason to proceed." (also for volume) / "You cannot override trip capacity."
• "Only a planned trip is dispatched." / "Assign cargo before dispatching the trip."
• "Stops are worked on a dispatched trip." / "Arrival is recorded once, at a pending stop." / "Only an open pickup stop is completed."
• "Delivery needs a proof of delivery reference." / "Only an open delivery stop is completed." / "Load every lot for this stop before delivering it."
• "Only an open delivery stop can fail." / "Only a failed delivery is redelivered." / "A redelivery stop already exists for this failure."
• "Only a dispatched trip is completed." / "Some cargo on this trip is not delivered yet."

Role differences

• Warehouse or dispatch user (operations.trip.view only): read-only trip page, no stop controls.
• Operations coordinator: can plan, assign, dispatch and work stops, but an over-capacity assignment with a reason is refused with "You cannot override trip capacity." Operations manager can override.

Procedures

Draft, check and issue a direct air waybill

1. Open the air job, tab Air. If the policy warning shows, ask a pricing manager to set the air chargeable-weight policy.
2. In Draft a waybill choose Type Direct, type the AWB number (11 digits with check digit), Origin, Destination, Pieces, Gross weight and either Dimensions or Or volume, then Terms, Shipper, Consignee, Nature of goods and Currency.
3. Click Draft waybill. Check Chargeable kg in the table.
4. For an export, record a passed security screening (see next procedure).
5. As an Operations manager click Issue and confirm.

Record screening and a dangerous-goods review

1. As an Operations manager open the Air tab.
2. If the cargo is dangerous goods, click Flag as dangerous goods.
3. In the review form choose Review type Security screening, Outcome Passed, type Method, Reviewed at (UTC) and Evidence, click Record review.
4. For dangerous goods record a second review with UN number, Hazard class, Packing group, and tick I hold current DG training.

Book a shipment on two flights (split shipment)

1. Under Add a flight, add each flight (Carrier, Flight number, Flight date, Origin, Destination) and click Add flight.
2. Choose the first Flight, type part of the pieces, click Book pieces on flight; repeat with the second flight for the rest.
3. When each flight leaves, use Event Departed with Pieces, Occurred (UTC) and Evidence, click Record event.
4. The job shows departed only when every piece has departed; arrival likewise.

Build a consolidation and split a shared carrier cost

1. Open Operations > Consolidations, choose Branch and Mode, click Open consolidation.
2. On the detail page enter Job id and Pieces and click Assign lot for each job.
3. Enter Declared pieces equal to the total and click Declare total. Status must be open.
4. In Carrier cost estimate choose Charge, Payee, type Quantity, choose Unit, type Rate, choose Currency, click Record estimate.
5. Choose the Split basis and click Propose split. Check that the shares add up to the estimate.
6. Click Approve allocation and confirm.
7. Sign in as a different user with operations.cost_estimate.approve and click Approve estimate.
8. A user with finance.accrual.post and access to the page clicks Accrue cost (staging only).

Correct a carrier cost after approval

1. Open Revise on the estimate.
2. Before accrual: type the new quantity and rate and a reason, click Revise estimate, then propose and approve a new split and approve again.
3. After accrual: an increase creates an adjustment line; a decrease is refused and is handled on the supplier bill or a credit note.
4. If lots changed after approval, type the reason and click Revise split; for an accrued cost, a different approver clicks Approve split revision.

Plan and run a road trip

1. Open Operations > Road trips, fill Plan a trip and click Plan trip.
2. On the trip, add a Pickup stop and a later Delivery stop with Add stop.
3. Choose Road job, type Pieces, choose Pickup stop and Delivery stop, click Assign.
4. Click Dispatch trip and confirm.
5. At the pickup: Arrived, then Loaded with time and evidence.
6. At the delivery: Delivered with time, POD reference and signer.
7. Click Complete trip and confirm.

Handle a failed delivery

1. On the delivery stop type Failed at (UTC) and the reason, click Failed and confirm.
2. Open Workspace > Tasks to see "Arrange redelivery: …".
3. On the failed stop enter the new window and click Schedule redelivery. Deliver the new stop as usual.

Troubleshooting

7. Customs, custody, release and documents

This chapter covers what happens to cargo and papers around the border and the warehouse: customs cases with declaration lines, assessments, status changes and duty or tax payments; warehouse receipts and dispatches from custody; the cargo and document release with its blocking checks and the release exception; and the documents filed on a job, including the house bill of lading issue and the company's private file store.

Who uses it:

Spec references: §11.1 (customs), §11.2 (custody), §12 (holds, exceptions and approvals), §13 (documents), §15 (credit control on release). UML: 12, 13, 14, 15, 52. Acceptance: A09 (release with holds), A24 (unsafe upload and unauthorised download), A01 (company isolation).

Customs cases

Open: sidebar Operations > Customs. Route: /customs. Needs operations.customs.view. Page title Customs (الجمارك), heading Customs cases (الحالات الجمركية).

The subtitle reads "Customs cases across jobs. A held case places a customs hold on the job's cargo release until it is released." The table lists up to 200 cases, open cases first and newest first: Case (reference starting with CUS, links to the job's Customs tab), Job, Direction, Declaration (type), Number (declaration number), Status, Updated. With no cases the page says "No customs cases. Open one from a job's Customs tab."

Case statuses and the moves the code allows:

Fields

The list has no form.

Actions

Rules and messages

• Only cases of your current company are listed.

Role differences

Customs coordinator, Operations coordinator, Operations manager and Finance manager see the list. Roles without operations.customs.view (for example Documentation officer, Warehouse or dispatch user) have no sidebar link and get "You do not have permission for this action." (403).

Job customs (Customs tab)

Open: job page > Customs tab, or a case link on the Customs cases list. Route: /jobs/{id}/customs. Needs operations.customs.view.

Numbered areas: 1 case details, 2 Declaration lines, 3 Assessments, 4 Change status, 5 Duty and tax payments.

The subtitle reads "Duty and tax payments are requested here and approved by finance. Recording a payment here posts no ledger entry; the payment is recognised when finance records it." Without a case the tab says "No customs case on this job." and shows Open a customs case (فتح حالة جمركية) to users who may manage customs.

Each case shows its reference and status, then Direction, Declaration type, Declaration, Broker, Office and Released (release time and reference). A held case shows a red Held notice with the hold note.

• Declaration lines (بنود البيان): #, HS code, Description, Origin, Quantity, Customs value. "No lines." when empty.
• Assessments (الربوط الجمركية): Type, Amount, Reference, Assessed.
• Change status (تغيير الحالة): the next statuses allowed for the current status.
• Duty and tax payments (مدفوعات الرسوم والضرائب): Payee, Purpose, Funding, Amount, Status (requested, paid), Approval (status of the finance approval). "None requested." when empty.
• History: every status change with time, user and note.

Fields

Open a customs case: