Ticket System Integration

Integration of external ticketing platforms with Open Ticket AI using the TicketSystemService base class.

Ticket System Integration

Die Basisklasse TicketSystemService definiert einen minimalen Kontrakt für Adapter, die externe Ticketplattformen mit Open Ticket AI integrieren. Die Klasse stellt benannte Coroutine-Methoden bereit, die immer UnifiedTicket-Daten zurückgeben, während sie flexible Keyword-Argumente für plattformspezifisches Verhalten akzeptieren.

Flexible Adapter-Kontrakte

Adapter müssen Implementierungen für diese Methoden bereitstellen:

• find_tickets
• find_first_ticket
• get_ticket
• create_ticket
• update_ticket
• add_note

Jede Methode kann Keyword-Argumente (**kwargs) akzeptieren, die aus der YAML-Konfiguration generiert werden. Dies ermöglicht jedem Adapter, die Argumentformen zu exponieren, die das unterstützende SDK erwartet, ohne sie zunächst in ein starres Schema zu pressen. Methoden können weiterhin Hilfsmodelle wie UnifiedTicket akzeptieren, aber Adapter sind dafür verantwortlich, ihre native Modelle zurück in UnifiedTicket zu konvertieren, bevor sie Ergebnisse zurückgeben.

Wann Unified Models verwendet werden sollten

Unified Models bleiben verfügbar für Teams, die einen normalisierten Payload wollen. Jeder Adapter kann Konverter-Helfer exponieren (zum Beispiel otai_otobo_znuny.models.otobo_ticket_to_unified_ticket) um die Übersetzung von nativen Ticketrepräsentationen in das Unified Schema zu zentralisieren. Adapter können die gleichen Helfer intern verwenden, und Aufrufer können sie wiederverwenden, wenn sie mit nativen Modellen arbeiten, die direkt vom upstream SDK abgerufen wurden.

YAML-Beispiele

services:
  - id: 'otobo'
    use: 'otobo-znuny:OTOBOZnunyTicketSystemService'
    params:
      webservice_name: 'GenericTicketConnector'
      base_url: 'https://helpdesk.example.com'
      username: 'agent'
      password: '${{ secrets.OTOBO_PASSWORD }}'

pipes:
  - id: 'fetch-isOpen'
    use: 'otai_base:pipes.ticket_system_pipes.FetchTicketsPipe'
    params:
      ticket_search_criteria:
        queue:
          id: '5'
        limit: 20

  - id: 'create'
    use: 'my_plugin:CreateTicketPipe'
    params:
      ticket_payload:
        subject: '{{ context.subject }}'
        body: '{{ context.body }}'

Die oben gezeigten YAML-Snippets werden in Keyword-Argumente umgewandelt, die direkt in Adapter-Methoden übergeben werden. Sie können auch in Unified Models in Custom Pipes konvertiert werden, wenn der Workflow normalisierte Daten erwartet.

Migration bestehender Adapter

1. Entfernen Sie @abstractmethod-Implementierungen und erzwingen Sie nur die Methodennamen, die auf TicketSystemService definiert sind.
2. Akzeptieren Sie Keyword-Argumente (zum Beispiel async def create_ticket(self, **kwargs)) oder behalten Sie optionale Unified Models, wenn sie Konvertierungen vereinfachen.
3. Konvertieren Sie native SDK-Antworten in UnifiedTicket-Instanzen, bevor Sie sie von find_tickets, find_first_ticket, get_ticket und create_ticket zurückgeben.
4. Bieten Sie Hilfsfunktionen für Konsumenten an, die direkt mit nativen Ticketobjekten arbeiten müssen.

Adapter, die mit diesen Richtlinien gebaut werden, bleiben kompatibel mit bestehenden Pipelines, während sie die Flexibilität erhalten, um reichhaltige plattformspezifische Features zu exponieren.