Syteca API Bridge

Spis treści

1. Czym jest API Bridge?
2. Interfejs REST
   
3. Jak korzystać z API Bridge
4. Jak skonfigurować API Bridge w Konsoli Zarządzania

1. Czym jest API Bridge?

Funkcja integracji z systemami zgłoszeniowymi w Syteca umożliwia wymuszanie podania numeru zgłoszenia przez użytkownika przy logowaniu do komputera z agentem monitorowania. Więcej informacji znajdziesz w sekcji Integracja z systemami zgłoszeniowymi.

Problemem, który należało rozwiązać, było następujące ograniczenie: ogólna koncepcja polegała na tworzeniu adaptera dla każdego nowego systemu zgłoszeniowego, co jest trudne w utrzymaniu ze względu na różnorodność API i konieczność wprowadzania zmian w produkcie przy każdej nowej integracji.

Wszystkie komponenty integrujące działały wewnątrz produktu, co powodowało, że każda zmiana API, czy nowy system zgłoszeniowy, wymagały wydania nowej wersji produktu. Dodatkowo niektóre systemy mają niestandardowe lub zmienne API, co utrudnia ich implementację.

Rozwiązaniem tych problemów jest API Bridge — komponent zaprojektowany z myślą o elastycznej integracji.

Główna idea polega na zdefiniowaniu oczekiwanego interfejsu oraz dostarczeniu prostej usługi, która ten interfejs implementuje. Udostępniamy kod źródłowy tej usługi, aby każdy mógł ją dostosować do dowolnego systemu zgłoszeniowego — czy to znanego (np. SysAid, ServiceNow), czy własnego.

Nie ma potrzeby wydawania nowej wersji Syteca — wystarczy dostosować API Bridge do nowego systemu. Nie zależy nam od konkretnego języka czy kodu — wystarczy, że interfejs REST będzie zgodny.

API Bridge to usługa REST, którą uruchamiasz jako zewnętrzną usługę. Powinna ona implementować określony interfejs REST. Tak długo jak to wymaganie jest spełnione, możesz modyfikować API Bridge według własnych potrzeb.

2. Interfejs REST

Poniżej przedstawiono wymagany interfejs REST w formacie OpenAPI:

openapi: 3.0.0
info:
  version: "0"
  title: "Syteca Ticketing System Integration API Bridge"
paths:
  /connect:
    post:
      summary: Żądanie sessionID.
      tags: [bridge]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                connectionString:
                  type: string
      responses:
        '200':
          description: Obiekt JSON zawierający ID zgłoszenia i status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
        '422': { description: Błędny connection string. }
        default: { description: Nieoczekiwany błąd. }

  /ticket-status:
    get:
      summary: Sprawdzenie statusu zgłoszenia.
      description: Weryfikuje, czy zgłoszenie istnieje i nie jest zamknięte.
      tags: [bridge]
      parameters:
        - name: sessionId
          in: query
          required: true
          schema: { type: string }
        - name: ticketId
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Obiekt JSON zawierający ID zgłoszenia i status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticketId: { type: string }
                  status: { type: number }
        '401': { description: Nieautoryzowane (nieważna sesja). }
        '404': { description: Nie znaleziono zgłoszenia. }
        default: { description: Nieoczekiwany błąd. }

  /add-ticket-comment:
    post:
      summary: Dodanie komentarza do zgłoszenia.
      description: Dodaje komentarz z linkiem do miejsca w wynikach monitorowania w Konsoli Zarządzania.
      tags: [bridge]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sessionId, ticketId, ticketComment]
              properties:
                sessionId: { type: string }
                ticketId: { type: string }
                ticketComment: { type: string }
      responses:
        '201': { description: OK. }
        '401': { description: Nieautoryzowane (nieważna sesja). }
        '404': { description: Nie znaleziono zgłoszenia. }
        default: { description: Nieoczekiwany błąd. 

Np. /connect oznacza, że jeśli usługa działa pod adresem http://127.0.0.1/, to pod http://127.0.0.1/connect musi być możliwość wysyłania żądań POST.

3. Jak korzystać z API Bridge

Możesz zaimplementować usługę samodzielnie, w dowolnym języku dostosowanym do swojej infrastruktury.

Dostępna jest darmowa usługa Swagger (https://swagger.io/), która na podstawie specyfikacji OpenAPI generuje prostą usługę w wybranym języku.

Dostarczamy przykład usługi napisanej w ASP.NET Core. Możesz:

• skompilować ją ze źródeł,

• lub uruchomić gotowy plik wykonywalny.

Do testowania udostępniamy plik .json z przykładowym zestawem zgłoszeń — należy umieścić go w katalogu wwwroot.

Plik JSON znajduje się w archiwum z kodem źródłowym.

Aby uruchomić usługę testową:

• Rozpakuj archiwum APIBridgePackage.

• Przenieś plik .json do folderu wwwroot.

• Edytuj plik JSON (np. w Notatniku):

  • W sekcji Sessions zdefiniuj dane logowania do systemu zgłoszeniowego.

  • W sekcji Tickets podaj nazwę zgłoszenia, które użytkownik musi wpisać przy logowaniu.

• W folderze APIBridgeSampleBinaries uruchom IO.Swagger.

• W oknie konsoli podaj numer portu, który będzie używany do komunikacji z Syteca i systemem zgłoszeniowym, a następnie naciśnij Enter.

• Adres URL usługi zgłoszeniowej zostanie wyświetlony w konsoli.

4. Jak skonfigurować API Bridge w Konsoli Zarządzania

Aby dowiedzieć się, jak skonfigurować dane uwierzytelniające w Konsoli Zarządzania, zapoznaj się z sekcją Definiowanie ustawień integracji z systemem zgłoszeniowym.