Skip to content

Activity Ticketing System - Use Case Specification

1. Introduction

1.1 Purpose

This document describes the use cases for the Activity Ticketing System, detailing the interactions between actors and the system for booking tours, activities, and experiences from third-party ticket suppliers.

1.2 Scope

This document covers: - Customer-facing use cases for browsing, booking, and managing activities - Administrative use cases for booking management - System use cases for catalog synchronization

1.3 Actors

Primary Actors: - Customer - End user browsing and booking activities - Agent - Travel agent managing bookings on behalf of customers - Administrator - System administrator managing configurations

Secondary Actors: - Supplier System - External third-party ticket provider API - System Scheduler - Automated background processes

2. Use Case Overview

2.1 Use Case Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                    Activity Ticketing System                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Customer                Agent              Administrator           │
│     │                      │                      │                 │
│     ├──► UC-01: Browse and Search Products        │                 │
│     │                      │                      │                 │
│     ├──► UC-02: View Product Details              │                 │
│     │                      │                      │                 │
│     ├──► UC-03: Configure Tour Selection          │                 │
│     │                      │                      │                 │
│     ├──► UC-04: Check Availability & Pricing      │                 │
│     │                      │                      │                 │
│     ├──► UC-05: Create Booking                    │                 │
│     │         ◄────────────┤                      │                 │
│     │                      │                      │                 │
│     ├──► UC-06: Receive Ticket Confirmation       │                 │
│     │                      │                      │                 │
│     ├──► UC-07: View Booking Details              │                 │
│     │         ◄────────────┤                      │                 │
│     │                      │                      │                 │
│     ├──► UC-08: Download Tickets                  │                 │
│     │         ◄────────────┤                      │                 │
│     │                      │                      │                 │
│     ├──► UC-09: Amend Booking                     │                 │
│     │         ◄────────────┤                      │                 │
│     │                      │                      │                 │
│     ├──► UC-10: Cancel Booking                    │                 │
│     │         ◄────────────┤                      │                 │
│     │                      │                      │                 │
│     │                      ├──► UC-11: Process Booking Manually     │
│     │                      │             ◄────────┤                 │
│     │                      │                      │                 │
│     │                      │                      ├──► UC-12: Synchronize Catalog
│     │                      │                      │                 │
│     │                      │                      ├──► UC-13: Manage Supplier Config
│     │                      │                      │                 │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

2.2 Use Case List

UC ID Use Case Name Primary Actor Priority
UC-01 Browse and Search Products Customer High
UC-02 View Product Details Customer High
UC-03 Configure Tour Selection Customer High
UC-04 Check Availability & Pricing Customer High
UC-05 Create Booking Customer/Agent High
UC-06 Receive Ticket Confirmation Customer High
UC-07 View Booking Details Customer/Agent High
UC-08 Download Tickets Customer/Agent High
UC-09 Amend Booking Customer/Agent Medium
UC-10 Cancel Booking Customer/Agent High
UC-11 Process Booking Manually Agent/Admin Medium
UC-12 Synchronize Catalog System/Admin High
UC-13 Manage Supplier Configuration Administrator Low

3. Use Case Specifications

UC-01: Browse and Search Products

Primary Actor: Customer

Stakeholders and Interests: - Customer: Wants to discover available tours and activities easily - Business: Wants to showcase product catalog effectively to drive bookings

Preconditions: - Product catalog has been synchronized from supplier - Customer has access to the website

Postconditions: - Customer identifies products of interest - Selected products are available for detailed viewing

Main Success Scenario:

  1. Customer navigates to tours/activities section
  2. System displays product categories (e.g., Desert Safari, Water Sports, Cultural Tours)
  3. Customer selects a category of interest
  4. System retrieves all products in the selected category
  5. System displays product grid with:
  6. Product thumbnail image
  7. Product name
  8. Brief description
  9. Starting price ("From AED XXX")
  10. Duration
  11. Customer browses through product listings
  12. Customer clicks on a product for more details
  13. System navigates to product detail page (see UC-02)

Alternative Flows:

A1: Search by Keywords - At step 3, customer enters search keywords instead of selecting category - System searches products by name, description, destination - System displays search results in grid format - Continue from step 6

A2: Filter Products - At step 6, customer applies filters: - Destination (city, country) - Price range - Duration - Product type - Date availability - System refreshes product grid with filtered results - Continue from step 6

A3: Sort Products - At step 6, customer selects sorting option: - Price (low to high, high to low) - Popularity - Rating - Name (alphabetical) - System re-orders product display - Continue from step 6

A4: No Products Found - At step 4, no products match the criteria - System displays "No products found" message - System suggests alternative categories or search terms - Customer can modify search or select different category - Return to step 3

Exception Flows:

E1: Catalog Data Unavailable - System cannot retrieve product data - System displays error message: "Unable to load products at this time" - System logs error for investigation - Customer can retry or contact support

Business Rules: - Only active products with available inventory are displayed - Products are displayed in order of configuration priority unless sorted - Minimum product information required: name, image, starting price

Technical Notes: - API Endpoint: POST /tlinq-api/product/getCategories, POST /tlinq-api/product/getCategoryProducts - Frontend Module: products.js - loadCategories(), loadCategoryProducts(categoryId) - Caching: Product catalog cached for 1 hour

UC-02: View Product Details

Primary Actor: Customer

Stakeholders and Interests: - Customer: Wants comprehensive information to make informed booking decision - Business: Wants to provide complete product information to increase conversion

Preconditions: - Product exists in catalog - Customer has selected a product from browse/search

Postconditions: - Customer has complete product information - Customer can proceed to configure and book

Main Success Scenario:

  1. Customer clicks on product from listing
  2. System retrieves detailed product information
  3. System displays product detail page with:
  4. Product name and type
  5. Image gallery (multiple photos)
  6. Detailed description and itinerary
  7. Duration and languages available
  8. Inclusions (what's included)
  9. Important information and notes
  10. Terms and conditions
  11. Cancellation policy
  12. Age restrictions (adult/child/infant definitions)
  13. FAQ section
  14. Customer reviews product information
  15. Customer scrolls to view all content sections
  16. Customer views image gallery (clicks to view larger images)
  17. Customer reads terms and cancellation policy
  18. Customer decides to book and clicks "Book Now"
  19. System proceeds to tour configuration (see UC-03)

Alternative Flows:

A1: View Pricing Options - At step 7, customer clicks "View Pricing" - System displays pricing breakdown: - Adult price - Child price (with age range) - Infant price (with age range) - Available product options and their prices - Transfer types and prices - Customer reviews pricing - Continue from step 7

A2: Share Product - At step 7, customer clicks "Share" button - System displays sharing options (email, social media, copy link) - Customer shares product link - Continue from step 7

A3: View Reviews - At step 7, customer clicks "Reviews" section - System displays customer reviews and ratings (when available) - Customer reads reviews - Continue from step 7

A4: View Map/Location - At step 7, customer clicks "View Location" - System displays map with departure point or activity location - Customer views map - Continue from step 7

A5: Not Ready to Book - At step 7, customer decides not to book now - Customer clicks back or closes page - Use case ends

Exception Flows:

E1: Product Not Available - At step 2, product ID is invalid or product no longer available - System displays "Product not found" message - System suggests similar products - Customer can select alternative product - Return to UC-01

E2: Product Data Incomplete - At step 3, essential product information is missing - System displays available information with notice - Customer can contact support for details - Use case continues with partial information

Business Rules: - All active products must have minimum required information (name, description, price) - Images are optimized for web display - Terms and cancellation policies must be prominently displayed

Technical Notes: - API Endpoint: POST /tlinq-api/product/getProduct - Frontend Module: products.js - getProduct(productId) - Product information cached in session storage

UC-03: Configure Tour Selection

Primary Actor: Customer

Stakeholders and Interests: - Customer: Wants to customize tour to their preferences and group size - Business: Wants to offer flexible configuration options while ensuring valid selections

Preconditions: - Customer has selected a product to book - Product has configurable attributes (options, transfers, timeslots)

Postconditions: - Valid tour configuration is selected - All required attributes are specified - Configuration is ready for availability check

Main Success Scenario:

  1. System displays tour configuration widget with:
  2. Date picker for travel date
  3. Passenger count inputs (Adults, Children, Infants)
  4. Product option dropdown (if multiple options available)
  5. Transfer type dropdown (if transfers available)
  6. Timeslot selector (if multiple timeslots available)
  7. Customer selects travel date using date picker
  8. System validates date (must be future date, within booking window)
  9. Customer enters party size:
  10. Number of adults (minimum 1)
  11. Number of children (optional, with age range displayed)
  12. Number of infants (optional, with age range displayed)
  13. System retrieves available product attributes for selected date
  14. System displays product option dropdown with available options
  15. Customer selects preferred product option (e.g., "Standard Tour", "VIP Tour")
  16. System filters available transfers based on selected option
  17. System displays transfer type dropdown with compatible transfers
  18. Customer selects transfer type (e.g., "Shared Transfer", "Private Transfer", "No Transfer")
  19. System retrieves available timeslots for configuration
  20. System displays timeslot selector (if product has timeslots)
  21. Customer selects preferred timeslot
  22. System validates complete configuration
  23. System proceeds to availability check (see UC-04)

Alternative Flows:

A1: Product Has No Options - At step 6, product has single option only - System auto-selects default option - Continue from step 8

A2: Product Has No Transfers - At step 9, product does not require transfer selection - System skips transfer selection - Continue from step 11

A3: Product Has No Timeslots - At step 12, product operates at fixed time or any time - System skips timeslot selection - Continue from step 14

A4: Change Date After Configuration - At step 13, customer changes travel date - System clears attribute selections - System retrieves attributes for new date - Return to step 5

A5: Change Party Size After Configuration - At step 13, customer changes passenger counts - System recalculates pricing - System validates new party size against product limits - Continue from step 14

A6: Date Not Available - At step 3, selected date is blocked or outside booking window - System displays validation message: "Selected date not available" - System highlights valid date range - Customer selects different date - Return to step 3

Exception Flows:

E1: Invalid Date Selected - At step 3, customer selects past date or date beyond booking window - System displays error: "Please select a valid date" - Customer corrects date selection - Return to step 3

E2: Invalid Party Size - At step 4, party size violates product constraints (min/max passengers) - System displays error: "Party size must be between X and Y" - Customer adjusts passenger counts - Return to step 4

E3: No Available Attributes - At step 5, no options/transfers available for selected date - System displays message: "This product is not available on selected date" - Customer can select different date or different product - Return to step 2 or UC-01

E4: Dependent Attributes Unavailable - At step 8, no transfers compatible with selected option - System displays message explaining unavailability - Customer can change option or select product without transfer - Return to step 7

Business Rules: - Minimum 1 adult required per booking - Child/infant age ranges defined per product - Attribute dependencies enforced (certain transfers only work with certain options) - Date must be within supplier's advance booking and maximum booking windows - Maximum party size enforced per product

Technical Notes: - API Endpoints: - POST /tlinq-api/product/getProductAttributes - POST /tlinq-api/product/getProductVariants - POST /tlinq-api/product/getVariant - POST /tlinq-api/product/getTimeslots - Frontend Module: productbook.js - loadVariant(), refreshVariant(), refreshSlotsAndPrices() - Attribute dependencies stored in database and enforced in UI

UC-04: Check Availability & Pricing

Primary Actor: Customer

Stakeholders and Interests: - Customer: Wants to know if tour is available and the exact price before booking - Business: Wants to provide real-time availability and accurate pricing - Supplier: Wants to control inventory and pricing dynamically

Preconditions: - Customer has completed tour configuration (UC-03) - Valid product variant is selected

Postconditions: - Availability status is known - Accurate pricing is displayed - Customer can proceed to booking or modify configuration

Main Success Scenario:

  1. System automatically triggers availability check after configuration complete
  2. System prepares availability request with:
  3. Product ID
  4. Selected date
  5. Selected option
  6. Selected transfer
  7. Selected timeslot (if applicable)
  8. Party size (adults, children, infants)
  9. System sends request to supplier API
  10. System displays "Checking availability..." indicator
  11. Supplier system processes request
  12. Supplier system returns availability response:
  13. Status: "Available"
  14. Adult price
  15. Child price
  16. Infant price
  17. Total cost
  18. Supplier cost (purchase price)
  19. System calculates total booking amount
  20. System displays availability result:
  21. Green checkmark with "Available"
  22. Price breakdown by passenger type
  23. Total price clearly shown
  24. "Add to Cart" or "Book Now" button enabled
  25. Customer reviews pricing
  26. Customer proceeds to create booking (see UC-05)

Alternative Flows:

A1: On Request Status - At step 6, supplier returns status "On Request" - System displays amber indicator with "On Request" - System shows message: "This booking requires manual confirmation from supplier" - System displays estimated confirmation time - "Request Booking" button enabled instead of "Book Now" - Customer can proceed with request or modify configuration - Continue from step 9

A2: Not Available Status - At step 6, supplier returns status "Not Available" or "Sold Out" - System displays red indicator with "Not Available" - System shows message: "This tour is not available on selected date/time" - System suggests alternative dates or timeslots - "Book Now" button disabled - Customer must modify configuration to proceed - Return to UC-03

A3: Pricing Variation by Selection - At step 9, customer changes configuration (e.g., different transfer) - System automatically rechecks availability and pricing - System displays updated pricing - Continue from step 9

A4: Additional Requirements Detected - At step 6, supplier indicates additional information required - System displays requirements: - Pickup location needed - Specific passenger details required - Dietary requirements - Special requests - System adds required fields to booking form - Continue from step 9

A5: Check Availability for Multiple Items - At step 2, customer has multiple items in cart - System checks availability for all items - System displays aggregate availability status - If any item unavailable, system indicates which item(s) - Continue from step 9

Exception Flows:

E1: Supplier Timeout - At step 5, supplier API does not respond within timeout (5 seconds) - System displays: "Unable to check availability. Please try again." - System logs timeout for monitoring - Customer can retry or modify configuration - Return to step 1

E2: Supplier Error - At step 5, supplier returns error response - System interprets error and displays user-friendly message - System logs error details - Customer can retry or contact support - Return to step 1

E3: Price Changed Since Last Check - At step 6, price differs from cached price - System displays new price with indication it changed - System shows percentage difference if significant - Customer acknowledges price change - Continue from step 9

E4: Connection Failure - At step 3, network connection to supplier unavailable - System displays: "Service temporarily unavailable" - System queues request for retry - Customer can wait and retry or modify configuration - Return to step 1

Business Rules: - Availability must be checked before allowing booking - Prices are displayed in configured currency (AED in this system) - Supplier cost must not be displayed to customers (only to agents/admin) - Availability check results valid for configured time period (typically 10-15 minutes) - System must handle various availability statuses: Available, On Request, Sold Out, Not Available

Technical Notes: - API Endpoint: POST /tlinq-api/product/getAvailability - Frontend Module: products.js - checkProductAvailability(bookingRequest) - Timeout: 5 seconds for availability requests - Retry logic: 2 retries with exponential backoff - Pricing includes breakdown: supplier cost, markup, total selling price

UC-05: Create Booking

Primary Actor: Customer/Agent

Stakeholders and Interests: - Customer: Wants quick, easy booking process with confirmation - Agent: Wants to efficiently create bookings for customers - Business: Wants to maximize successful bookings while collecting required information - Supplier: Wants accurate booking information for fulfillment

Preconditions: - Product availability confirmed (UC-04) - Valid tour configuration selected - Customer ready to provide passenger details

Postconditions: - Booking request created in system - Request submitted to supplier - Customer receives booking confirmation or request acknowledgment - Tickets generated (if confirmed)

Main Success Scenario:

  1. Customer clicks "Book Now" or "Add to Cart" button
  2. System adds configured product to booking cart
  3. System navigates to checkout/booking form
  4. System displays booking summary:
  5. Product name and selected options
  6. Travel date and time
  7. Party size
  8. Total price
  9. System displays passenger information form
  10. Customer enters lead passenger details:
  11. Full name (first name, last name)
  12. Email address
  13. Mobile phone number
  14. Nationality
  15. System displays additional passenger details (if required)
  16. Customer enters details for all passengers
  17. System displays additional requirements fields (if detected in UC-04):
  18. Pickup location (if transfer selected)
  19. Special requests
  20. Dietary requirements
  21. Customer provides additional required information
  22. System displays terms and conditions
  23. Customer reviews and accepts terms
  24. System validates all required information complete
  25. Customer clicks "Confirm Booking"
  26. System creates booking request with:
    • Unique booking request ID
    • Customer-facing booking reference number
    • All product and passenger details
    • Status: "Pending"
  27. System displays "Processing booking..." indicator
  28. System prepares supplier booking request:
    • Consolidates identical items (same product/date/option)
    • Aggregates passenger counts
    • Transforms to supplier-specific format
  29. System submits booking to supplier API
  30. Supplier processes booking request
  31. Supplier returns confirmation:
    • Supplier booking reference
    • Voucher number
    • Confirmation status: "Confirmed"
    • Final pricing
  32. System updates booking request:
    • Status: "Confirmed"
    • Supplier reference stored
    • Confirmation timestamp
  33. System generates tickets/vouchers (see UC-06)
  34. System displays booking confirmation page:
    • Booking reference number
    • Confirmation message
    • Booking details summary
    • Next steps information
  35. Customer receives booking details

Alternative Flows:

A1: Add Multiple Products to Cart - At step 2, customer clicks "Add to Cart" instead of "Book Now" - System adds product to cart - Customer continues browsing (return to UC-01) - Customer adds more products to cart - Customer clicks "Checkout" when ready - Continue from step 3

A2: Apply to Multiple Passengers - At step 8, all passengers have same details (e.g., family booking) - Customer checks "Use lead passenger details for all" - System auto-fills passenger information - Customer reviews and confirms - Continue from step 9

A3: Guest Checkout - At step 5, customer is not logged in - System offers guest checkout option - Customer proceeds without account creation - Continue from step 6

A4: Registered User Checkout - At step 5, customer is logged in - System pre-fills customer information from profile - Customer reviews and edits if needed - Continue from step 9

A5: Agent Creating Booking - At step 1, agent creates booking on behalf of customer - Agent enters customer contact information - Agent enters passenger details - System records agent ID with booking - Continue from step 13

A6: On Request Booking - At step 20, supplier returns status "On Request" - System updates booking status: "On Request" - System displays message: "Booking request submitted, awaiting supplier confirmation" - System schedules status check polling - Customer receives acknowledgment email - Use case ends (confirmation follows later)

A7: Save for Later - At step 3, customer not ready to complete booking - Customer clicks "Save for Later" or "Save to Wishlist" - System saves partial booking - Customer can return later to complete - Use case ends

A8: Payment Integration - After step 14, system requires payment - System redirects to payment gateway - Customer completes payment - System receives payment confirmation - Continue from step 15

Exception Flows:

E1: Validation Errors - At step 13, required information missing or invalid - System displays validation errors: - Highlight fields with issues - Show error messages inline - Customer corrects information - Return to step 13

E2: Availability Changed - At step 18, product no longer available - Supplier returns "Sold Out" or "Not Available" - System displays error: "Sorry, this product is no longer available" - System offers alternatives: - Different date - Different timeslot - Similar products - Customer can modify configuration or cancel - Return to UC-03 or end use case

E3: Price Changed - At step 20, supplier returns different price than quoted - System detects price discrepancy - System displays price change notification - Customer must accept new price to continue - If customer declines, booking cancelled - If accepts, continue from step 21

E4: Supplier Booking Failed - At step 19, supplier returns error or rejection - System updates booking status: "Failed" - System displays error message: "Unable to complete booking" - System provides error details and reference number - Customer can retry or contact support - System logs error for investigation - Use case ends

E5: Timeout During Booking - At step 19, supplier does not respond within timeout (10 seconds) - System continues to retry in background - System displays: "Booking is processing, you will receive confirmation shortly" - System sends email when confirmation received - Booking status: "Submitted" - Use case ends (background process continues)

E6: Duplicate Booking Detected - At step 15, system detects potential duplicate (same product, date, customer) - System displays warning: "You may have already booked this tour" - System shows existing booking details - Customer confirms this is intentional or cancels - If confirmed, continue from step 16

E7: Network Failure - At step 18, network connection lost - System queues booking request - System displays: "Connection issue. Your booking will be processed shortly." - System processes when connection restored - Customer receives confirmation via email - Use case ends

Business Rules: - Minimum 1 adult passenger required - Lead passenger must be adult (18+ years) - Valid email required for ticket delivery - Mobile phone required for some products - Terms and conditions must be accepted - Booking references must be unique and easily readable - Multiple items can be combined in single booking if from same supplier - Booking consolidation rules: - Same product + same date + same option + same transfer + same timeslot = consolidated - Passenger counts aggregated - Original cart item references maintained

Technical Notes: - API Endpoints: - Internal booking creation in BookingRequestFacade - Supplier submission via RaynaTicketingService - Frontend Module: ticketbook.js - Booking request consolidation logic in RaynaTicketingService.initBookingData() - Timeout: 10 seconds for booking submission - Retry: 3 attempts with exponential backoff - Booking reference format: configurable (e.g., "BK" + 8-digit number)

UC-06: Receive Ticket Confirmation

Primary Actor: Customer

Stakeholders and Interests: - Customer: Wants clear confirmation and tickets immediately - Business: Wants to provide professional confirmation to increase trust - Supplier: Wants customers to have vouchers for redemption

Preconditions: - Booking successfully created (UC-05) - Booking status is "Confirmed" - Supplier has provided booking reference

Postconditions: - Customer has received confirmation email - Tickets/vouchers are generated and delivered - Customer can access tickets for tour redemption

Main Success Scenario:

  1. System triggers ticket generation after booking confirmation
  2. System retrieves booking details:
  3. Booking reference
  4. Supplier confirmation/voucher number
  5. Product details
  6. Travel date and time
  7. Passenger information
  8. Pickup location (if applicable)
  9. System generates barcode/QR code:
  10. Unique code per booking item
  11. Encodes booking reference and product ID
  12. Generates QR code image
  13. Generates PDF417 barcode image
  14. System prepares ticket document:
  15. Booking reference number prominently displayed
  16. Supplier voucher number
  17. Product name and description
  18. Service date and time
  19. Passenger names
  20. Pickup information (if applicable)
  21. QR code / barcode embedded
  22. Terms and conditions
  23. Important instructions
  24. Redemption information
  25. Emergency contact details
  26. System generates ticket in multiple formats:
  27. PDF voucher for printing
  28. HTML ticket for email
  29. Mobile-optimized version
  30. System prepares confirmation email:
  31. Subject: "Booking Confirmed - [Product Name] - [Reference]"
  32. Personalized greeting
  33. Confirmation message
  34. Booking summary table
  35. Attached PDF ticket
  36. Embedded HTML ticket
  37. Link to view booking online
  38. Link to download ticket
  39. Customer support contact
  40. System sends email to customer's registered address
  41. System records email sent timestamp
  42. Customer receives email
  43. Customer opens email and views confirmation
  44. Customer downloads/saves PDF ticket
  45. Customer views important information and instructions
  46. Use case ends

Alternative Flows:

A1: Multiple Items in Booking - At step 3, booking contains multiple tour items - System generates separate ticket for each item - Each ticket has unique barcode - All tickets included in confirmation email - Confirmation email lists all items - Continue from step 7

A2: Mobile Ticket Preference - At step 11, customer prefers mobile ticket - Customer adds ticket to mobile wallet (if supported) - Customer saves ticket to mobile device - Customer can display QR code from mobile at tour - Continue from step 13

A3: Print Ticket - At step 11, customer wants to print ticket - Customer opens PDF attachment - Customer prints ticket - Printed voucher has clear barcode for scanning - Continue from step 13

A4: Email Not Received - After step 9, customer does not receive email (see UC-08 alternative flow) - Customer can request resend - System resends confirmation email - Continue from step 9

A5: On Request Confirmation (Delayed) - After UC-05, booking was "On Request" - System polls supplier for status - Supplier confirms booking later - System generates tickets at confirmation time - Continue from step 1

A6: SMS Notification - At step 7, customer opted for SMS notifications - System sends SMS with: - Booking reference - Confirmation message - Link to view booking - Customer receives SMS - Continue from step 7

Exception Flows:

E1: Ticket Generation Failed - At step 4, PDF generation service fails - System logs error - System sends confirmation email without PDF attachment - Email includes link to view/download ticket online - System alerts admin for investigation - Customer can access ticket via booking management (UC-08)

E2: Barcode Generation Failed - At step 3, barcode generation fails - System creates ticket without barcode - System includes textual reference numbers prominently - System alerts admin for investigation - Continue from step 4

E3: Email Delivery Failed - At step 7, email service returns delivery failure - System logs failure - System retries email delivery (3 attempts) - If all attempts fail, system alerts admin - System marks booking for manual follow-up - Customer can access confirmation via booking management (UC-08)

E4: Invalid Email Address - At step 7, email address is invalid or bounces - System receives bounce notification - System marks email delivery failed - System alerts agent if booking by agent - Agent contacts customer via alternate method - Use case ends

Business Rules: - Confirmation email must be sent immediately upon booking confirmation - Tickets must include all essential information for redemption - Barcodes must be unique and scannable - PDF format required for print-at-home tickets - Mobile tickets must be easy to display and scan - Confirmation must include clear next steps - Emergency contact information must be provided - Tickets valid only for specified date/time unless transferable

Technical Notes: - Ticket generation in BookingRequestFacade.generateAndSendTickets() - Barcode generation: QR Code and PDF417 formats supported - PDF generation: iText library or similar - Email service: Platform email notification service - Ticket template: Configurable HTML/PDF template - Barcode encoding: [booking reference]|[product ID]|[date]

UC-07: View Booking Details

Primary Actor: Customer/Agent

Stakeholders and Interests: - Customer: Wants to review booking, access tickets, check status - Agent: Wants to view customer bookings for support - Business: Wants to provide self-service access to reduce support calls

Preconditions: - Booking exists in system - Actor has authorization to view booking

Postconditions: - Booking details displayed - Actor can take further actions (download tickets, amend, cancel)

Main Success Scenario:

  1. Customer navigates to "My Bookings" section
  2. System displays booking search form
  3. Customer enters booking reference number and email address
  4. System validates credentials
  5. System retrieves booking details
  6. System displays booking information:
  7. Booking reference number
  8. Current status (Confirmed, Pending, Cancelled)
  9. Product name and description
  10. Travel date and time
  11. Passenger details
  12. Pickup location (if applicable)
  13. Total amount paid
  14. Booking date
  15. System displays available actions:
  16. Download tickets button
  17. Resend confirmation button
  18. View terms and conditions
  19. Amend booking button (if amendable)
  20. Cancel booking button (if cancellable)
  21. Contact support
  22. Customer reviews booking details
  23. Customer performs desired action or closes view
  24. Use case ends

Alternative Flows:

A1: Access via Email Link - At step 1, customer clicks link in confirmation email - Link includes secure access token - System validates token - System displays booking directly - Continue from step 6

A2: Registered User Login - At step 1, customer logs into account - System displays all bookings for logged-in user - Customer selects specific booking to view - Continue from step 6

A3: Agent Access - At step 1, agent logs into admin interface - Agent searches booking by: - Booking reference - Customer name - Email address - Travel date - Supplier reference - System displays search results - Agent selects booking to view - System displays detailed booking with additional information: - Supplier booking reference - Supplier cost (purchase price) - Selling price and margin - Payment status - Communication history - Audit trail - Continue from step 8

A4: View Multiple Bookings - At step 3, customer enters only email address - System displays all bookings for that email - System sorts by travel date (upcoming first) - Customer selects specific booking to view - Continue from step 6

A5: QR Code Access - At step 1, customer scans QR code from ticket - QR code contains booking reference - System validates and retrieves booking - Continue from step 6

A6: View Booking History - At step 8, customer clicks "View History" - System displays booking modification history: - Original booking details - Amendments made - Cancellation requests - Status changes - Timestamps - Customer reviews history - Continue from step 9

Exception Flows:

E1: Booking Not Found - At step 5, booking reference does not exist - System displays: "Booking not found" - System suggests verifying reference number - Customer can re-enter or contact support - Return to step 3

E2: Invalid Credentials - At step 4, email does not match booking - System displays: "Invalid booking reference or email" - System limits attempts to prevent brute force - After 3 failed attempts, system requires CAPTCHA - Return to step 3

E3: Expired Access Link - At step 2 (A1), access token is expired - System displays: "This link has expired" - System offers option to request new link - Customer enters email to receive new link - Return to step 1

E4: Booking Data Incomplete - At step 6, booking data is missing or corrupted - System displays available information - System shows message: "Some booking details unavailable" - System provides support contact for assistance - Use case continues with partial data

Business Rules: - Customers can only view their own bookings - Email verification required for guest access - Agents can view all bookings with proper authorization - Access links expire after configured time period (typically 24-48 hours) - Booking details remain accessible after travel date for configured retention period - Sensitive information (payment details) not displayed to customers

Technical Notes: - API Endpoints: Booking retrieval methods in BookingRequestFacade - Access token: JWT with expiration - Security: Email verification required for guest access - Agent interface: Full CRUD operations with authorization checks

UC-08: Download Tickets

Primary Actor: Customer/Agent

Stakeholders and Interests: - Customer: Wants easy access to tickets for tour redemption - Business: Wants to provide convenient ticket access

Preconditions: - Booking is confirmed (status: "Confirmed") - Tickets have been generated - Actor is viewing booking details (UC-07)

Postconditions: - Ticket document downloaded to device - Customer has ticket ready for tour redemption

Main Success Scenario:

  1. Customer views booking details (UC-07)
  2. System displays "Download Tickets" button
  3. Customer clicks "Download Tickets"
  4. System retrieves ticket documents from storage
  5. System prepares PDF voucher for download
  6. System initiates file download
  7. Browser downloads PDF file (filename: "Ticket-[Reference].pdf")
  8. Customer opens downloaded PDF
  9. Customer verifies ticket information correct
  10. Customer saves file for tour date
  11. Use case ends

Alternative Flows:

A1: Email Tickets - At step 3, customer clicks "Email Tickets" instead - System displays email address confirmation - Customer confirms or updates email address - System resends confirmation email with tickets attached - Customer receives email - Customer opens email and downloads from attachment - Continue from step 9

A2: Download Individual Tickets - At step 2, booking has multiple tour items - System displays separate download button for each item - Customer selects specific ticket to download - Continue from step 5

A3: Download All Tickets - At step 2, booking has multiple tour items - Customer clicks "Download All" - System creates ZIP file with all tickets - System initiates ZIP download - Continue from step 8

A4: View Ticket Online - At step 3, customer clicks "View Ticket" instead - System displays ticket in browser (HTML format) - Customer views ticket online - Customer can print directly from browser - Continue from step 11

A5: Mobile Wallet - At step 3, customer clicks "Add to Wallet" - System generates mobile wallet pass (Apple Wallet / Google Pay) - System downloads wallet pass file - Customer adds pass to mobile wallet app - Ticket accessible from wallet app - Continue from step 11

A6: Print Ticket - After step 8, customer clicks print - System opens print dialog - Customer prints ticket on paper - Printed ticket has clear barcode - Continue from step 11

A7: Multiple Format Download - At step 3, customer selects ticket format - System offers: PDF, HTML, Mobile Wallet - Customer selects preferred format - System downloads selected format - Continue from step 9

Exception Flows:

E1: Ticket Not Available - At step 4, ticket document not found - System displays: "Ticket not ready. Please wait a moment." - System triggers ticket regeneration - System displays progress indicator - When ready, system enables download - Return to step 3

E2: Booking Not Confirmed - At step 2, booking status is "Pending" or "On Request" - System displays: "Tickets not available. Booking awaiting confirmation." - Download button disabled - System displays estimated confirmation time - Use case ends

E3: Booking Cancelled - At step 2, booking status is "Cancelled" - System displays: "This booking has been cancelled" - Download button disabled or shows "Cancelled" ticket - Use case ends

E4: Download Failed - At step 6, download fails due to network issue - Browser displays download error - Customer can retry download - System logs failure - Return to step 3

E5: Corrupted Ticket File - At step 8, PDF cannot be opened - Customer sees error opening file - Customer clicks "Resend Tickets" in booking view - System regenerates ticket - Continue from step 4

Business Rules: - Tickets only available for confirmed bookings - Each ticket download logged for audit - Tickets can be downloaded multiple times - Original ticket format (PDF) always available - Mobile wallet passes optional feature - Ticket files named clearly with booking reference

Technical Notes: - Ticket storage: File system or cloud storage (S3, Azure Blob) - PDF served via streaming to prevent large memory usage - Download endpoint secured with authentication token - Ticket file retention: Retained for configured period after travel date - Multiple format support: PDF (primary), HTML, Apple Wallet (.pkpass), Google Pay

UC-09: Amend Booking

Primary Actor: Customer/Agent

Stakeholders and Interests: - Customer: Wants flexibility to change booking details - Business: Wants to accommodate changes while following supplier policies - Supplier: Wants to enforce amendment rules and fees

Preconditions: - Booking exists and is confirmed - Booking is amendable per supplier policy - Amendment requested before cut-off time

Postconditions: - Booking updated with new details (if approved) - Amendment fees applied (if applicable) - Updated tickets generated and sent - Or amendment request rejected with reason

Main Success Scenario:

  1. Customer views booking details (UC-07)
  2. System displays "Amend Booking" button
  3. Customer clicks "Amend Booking"
  4. System retrieves amendment policy for the product
  5. System displays amendment options:
  6. Change date
  7. Change time slot
  8. Change passenger count
  9. Change option/variant
  10. Change transfer type
  11. System displays amendment policy:
  12. Amendment allowed until X hours before tour
  13. Amendment fee: AED XXX
  14. Price difference may apply
  15. Customer selects amendment type (e.g., "Change Date")
  16. System displays amendment form for selected type
  17. Customer enters new date using date picker
  18. System checks availability for new date
  19. System retrieves pricing for new date
  20. System calculates amendment impact:
    • Original price: AED XXX
    • New price: AED YYY
    • Price difference: AED (YYY-XXX)
    • Amendment fee: AED ZZZ
    • Total additional charge: AED (difference + fee)
    • Or refund if new price lower
  21. System displays amendment summary:
    • Original booking details
    • New booking details
    • Price impact
    • Total amount due or refund
  22. System requests customer confirmation
  23. Customer reviews and confirms amendment
  24. System creates amendment request:
    • Amendment ID
    • Original booking reference
    • Requested changes
    • Status: "Processing"
  25. System submits amendment to supplier API
  26. Supplier processes amendment
  27. Supplier confirms amendment accepted
  28. System updates booking:
    • Apply new date/time/option
    • Update pricing
    • Add amendment fee to booking
    • Update status
    • Record amendment history
  29. System cancels old tickets
  30. System generates new tickets with updated details
  31. System sends confirmation email:
    • Amendment confirmed
    • Updated booking details
    • New tickets attached
    • Additional payment details (if applicable)
  32. Customer receives amendment confirmation
  33. Use case ends

Alternative Flows:

A1: Free Amendment - At step 12, amendment policy allows free change - No amendment fee applied - Only price difference charged (if new price higher) - Continue from step 13

A2: Multiple Changes - At step 7, customer wants to change multiple aspects - Customer selects all changes (date + passenger count + option) - System checks availability for complete new configuration - System calculates total impact of all changes - Continue from step 12

A3: Amendment Requires Approval - At step 19, supplier requires manual approval - System updates amendment status: "Awaiting Approval" - System displays message: "Amendment request submitted, awaiting supplier approval" - System polls supplier for decision - Customer receives email when decision made - Use case ends

A4: Downgrade Refund - At step 12, new configuration is cheaper - System calculates refund amount (minus amendment fee) - System displays refund details - Customer confirms wanting refund - System processes refund after amendment confirmed - Continue from step 15

A5: Agent-Initiated Amendment - At step 1, agent initiates amendment - Agent enters customer request reason - Agent processes amendment on behalf of customer - Agent can override fees with manager approval - Continue from step 8

A6: Price Only Changed - At step 11, date available but price significantly different - System alerts customer: "Price has changed for new date" - Customer can accept new price or try different date - If accepts, continue from step 12 - If declines, return to step 9

Exception Flows:

E1: Amendment Not Allowed - At step 4, product amendment policy is "non-amendable" - System displays: "This booking cannot be amended" - System displays cancellation policy as alternative - Amendment button disabled - Use case ends

E2: Amendment Cut-off Passed - At step 4, current time past amendment deadline - System displays: "Amendment deadline has passed (must amend before X hours)" - System displays cancellation option - Use case ends

E3: New Date Not Available - At step 10, requested date has no availability - System displays: "Selected date not available" - System suggests alternative dates with availability - Customer can select alternative or cancel amendment - Return to step 9 or use case ends

E4: Supplier Rejects Amendment - At step 19, supplier rejects amendment request - System receives rejection with reason - System updates amendment status: "Rejected" - System displays rejection reason to customer - System offers alternatives (different date, cancellation) - Use case ends

E5: Price Increased Significantly - At step 12, price difference exceeds threshold (e.g., 50% increase) - System highlights price increase - System requires explicit customer acceptance - Customer can accept or cancel amendment - If cancels, use case ends

E6: Amendment Processing Failed - At step 17, supplier API returns error - System logs error - System displays: "Unable to process amendment" - System keeps original booking unchanged - Customer can retry or contact support - Use case ends

E7: Payment Failed for Additional Charge - After step 20, additional payment required but payment fails - System rolls back amendment - Original booking remains unchanged - System notifies customer of payment failure - Use case ends

Business Rules: - Amendment policy defined per product/supplier - Common policies: - Free amendment until 48 hours before - Amendment fee applies after 48 hours - No amendments within 24 hours of tour - Price difference always charged or refunded - Amendment fees non-refundable - Multiple amendments allowed but each incurs fee - Amendment must maintain minimum passenger requirements - New configuration must be available - Original booking reference retained - Amendment history tracked

Technical Notes: - Amendment policies stored in database (cancelpolicy table) - Amendment types: DATE, TIMESLOT, PASSENGER_COUNT, OPTION, TRANSFER - Amendment fees configurable per supplier - Amendment submission via RaynaTicketingService.amendTicketingRequest() - Ticket regeneration triggered automatically after successful amendment - Amendment history stored for audit trail

UC-10: Cancel Booking

Primary Actor: Customer/Agent

Stakeholders and Interests: - Customer: Wants to cancel booking and receive appropriate refund - Business: Wants to handle cancellations efficiently while following policies - Supplier: Wants to enforce cancellation policies and recover costs

Preconditions: - Booking exists and is confirmed - Cancellation requested before tour departure - Actor has authorization to cancel

Postconditions: - Booking status updated to "Cancelled" - Cancellation processed with supplier - Refund calculated per policy - Cancellation confirmation sent to customer

Main Success Scenario:

  1. Customer views booking details (UC-07)
  2. System displays "Cancel Booking" button
  3. Customer clicks "Cancel Booking"
  4. System retrieves cancellation policy for the product
  5. System displays cancellation policy:
  6. Cancellation deadline and cut-off times
  7. Refund percentages based on timing
  8. Cancellation fees
  9. System calculates potential refund:
  10. Original booking amount: AED XXX
  11. Cancellation fee: AED YYY
  12. Refund amount: AED (XXX - YYY)
  13. System displays cancellation impact:
  14. Booking reference
  15. Product details
  16. Original amount paid
  17. Cancellation fee
  18. Refund amount
  19. Refund processing time
  20. System displays cancellation reasons (optional dropdown):
  21. Change of plans
  22. Found better option
  23. Travel cancelled
  24. Emergency
  25. Other
  26. Customer selects cancellation reason (optional)
  27. System displays cancellation confirmation dialog:
    • "Are you sure you want to cancel this booking?"
    • Refund amount highlighted
    • Cannot be undone warning
  28. Customer confirms cancellation
  29. System creates cancellation request:
    • Cancellation ID
    • Booking reference
    • Cancellation reason
    • Requested timestamp
    • Status: "Processing"
  30. System submits cancellation to supplier API
  31. Supplier processes cancellation
  32. Supplier confirms cancellation accepted
  33. System updates booking:
    • Status: "Cancelled"
    • Cancellation timestamp
    • Cancellation reason
    • Refund amount
  34. System invalidates tickets/vouchers
  35. System initiates refund process:
    • Creates refund request
    • Submits to payment system
    • Records refund reference
  36. System sends cancellation confirmation email:
    • Cancellation confirmed message
    • Booking details
    • Refund amount and timeline
    • Refund method
    • Support contact
  37. Customer receives cancellation confirmation
  38. Use case ends

Alternative Flows:

A1: Partial Cancellation - At step 3, booking has multiple items - Customer selects specific items to cancel - System calculates refund for selected items only - Other items remain active - Continue from step 6

A2: Full Refund Cancellation - At step 6, cancellation within free cancellation period - No cancellation fee applied - Full refund amount = original payment - Continue from step 7

A3: No Refund Cancellation - At step 6, cancellation past deadline or non-refundable booking - Refund amount: AED 0 - System displays "No refund available" message - Customer can still cancel to close booking - Continue from step 8

A4: Agent-Initiated Cancellation - At step 1, agent cancels on behalf of customer - Agent logs cancellation reason - Agent can override fees with manager approval - System records agent ID with cancellation - Continue from step 12

A5: Supplier-Initiated Cancellation - Before step 1, supplier cancels tour (e.g., weather, insufficient bookings) - System receives cancellation notification from supplier - System updates booking status: "Cancelled by Supplier" - System processes full refund automatically - System sends notification to customer - Use case ends

A6: Refund as Credit - At step 18, customer chooses credit instead of refund - System issues travel credit/voucher - Credit valid for future bookings - Credit amount equals refund amount - Continue from step 19

A7: Cancellation Requires Approval - At step 15, supplier requires manual approval - System updates status: "Cancellation Pending" - System displays: "Cancellation request submitted, awaiting supplier approval" - System polls supplier for decision - Customer notified when decision made - Use case ends

Exception Flows:

E1: Cancellation Not Allowed - At step 4, product is non-cancellable - System displays: "This booking cannot be cancelled" - System shows policy details - Customer can contact support for exceptions - Use case ends

E2: Cancellation Deadline Passed - At step 4, current time past cancellation deadline - System displays: "Cancellation deadline has passed" - System shows no refund available - Customer can still cancel to close booking (no refund) - Customer decides whether to proceed - If yes, continue from step 10 with zero refund

E3: Supplier Rejects Cancellation - At step 15, supplier rejects cancellation - System receives rejection with reason - System displays: "Cancellation request rejected by supplier" - System shows rejection reason - Customer can contact support to resolve - Use case ends

E4: Already Cancelled - At step 2, booking status is already "Cancelled" - System displays: "This booking has already been cancelled" - Cancel button disabled - Use case ends

E5: Booking Already Used - At step 4, tour date has passed - System displays: "Cannot cancel past bookings" - Customer can contact support for exceptions - Use case ends

E6: Supplier Communication Failed - At step 13, cannot reach supplier API - System logs error - System displays: "Unable to process cancellation at this time" - System offers: - Retry later - Submit cancellation request (processed when supplier available) - Contact support - Customer chooses option - If request submitted, system processes in background

E7: Refund Processing Failed - At step 18, payment system returns error - System logs failure - Cancellation still completed - System alerts admin for manual refund processing - System notifies customer of delay in refund - Use case ends (refund processed manually)

Business Rules: - Cancellation policies defined per product/supplier - Common policy structure: - Free cancellation until X hours/days before tour - 50% refund if cancelled Y hours/days before - No refund if cancelled within Z hours of tour - Non-refundable bookings identified clearly at booking time - Cancellation fees may be percentage or fixed amount - Supplier cancellations result in full refund always - Partial cancellations allowed for multi-item bookings - Refunds processed to original payment method - Refund processing time: 5-10 business days (standard) - Cancelled bookings retained in system for records

Technical Notes: - Cancellation policies stored in cancelpolicy table - Cancellation submission via RaynaTicketingService.cancelTicketRequest() - Refund calculation considers: - Time until tour date - Policy percentage/fixed fee - Supplier fees - Processing fees - Cancelled tickets marked invalid in system - Refund integration with payment gateway - Cancellation reasons tracked for analytics

UC-11: Process Booking Manually

Primary Actor: Agent/Administrator

Stakeholders and Interests: - Agent: Wants to handle special cases and customer requests efficiently - Customer: Wants personalized service for complex bookings - Business: Wants flexibility to handle exceptions and maximize bookings

Preconditions: - Agent logged into admin interface - Booking exists in system or agent creating new booking - Agent has appropriate authorization

Postconditions: - Booking processed successfully - Customer notified of outcome - All changes documented in audit trail

Main Success Scenario:

  1. Agent logs into admin interface
  2. System displays agent dashboard
  3. Agent navigates to booking management section
  4. Agent searches for existing booking or creates new booking
  5. System displays booking details or new booking form
  6. Agent identifies issue requiring manual intervention:
  7. Availability check failed but supplier confirmed by phone
  8. Price override needed
  9. Special customer request
  10. System error during booking
  11. Agent reviews booking requirements:
  12. Product details
  13. Customer information
  14. Special requests
  15. Agent makes necessary adjustments:
  16. Override availability check
  17. Adjust pricing (with authorization code)
  18. Add special notes/instructions
  19. Modify configuration beyond normal limits
  20. Agent enters justification for manual processing
  21. System records agent action with audit trail:
    • Agent ID
    • Action taken
    • Justification
    • Timestamp
    • Authorization code (if applicable)
  22. Agent submits booking for processing
  23. System processes booking with manual overrides applied
  24. System confirms booking with supplier
  25. System generates tickets
  26. Agent reviews confirmation details
  27. Agent sends confirmation to customer (email/phone)
  28. System updates booking status: "Confirmed - Manual"
  29. Use case ends

Alternative Flows:

A1: Force Booking Confirmation - At step 8, availability shows "Not Available" but phone confirmation received - Agent selects "Force Confirmation" option - Agent enters supplier reference number from phone call - Agent enters authorization code - System bypasses availability check - Continue from step 11

A2: Apply Price Override - At step 8, customer negotiated special price - Agent clicks "Override Price" - Agent enters new price - Agent enters manager authorization code - System validates authorization - System applies override price - Continue from step 9

A3: Manual Payment Entry - At step 8, customer paid via bank transfer - Agent selects "Manual Payment" - Agent enters payment details: - Amount - Payment method - Transaction reference - Payment date - System records manual payment - Continue from step 11

A4: Expedite On Request Booking - At step 6, booking status "On Request" but customer needs urgent confirmation - Agent contacts supplier directly (phone/email) - Supplier confirms availability - Agent updates booking status manually: "Confirmed" - Agent enters supplier confirmation details - Continue from step 14

A5: Split Booking - At step 8, large group booking needs to be split across multiple dates - Agent creates multiple bookings from original request - Agent links related bookings - Agent applies group discount - Agent processes each booking - Continue from step 17

A6: Handle Failed Booking - At step 4, agent reviews failed booking - Agent identifies failure reason (supplier timeout, system error) - Agent resubmits booking manually - System retries supplier submission - Continue from step 13

Exception Flows:

E1: Unauthorized Action - At step 10, agent attempts action beyond authorization level - System requests supervisor authorization code - If valid code entered, action allowed - If invalid or not provided, action blocked - System logs unauthorized attempt

E2: Invalid Override Attempt - At step 8, agent tries to override critical business rule - System blocks override - System displays: "This action cannot be overridden" - Agent must use standard process or escalate - Use case ends

E3: Supplier Still Rejects - At step 13, supplier rejects despite manual override - System receives rejection - Agent reviews rejection reason - Agent contacts supplier to resolve - Agent either resolves and resubmits or cancels booking - Use case ends

E4: Audit Trail Failure - At step 10, audit logging fails - System blocks manual action - System displays error - Agent must wait for system recovery - Use case ends (manual actions require audit trail)

Business Rules: - All manual interventions require justification - Price overrides require manager authorization - Authorization codes time-limited and single-use - Manual bookings flagged for quality review - Override limits defined by agent role: - Agent: Minor adjustments only - Senior Agent: Price override up to 10% - Manager: Full override authority - All actions logged in audit trail - Manual processing should be exception, not norm

Technical Notes: - Admin interface: Separate authenticated portal - Authorization codes: Generated by manager, time-limited - Audit trail: All actions logged to audit table - Override flags stored with booking - Manual booking indicator in booking record

UC-12: Synchronize Catalog

Primary Actor: System Scheduler / Administrator

Stakeholders and Interests: - Business: Wants fresh, accurate product catalog - Customers: Want current availability and pricing - System: Maintains data consistency with supplier

Preconditions: - Supplier API accessible - Database connection available - Sync service configured properly

Postconditions: - Local catalog updated with latest supplier data - Sync status recorded - Errors logged (if any) - Cache refreshed

Main Success Scenario:

  1. System scheduler triggers sync job (hourly)
  2. System initializes refresh service (SDRefresher)
  3. System records sync start time
  4. System connects to supplier API
  5. System retrieves latest catalog data from supplier:
  6. Countries and cities (destination catalog)
  7. Tours catalog with full details
  8. Tour options and pricing
  9. Transfer types
  10. Cancellation policies
  11. Tour prices by date range
  12. Tour times and schedules
  13. Image references
  14. System processes each data entity:
  15. Countries (fetch all, update local)
  16. Cities (fetch all, update local)
  17. Tours (fetch all, update/insert)
  18. Tour Options (fetch per tour, update/insert)
  19. Tour Transfers (fetch mappings, update)
  20. Tour Prices (fetch date ranges, update)
  21. Tour Times (fetch schedules, update)
  22. Cancellation Policies (fetch rules, update)
  23. For each entity, system:
  24. Fetches remote data
  25. Compares with local data
  26. Updates changed records
  27. Inserts new records
  28. Marks inactive records (if removed from supplier)
  29. System updates refresh status table:
  30. Entity name
  31. Last successful refresh timestamp
  32. Record count
  33. Status: "Success"
  34. System refreshes memory cache (Hazelcast):
  35. Clear old cached data
  36. Load updated data
  37. System logs sync completion
  38. System records sync end time and duration
  39. Use case ends

Alternative Flows:

A1: Manual Sync Triggered - At step 1, administrator triggers sync manually - Administrator navigates to admin panel - Administrator clicks "Refresh Catalog" - System starts immediate sync - Continue from step 2

A2: Incremental Sync - At step 5, system requests only changed data since last sync - Supplier returns delta changes only - System processes incremental updates - Faster sync completion - Continue from step 7

A3: Full Refresh - At step 5, administrator selected "Full Refresh" - System requests complete catalog - System clears local catalog tables - System rebuilds entire catalog from scratch - Continue from step 6

A4: Partial Entity Sync - At step 1, administrator selects specific entities to sync - System syncs only selected entities (e.g., only prices) - Continue from step 6 for selected entities only

A5: No Changes Detected - At step 7, supplier data unchanged since last sync - System skips updates - System records "No changes" in log - Continue from step 8

Exception Flows:

E1: Supplier API Unavailable - At step 4, cannot connect to supplier API - System logs connection error - System retries connection (3 attempts with backoff) - If all attempts fail: - System records sync status: "Failed - Connection Error" - System alerts administrator - System schedules retry at next interval - Use case ends

E2: Supplier Returns Error - At step 5, supplier API returns error response - System logs error details - System records sync status: "Failed - Supplier Error" - System continues with other entities (if partial sync possible) - System alerts administrator - Use case ends

E3: Data Validation Failed - At step 7, supplier data fails validation - System logs validation errors - System skips invalid records - System processes valid records - System records: "Completed with errors" - System alerts administrator with error details - Continue from step 8

E4: Database Error - At step 7, database update fails - System logs database error - System rolls back transaction - System retries transaction (1 retry) - If retry fails: - System records: "Failed - Database Error" - System alerts administrator - Use case ends

E5: Partial Sync Failure - At step 6, some entities sync successfully, others fail - System completes successful entities - System logs failed entities - System records: "Partial Success" - System records which entities failed - System schedules retry for failed entities - Use case ends

E6: Timeout During Sync - At step 5, supplier response too slow (exceeds 5 minutes) - System times out request - System logs timeout error - System records sync status: "Failed - Timeout" - System schedules retry - Use case ends

E7: Cache Refresh Failed - At step 9, cannot update memory cache - System logs cache error - Database still updated successfully - System attempts cache refresh again - System records: "Success with cache warning" - Cache will refresh on next read - Continue from step 10

Business Rules: - Sync runs automatically every 1 hour - Sync during off-peak hours preferred for full refresh - Failed syncs retried at next scheduled interval - Consecutive failures (3+) trigger alert - Sync must not impact user-facing operations - Database transactions ensure consistency - Old data retained for configured period before deletion - Sync duration should not exceed 30 minutes (incremental) or 2 hours (full)

Technical Notes: - Scheduler: Java ScheduledExecutorService in RaynaB2BActPlugin - Refresh Service: SDRefresher and SDRefreshRunner classes - Database Schema: 'rayna' schema in PostgreSQL - Cache: Hazelcast distributed cache (RaynaCacheManager) - Entities Synced: 12+ entity types (Tour, Touroption, Tourtransfer, etc.) - Sync Status: Stored in refreshstatus table - API Timeout: 5 minutes per entity request - Batch Processing: Tours processed in batches of 100 - Retry Strategy: Exponential backoff (1 min, 5 min, 15 min)

UC-13: Manage Supplier Configuration

Primary Actor: Administrator

Stakeholders and Interests: - Administrator: Wants to configure supplier settings easily - Business: Wants flexibility to adjust supplier integration - Development: Wants configuration externalized from code

Preconditions: - Administrator logged into admin interface - Administrator has configuration management authorization

Postconditions: - Supplier configuration updated - Changes applied without code deployment - System behavior reflects new configuration

Main Success Scenario:

  1. Administrator logs into admin panel
  2. System displays admin dashboard
  3. Administrator navigates to "Supplier Configuration" section
  4. System displays list of configured suppliers
  5. Administrator selects supplier (e.g., "Rayna B2B")
  6. System displays supplier configuration form with current settings:
  7. Connection Settings:
    • API Endpoint URL
    • API Key / Credentials
    • Timeout settings
    • Retry configuration
  8. Business Settings:
    • Active/Inactive status
    • Default markup percentage
    • Commission rate
    • Currency
  9. Sync Settings:
    • Sync schedule (cron expression)
    • Sync timeout
    • Full refresh schedule
  10. Feature Flags:
    • Enable availability check
    • Enable real-time pricing
    • Enable timeslots
    • Enable transfers
  11. Administrator modifies settings:
  12. Updates API endpoint (e.g., production vs. staging)
  13. Adjusts timeout from 5s to 10s
  14. Changes sync schedule from hourly to every 2 hours
  15. System validates configuration values:
  16. URL format correct
  17. Timeout values within acceptable range
  18. Cron expression valid
  19. Administrator clicks "Save Configuration"
  20. System displays confirmation dialog:
    • "Changes will affect supplier integration immediately"
    • List of changed settings
  21. Administrator confirms changes
  22. System saves configuration:
    • Updates database configuration table
    • Updates XML configuration file (if applicable)
    • Records change in audit log:
    • Administrator ID
    • Changed settings
    • Old values
    • New values
    • Timestamp
  23. System refreshes configuration cache
  24. System displays success message: "Configuration updated successfully"
  25. System applies new settings immediately (no restart required for most settings)
  26. Use case ends

Alternative Flows:

A1: Test Connection - At step 7, administrator clicks "Test Connection" - System attempts connection to supplier API with new settings - System displays test result: - Success: "Connection successful" - Failure: "Connection failed" with error details - Administrator can adjust settings and test again - Continue from step 7

A2: Reset to Defaults - At step 7, administrator clicks "Reset to Defaults" - System displays confirmation: "This will reset all settings to default values" - Administrator confirms - System loads default configuration values - Continue from step 9

A3: Clone Configuration - At step 6, administrator clicks "Clone to Another Environment" - System displays target environment selection - Administrator selects target (e.g., staging, test) - System copies configuration to target environment - Continue from step 14

A4: Enable/Disable Supplier - At step 7, administrator toggles "Active" status to "Inactive" - System displays warning: "Disabling supplier will prevent new bookings" - Administrator confirms - System disables supplier: - Products hidden from catalog - New bookings blocked - Existing bookings unaffected - Continue from step 9

A5: Configure Advanced Settings - At step 6, administrator clicks "Advanced Settings" - System displays additional configuration options: - Request/response logging level - Error handling strategy - Fallback behavior - Cache TTL settings - Rate limiting - Administrator modifies advanced settings - Continue from step 8

A6: View Configuration History - At step 6, administrator clicks "View History" - System displays configuration change log: - Date/time of change - Administrator who made change - Settings changed - Old and new values - Administrator reviews history - Continue from step 6

Exception Flows:

E1: Validation Failed - At step 8, configuration values invalid - System displays validation errors: - Highlight invalid fields - Show specific error messages - Administrator corrects values - Return to step 7

E2: Connection Test Failed - At step A1, connection test fails - System displays error details: - Error message - Error code - Suggested resolution - Administrator can: - Correct settings and retry - Save anyway (with warning) - Cancel changes - Return to step 7

E3: Save Failed - At step 12, database update fails - System displays error: "Failed to save configuration" - System logs error details - Configuration remains unchanged - Administrator can retry or contact support - Use case ends

E4: Unauthorized Access - At step 3, administrator lacks configuration permission - System displays: "Unauthorized - Configuration management requires admin role" - Use case ends

E5: Conflicting Changes - At step 12, another administrator modified same settings - System detects conflict - System displays: "Configuration changed by another user" - System shows both versions - Administrator can: - Overwrite with their changes - Discard their changes - Merge changes manually - Return to step 7

Business Rules: - Only administrators can modify supplier configuration - Critical settings (API credentials) require elevated authorization - Configuration changes logged for audit - Most settings apply immediately without restart - Some settings (database connection) require service restart - Default configurations provided for new suppliers - Invalid configurations prevented from saving - Inactive suppliers not displayed in customer-facing catalog - Test connection feature available to verify settings

Technical Notes: - Configuration Storage: - Database: Configuration table for runtime settings - XML Files: config/RaynaPluginConfig.xml for structural config - Properties Files: config/tlinqapi.properties for system-wide settings - Configuration Cache: Cached for performance, refreshed on update - Hot Reload: Most settings can be changed without restart - Configuration Validation: Java validation annotations - Audit Trail: All changes logged to audit table - Admin Interface: Web-based configuration UI - Security: API credentials encrypted at rest

4. Use Case Relationships

4.1 Includes Relationships

  • UC-05 (Create Booking) includes UC-04 (Check Availability & Pricing)
  • UC-06 (Receive Ticket Confirmation) includes UC-05 (Create Booking)
  • UC-07 (View Booking Details) included by UC-08, UC-09, UC-10
  • UC-09 (Amend Booking) includes UC-04 (Check Availability & Pricing)

4.2 Extends Relationships

  • UC-11 (Process Booking Manually) extends UC-05 (Create Booking)
  • UC-08 (Download Tickets) extends UC-07 (View Booking Details)
  • UC-09 (Amend Booking) extends UC-07 (View Booking Details)
  • UC-10 (Cancel Booking) extends UC-07 (View Booking Details)

4.3 Dependencies

UC-01 (Browse) → UC-02 (View Details) → UC-03 (Configure) → UC-04 (Check Availability) → UC-05 (Create Booking) → UC-06 (Receive Tickets)
                                                                                               ↓
                                                      UC-07 (View Booking) ← UC-08 (Download Tickets)
                                                                          ← UC-09 (Amend)
                                                                          ← UC-10 (Cancel)

UC-12 (Synchronize Catalog) → UC-01 (Browse) [enables product discovery]

UC-13 (Manage Configuration) → All Use Cases [configures system behavior]

5. Cross-Cutting Concerns

5.1 Error Handling

All use cases implement standard error handling: - User-friendly error messages displayed - Technical errors logged for investigation - Error codes provided for support reference - Retry mechanisms for transient failures - Graceful degradation when possible

5.2 Security

All use cases enforce security: - Authentication required for customer/agent actions - Authorization checked for administrative functions - Sensitive data encrypted (payment info, credentials) - Audit trail for all significant actions - Session timeout for inactive users - HTTPS for all communications

5.3 Performance

All use cases consider performance: - Caching of frequently accessed data - Asynchronous processing for long operations - Progress indicators for user feedback - Database query optimization - API timeout management - Horizontal scaling support

5.4 Logging and Monitoring

All use cases generate logs: - Info level: Normal operations - Warning level: Unusual but handled conditions - Error level: Failures requiring attention - Debug level: Detailed diagnostics (dev/test only) - Metrics collected for performance monitoring

Document Information

Document Version: 1.0 Date: 2025-11-23 Status: Approved Author: System Architecture Team Related Documents: - RAYNA_B2B_FUNCTIONAL_DESCRIPTION.md - Activity_Ticketing_Requirement_Spec.md - Activity_Ticketing_Implementation_Spec.md