Web-Services

Wie in der Feature-Liste erwähnt, werden Grundkenntnisse über OTRS und SolMan Webservices vorausgesetzt.

Ein Beispiel-Webservice wird mit dem Paket in doc/SolManConnectorExample.yml bereitgestellt. Es könnte eine gute Idee sein, diesen Webservice als Duplikat auf Ihrem System als Referenz installiert (aber deaktiviert) zu behalten.

Notwendige und empfohlene Änderungen für jeden Webservice-Teil siehe Abschnitte unten. Modifikationen beziehen sich auf das mitgelieferte Beispiel.

Requester-Transport

Stellen Sie sicher, dass Sie den Transport HTTP::SOAPSolMan verwenden. Dies ist für die korrekte Namespace-Generierung notwendig.

Stellen Sie den Endpunkt (URI) Ihrer SolMan-Instanz ein und legen Sie ggf. Authentifizierungs-, Proxy- und SSL-Optionen fest.

Die SOAPAction-Optionen, der Namespace und das Namensschema sollten nicht verändert werden.

Requester Invokers

Dieses Paket enthält drei verschiedene Invoker-Controller, die Funktionalität für alle unterstützten Funktionsaufrufe bieten.

  • Der Controller SolMan::IncidentCreate übernimmt die initiale Übergabe eines Tickets an SolMan (z.B. ProcessIncident, ReplicateIncident).

  • Der Controller SolMan::IncidentUpdate kümmert sich um die Folgeübertragungen eines Tickets an SolMan (z.B. AcceptIncidentProcessing, AddInfo, CloseIncident, RejectIncidentSolution, VerifyIncidentSolution).

  • Der Controller SolMan::RequestSystemGuid wird verwendet, um System-GUID-Informationen von SolMan anzufordern.

Es ist wichtig, zwischen IncidentCreate und IncidentUpdate Controllern zu unterscheiden. Ansonsten machen die Invoker-Namen handhabungstechnisch in OTRS keinen Unterschied (außer CloseIncident, der abbricht, wenn Sie versuchen, ein bereits geschlossenes Ticket zu aktualisieren).

Wenn für ein Ticket ohne vorherige Synchronisierungsaktivität ein Aufruf vom Typ „Update“ ausgelöst wird, wird automatisch ein Aufruf vom Typ „Create“ ausgelöst (ProcessIncident, falls vorhanden oder alternativ ReplicateIncident).

Der Invoker zur Abfrage der SolMan-System-GUID wird automatisch ausgelöst, wenn diese Information im OTRS nicht bekannt ist.

Jeder reguläre Invoker überträgt alle vorhandenen Artikel, die nicht bis zu diesem Punkt übertragen wurden.

Standardmäßig wird der AddInfo-Invoker für jeden in OTRS angelegten Artikel über einen Event-Trigger ausgelöst. Es wird dringend empfohlen, für alle relevanten Invoker Event-Trigger zu konfigurieren (z.B. für Status- und Prioritätsänderungen) und diese über Event-Bedingungen einzuschränken (z.B. auf Tickets in bestimmten Queues).

Requester Mapping

Das Mapping zwischen OTRS und SolMan erfolgt in OTRS über eine XSLT-Konfiguration.

Die mitgelieferte Konfiguration enthält funktionierende XSLT-Vorlagen. Für Standardanforderungen ist es nur notwendig, die Ausgangs-Mapping-Vorlage anzupassen in Bezug auf:

  • OTRS-Dateipfad für XSL-Helper-Templates

  • OTRS → SolMan-Status-Mapping

  • OTRS → SolMan Prioritäts-Mapping

  • Dynamische Feldauswahl und Namenszuordnung

  • OTRS → SolMan-Artikeltyp-Zuordnung

Die Vorlagen müssen individuell pro Invoker angepasst werden, sind aber (standardmäßig) für alle regulären Invoker identisch.

Die von den Invokern bereitgestellte Datenstruktur ähnelt der Struktur des OTRS-Ticket-Connectors, jedoch mit einigen Änderungen und zusätzlichen Daten. Dies ist eine Kurzreferenz:

<Customer>
    <*> customer attributes, e.g. 'UserEmail' </*>
</Customer>
<Owner>
    <*> owner (agent) attributes, e.g. 'UserEmail' </*>
</Owner>
<SolMan>
    <IncidentId> incident id </IncidentId>
    <IncidentGuid> incident guid </IncidentGuid>
    <LocalSystemGuid> OTRS system guid </LocalSystemGuid>
    <RemoteSystemGuid> SolMan system guid </RemoteSystemGuid>
</SolMan>
<Ticket>
    <Article> # can occur 0-n times
        <Attachment> # can occur 0-n times
            <*> attachment attributes, e.g. 'Filename' </*> # 'Content' is base64-encoded automatically
        </Attachment>
        <DynamicField> # can occur 0-n times
            <Name> dynamic field name </Name>
            <Value> dynamic field value(s) </Value>
        </DynamicField>
        <*> article attributes, e.g. 'From' </*>
    </Article>
    <DynamicField> # can occur 0-n times
        <Name> ticket dynamic field name </Name>
        <Value> ticket dynamic field value(s) </Value>
    </DynamicField>
    <*> ticket attributes, e.g. 'TicketNumber' </*>
</Ticket>

Die voreingestellten XSLT-Vorlagentypen werden als einzelne Dateien zur Referenz bereitgestellt (siehe doc/ExampleMapping-Invoker-*.xsl, die vom Paket bereitgestellt werden).

Requester Error Handling

Einige Fehlerbehandlungsmodule sind vorkonfiguriert und werden verwendet, um Anforderungen neu zu planen, wenn ein bestimmtes Problem auftritt. Umgeplante Anforderungen werden in Intervallen von 1 Minute für bis zu 5 Versuche ausgeführt.

Standardmäßig führen alle Transportfehler zu einer Neuplanung sowie eine Datenaufbereitung, bei der die SolMan-System-GUID nicht abgerufen werden konnte.

Außerdem werden die Anforderungen neu geplant, wenn der SolMan einen Fehlercode zurückgibt, außer wenn dieser Code 01, 02, 03 oder 04 ist.

Es wird empfohlen, die Wiederholungsoptionen an Ihre Bedürfnisse anzupassen und zu prüfen, ob die fehlercodespezifische Behandlung Ihren Anforderungen entspricht.

Provider-Transport

Um Verwechslungen zu vermeiden, sollten Sie den Transport HTTP::SOAPSolMan verwenden. Im Gegensatz zum Requester ist dies nicht unbedingt notwendig.

Ändern Sie die Länge der Nachricht, falls erforderlich.

Die SOAPAction-Optionen, der Namespace und das Namensschema sollten nicht verändert werden.

Provider-Operationen

Dieses Paket enthält drei verschiedene Betriebssteuerungen, die Funktionalität für alle unterstützten Funktionsaufrufe bieten.

  • Der Controller SolMan::IncidentCreate übernimmt die initiale Übertragung eines Tickets von SolMan (z.B. ProcessIncident, ReplicateIncident).

  • Der Controller SolMan::IncidentUpdate kümmert sich um die Folgeübertragungen eines Tickets an SolMan (z.B. AcceptIncidentProcessing, AddInfo, CloseIncident, RejectIncidentSolution, VerifyIncidentSolution).

  • Der Controller SolMan::RequestSystemGuid wird verwendet, um System-GUID-Informationen von SolMan anzufordern.

Es ist wichtig, zwischen IncidentCreate und IncidentUpdate Controllern zu unterscheiden. Ansonsten machen die Invoker-Namen handhabungstechnisch in OTRS keinen Unterschied.

Wenn ein Ticket ausstehende Aktualisierungen hat, die von OTRS zum SolMan übertragen werden müssen (z. B. neue Artikel), werden Aktualisierungen aus dem SolMan vorübergehend blockiert.

Aufgrund der Natur des SolMan können die gesendeten Anhänge nicht mehr als einem Artikel zugeordnet werden. Artikel, die innerhalb einer Anfrage gesendet werden, werden automatisch an den letzten Artikel angehängt, der innerhalb dieser Anfrage erstellt wurde. Wenn die Anfrage keinen Artikel enthält, wird ein Dummy-Artikel für die Anhänge angelegt.

Provider Mapping

Das Mapping zwischen OTRS und SolMan erfolgt in OTRS über eine XSLT-Konfiguration.

Die mitgelieferte Konfiguration enthält funktionierende XSLT-Vorlagen. Für Standardanforderungen ist es nur notwendig, die Ausgangs-Mapping-Vorlage anzupassen in Bezug auf:

  • OTRS-Dateipfad für XSL-Helper-Templates

  • OTRS-Ziel-Queue

  • SolMan → OTRS-Status-Mapping

  • SolMan → OTRS Prioritäts-Mapping

  • Dynamische Feldauswahl und Namenszuordnung

  • SolMan → OTRS-Artikel-Typen-Mapping

Die Vorlagen müssen pro Operation individuell angepasst werden, sind aber (standardmäßig) für alle regulären Operationen identisch.

Die Datenstruktur, die von den Operationen erwartet wird, ähnelt der Struktur des OTRS-Ticket-Connectors, jedoch mit einigen Änderungen und zusätzlichen Daten. Dies ist eine Kurzreferenz:

<Attachment> # can occur 0-n times
    <*> attachment attributes, e.g. 'Filename' </*> # 'Content' is base64-decoded automatically
</Attachment>
<Ticket>
    <Article> # can occur 0-n times
        <*> article attributes, e.g. 'From' </*>
    </Article>
    <DynamicField> # can occur 0-n times
        <Name> ticket dynamic field name </Name>
        <Value> ticket dynamic field value(s) </Value>
    </DynamicField>
    <*> ticket attributes, e.g. 'TicketNumber' </*>
</Ticket>
<SolMan>
    <IncidentGuid> incident guid </IncidentGuid>
    <LocalSystemGuid> OTRS system guid </LocalSystemGuid>
    <RemoteSystemGuid> SolMan system guid </RemoteSystemGuid>
    <Person> # can occur 0-n times
        <Meta>
            <ID> OTRS id of agent / or login of customer user </ID>
            <ExternalID> SolMan id of person </ExternalID>
            <Type> CustomerUser, Owner or Agent </Type>
        </Meta>
        <*> agent or customer user attributes, e.g. 'UserEmail' </*>
    </Person>
</SolMan>

Die voreingestellten XSLT-Vorlagentypen werden als einzelne Dateien zur Referenz bereitgestellt (siehe doc/ExampleMapping-Operation-*.xsl, die vom Paket bereitgestellt werden).

Nach oben scrollen