Waldur Support Module

The Support module provides a comprehensive helpdesk and ticketing system with multi-backend integration, enabling organizations to manage support requests through JIRA, SMAX, Zammad, or a basic built-in system.

Overview

The support module acts as an abstraction layer over multiple ticketing backends, providing:

• Unified API for ticket management across different backends
• Bidirectional synchronization with external ticketing systems
• Template-based issue creation
• Customer feedback collection
• SLA tracking and reporting
• Advanced permission management

Architecture

graph TB
    subgraph "Waldur Support"
        API[Support API]
        Models[Support Models]
        Backend[Backend Interface]
    end

    subgraph "External Systems"
        JIRA[JIRA/Service Desk]
        SMAX[Micro Focus SMAX]
        Zammad[Zammad]
    end

    subgraph "Integration"
        Webhook[Webhooks]
        Sync[Synchronization]
    end

    API --> Models
    Models --> Backend
    Backend --> JIRA
    Backend --> SMAX
    Backend --> Zammad

    JIRA --> Webhook
    SMAX --> Webhook
    Zammad --> Webhook
    Webhook --> Models

    Sync --> Backend

Core Components

1. Issue Management

The Issue model is the central entity for ticket management:

class Issue:
    # Identification
    key: str              # Backend ticket ID (e.g., "PROJ-123")
    backend_id: str       # Internal backend ID
    summary: str          # Issue title
    description: str      # Detailed description

    # Classification
    type: str            # INFORMATIONAL, SERVICE_REQUEST, CHANGE_REQUEST, INCIDENT
    status: str          # Backend-specific status
    priority: Priority   # Priority level

    # Relationships
    caller: User         # Waldur user who created the issue
    reporter: SupportUser # Backend user who reported
    assignee: SupportUser # Backend user assigned
    customer: Customer   # Associated customer
    project: Project     # Associated project
    resource: GenericFK  # Linked resource (VM, network, etc.)

    # Timing
    created: datetime
    modified: datetime
    deadline: datetime
    resolution_date: datetime

Issue Types:

• INFORMATIONAL - General information requests
• SERVICE_REQUEST - Service provisioning requests
• CHANGE_REQUEST - Change management requests
• INCIDENT - Incident reports and outages

2. Comment System

Comments provide threaded discussions on issues:

class Comment:
    issue: Issue         # Parent issue
    description: str     # Comment text
    author: SupportUser  # Comment author
    is_public: bool      # Visibility control
    backend_id: str      # Backend comment ID

Comment Features:

• Public/private visibility control
• Automatic user information formatting for backends
• Bidirectional synchronization

3. Attachment Management

File attachments for issues and templates:

class Attachment:
    issue: Issue
    file: FileField     # Stored in 'support_attachments/'
    backend_id: str     # Backend attachment ID

    # Properties from FileMixin
    mime_type: str
    file_size: int

4. User Management

SupportUser bridges Waldur users with backend systems:

class SupportUser:
    user: User          # Waldur user (optional)
    name: str           # Display name
    backend_id: str     # Backend user ID
    backend_name: str   # Backend type
    is_active: bool     # Activity status

5. Custom Field Integration

Resource Backend ID Synchronization:

The system supports automatic resource backend_id updates via Service Desk custom fields:

# Automatic sync flow during issue updates
def _update_resource_backend_id_from_custom_fields(issue):
    """
    Updates connected resource's backend_id from Service Desk custom fields.

    Triggered during: issue synchronization from helpdesk
    Requirements: ATLASSIAN_CUSTOM_ISSUE_FIELD_MAPPING_ENABLED = True
    Custom Field: waldur_backend_id (customfield_10200)
    """

Integration Benefits:

• External systems can update Waldur resource identifiers via Service Desk
• One-way data synchronization from helpdesk to Waldur resources
• Automated resource identifier management from external platforms
• Enhanced integration capabilities for third-party tools

Supported Resource Types:

• Marketplace Orders (marketplace.Order)
• Marketplace Resources (marketplace.Resource)
• Any resource with backend_id field connected via Issue generic foreign key

6. Template System

Templates enable standardized issue creation:

class Template:
    name: str
    description: str
    issue_type: str     # Issue classification

class TemplateConfirmationComment:
    template: Template
    comment: str        # Auto-response text

class TemplateStatusNotification:
    template: Template
    status: str         # Trigger status
    html_template: str  # Email template

7. Status Management

IssueStatus maps backend statuses to resolution types:

class IssueStatus:
    uuid: UUID          # Unique identifier
    name: str           # Backend status name (e.g., "Done", "Closed", "Cancelled")
    type: int           # RESOLVED or CANCELED

    # Types
    RESOLVED = 0        # Successfully completed
    CANCELED = 1        # Failed or canceled

Status Configuration:

Status configuration is critical for proper issue resolution detection. The system uses IssueStatus entries to determine whether an issue has been successfully resolved or canceled:

• RESOLVED: Statuses that indicate successful completion (e.g., "Done", "Resolved", "Completed")
• CANCELED: Statuses that indicate cancellation or failure (e.g., "Cancelled", "Rejected", "Failed")

Management Access:

• Staff users: Full CRUD access to manage status configurations
• Support users: Read-only access to view existing statuses
• Regular users: No access

API Operations:

# List all issue statuses
GET /api/support-issue-statuses/

# Create new status (staff only)
POST /api/support-issue-statuses/
{
  "name": "In Progress",
  "type": 0
}

# Update existing status (staff only)
PATCH /api/support-issue-statuses/{uuid}/
{
  "name": "Completed"
}

# Delete status (staff only)
DELETE /api/support-issue-statuses/{uuid}/

8. Feedback System

Customer satisfaction tracking:

class Feedback:
    issue: Issue
    evaluation: int     # 1-10 scale
    comment: str        # Optional feedback text

Backend Integration

Supported Backends

1. JIRA/Atlassian Service Desk

Full-featured integration with:

• Service Desk project support
• Request type management
• Customer portal integration
• Webhook support for real-time updates
• Custom field mapping with one-way resource synchronization (Service Desk → Waldur)

Authentication Methods:

Supports multiple authentication methods with automatic fallback:

1. OAuth 2.0 (Recommended for Enterprise)

ATLASSIAN_OAUTH2_CLIENT_ID=your_client_id
ATLASSIAN_OAUTH2_ACCESS_TOKEN=your_access_token
ATLASSIAN_OAUTH2_TOKEN_TYPE=Bearer  # Optional, defaults to Bearer

1. Personal Access Token (Server/Data Center)

ATLASSIAN_PERSONAL_ACCESS_TOKEN=your_personal_access_token

1. API Token (Cloud - Recommended)

ATLASSIAN_USERNAME=user@example.com
ATLASSIAN_TOKEN=your_api_token

1. Basic Authentication (Legacy)

ATLASSIAN_USERNAME=username
ATLASSIAN_PASSWORD=password

Authentication Priority Order: OAuth 2.0 > Personal Access Token > API Token > Basic Authentication

Security Recommendations:

• Use OAuth 2.0 for enterprise integrations with fine-grained permissions
• Use API Tokens for Atlassian Cloud instances
• Use Personal Access Tokens for Server/Data Center instances
• Avoid Basic Authentication in production environments

OAuth 2.0 Setup:

1. Create an OAuth 2.0 app in your Atlassian organization
2. Obtain client_id and access_token from the OAuth flow
3. Configure the credentials in your environment variables
4. The system will automatically use OAuth 2.0 when configured

Custom Field Mapping:

Waldur supports custom field mapping with Atlassian Service Desk for enhanced integration capabilities:

# Enable custom field mapping
ATLASSIAN_CUSTOM_ISSUE_FIELD_MAPPING_ENABLED = True

# Standard custom field mappings
ATLASSIAN_IMPACT_FIELD = "Impact"
ATLASSIAN_ORGANISATION_FIELD = "Reporter organization"
ATLASSIAN_PROJECT_FIELD = "Waldur Project"
ATLASSIAN_AFFECTED_RESOURCE_FIELD = "Affected Resource"
ATLASSIAN_REPORTER_FIELD = "Original Reporter"
ATLASSIAN_CALLER_FIELD = "Request participants"
ATLASSIAN_TEMPLATE_FIELD = "Issue Template"

Resource Backend ID Synchronization:

The system automatically synchronizes resource backend IDs using the waldur_backend_id custom field:

1. Jira Setup: Create a custom field named waldur_backend_id (text field, single line)
2. Field Mapping: The system automatically detects field ID customfield_10200 or uses field lookup
3. Service Desk → Waldur Sync:
4. Issue synchronization reads waldur_backend_id custom field and updates connected resource's backend_id
5. External systems can update Waldur resources by modifying the custom field in Service Desk tickets

Use Cases:

• External systems can update Waldur resource identifiers via Service Desk
• Cross-platform resource synchronization through helpdesk integration
• Automated data consistency maintenance across integrated systems
• Third-party tool integration via Service Desk custom field updates

Configuration Example:

# Enable custom field integration
ATLASSIAN_CUSTOM_ISSUE_FIELD_MAPPING_ENABLED = True

# The system will automatically:
# 1. Read waldur_backend_id custom field during issue synchronization
# 2. Update connected resource's backend_id with the custom field value
# 3. Enable external systems to update Waldur resources via Service Desk

2. Micro Focus SMAX

Enterprise ITSM integration:

• Request and incident management
• Change management workflows
• Service catalog integration
• REST API-based synchronization
• Webhook support for real-time updates

3. Zammad

Open-source ticketing system:

• Multi-channel support (email, web, phone)
• Customer organization management
• Tag-based categorization
• Webhook integration

4. Basic Backend

No-op implementation for:

• Development and testing
• Environments without external ticketing
• Minimal support requirements

Backend Interface

All backends implement the SupportBackend interface:

class SupportBackend:
    # Issue operations
    def create_issue(issue: Issue) -> Issue
    def update_issue(issue: Issue) -> Issue
    def delete_issue(issue: Issue)
    def sync_issues(issue_id: Optional[str])

    # Comment operations
    def create_comment(comment: Comment) -> Comment
    def update_comment(comment: Comment) -> Comment
    def delete_comment(comment: Comment)

    # Attachment operations
    def create_attachment(attachment: Attachment) -> Attachment
    def delete_attachment(attachment: Attachment)

    # User management
    def pull_support_users()
    def get_or_create_support_user(backend_user) -> SupportUser

    # Configuration
    def pull_priorities()
    def pull_request_types()

API Endpoints

Issue Management

Endpoint	Method	Description
/api/support-issues/	GET	List issues with filtering
/api/support-issues/	POST	Create new issue
/api/support-issues/{uuid}/	GET	Retrieve issue details
/api/support-issues/{uuid}/	PATCH	Update issue
/api/support-issues/{uuid}/	DELETE	Delete issue
/api/support-issues/{uuid}/comment/	POST	Add comment to issue
/api/support-issues/{uuid}/sync/	POST	Sync issue with backend

Comments

Endpoint	Method	Description
/api/support-comments/	GET	List comments
/api/support-comments/{uuid}/	GET	Retrieve comment
/api/support-comments/{uuid}/	PATCH	Update comment
/api/support-comments/{uuid}/	DELETE	Delete comment

Attachments

Endpoint	Method	Description
/api/support-attachments/	GET	List attachments
/api/support-attachments/	POST	Upload attachment
/api/support-attachments/{uuid}/	GET	Download attachment
/api/support-attachments/{uuid}/	DELETE	Delete attachment

Configuration & Management

Endpoint	Method	Description
/api/support-users/	GET	List support users
/api/support-priorities/	GET	List priorities
/api/support-templates/	GET/POST	Manage templates
/api/support-feedback/	GET/POST	Manage feedback
/api/support-issue-statuses/	GET/POST	Manage issue statuses (staff only)
/api/support-issue-statuses/{uuid}/	GET/PATCH/DELETE	Issue status details (staff only)

Webhooks

Endpoint	Method	Description
/api/support-jira-webhook/	POST	JIRA webhook receiver
/api/support-smax-webhook/	POST	SMAX webhook receiver
/api/support-zammad-webhook/	POST	Zammad webhook receiver

Reports

Endpoint	Method	Description
/api/support-statistics/	GET	Dashboard statistics
/api/support-feedback-report/	GET	Feedback summary
/api/support-feedback-average-report/	GET	Average ratings

Permissions

Permission Model

The support module uses Waldur's standard permission system with additional paths:

# Issue permissions follow customer/project hierarchy
permission_paths = [
    'customer',
    'project',
    'project.customer',
]

# Role-based access
- Customer Owner: Full access to customer issues
- Project Admin: Full access to project issues
- Project Manager: Read/comment on project issues
- Staff/Support: Full system access

Filtering

Advanced filtering capabilities:

• Customer/project-based filtering
• Resource-based filtering (VMs, networks)
• IP address lookup for resource issues
• Full-text search across summary/description
• Status, priority, and type filtering

Configuration

Django Settings

# Disable email notifications
WALDUR_SUPPORT['SUPPRESS_NOTIFICATION_EMAILS'] = True

# Enable feedback collection
WALDUR_SUPPORT['ISSUE_FEEDBACK_ENABLE'] = True

# Feedback token validity (days)
WALDUR_SUPPORT['ISSUE_FEEDBACK_TOKEN_PERIOD'] = 7

Constance Settings

Dynamic configuration via admin:

# Enable/disable support module
WALDUR_SUPPORT_ENABLED = True

# Select active backend
WALDUR_SUPPORT_ACTIVE_BACKEND_TYPE = 'atlassian'  # or 'zammad', 'smax', 'basic'

# Enable custom field mapping for enhanced integration
ATLASSIAN_CUSTOM_ISSUE_FIELD_MAPPING_ENABLED = True

# Configure custom field mappings
ATLASSIAN_IMPACT_FIELD = "Impact"
ATLASSIAN_ORGANISATION_FIELD = "Reporter organization"
ATLASSIAN_PROJECT_FIELD = "Waldur Project"
ATLASSIAN_AFFECTED_RESOURCE_FIELD = "Affected Resource"
ATLASSIAN_REPORTER_FIELD = "Original Reporter"
ATLASSIAN_TEMPLATE_FIELD = "Issue Template"

Backend Configuration

JIRA Configuration

WALDUR_SUPPORT['BACKEND'] = {
    'backend': 'waldur_mastermind.support.backend.atlassian.ServiceDeskBackend',
    'server': 'https://jira.example.com',
    'username': 'waldur-bot',
    'password': 'secret',
    'project_key': 'SUPPORT',
    'verify_ssl': True,
}

SMAX Configuration

WALDUR_SUPPORT['BACKEND'] = {
    'backend': 'waldur_mastermind.support.backend.smax.SmaxBackend',
    'api_url': 'https://smax.example.com/rest',
    'tenant_id': '12345',
    'user': 'integration-user',
    'password': 'secret',
}

Zammad Configuration

WALDUR_SUPPORT['BACKEND'] = {
    'backend': 'waldur_mastermind.support.backend.zammad.ZammadBackend',
    'api_url': 'https://zammad.example.com/api/v1',
    'token': 'api-token',
    'group': 'Support',
}

Workflows

Issue Creation Flow

sequenceDiagram
    participant User
    participant API
    participant Models
    participant Backend
    participant External

    User->>API: POST /support-issues/
    API->>Models: Create Issue
    Models->>Backend: create_issue()
    Backend->>External: Create ticket
    External-->>Backend: Ticket ID
    Backend-->>Models: Update backend_id
    Models-->>API: Issue created
    API-->>User: 201 Created

Synchronization Flow

sequenceDiagram
    participant Scheduler
    participant Backend
    participant External
    participant Models

    Scheduler->>Backend: sync_issues()
    Backend->>External: Fetch updates
    External-->>Backend: Issue data
    Backend->>Models: Update issues

    Note over Backend,Models: Update status, comments, attachments

    Backend->>Models: Process callbacks
    Note over Models: Trigger marketplace callbacks if needed

Webhook Flow

sequenceDiagram
    participant External
    participant Webhook
    participant Models
    participant Callbacks

    External->>Webhook: POST /support-*-webhook/
    Webhook->>Webhook: Validate signature
    Webhook->>Models: Update issue/comment

    alt Status changed
        Models->>Callbacks: Trigger callbacks
        Note over Callbacks: Resource state updates
    end

    Webhook-->>External: 200 OK

Celery Tasks

Scheduled background tasks:

Task	Schedule	Description
pull-support-users	Every 6 hours	Sync support users from backend
pull-priorities	Daily at 1 AM	Update priority levels
sync_request_types	Daily at 1 AM	Sync JIRA request types
sync-issues	Configurable	Full issue synchronization

Best Practices

1. Backend Selection

• Use JIRA for enterprise environments with existing Atlassian infrastructure
• Use SMAX for ITIL-compliant service management
• Use Zammad for open-source, multi-channel support
• Use Basic for development or minimal requirements

2. Status Configuration

• Map all backend statuses: Create IssueStatus entries for every status that your backend can return
• Define clear RESOLVED vs CANCELED mappings:
• RESOLVED (type=0): Statuses indicating successful completion
• CANCELED (type=1): Statuses indicating cancellation or failure
• Use descriptive names: Match the exact status names from your backend system
• Test status transitions: Verify resolution detection works correctly before production
• Staff-only management: Only staff users can create/modify status configurations
• Regular monitoring: Review status configurations when backend workflows change

3. Performance Optimization

• Enable webhooks for real-time updates
• Configure appropriate sync intervals
• Use pagination for large issue lists
• Implement caching for frequently accessed data

4. Security

• Use secure webhook endpoints with signature validation
• Implement proper permission checks
• Sanitize user input in comments/descriptions
• Use HTTPS for all backend connections

5. Custom Field Integration

• Enable custom field mapping: Set ATLASSIAN_CUSTOM_ISSUE_FIELD_MAPPING_ENABLED = True for enhanced integration
• Create required custom fields: Ensure waldur_backend_id custom field exists in Jira/Service Desk
• Test field permissions: Verify API user can read/write custom fields
• Monitor field updates: Log resource backend_id changes for audit trails
• Validate field values: Ensure custom field values are appropriate for resource backend IDs
• Document field usage: Maintain clear documentation of custom field purposes and expected values

6. Monitoring

• Monitor sync task execution
• Track webhook delivery failures
• Log backend API errors
• Set up alerts for SLA breaches
• Monitor custom field mapping operations
• Track resource backend_id updates via logs

Troubleshooting

Common Issues

1. Issues Not Syncing

• Check backend connectivity
• Verify API credentials
• Review sync task logs
• Ensure webhook configuration

2. Missing Status Updates

• Verify IssueStatus configuration
• Check webhook signature validation
• Review backend field mappings
• Monitor sync intervals

3. Permission Errors

• Verify user roles and permissions
• Check customer/project associations
• Review permission paths configuration
• Validate backend user permissions

4. Attachment Upload Failures

• Check file size limits
• Verify MIME type restrictions
• Review storage permissions
• Monitor backend API limits

5. Custom Field Mapping Issues

• Field Not Found: Verify waldur_backend_id custom field exists in Jira (should be customfield_10200)
• Mapping Disabled: Ensure ATLASSIAN_CUSTOM_ISSUE_FIELD_MAPPING_ENABLED = True
• Resource Not Updated: Check if issue is properly connected to resource via resource_content_type and resource_object_id
• Permission Errors: Verify Jira user has permission to read/write custom fields
• Field Name Mismatch: Ensure custom field name matches exactly waldur_backend_id
• API Errors: Check Jira REST API logs for custom field access issues

Debugging Custom Field Integration:

# Check if custom field exists
from waldur_mastermind.support.backend.atlassian import ServiceDeskBackend
backend = ServiceDeskBackend()

# Test field lookup
try:
    field_id = backend.get_field_id_by_name("waldur_backend_id")
    print(f"Found field ID: {field_id}")
except Exception as e:
    print(f"Field lookup failed: {e}")

# Test direct field access
issue_data = backend.get("/rest/api/2/issue/YOUR-TICKET-KEY")
waldur_field_value = issue_data["fields"].get("customfield_10200")
print(f"Custom field value: {waldur_field_value}")

Integration with Marketplace

The support module integrates with the marketplace for ticket-based offerings:

1. Orders create support issues automatically
2. Issue status changes trigger order callbacks
3. Resolution status determines order success/failure
4. Comments and attachments sync bidirectionally
5. Resource backend_id synchronization: Custom field mapping enables automatic resource identifier updates

Enhanced Marketplace Integration Features:

• Support.OfferingTemplate Integration: Marketplace orders for support offerings automatically create connected support issues
• One-way Resource Sync: Service Desk custom field updates can automatically update connected marketplace resource backend IDs
• Cross-System Data Flow: External systems can update Waldur resources via Service Desk custom field modifications
• Automated Identifier Management: Maintains consistent resource identifiers across integrated platforms

See Ticket-Based Offerings Documentation for detailed marketplace integration.

Extension Points

The support module provides several extension points:

1. Custom Backends: Implement SupportBackend interface
2. Template Processors: Custom template variable processing
3. Notification Handlers: Custom email/notification logic
4. Webhook Processors: Custom webhook payload processing
5. Feedback Collectors: Alternative feedback mechanisms

Multi-Tenant Provider Helpdesk

The support module includes a multi-tenant provider helpdesk system that enables service providers to register their own helpdesk backends. Tickets are automatically routed to the correct provider, with bidirectional comment forwarding between operator and provider via parent/child issue pairs.

Key capabilities:

• Per-provider helpdesk backends (Atlassian, Zammad, SMAX, Basic, Email)
• Automatic ticket routing based on resource/offering/provider chain
• SLA management with configurable deadlines and breach detection
• Auto-assignment with least-loaded and round-robin strategies
• Escalation workflow with provider notifications
• Provider team management and canned responses

See Provider Helpdesk Documentation for details.

Appendix

Database Schema

Key database tables:

• support_issue - Issue records
• support_comment - Issue comments
• support_attachment - File attachments
• support_supportuser - Backend user mapping
• support_priority - Priority levels
• support_issuestatus - Status configuration (with UUID support)
• support_template - Issue templates
• support_feedback - Customer feedback

API Filters

Available query parameters:

?customer=<uuid>           # Filter by customer
?project=<uuid>            # Filter by project
?status=<status>           # Filter by status
?priority=<uuid>           # Filter by priority
?type=<type>               # Filter by issue type
?caller=<uuid>             # Filter by caller
?assignee=<uuid>           # Filter by assignee
?created_after=<date>      # Created after date
?created_before=<date>     # Created before date
?search=<text>             # Full-text search
?resource=<uuid>           # Filter by resource
?o=<field>                 # Order by field

Error Codes

Common error responses:

Code	Description
400	Invalid request data
401	Authentication required
403	Permission denied
404	Issue/resource not found
409	Conflict (duplicate, state issue)
424	Backend dependency failed
500	Internal server error