Skip to content

Activity Ticketing Plugin - Functional Description

1. Overview & Purpose

The Rayna B2B plugin integrates the TQPro travel platform with Rayna Tours, a third-party supplier of tours, activities, and experiences. It enables the platform to offer a wide catalog of ticketed experiences (sightseeing tours, attractions, activities) to end customers through a seamless booking workflow.

Core Capabilities: - Search and browse tours and activities by destination - Display detailed tour information with images, descriptions, and terms - Real-time availability and pricing checks - Dynamic product configuration with options and transfers - Booking creation and confirmation - Local catalog caching for performance optimization

2. Product Catalog Management

2.1 Tour Information Structure

Each tour/activity in the system contains:

Basic Information: - Tour name, type, and unique identifier - Destination (country, city) - Duration and language availability - Age policies (adult, child, infant definitions) - Combo tour indicators - Timeslot availability flags

Descriptive Content: - Detailed descriptions and itineraries - Important information and notes - FAQ details - Inclusions (what's included in the tour) - Terms and conditions - Cancellation policies - Departure point information - Image galleries

2.2 Product Attributes & Variants

Tours can have multiple configurable attributes:

  1. Product Options - Different tour variants (e.g., "Standard Tour", "VIP Tour", "Sunset Tour")
  2. Transfer Types - Transportation options (e.g., "Shared Transfer", "Private Transfer", "No Transfer", "Self Drive")
  3. Timeslots - Available start times for tours (when applicable)

Dependency Rules: - Attributes can have dependencies (e.g., certain transfers are only available with specific tour options) - The system enforces these relationships to ensure valid combinations - Pricing varies based on the selected attribute combination

2.3 Pricing Structure

Pricing is segmented by passenger type: - Adult pricing - Standard passenger rate - Child pricing - Reduced rate for children (age range defined per tour) - Infant pricing - Usually free or minimal charge

Prices are dynamic and can vary by: - Selected tour date - Chosen product option - Selected transfer type - Number of passengers - Timeslot selection

3. Data Synchronization & Caching

3.1 Local Database Cache

The plugin maintains a local PostgreSQL database (schema: rayna) that stores:

Master Data: - Countries and cities (destination catalog) - Tours catalog with full details - Tour options and pricing information - Transfer types and availability - Cancellation policies - Image references - Terms and conditions

Operational Data: - Tour prices by date range - Tour times and schedules - Transfer mappings (which transfers work with which tours) - Refresh status tracking

3.2 Automated Refresh Mechanism

Scheduled Synchronization: - Runs automatically every 1 hour via a scheduled executor service - Fetches latest tour catalog data from Rayna's remote API - Updates local database with new tours, pricing, and availability - Maintains data freshness without impacting user experience

Refresh Tracking: - Monitors sync status per data entity - Tracks last successful refresh timestamp - Logs errors for failed synchronizations

3.3 Memory Caching

Hazelcast Distributed Cache: - High-speed memory cache for frequently accessed data - Caches transfer information for quick lookup - Reduces database queries for performance - Enables horizontal scaling across multiple servers

4. Product Discovery & Selection

4.1 Category Browsing

Users can: - Browse tours by category (e.g., "Desert Safari", "Water Sports", "Cultural Tours") - View all products within a specific category - Filter and search across the catalog

4.2 Product Detail Views

For each tour, users can view: - Complete product information and descriptions - Photo galleries showing the experience - Detailed inclusions and exclusions - Terms, conditions, and cancellation policies - Available options and pricing - Reviews and ratings (when available)

4.3 Attribute Selection Workflow

Step-by-Step Configuration:

  1. Select Travel Date - Choose the date for the experience
  2. Select Party Size - Specify number of adults, children, and infants
  3. Choose Product Option - Select the preferred tour variant
  4. Select Transfer Type - Choose transportation method (if applicable)
  5. Pick Timeslot - Select preferred start time (for tours with multiple daily departures)

Smart Dependencies: - System automatically filters available transfers based on selected tour option - Invalid combinations are prevented through UI constraints - Only available timeslots are shown based on previous selections

5. Availability & Pricing Checks

5.1 Real-Time Availability

Before allowing a booking, the system: - Queries Rayna's live API for current availability - Checks for the specific date, option, transfer, and timeslot combination - Returns availability status: - Available - Tour can be booked - On Request - Requires manual confirmation - Not Available - Cannot be booked - Sold Out - No remaining capacity

5.2 Live Pricing

The system retrieves: - Current supplier cost (purchase price) - Breakdown by passenger type (adult/child/infant rates) - Total cost calculation - Any applicable surcharges or fees

5.3 Additional Requirements Detection

Certain tour configurations require extra information: - Pickup Location - Required for shared or private transfers - Passenger Details - Name, nationality, contact information - Special Requests - Dietary requirements, accessibility needs

6. Booking & Ticketing Process

6.1 Booking Request Creation

When a customer confirms a booking:

  1. Booking Request Assembly:
  2. Consolidates all selected tour details
  3. Gathers passenger information
  4. Calculates final pricing

  5. Generates unique booking reference numbers

  6. Request Structure:

  7. Multiple tour items can be combined in one booking
  8. Each tour includes: tour ID, date, option, transfer, timeslot, quantities
  9. Passenger details: name, email, mobile, nationality, lead passenger designation

  10. Pickup information (when required)

  11. Data Consolidation:

  12. Groups items by identical tour/date/option/transfer/timeslot combinations
  13. Aggregates passenger counts to optimize pricing
  14. Maintains traceability to original cart items

6.2 Supplier Communication

The plugin sends booking requests to Rayna's API: - Transmits full booking details in supplier's required format - Includes unique reference numbers for tracking - Sends passenger information for ticket generation - Specifies service dates and times

6.3 Booking Confirmation

Upon successful booking: - Receives confirmation from Rayna with supplier booking reference - Obtains voucher/ticket details - Gets final pricing confirmation - Receives any special instructions or pickup details

6.4 Ticket Generation

The system can generate: - QR Codes - For mobile ticket scanning - PDF417 Barcodes - For printed vouchers - Formatted ticket documents with all booking details - Vouchers with redemption instructions

7. API Exposure & Frontend Integration

7.1 REST API Endpoints

The plugin exposes functionality through the Product API (/tlinq-api/product/*):

Catalog Access:

  • GET/POST /product/getCategories - Retrieve all tour categories
  • POST /product/getCategoryProducts - Get tours in a specific category
  • POST /product/getProduct - Fetch detailed tour information by ID or code
  • POST /product/searchProduct - Search tours by criteria
  • POST /product/productLookup - Quick product name lookup

Product Configuration:

  • POST /product/getProductAttributes - Get available attributes (options, transfers) for a tour
  • POST /product/getProductVariants - Get all possible variants for a tour
  • POST /product/getVariant - Get specific variant based on selected attributes
  • POST /product/getDefaultVariant - Get the default/standard variant
  • POST /product/getTimeslots - Get available start times for a variant

Availability & Pricing:

  • POST /product/getAvailability - Check live availability and get pricing for a configuration
  • POST /product/getTerms - Retrieve terms, conditions, and policies for a tour

7.2 Frontend Usage (tqweb-pub)

The public-facing website uses these APIs through JavaScript modules:

Key Frontend Modules:

products.js - Core product operations: 

// Load tour categories
loadCategories()

// Get tours in a category
loadCategoryProducts(categoryId)

// Get single tour details
getProduct(productId)

// Check availability and pricing
checkProductAvailability(bookingRequest)

// Get product variants
getAllProductVariants(productId, bookInfo)
getProductVariants(productId, bookInfo, attributes)

productbook.js - Tour booking workflow: - Handles attribute selection dropdowns - Manages timeslot picker - Calculates total pricing dynamically - Updates availability in real-time as options change - Prepares booking requests for cart

ticketbook.js - Booking confirmation and checkout - Finalizes tour bookings - Collects passenger information - Processes payments - Generates tickets/vouchers

User Interface Flow:

  1. Browse & Search:
  2. Customer browses categories or searches for tours

  3. Views tour listings with images and basic info

  4. Tour Detail Page:

  5. Displays comprehensive tour information
  6. Shows image galleries
  7. Presents pricing starting from lowest rate

  8. Displays terms, inclusions, and policies

  9. Configuration Widget:

  10. Interactive attribute selectors (dropdowns)
  11. Date picker for travel date
  12. Passenger count inputs (adults/children/infants)
  13. Dynamic pricing updates as selections change
  14. Availability status display

  15. Timeslot picker (when applicable)

  16. Add to Cart:

  17. Selected configuration added to shopping cart
  18. Cart shows detailed breakdown

  19. Multiple tours can be added

  20. Checkout:

  21. Passenger information collection
  22. Pickup location entry (if needed)
  23. Final price confirmation
  24. Payment processing
  25. Booking confirmation with voucher

8. Technical Architecture Patterns

8.1 Plugin Architecture

Component Structure: - Plugin Initialization - Registers with TQPro framework at startup - Service Factory - Creates service instances for different operations - Configuration Management - Loads settings from XML configuration files - Database Session - Manages Hibernate sessions for local database access - Cache Manager - Controls distributed memory cache

8.2 Service Layer Organization

Entity Services: - RaynaProductService - Handles all product catalog operations - RaynaTicketingService - Manages booking and ticketing workflows - RaynaEntityService - Base service with common functionality

Remote Services: - TourInfoService - Fetches tour static data from Rayna - TourOptionService - Retrieves pricing and options - TourAvailabilityService - Checks real-time availability - TourTimeslotService - Gets available time slots - TourBookingService - Creates bookings with supplier - TourCancelService - Handles booking cancellations

Facade Pattern: - CatalogFacade - Provides unified interface to catalog operations - Abstracts complexity of database and remote API interactions - Handles data transformation between local and remote formats

8.3 Data Flow

Outbound (Customer → Supplier): 1. Frontend captures user selections 2. API validates and transforms request 3. Product service prepares supplier-specific format 4. Remote service calls Rayna API 5. Response transformed to canonical format 6. Result returned to frontend

Inbound (Supplier → Local Cache): 1. Scheduled refresh job triggers 2. Fetches latest catalog from Rayna API 3. Transforms supplier data to local entities 4. Updates PostgreSQL database 5. Refreshes memory cache 6. Logs refresh status

9. Key Business Rules

9.1 Booking Constraints

  • Minimum passenger requirements (usually 1 adult minimum)
  • Age-based pricing tiers (adult/child/infant)
  • Date restrictions (advance booking requirements, blackout dates)
  • Capacity limits (maximum group sizes)
  • Cut-off times (last booking time before tour departure)

9.2 Pricing Rules

  • Supplier cost vs. selling price markup
  • Dynamic pricing based on date and availability
  • Volume discounts (not currently implemented)
  • Promotional pricing (configurable in product template)

9.3 Cancellation Policies

  • Cancellation deadlines (hours/days before tour)
  • Refund percentages based on cancellation timing
  • Non-refundable bookings
  • Amendment policies and fees

10. System Benefits

For Customers: - Wide selection of curated tours and activities - Real-time availability and instant confirmation - Transparent pricing with no hidden fees - Detailed tour information and reviews - Flexible configuration options - Digital vouchers/tickets

For Business: - Automated supplier integration (no manual processing) - Scalable catalog management (1000+ tours) - Performance optimization through caching - Real-time inventory synchronization - Reduced operational overhead - Multi-channel distribution capability

For Operations: - Hourly automatic catalog updates - Centralized supplier management - Booking tracking and reporting - Error handling and logging - Failover and retry mechanisms

11. Integration Points

Upstream Dependencies: - TQPro Core Framework - Plugin registration and lifecycle management - Entity System - Canonical product and booking entities - Service Factory - Dynamic service instantiation - Configuration System - XML-based configuration loading

Downstream Integrations: - Rayna B2B API - Supplier's REST/SOAP services - PostgreSQL Database - Local catalog storage (schema: rayna) - Hazelcast Cache - Distributed memory caching - Product Facade - Unified product management interface - Ticketing Service - Booking creation and fulfillment

Frontend Connections: - Product API - RESTful JSON endpoints - JavaScript Modules - ES6 modules for UI interactions - Session Management - User authentication and authorization

12. Module Structure

tqryb2b Module Organization:

tqryb2b/
├── config/
│   └── RaynaPluginConfig - Plugin configuration
├── db/
│   ├── TourEntity - Tour master data
│   ├── TouroptionEntity - Tour options
│   ├── TourtransferEntity - Transfer mappings
│   ├── TransferEntity - Transfer types
│   ├── TourpriceEntity - Pricing information
│   ├── TourtimeEntity - Tour schedules
│   ├── TourimageEntity - Image references
│   ├── TourinfoEntity - Descriptive content
│   ├── TourtermsEntity - Terms and conditions
│   ├── CancelpolicyEntity - Cancellation rules
│   ├── CountryEntity - Countries catalog
│   ├── CityEntity - Cities catalog
│   └── RefreshstatusEntity - Sync tracking
├── entity/
│   ├── RyProduct - Canonical product entity
│   ├── RyProductAttribute - Product attributes
│   ├── RyProductVariant - Product variants
│   ├── RyTimeslot - Available timeslots
│   ├── RyTransfer - Transfer options
│   └── RyActTicketing* - Ticketing request/response
├── service/
│   ├── RaynaServiceFactory - Service factory
│   ├── RaynaTicketingService - Booking service
│   ├── RaynaEntityService - Base entity service
│   ├── RaynaProductService - Product operations
│   ├── SDRefresher - Data refresh service
│   └── product/
│       └── CatalogFacade - Catalog management facade
├── remoteservice/
│   ├── TourOptionService - Remote pricing service
│   ├── TourAvailabilityService - Availability checks
│   ├── TourTimeslotService - Timeslot retrieval
│   ├── TourBookService - Booking creation
│   └── TourCancelService - Cancellation handling
└── util/
    ├── RaynaClientConfig - Configuration management
    ├── RaynaDBSession - Database session handling
    └── RaynaCacheManager - Cache management

Document Information

Version: 1.0 Date: 2025-11-23 Module: tqryb2b Purpose: Functional specification for Rayna B2B ticketing platform integration Audience: Business analysts, product managers, technical architects