Ticket-Based Offerings
Ticket-based offerings integrate Waldur marketplace with external ticketing systems (JIRA, SMAX, Zammad) to manage service provisioning through support tickets.
Overview
When offerings are configured with type = "Marketplace.Support"
, orders are processed through external ticketing systems rather than direct API provisioning. This enables:
- Manual service provisioning workflows
- Integration with existing ITSM processes
- Human approval and intervention
- Complex provisioning that requires multiple steps
Architecture
graph LR
Order[Marketplace Order] --> Issue[Support Issue]
Issue --> Backend[Ticketing Backend]
Backend --> Status[Status Change]
Status --> Callback[Resource Callback]
Callback --> Resource[Resource State]
Order Processing Flow
1. Order Creation
When a customer creates an order for a ticket-based offering:
- A support issue is created in the configured backend (JIRA/SMAX/Zammad)
- The order is linked to the issue via
issue.resource
- The issue contains order details in its description
2. Status Synchronization
The system monitors issue status changes through:
- Backend synchronization (
sync_issues()
) - Webhooks (JIRA, SMAX, Zammad - if configured)
- Periodic polling
3. Callback Triggering
When an issue status changes, the system determines the appropriate callback based on:
- Order Type (CREATE, UPDATE, TERMINATE)
- Resolution Status (resolved, canceled)
The callback mapping is defined in marketplace_support/handlers.py
:
1 2 3 4 5 6 7 8 |
|
Issue Resolution Detection
The system determines if an issue is resolved or canceled through the IssueStatus
model:
IssueStatus Configuration
Each status name from the ticketing system maps to one of two types:
IssueStatus.Types.RESOLVED
(0) - Successfully completedIssueStatus.Types.CANCELED
(1) - Failed or canceled
Model Structure:
1 2 3 4 |
|
Example Configuration:
1 2 3 4 |
|
Access Control:
- Staff users: Full CRUD access via API and admin interface
- Support users: Read-only access (can view existing statuses)
- Regular users: No access
Resolution Logic
- When an issue's status changes (e.g., from backend sync)
- The
issue.resolved
property is evaluated: - Looks up the status name in
IssueStatus
table - Returns
True
if type isRESOLVED
- Returns
False
if type isCANCELED
-
Returns
None
for other statuses -
Based on
(order.type, issue.resolved)
combination, the appropriate callback is triggered
Resource Deletion Failed Scenario
The resource_deletion_failed
callback is triggered when:
- Issue Status Changes: The support ticket's status is updated
- Order Type is TERMINATE: The order represents a resource deletion request
- Status Maps to CANCELED: The new status is configured as
IssueStatus.Types.CANCELED
- Callback Execution:
callbacks.resource_deletion_failed(order.resource)
is called
This typically happens when:
- Support staff reject a deletion request
- Technical issues prevent resource removal
- Business rules block the deletion
- The request is canceled before completion
Configuration
Backend Setup
Configure the ticketing backend in settings:
1 2 3 4 5 |
|
Status Mapping
IssueStatus objects can be configured through the API or admin interface to map backend statuses correctly.
API Management (Staff Only)
Staff users can manage IssueStatus configurations through the REST API:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
Response Format:
1 2 3 4 5 6 7 |
|
Programmatic Setup
For automated deployment, use data migrations or management commands:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Best Practices
- Status Configuration: Ensure all possible backend statuses are mapped in IssueStatus
- Use the
/api/support-issue-statuses/
API for programmatic management - Staff users should regularly review and update status mappings
-
Document your backend's status workflow and map all statuses accordingly
-
Monitoring: Regularly sync issues to detect status changes
- Error Handling: Implement proper error handling in callbacks
- Logging: Monitor handler execution through logs for debugging
- Testing: Test status transitions with different order types
- API Management: Use the REST API for consistent status configuration across environments
Troubleshooting
Callbacks Not Firing
- Check if IssueStatus entries exist for the backend's status values
- Verify the offering type is set to
"Marketplace.Support"
- Ensure issue synchronization is running
- Check logs for handler execution
Wrong Callback Triggered
- Review IssueStatus type configuration
- Verify the order type (CREATE/UPDATE/TERMINATE)
- Check the issue resolution logic in logs
Missing Status Mappings
If you see critical log messages about missing statuses:
1 |
|
Resolution Options:
- API Management (Recommended): Use the REST API to add missing statuses:
1 2 3 4 5 6 7 |
|
-
Admin Interface: Add the required IssueStatus entries through Django admin
-
Identify Missing Statuses: Check your backend system for all possible status values and ensure each has a corresponding IssueStatus entry
Common Missing Statuses by Backend:
- JIRA: "To Do", "In Progress", "Done", "Cancelled"
- SMAX: "Open", "In Progress", "Resolved", "Rejected"
- Zammad: "new", "open", "pending reminder", "pending close", "closed"
Use GET /api/support-issue-statuses/
to view currently configured statuses and compare against your backend's status list.