Inbound Group Management Module - Functional Description¶

Overview¶

The Inbound Group Management module is a comprehensive system for managing tourist group bookings, from initial quote through arrival and departure. It enables tour operators to coordinate all aspects of group travel including passenger information, accommodation, activities, transportation, and financial summaries.

Primary Use Cases¶

1. Group Lifecycle Management¶

Create New Groups: Register new inbound tourist groups with partner agency, arrival/departure dates, and expected number of passengers
Search & Filter Groups: Find groups by arrival date range and/or partner agency
Track Group Status: Monitor groups through multiple states:
- IN PREPARATION (initial planning)
- QUOTE SENT (proposal submitted to partner)
- CONFIRMED (booking confirmed)
- CANCELLED (booking cancelled)
- ARRIVED (group has arrived)
- DEPARTED (group has completed)

2. Passenger (Pax) Management¶

Register Passengers: Capture complete passenger information including:
- Personal details (name, gender, age, date of birth)
- Travel documents (passport number, nationality)
- Contact information (phone, email)
Bulk Passenger Creation: Auto-generate placeholder passenger records based on expected group size
Age Classification: Automatically categorize passengers as adults or children for pricing purposes

3. Accommodation Management¶

Hotel Booking Tracking: Record multiple hotel stays per group with:
- Check-in/check-out dates
- Hotel contacts
- Confirmation dates
- Status (OPEN, REQUESTED, QUOTED, CONFIRMED, CANCELLED)
- Contracted room rates (cost) and sale rates (price)
- Currency codes
Rooming List: Assign passengers to specific rooms with:
- Room capacity (number of beds)
- Extra bed indicators
- Room type (King bed, Split beds)
- Cost and price per room
- Notes for special requests
Room-Passenger Assignment: Track which passengers occupy which rooms, preventing double-booking

4. Activities & Services Management¶

Add Tour Activities: Schedule activities from the product catalog with:
- Separate adult and child pricing
- Number of adults and children participating
- Departure date/time
- Guide/driver assignment
- Ticket requirements tracking (needs tickets, tickets purchased)
- Transfer inclusion flags (auto-creates linked transport when enabled)
- Product variant selection
Activity Status Tracking: Monitor ticket procurement and transfer arrangements
Extra Costs: Add flat additional costs to activities (e.g., guide fees, parking, tips) via the activity details dialog. Each extra cost has a description, amount, and currency.
Ticket Requirements: Define per-attraction ticket requirements for activities that need tickets. Each requirement specifies an attraction from the offline tickets module and the quantity needed. The system shows fulfilled counts based on actual ticket sales.
Offline Ticket Assignment: Assign pre-purchased offline tickets directly to a group activity via the Offline Tickets module. When tickets are assigned:
- The activity's ticketsPurchased flag is automatically set to true
- Each ticket stores a reference to the activity (tripServiceId)
- Tickets are marked as SOLD with download codes generated
- No separate invoice or payment link is created (cost is covered by the group package)
- The schedule view shows "OK" status for activities with assigned tickets

5. Transportation Management¶

Ground Transport Coordination: Schedule and track:
- Airport pickups/dropoffs
- Hotel-to-venue transfers
- Inter-city transportation
Auto-Transfer Creation: When an activity includes transfers, a linked transport entry is automatically created with the activity's date/time and a default duration of 1 hour
Vehicle Details: Record vehicle type (sedan, 7-seater, 24-seater, etc.), driver information, and contact numbers
Duration Tracking: Transport duration is tracked in hours
Confirmation Status: Track whether each transport has been confirmed with the provider
Transport Costing: Track cost and sale price for each transport service
Cascade Delete: Auto-created transports are automatically deleted when their parent activity is deleted

6. Financial Summary & Quoting¶

Cost/Price Aggregation: Automatically summarize all components:
- Accommodation costs (grouped by hotel and rate)
- Activity costs (separate adult/child calculations)
- Transportation costs
Margin Calculation: Display profit margin for each line item and overall group
Itemized Quote Generation: Create customer-facing quotations with:
- Option to include/exclude specific items
- Editable costs and prices
- Automatic total calculations
Quote Export: Generate printable quotes for partner agencies
PDF Quotation: Generate professional PDF quotations with company header (logo, name, contacts), group details, accommodation, activities, transport (duration in hours), itemized cost breakdown, and chronological schedule

7. Schedule & Timeline Visualization¶

Schedule Table (on Groups List page): Consolidated view of upcoming events across all visible groups:
- Events grouped by date with separator rows
- Event types: hotel check-in/check-out, transport, activity
- Color-coded readiness status pills (OK, No confirmation, No driver, Not booked, Tickets needed)
- Configurable date range (2 weeks / 1 month / 2 months / 3 months)
- Print support with portrait orientation
- Excel export download
Trip Calendar View (per-group): Display group activities across the trip duration showing:
- Arrival and departure dates
- Scheduled activities per day
- Transportation events
- Visual highlighting for current day and trip boundaries

Key Workflows¶

Workflow 1: New Group Creation & Quoting¶

Search for existing groups or create new group
Enter group details (partner, dates, number of passengers, group leader)
Add passenger records (manually or auto-generate)
Add hotel accommodations with rates
Create rooming list and assign passengers to rooms
Add scheduled activities with pricing
Add transportation services
Review financial summary
Adjust costs/prices as needed
Generate and send quote to partner agency
Update status to "QUOTE SENT"

Workflow 2: Booking Confirmation¶

Select confirmed group
Update status to "CONFIRMED"
Set confirmation date and deadline
Confirm hotel bookings
Purchase activity tickets — either manually (update ticket status) or assign pre-purchased offline tickets via the Offline Tickets module (see Offline Tickets — Group Assignment)
Finalize transportation arrangements
Assign specific room numbers

Workflow 3: Pre-Arrival Operations¶

Review passenger documentation (passports, visas)
Confirm all hotel reservations
Verify activity tickets are purchased
Confirm transportation with vendors
Brief guides/drivers on schedule
Print final rooming lists and activity manifests

Workflow 4: Group Arrival & Departure¶

Update status to "ARRIVED" on arrival day
Monitor daily activities via calendar
Handle any last-minute changes or additions
Update status to "DEPARTED" on departure day
Generate final invoice

Data Relationships¶

Core Entities¶

CTripGroup (Group master record)
- Contains: Partner info, dates, pax count, nights, status, currency
- Linked to: Quote ID, Invoice ID
CTripPax (Passenger)
- Belongs to: One group
- Linked to: Multiple rooms (via room assignments)
CTripHotel (Hotel booking)
- Belongs to: One group
- References: Hotel master (hotel ID)
- Contains: Check-in/out dates, rates, status
CTripRoom (Individual room allocation)
- Belongs to: One group, one hotel booking
- Contains: Capacity, extra bed, rates, type
- Linked to: Multiple passengers
CTripService (Activity/service)
- Belongs to: One group
- References: Product master (product ID)
- Contains: Adult/child pricing, quantities, guide, ticket status
- Linked to: Offline tickets (via tripServiceId FK on offline_ticket table) — tickets assigned from the Offline Tickets module
CServiceExtraCost (Activity extra cost)
- Belongs to: One trip service/activity
- Contains: Description, cost amount, currency code
- Cascade-deleted when parent activity is deleted
CServiceTicketReq (Activity ticket requirement)
- Belongs to: One trip service/activity
- References: Offline attraction (attraction ID)
- Contains: Quantity required, fulfilled count (transient)
- Cascade-deleted when parent activity is deleted
CTripTransport (Ground transport)
- Belongs to: One group
- References: Transport partner (partner ID)
- Optionally linked to: One trip service/activity (for auto-created transfers via activityId)
- Contains: Vehicle, driver, duration (hours), timing, cost/price, confirmation status

API Operations¶

Group Operations¶

POST /groups/group/list: Search groups by partner and/or arrival dates
POST /groups/group/write: Create or update group record
POST /groups/group/loadExpanded: Load complete group data with all related records

Passenger Operations¶

POST /groups/pax/list: List passengers for a group
POST /groups/pax/write: Create or update passenger(s) - supports bulk operations
POST /groups/pax/read: Retrieve single passenger details

Accommodation Operations¶

POST /groups/hotel/list: List hotels for a group
POST /groups/hotel/write: Create or update hotel booking

Room Operations¶

POST /groups/triproom/list: List rooms for a group/hotel
POST /groups/triproom/write: Create or update room
POST /groups/triproom/delete: Delete room
POST /groups/triproom/listpax: List passengers assigned to room(s)
POST /groups/triproom/updatepaxlist: Bulk add/remove passengers from room

Transport Operations¶

POST /groups/transport/list: List transport services for a group
POST /groups/transport/write: Create or update transport service

Activity Operations¶

POST /groups/tripservice/write: Create or update trip service/activity
POST /groups/tripservice/delete: Delete activity (cascades to extra costs, ticket requirements, and linked transports)

Extra Cost Operations¶

POST /groups/extracost/list: List extra costs for an activity
POST /groups/extracost/write: Create or update an extra cost
POST /groups/extracost/delete: Delete an extra cost

Ticket Requirement Operations¶

POST /groups/ticketreq/list: List ticket requirements with fulfilled counts
POST /groups/ticketreq/write: Create or update a ticket requirement
POST /groups/ticketreq/delete: Delete a ticket requirement

Quotation Operations¶

POST /groups/quotation/generatePdf: Generate PDF quotation for a group

Export Operations¶

POST /groups/pax/exportExcel: Export passengers as Excel file (binary download)
POST /groups/exportSchedule: Export schedule events across multiple groups as Excel file (binary download)

Business Rules¶

Date Validation: Check-out date must be after check-in date for hotels
Capacity Management: Room passenger count cannot exceed room capacity plus extra beds
Status Progression: Groups typically progress: IN PREPARATION → QUOTE SENT → CONFIRMED → ARRIVED → DEPARTED
Cost/Price Separation: System maintains separate cost (vendor price) and price (customer price) for all billable items
Multi-Currency Support: Each group has a default currency, but costs can be in different currencies
Passenger Availability: Passengers can only be assigned to one room per hotel booking
Activity Pricing: Separate pricing for adults and children with flexible quantities

Key Features¶

Master-Detail Navigation: Select group from search results to view/edit all details in tabbed interface
Real-time Calculations: Automatic totaling of costs, prices, and margins
Lookup Integration: Auto-complete for partner agencies, hotels, and activity products
Flexible Quoting: Include/exclude items from quotes, adjust individual prices
Document Generation: Export quotes, rooming lists, and schedule as Excel; generate PDF quotations with company branding
Schedule Overview: Cross-group schedule table with date-grouped events and readiness alerts (print + Excel export)
Change Tracking: Detect unsaved changes and prompt before navigation
Bulk Operations: Auto-generate passengers, batch room creation
Visual Summary Cards: Quick overview of group details, hotels, transport, and activities

Creating Bookings from Inbound Groups¶

Inbound groups can be converted into bookings to track the full booking lifecycle including payments, actions, and documents.

Creating a New Booking¶

Open the Group Summary page for your inbound group
Click the Create Booking button in the action bar (visible only for INBOUND groups)
Confirm the action in the dialog

The system creates a booking with: - Customer: the partner agency (name and contact details from the partner record) - Hotels: one service line per hotel, with all room costs summed - Transports: one service line per transport - Activities/Services: one service line per activity, with adult and child costs aggregated - Passengers: all group passengers imported, with the first passenger marked as lead - Dates: arrival and departure dates from the group

Updating an Existing Booking¶

If you modify the group (add/remove services, change passengers, update hotels) and click Create Booking again: - If the booking is in ENQUIRY or QUOTED status, it is updated in-place — all service lines and passengers are replaced with the current group data - If the booking has been CONFIRMED or is further along in the lifecycle, the system will show an error. In this case, cancel the existing booking first or make changes directly on the booking detail page.

What Happens Next¶

After creation or update, you are redirected to the booking detail page where you can: - Review imported services and passengers - Manage the booking lifecycle (quote, confirm, collect payment) - Generate vouchers and documents - Track actions and amendments

Post-Booking Workflow¶

After the booking is created from the inbound group: - The booking appears in the booking list with source type GROUP_INBOUND - Service lines reflect the group's hotels, transport, and activities - Passengers are copied from the group passenger list - The lead passenger is set automatically

You can then: - Progress the booking through the standard lifecycle (quote, confirm, invoice) - Generate vouchers and send confirmation emails - Track payments and amendments

For details on managing the booking after creation, see Managing Bookings and Service Lines.

Suggested Improvements & Missing Features¶

Based on analysis of modern tour operator requirements and best practices in group travel management, the following enhancements are recommended:

1. Document Management¶

Current Gap: No centralized document storage for group-related files

Suggested Features: - Upload and attach documents to groups (contracts, vouchers, insurance certificates) - Attach documents to individual passengers (passport scans, visa copies, medical forms) - Version control for quotes and itineraries - Hotel confirmation voucher generation and storage - Activity ticket/voucher management - Document expiration tracking (passport validity, visa expiry)

2. Communication & Notifications¶

Current Gap: No built-in communication tracking or automated notifications

Suggested Features: - Email integration for sending quotes and confirmations directly from the system - Communication history log (emails, calls, meetings with partner agencies) - Automated notifications for: - Upcoming confirmation deadlines - Payment due dates - Document expiration warnings - Arrival/departure reminders - SMS notifications for guides/drivers about daily assignments - Partner portal for real-time group status visibility

3. Payment & Financial Management¶

Current Gap: Limited payment tracking - only references quote ID and invoice ID

Suggested Features: - Payment schedule management (deposit, installments, final payment) - Payment tracking with status (pending, received, overdue) - Multiple payment methods support - Currency exchange rate tracking and automatic conversion - Payment receipts generation - Outstanding balance alerts - Refund management for cancellations - Commission calculation for partner agencies

4. Meal Plan Management¶

Current Gap: No meal tracking for groups

Suggested Features: - Meal plan per hotel (breakfast, half-board, full-board, all-inclusive) - Special dietary requirements tracking per passenger - Meal voucher generation - Restaurant reservation management for group dining - Cost tracking for meals not included in hotel rate

5. Insurance & Risk Management¶

Current Gap: No insurance tracking

Suggested Features: - Travel insurance policy tracking per passenger or group - Insurance provider details and policy numbers - Coverage details and limits - Emergency contact information for each passenger - Medical conditions/allergies tracking - Emergency response procedures documentation

6. Flight & Visa Management¶

Current Gap: Only tracks arrival/departure dates, not flight details

Suggested Features: - Flight itinerary management (flight numbers, airlines, times) - Airport terminal information - Visa requirement tracking by nationality - Visa application status monitoring - Flight delay notifications integration - Meet & greet arrangements at airport

7. Reporting & Analytics¶

Current Gap: Limited reporting capabilities

Suggested Features: - Group profitability reports - Seasonal occupancy analysis - Partner performance metrics - Guide/driver utilization reports - Activity popularity analysis - Revenue forecasting - Cost variance analysis (budgeted vs actual) - Export capabilities (Excel, PDF, CSV)

8. Optimization & Smart Features¶

Current Gap: Manual processes for complex operations

Suggested Features: - Intelligent room assignment algorithm (families together, single travelers grouped) - Optimal vehicle allocation based on group size and luggage - Route optimization for multi-hotel/activity itineraries - Dynamic pricing suggestions based on demand/season - Duplicate passenger detection - Conflict detection (double-bookings, overlapping activities)

9. Multi-language Support¶

Current Gap: Single language interface

Suggested Features: - Multi-language interface for international teams - Multi-language quote/document generation - Translation of activity descriptions - Passenger communication in their native language

10. Mobile & Offline Capabilities¶

Current Gap: Web-only interface

Suggested Features: - Mobile app for guides and drivers - Offline access to daily schedules - Real-time group location tracking - Check-in/check-out QR code scanning - Photo upload for trip documentation - Emergency contact quick-access

11. Integration Capabilities¶

Current Gap: Appears to be standalone system

Suggested Features: - Hotel booking system integration (APIs for live availability) - Accounting software integration (QuickBooks, Xero) - CRM integration for partner relationship management - Payment gateway integration - Flight tracking API integration - Weather forecast integration for activity planning - WhatsApp/Telegram integration for group communication

12. Compliance & Audit¶

Current Gap: No audit trail visibility

Suggested Features: - Complete audit trail for all changes (who, when, what) - GDPR compliance tools (data export, deletion, consent tracking) - Booking terms & conditions acceptance tracking - Cancellation policy enforcement - User permission management by role - Activity logs for security monitoring

13. Template & Cloning Features¶

Current Gap: Manual recreation of similar groups

Suggested Features: - Group template creation for recurring itineraries - Clone existing groups with one click - Standard activity package templates - Quick-add pre-defined tour packages - Default settings per partner agency

14. Supplier Management¶

Current Gap: Basic partner/vendor tracking

Suggested Features: - Comprehensive supplier database (hotels, activity providers, transport companies) - Supplier contract management - Performance ratings for suppliers - Supplier payment terms tracking - Preferred supplier lists - Supplier blacklisting capability - Automated supplier payment reconciliation

15. Quality Control & Feedback¶

Current Gap: No post-trip feedback mechanism

Suggested Features: - Post-trip surveys for passengers - Quality ratings for hotels, guides, and activities - Issue tracking and resolution - Continuous improvement metrics - Partner satisfaction tracking - Service complaint management

Implementation Priority Recommendations¶

High Priority (Immediate Business Impact)¶

Payment & Financial Management - Critical for cash flow
Document Management - Reduces manual work, improves organization
Communication & Notifications - Improves customer service and reduces missed deadlines
Reporting & Analytics - Essential for business intelligence

Medium Priority (Operational Efficiency)¶

Flight & Visa Management - Completes the trip lifecycle
Meal Plan Management - Common customer requirement
Template & Cloning - Significant time savings
Integration Capabilities - Reduces data entry errors

Lower Priority (Nice to Have)¶

Insurance & Risk Management - Important but can be managed externally initially
Mobile & Offline - Valuable but web version adequate initially
Optimization Features - Can provide incremental improvements
Quality Control & Feedback - Long-term improvement tool

This module serves as the operational heart of inbound tour operations, providing end-to-end management from initial inquiry through post-departure invoicing. The suggested improvements would transform it into a best-in-class group travel management platform.