Outbound Group Management - Use Cases¶

Document Information¶

Property	Value
Document Version	1.0
Last Updated	2026-02-16
Status	Current
Owner	Product Management
Module	tqweb-adm

Table of Contents¶

Overview
Users and Roles
Trip Lifecycle
Use Cases: Trip Management
Use Cases: Itinerary Planning
Use Cases: Passenger Management
Use Cases: Accommodation
Use Cases: Activities and Tours
Use Cases: Ground Transportation
Use Cases: Room Assignments
Use Cases: Pricing
Use Cases: Financial Overview
Use Cases: Invoicing
Business Rules

1. Overview¶

1.1 Purpose¶

Outbound Group Management handles the complete lifecycle of organized group trips departing from the UAE to international destinations. It covers trip planning, passenger coordination, supplier management, pricing, and invoicing.

This is distinct from inbound group management (groups arriving to the UAE). Both share the same underlying data model but have separate workflows and user interfaces.

1.2 Business Context¶

A travel operator receives a request from a partner agency (e.g., a corporate client or travel partner) to organize an outbound group trip. The operator must:

Plan the itinerary day by day
Source and manage suppliers for hotels, activities, and transport
Track passenger details including visa requirements
Define pricing tiers and calculate margins
Create invoices for passengers or the partner agency

1.3 Trip Types¶

Type	Description
Collaborative	Organized jointly with a partner agency; the partner provides the passenger list and the operator handles logistics
Self-Organized	Fully organized internally by the operator, typically for corporate or retail group sales

2. Users and Roles¶

Role	Responsibilities
Operations Coordinator	Creates and manages trips, builds itineraries, coordinates suppliers
Reservations Agent	Manages passenger lists, room assignments, visa tracking
Finance Staff	Sets pricing tiers, reviews financial summaries, creates invoices
Manager	Monitors trip portfolio, reviews margins, approves quotes

All roles require authenticated access (agent or admin level).

3. Trip Lifecycle¶

A trip progresses through the following statuses:

Status	Description
Draft	Trip created, initial details being entered
Quoted	Quote prepared and sent to partner agency
Negotiation	Price or scope being negotiated with partner
Confirmed	Partner has confirmed; preparation begins
Preparing	Active preparation: finalizing suppliers, visas, rooming
Traveling	Group is currently on the trip
Completed	Trip finished; post-trip processing (invoicing, reconciliation)
Cancelled	Trip cancelled at any stage

Typical flow: Draft > Quoted > Negotiation > Confirmed > Preparing > Traveling > Completed

4. Use Cases: Trip Management¶

UC-OG-001: Browse Outbound Trips¶

Actor: Operations Coordinator, Manager

The user views all outbound trips as cards on the main dashboard. Each card shows the trip name, partner agency, route (origin to destination), departure and return dates, passenger count, nights, trip type, and current status.

Filtering options: - Partner agency (search by name) - Departure date range - Status

UC-OG-002: Create New Trip¶

Actor: Operations Coordinator

The user creates a new outbound trip by providing:

Partner agency (mandatory) - selected via search lookup from existing companies
Trip name (mandatory) - descriptive name for the trip
Origin - departure location (e.g., "Dubai, UAE")
Destination country (mandatory) - selected via country lookup from restcountries.com; stores ISO Alpha-3 code (destinationCountry). Used for visa requirement lookups.
Destination city - free text (e.g., "Istanbul")
Departure and return date/time
Expected number of passengers and nights
Trip type (Collaborative or Self-Organized)
Currency (AED, EUR, or USD)
Trip leader name and partner contact

After creation, the user is taken to the trip summary page.

UC-OG-003: Edit Trip Details¶

Actor: Operations Coordinator

The user modifies the basic details of an existing trip (partner, dates, destination, status, etc.) via the same form used for creation. The edit dialog is available from both the trip list page and the trip summary page (via an Edit button in the header card).

UC-OG-004: Navigate Trip Management¶

Actor: All roles

From any trip's summary page, the user can navigate to specialized management pages: Itinerary, Passengers, Accommodation, Activities, Transport, Rooming, Pricing, and Invoicing.

The summary page displays a workflow progress indicator showing completion status for each management area. Each step has three visual states: - Complete (green check) - all required data is present (e.g., passengers count matches expected numPax) - Partial (amber clock) - data has been entered but is incomplete (e.g., some passengers added but fewer than expected numPax) - Not started (grey circle) - no data entered yet

5. Use Cases: Itinerary Planning¶

UC-OG-010: View Itinerary¶

Actor: Operations Coordinator

The user views the day-by-day itinerary for a trip, displayed as ordered day cards showing the day number, date, title, and description.

UC-OG-011: Auto-Generate Itinerary Days¶

Actor: Operations Coordinator

The user clicks a button to automatically generate itinerary day entries for the full duration of the trip (based on departure and return dates). The system:

Creates one entry per day
Numbers days sequentially
Labels the first day as "Arrival" and the last day as "Departure"
Skips days that already exist (safe to run multiple times)

UC-OG-012: Add/Edit Itinerary Day¶

Actor: Operations Coordinator

The user manually adds or edits an itinerary day with:

Day number
Date
Day title (e.g., "City Tour & Shopping")
Detailed description of the day's activities

UC-OG-013: Delete Itinerary Day¶

Actor: Operations Coordinator

The user removes an itinerary day entry.

6. Use Cases: Passenger Management¶

UC-OG-020: View Passenger List¶

Actor: Reservations Agent

The user views all passengers registered for a trip in a table format, showing name, nationality, passport details, visa status, and emergency contact information.

UC-OG-021: Add/Edit Passenger¶

Actor: Reservations Agent

The user adds or edits passenger details:

Name (first, last), gender
Date of birth
Nationality (mandatory) - selected via country lookup from restcountries.com; stores both display name and ISO Alpha-3 code (nationalityCode). On selection, auto-checks visa requirement against the trip's destination country.
Passport number
Phone (mandatory) and Email (mandatory) - required for CRM customer creation and visa applications
Emergency contact name and telephone
Visa information:
Visa Required - auto-populated on nationality selection; values: Unknown, Not Required, Visa On Arrival, Online Visa, Visa Required. An IATA Travel Centre link button is provided for manual verification.
Visa Status - values: Doc Pending, Doc Complete, Applied, Approved, Rejected, Not Needed. A "Create/Open Visa Application" button is provided (enabled only when editing an existing passenger who requires a visa).
Notes

Input validation: - Email must be a valid email format - Phone and emergency telephone must contain 7-15 digits - Date of birth must not be in the future - Passport number must be alphanumeric (max 20 characters) - Nationality must be selected from the country lookup (not free-typed)

Post-save behavior: When a new passenger is saved with visa required as ONLINE or REQUIRED, the system prompts to create a visa application. If confirmed, the application is created and a notification is shown ("Visa application for FirstName LastName created") — the user stays on the passengers page rather than being redirected to the visa management page.

UC-OG-022: Delete Passenger¶

Actor: Reservations Agent

The user removes a passenger from the trip.

UC-OG-023: Import Passengers from Excel¶

Actor: Reservations Agent

The user uploads an Excel file to bulk-import passengers. The system parses the file and creates passenger records for each valid row. This is useful when the partner agency provides a passenger manifest.

UC-OG-024: Export Passengers to Excel¶

Actor: Reservations Agent

The user downloads the complete passenger list as an Excel file, including visa status and emergency contact fields. This can be shared with the partner agency or used for record-keeping.

UC-OG-025: Bulk Visa Check¶

Actor: Reservations Agent

The user triggers a bulk visa requirement check for all passengers based on the trip's destination country (stored as destinationCountry Alpha-3 code on the group). The destination is displayed as read-only (from group data). The system:

If a passenger's nationality matches the destination country, immediately classifies as NOT_REQUIRED (skips the API call)
Converts nationality codes (Alpha-3) and destination code to Alpha-2 for the TravelBuddyAI API (v2)
Classifies the API response using a data-driven rules array that matches visa_rules.primary_rule.name against keywords (see Visa Category Classification)
Updates the "Visa Required" field: NOT_REQUIRED, VOA (Visa on Arrival), ONLINE (e-visa/eTA), REQUIRED, UNKNOWN
For visa-free passengers, automatically sets Visa Status to NOT_NEEDED
Passengers without a nationality code are marked as UNKNOWN

UC-OG-026: Filter Passengers by Visa Status¶

Actor: Reservations Agent

The user toggles a filter to show only passengers who require visa (REQUIRED, ONLINE, or legacy YES) and whose visa status is not yet APPROVED or NOT_NEEDED.

UC-OG-027: Create Visa Application for Passenger¶

Actor: Reservations Agent

From the passenger edit modal, the user clicks the "Create Visa Application" button (enabled only when visa is ONLINE or REQUIRED). The system:

Creates a customer in the CRM (Odoo) using the passenger's name, phone, and email
Creates a visa application in the visa module with travel dates and destination from the group
Creates a visa applicant record with the passenger's personal details (name, DOB, nationality, passport)
Links the passenger to the visa application via visaApplicationId
Sets the passenger's visa status to DOC_PENDING
Shows a success notification ("Visa application for FirstName LastName created")

If the passenger already has a linked visa application, the button instead opens the existing application.

UC-OG-028: Auto-Open Visa Application from URL¶

Actor: Reservations Agent

When visamgmt.html is opened with an appId URL parameter, it automatically opens the manage modal for that application, enabling seamless navigation from the passenger page.

7. Use Cases: Accommodation¶

UC-OG-030: View Hotels¶

Actor: Operations Coordinator

The user views all hotels booked for the trip, displayed as cards showing hotel name, check-in/check-out dates, nights, meal plan, and supplier information.

UC-OG-031: Add/Edit Hotel¶

Actor: Operations Coordinator

The user adds or edits a hotel booking:

Hotel name (free text entry)
Check-in and check-out dates (nights calculated automatically)
Meal plan (None, Bed & Breakfast, Half Board, Full Board, All Inclusive)
Currency
Supplier name and contact
Quote document reference
Inclusions (what the rate covers)
Exclusions (what is not covered)
General notes

UC-OG-032: Navigate to Room Assignments¶

Actor: Operations Coordinator

From a hotel card, the user navigates directly to the rooming page for that hotel to manage room assignments.

8. Use Cases: Activities and Tours¶

UC-OG-040: View Activities¶

Actor: Operations Coordinator

The user views all activities, tours, and excursions planned for the trip.

UC-OG-041: Add/Edit Activity¶

Actor: Operations Coordinator

The user adds or edits an activity:

Activity name (free text)
Date and time
Number of adults and children participating
Cost per adult and per child
Supplier name and contact
Inclusions and exclusions
Notes

The total cost is calculated automatically (cost per person multiplied by participant count).

UC-OG-042: Delete Activity¶

Actor: Operations Coordinator

The user removes an activity from the trip.

9. Use Cases: Ground Transportation¶

UC-OG-050: View Transfers¶

Actor: Operations Coordinator

The user views all ground transportation arrangements for the trip.

UC-OG-051: Add/Edit Transfer¶

Actor: Operations Coordinator

The user adds or edits a transfer:

Description
Route: from location and to location
Vehicle type (Sedan, 7-Seater SUV, 14/24/30/40/52-Seater bus)
Start and end time
Driver name and telephone
Supplier name
Cost (supplier charge) and price (charge to client)
Currency

UC-OG-052: Delete Transfer¶

Actor: Operations Coordinator

The user removes a transfer from the trip.

10. Use Cases: Room Assignments¶

UC-OG-060: View Rooming List¶

Actor: Reservations Agent

The user views the room assignment board for a selected hotel, showing:

Unassigned passengers (highlighted prominently at the top)
Room cards with type, capacity, occupancy indicator, and assigned passenger names
Room cost and price

If the trip has multiple hotels, the user selects which hotel to view from a dropdown.

UC-OG-061: Add Room¶

Actor: Reservations Agent

The user adds a room to a hotel:

Room type (Double, Single, Twin, Triple, Quad)
Capacity (1-6 persons)
Room cost and room price
Notes

UC-OG-062: Assign Passenger to Room¶

Actor: Reservations Agent

The user assigns an unassigned passenger to a room via a dropdown selector. The room's occupancy indicator updates in real time.

UC-OG-063: Remove Passenger from Room¶

Actor: Reservations Agent

The user removes a passenger from a room, returning them to the unassigned list.

UC-OG-064: Copy Rooming Between Hotels¶

Actor: Reservations Agent

When a group moves between hotels during the trip (e.g., Hotel A for the first 3 nights, Hotel B for the next 4 nights), the user copies all room assignments from one hotel to another. This avoids manually re-creating rooms and reassigning passengers for each hotel.

UC-OG-065: Delete Room¶

Actor: Reservations Agent

The user removes a room from the hotel (passengers in that room become unassigned).

11. Use Cases: Pricing¶

UC-OG-070: View Pricing Tiers¶

Actor: Finance Staff

The user views the pricing structure for the trip: a table of pricing tiers with per-person prices and passenger counts, plus totals.

UC-OG-071: Add/Edit Pricing Tier¶

Actor: Finance Staff

The user defines pricing categories for the trip:

Basis description (e.g., "Adult", "Child 4-11", "Infant under 4", "Single Supplement")
Price per person
Number of passengers in this tier
Currency

The total revenue for each tier (price multiplied by passenger count) is calculated and displayed automatically.

UC-OG-072: Delete Pricing Tier¶

Actor: Finance Staff

The user removes a pricing tier.

UC-OG-073: Review Revenue Totals¶

Actor: Finance Staff, Manager

The system displays:

Total passengers across all tiers
Total revenue across all tiers

12. Use Cases: Financial Overview¶

UC-OG-080: View Financial Summary¶

Actor: Finance Staff, Manager

The trip summary page displays a financial dashboard:

Metric	Description
Total Cost	Sum of all supplier costs (accommodation + activities + transport)
Total Revenue	Sum of all pricing tier revenues (price per person multiplied by pax count)
Margin	Revenue minus cost
Margin %	Margin as a percentage of revenue

UC-OG-081: View Cost Breakdown¶

Actor: Finance Staff, Manager

The financial summary includes a breakdown of costs by category:

Accommodation costs (sum of all hotel costs)
Activity costs (sum of all activity costs)
Transport costs (sum of all transport costs)

This helps identify which cost categories have the most impact on the trip margin.

13. Use Cases: Invoicing¶

UC-OG-090: View Invoice Status¶

Actor: Finance Staff

The user views all passengers with their invoicing status:

Not Invoiced - passenger has no associated invoice
Invoiced - passenger has been included in an invoice (invoice number displayed)

UC-OG-091: Select Passengers for Invoicing¶

Actor: Finance Staff

The user selects one or more uninvoiced passengers for bulk invoicing. Passengers who have already been invoiced cannot be selected (prevents duplicate invoicing). A "Select All" option is available to select all uninvoiced passengers at once.

UC-OG-092: Create Invoice¶

Actor: Finance Staff

The user creates an invoice for the selected passengers by providing:

Total price for the invoice
Description (auto-generated with passenger names, editable)

The system creates an invoice in the integrated accounting system (Odoo) and records the invoice ID against each included passenger.

14. Business Rules¶

General¶

Partner agency is mandatory - every outbound trip must be linked to an existing partner agency selected via lookup.
Trip type determines workflow context - Collaborative trips involve partner coordination; Self-Organized trips are managed internally.
Currency is set at trip level - all costs and prices within a trip use the same currency.

Passengers and Visas¶

Visa checking is destination-based - the system evaluates each passenger's nationalityCode (Alpha-3) against the trip's destinationCountry (Alpha-3). Country codes are converted to Alpha-2 for the external visa API.
Same-country short-circuit - when a passenger's nationality matches the destination country, the system immediately returns NOT_REQUIRED without calling the external API.
Country codes use Alpha-3 (cca3) - consistent with the visa module. The restcountries.com API provides both Alpha-2 and Alpha-3 codes; Alpha-3 is stored, Alpha-2 is used for visa API calls.
Visa category classification uses data-driven rules - the TravelBuddyAI v2 API response field visa_rules.primary_rule.name is matched against keyword arrays (e.g., "eta" and "e-visa" both classify as ONLINE). Falls back to the legacy category field. See Visa API docs.
Visa application integration - passengers can be linked to the visa module via visaApplicationId. Creating a visa application automatically creates a CRM customer and populates the visa applicant with passenger data. When created from the passenger save prompt, a notification is shown instead of redirecting to the visa management page.
Phone and email are mandatory - required for CRM customer creation during visa application flow.
Input validation is enforced on all dialogs - all outbound group management dialogs validate inputs: email format, phone digit count (7-15), non-negative costs/prices, date ordering (check-out after check-in, end time after start), passport format (alphanumeric), date of birth not in future, and required field presence.
Excel import is additive - importing passengers creates new records; it does not delete existing passengers.

Accommodation and Rooming¶

Room capacity is enforced visually - the occupancy indicator shows current vs. maximum capacity, but the system does not block over-assignment.
Rooming copy preserves structure - when copying between hotels, room types, capacities, and passenger assignments are replicated.

Pricing and Financials¶

Revenue is tier-based - total revenue is the sum of (price per person multiplied by passenger count) across all pricing tiers.
Costs are supplier-based - total cost is the sum of all hotel, activity, and transport supplier charges.
Margin is calculated automatically - margin = revenue - cost; margin % = margin / revenue.

Invoicing¶

No duplicate invoicing - once a passenger is included in an invoice, they cannot be invoiced again.
Invoicing creates an accounting record - invoices are created in the integrated ERP system (Odoo) with a single line item for the group trip.

Supplier Management¶

Inclusions and exclusions are documented per element - each hotel, activity, and transport entry tracks what is and is not included in the supplier's rate, preventing scope disputes.