Tiqets Integration - Use Case Specification¶

1. Introduction¶

1.1 Purpose¶

This document describes all implemented use cases for the Tiqets integration plugin (tqtiqets), detailing the interactions between actors and the system for browsing, booking, and managing activity tickets through the Tiqets supplier API.

1.2 Scope¶

This document covers: - Catalog browsing use cases (countries, cities, experiences, products) - Real-time availability and pricing use cases - Booking and ticketing workflow use cases - Administrative use cases for catalog management - System use cases for data synchronization

1.3 Actors¶

Primary Actors: - Customer - End user browsing and booking activities via B2C website - Agent - Travel agent managing bookings via B2B portal - Administrator - System administrator managing catalog and configuration

Secondary Actors: - Tiqets API - External Tiqets supplier system - System Scheduler - Automated background refresh processes - TQPro Booking Engine - Internal booking infrastructure

Supplier Integration - Technical implementation details
Tiqets API Specification - API endpoint specifications
Activity Ticketing Use Cases - General activity ticketing use cases

2. Use Case Overview¶

2.1 Use Case Diagram¶

+-------------------------------------------------------------------------+
|                        Tiqets Integration System                         |
+-------------------------------------------------------------------------+
|                                                                          |
|  Customer/Agent              Administrator              System           |
|       |                           |                        |             |
|       +---> UC-01: Browse Countries                        |             |
|       |                           |                        |             |
|       +---> UC-02: Browse Cities  |                        |             |
|       |                           |                        |             |
|       +---> UC-03: Browse Experiences                      |             |
|       |                           |                        |             |
|       +---> UC-04: View Experience Details                 |             |
|       |                           |                        |             |
|       +---> UC-05: Browse Products by Experience           |             |
|       |                           |                        |             |
|       +---> UC-06: Browse Products by City                 |             |
|       |                           |                        |             |
|       +---> UC-07: View Product Details with Variants      |             |
|       |                           |                        |             |
|       +---> UC-08: Check Real-time Availability            |             |
|       |                           |                        |             |
|       +---> UC-09: Get Timeslots for Product               |             |
|       |                           |                        |             |
|       +---> UC-10: Browse Activity Tags                    |             |
|       |                           |                        |             |
|       +---> UC-11: Filter Experiences by Tag               |             |
|       |                           |                        |             |
|       +---> UC-12: Create Ticket Order                     |             |
|       |                           |                        |             |
|       +---> UC-13: Confirm Ticket Order                    |             |
|       |                           |                        |             |
|       +---> UC-14: Check Order Status                      |             |
|       |                           |                        |             |
|       +---> UC-15: Cancel Ticket Order                     |             |
|       |                           |                        |             |
|       +---> UC-16: Download Tickets PDF                    |             |
|       |                           |                        |             |
|                           +---> UC-17: Enable/Disable City              |
|                           |                        |                    |
|                           +---> UC-18: Sync Tags from API               |
|                           |                        |                    |
|                           +---> UC-19: Trigger Manual Refresh           |
|                           |                        |                    |
|                                                    +---> UC-20: Scheduled Catalog Refresh
|                                                    |                    |
|                                                    +---> UC-21: Initial Catalog Bootstrap
|                                                    |                    |
|                                                    +---> UC-22: Quick Experience Sync
|                                                                         |
+-------------------------------------------------------------------------+

2.2 Use Case List¶

UC ID	Use Case Name	Primary Actor	Priority	Status
UC-01	Browse Countries	Customer	High	Implemented
UC-02	Browse Cities	Customer	High	Implemented
UC-03	Browse Experiences	Customer	High	Implemented
UC-04	View Experience Details	Customer	High	Implemented
UC-05	Browse Products by Experience	Customer	High	Implemented
UC-06	Browse Products by City	Customer	High	Implemented
UC-07	View Product Details with Variants	Customer	High	Implemented
UC-08	Check Real-time Availability	Customer	High	Implemented
UC-09	Get Timeslots for Product	Customer	High	Implemented
UC-10	Browse Activity Tags	Customer	Medium	Implemented
UC-11	Filter Experiences by Tag	Customer	Medium	Implemented
UC-12	Create Ticket Order	Customer/Agent	High	Implemented
UC-13	Confirm Ticket Order	Customer/Agent	High	Implemented
UC-14	Check Order Status	Customer/Agent	High	Implemented
UC-15	Cancel Ticket Order	Customer/Agent	High	Implemented
UC-16	Download Tickets PDF	Customer/Agent	High	Implemented
UC-17	Enable/Disable City	Administrator	Medium	Implemented
UC-18	Sync Tags from API	Administrator	Low	Implemented
UC-19	Trigger Manual Refresh	Administrator	Low	Implemented
UC-20	Scheduled Catalog Refresh	System	High	Implemented
UC-21	Initial Catalog Bootstrap	System	High	Implemented
UC-22	Quick Experience Sync	System	Medium	Implemented

3. Catalog Browsing Use Cases¶

UC-01: Browse Countries¶

Primary Actor: Customer/Agent

Description: List all countries that have Tiqets activities available.

Preconditions: - Catalog data has been synchronized from Tiqets API - In-memory cache is initialized

Postconditions: - List of countries returned with supplier IDs, names, and ISO codes

Main Success Scenario: 1. Customer navigates to activity browsing section 2. System retrieves countries from in-memory cache (TiqetsCacheManager) 3. System returns array of TqCountry entities containing: - Supplier country ID - Country name - ISO country code (e.g., "AE", "GB") 4. Customer views available countries

Technical Notes: - Service: TiqetsCatalogFacade.listCountries() - API Endpoint: POST /tiqets/countries - Data Source: In-memory cache (loaded from tiqets.country table)

UC-02: Browse Cities¶

Primary Actor: Customer/Agent

Description: List cities, optionally filtered by country and enabled status.

Preconditions: - Countries have been loaded - Cities have been synchronized

Postconditions: - List of cities matching filter criteria returned

Main Success Scenario: 1. Customer selects a country or views all cities 2. System retrieves cities from cache with optional filters: - countryId - Filter by country (supports both ISO code and supplier ID) - enabledOnly - Return only enabled cities (default: false) 3. System returns array of TqCity entities containing: - Supplier city ID - City name - Country reference - Timezone - Currency (default: AED) - Coordinates (latitude/longitude) - Enabled status 4. Customer views available cities

Alternative Flows:

A1: Filter by ISO Country Code - Customer provides ISO code (e.g., "AE" for UAE) - System converts ISO code to supplier country ID using getSupplierCountryIdByCode() - Continue from step 3

A2: Only Enabled Cities - Customer requests only enabled cities - System filters to return cities where enabled = true - Continue from step 3

Technical Notes: - Service: TiqetsCatalogFacade.listCities(countryId, enabledOnly) - API Endpoint: POST /tiqets/cities - Uses reverse index: citiesByCountry for efficient lookup

UC-03: Browse Experiences¶

Primary Actor: Customer/Agent

Description: List experiences (attractions/activities) with optional filtering and pagination.

Preconditions: - Experiences have been synchronized from Tiqets API - At least one enabled city exists

Postconditions: - Paginated list of experiences matching criteria returned

Main Success Scenario: 1. Customer selects browsing criteria: - City ID (optional) - Country ID (optional) - Category/tag filter (optional) - Page number (default: 1) - Page size (default: 50, max: 100) 2. System retrieves experiences from cache 3. System applies filters and pagination 4. System returns array of TqExperience entities containing: - Experience ID and type - Title, tagline, description - City and country references - Images (small, medium, large, xlarge) - Rating (average and count) - Starting price ("from price") - Tag IDs for filtering - Product IDs for navigation 5. Customer views experience listings

Alternative Flows:

A1: Browse by City - Customer selects specific city (e.g., "dubai") - System uses experiencesByCity reverse index - Returns experiences in that city only

A2: Browse by Country - Customer selects country without city - System returns all experiences in all cities of that country

A3: No Experiences Found - No experiences match criteria - System returns empty array - Frontend displays "No experiences found" message

Technical Notes: - Service: TiqetsCatalogFacade.listExperiences(cityId, countryId, category, page, pageSize) - API Endpoint: POST /tiqets/experiences - Frontend: uaeexp.js handles display and filtering

UC-04: View Experience Details¶

Primary Actor: Customer/Agent

Description: Get detailed information about a specific experience.

Preconditions: - Experience exists in catalog

Postconditions: - Complete experience details returned

Main Success Scenario: 1. Customer clicks on experience from listing 2. System retrieves experience by supplier ID from cache 3. If not in cache, system fetches from Tiqets API 4. System returns TqExperience with full details: - All basic fields from UC-03 - Full description and tagline - Complete image set with alt text and credit - Location coordinates - Google Place ID (if available) - Product IDs for related products 5. Customer views complete experience information

Exception Flows:

E1: Experience Not Found - Experience ID does not exist - System throws TlinqClientException with NOTFOUND error - Frontend displays error message

Technical Notes: - Service: TiqetsCatalogFacade.getExperience(experienceId) - API Endpoint: POST /tiqets/experience - Falls back to API if not in cache

UC-05: Browse Products by Experience¶

Primary Actor: Customer/Agent

Description: List all bookable products for a specific experience.

Preconditions: - Experience exists - Products have been synchronized

Postconditions: - List of products for the experience returned

Main Success Scenario: 1. Customer views experience and wants to see bookable options 2. System retrieves products using productsByExperience index 3. System returns array of TqProduct entities containing: - Product ID and title - Description, highlights, inclusions, exclusions - Duration (minutes and formatted) - Pricing (min price, retail price, discounts) - Booking configuration (timeslots, cutoff, max tickets) - Feature flags (wheelchair access, smartphone tickets, etc.) - Language support - Images and URLs 4. Customer views available product options

Technical Notes: - Service: TiqetsCatalogFacade.listProducts(experienceId, null) - API Endpoint: POST /tiqets/products - Uses productsByExperience reverse index

UC-06: Browse Products by City¶

Primary Actor: Customer/Agent

Description: List all products available in a city, regardless of experience grouping.

Preconditions: - City exists and is enabled - Products have been synchronized

Postconditions: - All products in the city returned

Main Success Scenario: 1. Customer wants to browse all activities in a city 2. System retrieves products using productsByCity index 3. System returns all TqProduct entities in that city 4. Customer browses complete city product catalog

Use Case: Useful for "Things to do in Dubai" style pages.

Technical Notes: - Service: TiqetsCatalogFacade.listProducts(null, cityId) - API Endpoint: POST /tiqets/products - Uses productsByCity reverse index

UC-07: View Product Details with Variants¶

Primary Actor: Customer/Agent

Description: Get complete product information including all ticket variants.

Preconditions: - Product exists in catalog

Postconditions: - Product details and variants returned

Main Success Scenario: 1. Customer selects a product to book 2. System retrieves product from cache 3. System retrieves variants using variantsByProduct index 4. System returns TqProduct with full content: - All fields from UC-05 - Important information - Cancellation policy details - Venue information (ID, name, address) - Starting points and meeting locations - Supplier information 5. System returns array of TqProductVariant entities: - Variant ID and label (e.g., "Adult", "Child") - Description - Variant type - Max tickets per variant - Cancellation window (hours) 6. Customer views complete booking options

Technical Notes: - Service: TiqetsCatalogFacade.getProduct(productId) + getProductVariants(productId) - API Endpoints: POST /tiqets/product, POST /tiqets/product/variants

4. Availability Use Cases¶

UC-08: Check Real-time Availability¶

Primary Actor: Customer/Agent

Description: Get real-time availability and pricing for a product within a date range.

Preconditions: - Product exists and is active - Date range is valid (max 90 days)

Postconditions: - Real-time availability with pricing returned

Main Success Scenario: 1. Customer selects travel dates on booking calendar 2. System validates date range: - Format: yyyy-MM-dd - Maximum range: 90 days - Start date not in past 3. System calls Tiqets API: GET /products/{id}/availability 4. System returns TqAvailability containing: - Product ID - Date range queried - Available dates array with: - Date - Availability status (boolean) - Capacity/vacancy count - Timeslots (if product has timeslots): - Time - Label - Capacity - Pricing per variant 5. Customer views available dates and timeslots

Alternative Flows:

A1: Product Has No Timeslots - Product operates at fixed time or any time - Timeslots array is empty - Customer selects date only

A2: Date Sold Out - Specific date has no availability - isAvailable = false for that date - Customer selects different date

Exception Flows:

E1: Invalid Date Format - Date not in yyyy-MM-dd format - System returns validation error - Customer corrects date format

E2: Date Range Exceeds Maximum - Range exceeds 90 days - System returns validation error - Customer narrows date range

Technical Notes: - Service: TiqetsCatalogFacade.getAvailability(productId, dateFrom, dateTo) - API Endpoint: POST /tiqets/availability - Real-time call - not cached - Input validation: TiqetsInputValidator

UC-09: Get Timeslots for Product¶

Primary Actor: Customer/Agent

Description: Get flattened timeslot list for booking form population.

Preconditions: - Product has timeslots enabled - Valid date range provided

Postconditions: - Flattened timeslot array returned

Main Success Scenario: 1. Customer needs to select a timeslot 2. System retrieves availability (UC-08) 3. System flattens availability into timeslot array: - Each timeslot includes date + time - Capacity information - Variant-specific pricing 4. Customer selects preferred timeslot

Technical Notes: - Service: TiqetsCatalogService.getTiqetsTimeslots(input) - API Endpoint: POST /tiqets/timeslots - Transforms nested availability structure to flat array

5. Tag and Filtering Use Cases¶

UC-10: Browse Activity Tags¶

Primary Actor: Customer/Agent

Description: List activity category tags for filtering.

Preconditions: - Tags have been synchronized from Tiqets API

Postconditions: - List of tags returned, optionally filtered by type group

Main Success Scenario: 1. Customer views category filter options 2. System retrieves tags from database 3. System optionally filters by type group name: - "Activity categories" - "Venue categories" - "Service categories" 4. System returns array of TqTag entities: - Tag ID and name - Type reference - Type group name - Icon URL 5. Customer views available filter categories

Technical Notes: - Service: TiqetsCatalogFacade.listTagsNative(typeGroupName) - API Endpoint: POST /tiqets/tags - Frontend loads multiple type groups and merges

UC-11: Filter Experiences by Tag¶

Primary Actor: Customer/Agent

Description: Filter displayed experiences by selected tag.

Preconditions: - Experiences are loaded - Tags are loaded

Postconditions: - Only experiences with selected tag are displayed

Main Success Scenario: 1. Customer clicks on a tag chip (e.g., "Museums") 2. Frontend retrieves tag ID 3. Frontend iterates through loaded experiences 4. For each experience, checks if tagIds contains selected tag: - Handles both array and comma-separated formats 5. Frontend shows/hides experience cards based on match 6. Customer views filtered results

Alternative Flows:

A1: Clear Tag Filter - Customer clicks active tag again - Filter is cleared - All experiences are displayed

Technical Notes: - Frontend implementation in uaeexp.js - Tags are filtered to only show those present in loaded experiences - Uses CSS display property for show/hide

6. Booking Use Cases¶

UC-12: Create Ticket Order¶

Primary Actor: Customer/Agent (via TQPro Booking Engine)

Description: Create a new order with Tiqets for selected products.

Preconditions: - Availability confirmed (UC-08) - Customer has selected product, date, timeslot (if required), and variants - Customer information collected

Postconditions: - Order created with Tiqets in PENDING status - Order reference and payment confirmation token returned - Local order entity created for tracking

Main Success Scenario: 1. Booking engine calls TiqetsTicketingService.initTicketRequest(request) 2. System validates ticket request: - Product ID exists - Booking date valid - Variants and quantities specified - Customer information complete 3. System builds CreateOrderRequest: - Product ID - Booking date (yyyy-MM-dd) - Timeslot ID (if applicable) - Variants array (variant ID + quantity pairs) - Customer details (first name, last name, email, phone) - Currency - External reference (TQPro booking request ID) 4. System creates local TiqetsOrderEntity to track request 5. System calls sendTicketRequest(request): - Signs request with JWT (RS256) - Calls Tiqets API: POST /orders 6. Tiqets returns: - Order reference ID - Payment confirmation token - Status: PENDING or CREATED 7. System updates local order entity with response 8. System returns TqTicketingResponse with order details

Alternative Flows:

A1: Multi-Variant Order - Customer selects multiple variant types (e.g., 2 Adults + 1 Child) - System aggregates quantities by variant ID - Single order contains multiple variant entries

Exception Flows:

E1: Product Not Available - Tiqets returns availability error - System marks order as FAILED - Returns error to booking engine

E2: Validation Failed - Request missing required fields - System returns validation error without calling API

Technical Notes: - Service: TiqetsTicketingService.initTicketRequest(), sendTicketRequest() - Uses JWT signing via TiqetsHttpClient.postSigned() - Order stored in tiqets.tiqets_order table

UC-13: Confirm Ticket Order¶

Primary Actor: Customer/Agent (via TQPro Booking Engine)

Description: Confirm order after payment and retrieve tickets.

Preconditions: - Order created (UC-12) with PENDING status - Payment completed - Payment confirmation token available

Postconditions: - Order confirmed with Tiqets - Tickets generated and available for download - Order status updated to OK

Main Success Scenario: 1. Payment handler calls TiqetsTicketingService.confirmTicketRequest(request) 2. System retrieves order reference and payment token 3. System calls Tiqets API: PUT /orders/{id} with payment token (JWT signed) 4. System polls for order completion: - Maximum 30 attempts - 10-second intervals (max 5 minutes total) - Waits for status = "done" or "completed" 5. Once complete, system fetches tickets: - Calls Tiqets API: GET /orders/{id}/tickets 6. System receives ticket data: - Barcodes for each ticket - PDF download URL - Validity dates 7. System updates local order entity: - Status: OK - Tickets PDF URL stored 8. System returns complete TqTicketingResponse with ticket details

Alternative Flows:

A1: Instant Confirmation - Product has instantConfirmation = true - Order completes immediately without polling - Continue from step 6

Exception Flows:

E1: Confirmation Timeout - Order not confirmed within 5 minutes - System returns timeout error - Order may still complete (background polling)

E2: Order Failed - Tiqets returns failure status - System updates order status: FAILED - Error code and message stored - Returns error to booking engine

Technical Notes: - Service: TiqetsTicketingService.confirmTicketRequest() - Uses OrdersService.waitForOrderCompletion() for polling - Mapped via TiqetsResponseMapper

UC-14: Check Order Status¶

Primary Actor: Customer/Agent

Description: Check current status of an existing order.

Preconditions: - Order exists in system

Postconditions: - Current order status returned with tickets if available

Main Success Scenario: 1. System calls TiqetsTicketingService.checkTicketRequest(request) 2. System retrieves order from Tiqets API: GET /orders/{id} 3. If order is completed, system fetches tickets: GET /orders/{id}/tickets 4. System returns current status: - Order status (PENDING, OK, FAILED, CANCELLED) - Ticket data (if available) - Error information (if failed)

Order Status Values: - pending/created - Waiting for payment confirmation - done/completed - Order complete, tickets ready - failed - Order failed (error details available) - cancelled - Order was cancelled

Technical Notes: - Service: TiqetsTicketingService.checkTicketRequest() - Maps Tiqets status to TQPro result codes via TiqetsResponseMapper

UC-15: Cancel Ticket Order¶

Primary Actor: Customer/Agent

Description: Cancel an existing order.

Preconditions: - Order exists and is not already cancelled - Cancellation allowed per product policy

Postconditions: - Order cancelled with Tiqets - Local order status updated to CANCELLED

Main Success Scenario: 1. System calls TiqetsTicketingService.cancelTicketRequest(request, prevResponse) 2. System retrieves order reference 3. System calls Tiqets API: DELETE /orders/{id} (JWT signed) 4. Tiqets confirms cancellation 5. System updates local order entity: - Status: CANCELLED - Updated timestamp 6. System returns cancellation confirmation

Exception Flows:

E1: Cancellation Not Allowed - Product is non-cancellable or past cutoff - Tiqets returns error - System returns cancellation failure

Technical Notes: - Service: TiqetsTicketingService.cancelTicketRequest() - Uses OrdersService.cancelOrder() with JWT signing

UC-16: Download Tickets PDF¶

Primary Actor: Customer/Agent

Description: Retrieve ticket PDF for confirmed order.

Preconditions: - Order is confirmed (status: OK) - Tickets have been generated

Postconditions: - Ticket PDF URL provided for download

Main Success Scenario: 1. Customer requests ticket download 2. System retrieves TiqetsOrderEntity from database 3. System returns ticketsPdfUrl stored during confirmation 4. Customer downloads PDF from Tiqets URL

Technical Notes: - PDF URL stored in tiqets.tiqets_order.tickets_pdf_url - URL points to Tiqets-hosted PDF - Tickets contain barcodes for venue scanning

7. Administrative Use Cases¶

UC-17: Enable/Disable City¶

Primary Actor: Administrator

Description: Control which cities appear in the public catalog.

Preconditions: - City exists in database

Postconditions: - City enabled/disabled status updated - Affects visibility in customer-facing catalog

Main Success Scenario: 1. Administrator navigates to city management 2. Administrator selects city to enable or disable 3. System calls TiqetsCatalogFacade.enableCity(cityId) or disableCity(cityId) 4. System updates enabled flag in tiqets.city table 5. Cache is updated 6. City appears/disappears from customer browsing

Technical Notes: - Service: TiqetsCatalogFacade.enableCity(), disableCity() - API Endpoint: POST /tiqets/city/enable, POST /tiqets/city/disable - Only enabled cities returned when enabledOnly = true

UC-18: Sync Tags from API¶

Primary Actor: Administrator

Description: Synchronize tag taxonomy from Tiqets API.

Preconditions: - Tiqets API accessible

Postconditions: - Local tag database updated with latest Tiqets tags

Main Success Scenario: 1. Administrator triggers tag sync 2. System calls TiqetsCatalogFacade.syncTagTypes(): - Fetches all tag types from Tiqets API - Updates tiqets.tag_type table 3. System calls TiqetsCatalogFacade.syncTags(): - Fetches all tags (paginated) - Updates tiqets.tag table 4. System returns count of synced items 5. Tags available for filtering

Technical Notes: - Service: TiqetsCatalogFacade.syncTagTypes(), syncTags() - API Endpoint: POST /tiqets/tags/sync - Uses TagsService for API calls

UC-19: Trigger Manual Refresh¶

Primary Actor: Administrator

Description: Manually trigger catalog data refresh.

Preconditions: - Tiqets API accessible - No refresh currently running

Postconditions: - Catalog data refreshed from Tiqets API

Main Success Scenario: 1. Administrator triggers manual refresh 2. System calls TiqetsPlugin.triggerRefresh() 3. TiqetsDataRefresher.refreshAll() executes: - Gets all enabled cities - For each city, refreshes experiences and products - Updates database - Refreshes in-memory cache 4. System logs completion

Technical Notes: - Service: TiqetsPlugin.triggerRefresh(), TiqetsDataRefresher.refreshAll() - Uses refreshAllOptimized() for ~100x faster performance - Updates tiqets.refresh_status table

8. System Use Cases¶

UC-20: Scheduled Catalog Refresh¶

Primary Actor: System Scheduler

Description: Automatically refresh catalog data on schedule.

Preconditions: - Plugin initialized with auto-refresh enabled - Refresh interval configured (default: 6 hours)

Postconditions: - Catalog data current with Tiqets API

Main Success Scenario: 1. Scheduler triggers at configured interval 2. System checks if refresh should run: - shouldRunRefresh(intervalHours) compares last refresh time 3. If due, system executes refreshAll(): - Records refresh status: RUNNING - For each enabled city: - Fetches experiences from Tiqets API - Fetches products for each experience - Updates database entities - Refreshes in-memory cache - Records refresh status: COMPLETED 4. System logs completion with item counts

Alternative Flows:

A1: Optimized Refresh - System uses refreshAllOptimized() for batch processing - Fetches products directly by city (not by experience) - 50 products per transaction - ~100x faster than standard refresh

A2: Refresh Already Running - Previous refresh still in progress - System skips this execution - Logs skip reason

Exception Flows:

E1: API Error During Refresh - Tiqets API returns error - System logs error - Records refresh status: FAILED with error message - Retries at next scheduled interval

Technical Notes: - Scheduled in TiqetsPlugin.scheduleDataRefresh() - Uses ScheduledExecutorService with daemon thread - No initial refresh on startup - first check after interval - Configurable via tiqets.refresh.interval.hours property

UC-21: Initial Catalog Bootstrap¶

Primary Actor: System

Description: Bootstrap catalog with initial data load.

Preconditions: - Plugin starting for first time or cache empty - Tiqets API accessible

Postconditions: - Basic catalog structure loaded (countries, cities, experiences)

Main Success Scenario: 1. System detects empty cache on startup 2. System calls TiqetsDataRefresher.initialSync(maxPages): - Fetches all countries - Fetches all cities - Fetches experiences (paginated, up to maxPages) - Fetches products for each experience 3. System populates database tables 4. System initializes in-memory cache 5. Catalog ready for browsing

Technical Notes: - Service: TiqetsDataRefresher.initialSync(maxPages) - Called during first-time setup or data recovery

UC-22: Quick Experience Sync¶

Primary Actor: System/Administrator

Description: Fast sync of experiences only (without products).

Preconditions: - Tiqets API accessible

Postconditions: - Experience catalog updated quickly

Main Success Scenario: 1. System calls TiqetsDataRefresher.quickExperienceSync(maxPages) 2. System fetches experiences (no products): - Faster than full refresh - Updates location hierarchy 3. System updates database and cache 4. Returns count of synced experiences

Use Case: Quick update of experience listing without full product refresh.

Technical Notes: - Service: TiqetsDataRefresher.quickExperienceSync(maxPages) - Useful for bootstrapping or quick updates

9. Data Flow Summary¶

Booking Flow¶

1. Browse Catalog (cached)
   └─> Countries → Cities → Experiences → Products

2. Check Availability (real-time)
   └─> Product + Date Range → Tiqets API → Availability + Timeslots

3. Create Order
   └─> Selection + Customer → JWT-signed POST /orders → Order Reference + Token

4. Confirm Order (after payment)
   └─> Order + Token → JWT-signed PUT /orders/{id} → Poll for completion → Tickets

5. Get Tickets
   └─> Order Reference → GET /orders/{id}/tickets → PDF URL + Barcodes

Refresh Flow¶

1. Scheduled/Manual Trigger
   └─> TiqetsPlugin → TiqetsDataRefresher

2. Fetch from API
   └─> Countries → Cities → Experiences → Products → Variants

3. Update Database
   └─> PostgreSQL tiqets.* tables

4. Refresh Cache
   └─> TiqetsCacheManager (in-memory)

10. Cross-Cutting Concerns¶

Security¶

API Key Authentication: Used for read-only catalog APIs
JWT Signing (RS256): Required for booking operations (POST, PUT, DELETE /orders)
Input Validation: TiqetsInputValidator enforces date formats, ID patterns, pagination limits

Performance¶

In-Memory Caching: TiqetsCacheManager provides fast catalog access
Reverse Indexes: Efficient lookups by city, experience, product
Optimized Refresh: Batch processing ~100x faster than per-experience refresh
Real-time Only for Availability: Catalog cached, availability always fresh

Error Handling¶

Standard Error Codes: OK, ERR00001 (GENERAL), ERR00003 (NOTFOUND), ERR00014 (INVALID_PARAMETER)
Exception Mapping: TiqetsResponseMapper converts API errors to TQPro format
Retry Logic: Polling for order confirmation with timeout

Monitoring¶

Refresh Status Table: tiqets.refresh_status tracks sync operations
Order Tracking: tiqets.tiqets_order stores all booking attempts
Logging: Comprehensive logging at INFO and FINE levels

Document Information¶

Document Version: 1.0 Date: 2025-01-13 Status: Complete Author: System Architecture Team

Tiqets Integration - Use Case Specification¶

1. Introduction¶

1.1 Purpose¶

1.2 Scope¶

1.3 Actors¶

1.4 Related Documents¶

2. Use Case Overview¶

2.1 Use Case Diagram¶

2.2 Use Case List¶

3. Catalog Browsing Use Cases¶

UC-01: Browse Countries¶

UC-02: Browse Cities¶

UC-03: Browse Experiences¶

UC-04: View Experience Details¶

UC-05: Browse Products by Experience¶

UC-06: Browse Products by City¶

UC-07: View Product Details with Variants¶

4. Availability Use Cases¶

UC-08: Check Real-time Availability¶

UC-09: Get Timeslots for Product¶

5. Tag and Filtering Use Cases¶

UC-10: Browse Activity Tags¶

UC-11: Filter Experiences by Tag¶

6. Booking Use Cases¶

UC-12: Create Ticket Order¶

UC-13: Confirm Ticket Order¶

UC-14: Check Order Status¶

UC-15: Cancel Ticket Order¶

UC-16: Download Tickets PDF¶

7. Administrative Use Cases¶

UC-17: Enable/Disable City¶

UC-18: Sync Tags from API¶

UC-19: Trigger Manual Refresh¶

8. System Use Cases¶

UC-20: Scheduled Catalog Refresh¶

UC-21: Initial Catalog Bootstrap¶

UC-22: Quick Experience Sync¶

9. Data Flow Summary¶

Booking Flow¶

Refresh Flow¶

10. Cross-Cutting Concerns¶

Security¶

Performance¶

Error Handling¶

Monitoring¶

Document Information¶