• Stammdatenabgleich
• Serviceauftragserstellung aus dem Zammad-Ticket-System

• Abgleich von Firmen und Ansprechpartnern
• Firmen werden in Zammad als „Organization“ angelegt
• Ansprechpartner werden in Zammad als User angelegt.
• Führendes System ist Concept Office, sprich Änderungen der Stammdaten in Zammad führen zu keiner Änderung in Concept Office. Beim nächsten Abgleich der Systeme werden alle Änderungen die ausschließlich in Zammad erfolgten, verworfen.

Übertragen werden die folgenden drei Kategorien:

1. Alle Datenbankfelder in der Tabelle „Kontakte“.
2. Default-Felder in Zammad:
   1. „Zammad.Organisations.Name“ (Der Langname der Firma)
   2. „Zammad.Organisations.DomainAssignment“ (Konfigurierbar über Schema-Schalter)
   3. „Zammad.Organisations.Note“ (Der Kontakthinweistext als)
3. Zusätzlich können individuelle Felder über selbst erstellte Recherchen übertragen werden. (Mehr zum Thema selbst erstellte Recherchefelder im Kapitel Recherchefelder).

Übertragen werden die Folgenden drei Kategorien:

1. Alle Datenbankfelder in der Tabelle „Ansprechpartner“.
2. Default-Felder in Zammad:
   1. „Firstname“, „Lastname“, „Email“, „Organization“, „Roles“
3. Zusätzlich können individuelle Felder über selbst erstellte Recherchen übertragen werden. (Mehr zum Thema selbst erstellte Recherchefelder im Kapitel Recherchefelder).

Mithilfe von Recherchen können weitere Datenfelder an Zammad übertragen und synchronisiert werden.

Ablauf am Beispiel des Feldes „street“ am „user“

1. In Zammad über Einstellungen –> Objects –> User ein neues Objekt mit dem entsprechenden Namen anlegen.
2. In CO eine Recherche anlegen, die das gewünschte Ergebnis bringt.

Beispiel:

declare @pk as int

SELECT Anschriften.Strasse FROM Ansprechpartner
LEFT JOIN Anschriften ON AnsprechPartner.Mandant = Anschriften.Mandant AND
AnsprechPartner.KontaktNummer = Anschriften.KontaktNummer WHERE
Anschriften.AnschriftsNummer = AnsprechPartner.Anschriftsnummer AND 
AnsprechPartner.AnsprechpartnerNummer = @pk

1. Zu Beachten ist das declare @pk as int. Dieses bezieht sich je nach Kontext entweder auf die Ansprechpartner-Nummer oder aber auf die Firmen-Nummer.

1. In der coMsgQueueServer.ini muss ein Verweis auf das Schema hinterlegt werden, welches die Definitionen für die Recherchefelder beinhaltet. Mehr dazu im Kaptiel coMsgQueueServer.ini

Der CO-Webservice bietet zwei dedizierte Schnittstellen für das Zammad-Ticket System.

1. /Office/CoServiceRestApi/office/zammad/serviceauftrag
2. /Office/CoServiceRestApi/office/zammad/taetigkeit

Der erste Endpunkt dient der Auftragsanlage, während der Zweite Tätigkeitspositionen anlegt UND allgemeine Ticket-Status Änderungen entgegennimmt.

• Durch das Schreiben von Notizen mit hinterlegter Zeiterfassung in Zammad entstehen in Concept Office Tätigkeitspositionen. Hierfür müssen der Webhook, Trigger, die Serviceaufträge_einlesen.ini und das Externe System korrekt angelegt worden sein.

Wennn eine Zammad-Notiz als „intern“ gekennzeichnet wurde und der entsprechende Schalter in der bereits erwähnte .ini Datei korrekt gesetzt wurde, dann werden aus diesen Notizen keine Positionen im Auftrag. Das Gleiche gilt für Zeiterfassungen mit 0 Minuten. Voraussetzung zur Anlage von Tätigkeitsartikeln ist, das zuvor ein Serviceauftrag durch die entsprechende Zammad-Webschnittstelle entstanden ist und das die Auftragsnummer im Zammad-Ticket sichtbar ist. Die Auftragsnummer wird automatisch befüllt.

• [Mode]
• Export=2
• Import=0
• [Export_1]
• DateiFormat=Zammad
• ExportTyp=Kontakte
• ErstellerName=ConceptOffice
• SchemaKey=Zammad
• [Export_2]
• DateiFormat=Zammad
• ExportTyp=ansprechpartner
• ErstellerName=ConceptOffice
• SchemaKey=Zammad
• [MsgQTables]
• anschriften=0
• ansprechpartner=0
• ansprechpartnerfunktionen=0
• ansprechpartnerstichworte=0
• artikel=1
• auftragskoepfe=0
• kontakte=0
• kontaktgeschaeftsbereiche=0
• kontaktkontakte=0
• kontaktmitarbeiter=0
• kontaktprojekte=0
• kontaktstichworte=0
• kontaktwerbemittel=0
• kundensonderkonditionen=0
• kundensonderpreise=0
• maschinen=1
• maschinenOnly=0
• mitarbeiter=0
• verbindungen=0

Das unter SchemaKey angegebene Schema, muss in der MsgQueueExport.ini definiert werden. Wenn die Datei noch nicht vorhanden sein sollte, dann muss diese unter Sysdata –> ImportExport anlegegt werden. Mehr zum Aufbau der Datei in dem Kaptitel MsgQueueExport.Ini

Die MsgQTable-Definitionen steuern das Lese-Verhalten aus der MsgQueueData Tabelle. Sprich auch wenn in der MsgQData Tabelle Beispielsweise Einträge zu Kontakten enthält, werden diese nur vom MsgQ-Server abgearbeitet, wenn ein entsprechender Eintrag für die Kontakte auf 1 gesetzt wurde. Beachten: Wenn gar keine Schalter hinterlegt werden, dann werden ALLE Tabellen vom MsgQ-Server herangezogen und entsprechend nach der Verarbeitung gelöscht.

• [Zammad]

(Firmen Einstellungen)

• NurAktiveFirmen=1
• AuchInteressenten=0
• NurKunden=1
• MitReinenLieferanten=0
• OrganizationDomainAssignment=0
• PruefungFremdschluesselAusFremdsystemOrganizations=1
• PruefungFremdschluesselMitCoPKImNamen=1
• KontaktnamenMitKontaktnummerExportieren=1
• CustomFieldOrganizations_1=„BeispielFeldName“,50007

(Ansprechpartner Einstellungen)

• CustomFieldUsers_1=„street“,50642
• CustomFieldUsers_2=„BeispielFeldName2“,50643
• CustomFieldUsers_3=„BeispielFeldName3“,50644
• AuchPrivateAPMailAdressenVerwenden=1
• PruefungFremdschluesselAusFremdsystemUsers=1

(Algemeine Einstellungen)

• LimitSearchResult=3
• AnzahlCustomFields=10

Anmerkungen:

• Selbst defininerte Recherche-Felder müssen unter dem Namen „CustomFieldUsers“ oder „CustomFieldOrganizations“ definiert werden. Die Definitionen müssen mit einem Unterstrich durchnummeriert werden. Der Aufbau nach dem Gleichheitszeichen ist erst der Zammad-Feldname dann ein Komma und dann die Recherche-Nummer die ausgeführt werden soll. Anschließend muss „AnzahlCustomFields“ angehoben werden.

• „OrganizationDomainAssignment“: funktioniert nur, wenn am CO-Kontakt eine Internet-Adresse in den Verbindungen hinterlegt wurde.

• „PruefungFremdschluesselImportAusFremdsystem“: Mit aktivierter Prüfung dauert der Abgleich länger, hierbei wird der PK aus Zammad mit dem äquivalenten Feld in CO verglichen. Sollte aus Performance-Gründen nur bei der Erstübernahme aktiviert werden und danach wieder deaktiviert werden. Funktioniert nur, wenn die Zammad-Suchfunktion aktiv ist (elasticsearch). Zudem muss der Suchindex vor und nach der Datenübernahme neu aufgebaut werden.

• „LimitSearchResult“: Wird nur ausgewertet, wenn PruefungFremdschluesselImportAusFremdsystem aktiviert ist. Die angegebene Anzahl entspricht der Anzahl der Vergleichsdatensätze aus Zammad.

• „AnzahlCustomFields“: Dient zum Aufbauen der selbst erstellten Recherche-Felder. Wenn hier weniger eingestellt ist, als es CustomField-Definitionen gibt, dann werden diese ignoriert. Wenn zuviele angegeben sind, ist es prinzipiell nicht schadhaft, kann aber die Laufzeit verlängern.

• WriteMsgQueueDataAnschriften=1
• WriteMsgQueueDataAnsprechpartner=1
• WriteMsgQueueDataAnsprechpartnerFunktionen=1
• WriteMsgQueueDataAnsprechpartnerStichworte=1
• WriteMsgQueueDataArtikel=1
• WriteMsgQueueDataAuftragskoepfe=1
• WriteMsgQueueDataKontakte=1
• WriteMsgQueueDataKontaktGeschaeftsBereiche=1
• WriteMsgQueueDataKontaktKontakte=1
• WriteMsgQueueDataKontaktMitarbeiter=1
• WriteMsgQueueDataKontaktProjekte=1
• WriteMsgQueueDataKontaktStichworte=1
• WriteMsgQueueDataKontaktWerbeMittel=1
• WriteMsgQueueDataKundensonderkonditionen=1
• WriteMsgQueueDataKundensonderPreise=1
• WriteMsgQueueDataMaschinen=1
• WriteMsgQueueDataMaschinenOnly=1
• WriteMsgQueueDataMitarbeiter=1
• WriteMsgQueueDataVerbindungen=1

Mit diesen Einstellugen ist es möglich, das nur bestimmte Tabellen für MsgQ-Einträge beachtet werden. Wenn gar keine MsgQ-Schalter in der Office.dat hinterlegt werden, dann werden alle Tabellen für die MsgQ Verwendet. Wichtig die Einstellung die hier getroffen werden, steuer nur das Schreiben in die MsgQueueData Tabelle, nicht das Lesen dieser Einträge. Das Lesen wird über die „coMsgQueueServer.ini“ gesteuert.

• [SchemaName]
• ToleranteKontaktPruefung=1 (bool)
• FremdschluesselAnlegenBeiErfolgreicherSuche=0 (bool)
• BearbeitungsStatus=0
• UnterbearbeitungsStatus=1
• Geschaeftsbereich=TKD
• TaetigkeitsartikelNr=1001
• InternalMessageIgnorieren=1 (bool)
• Stundenart=7
• NullZeitenErlauben=0 (bool)

Die hier hinterlegten Schalter Steuern die Auftragsanlage sowie die Anlage von Auftragspositionen aus dem Zammad-Ticket.

Zum Schalter „ToleranteKontaktPruefung“:

Wenn auf 1 gestellt (true), dann wird nicht mehr der CO-Firmennamen gegen den Ticket-Firmennamen geprüft. Hintergrund: Der Sachbearbeiter könnte ja versehentlich eine Maschine vom falschen Kunden am Zammad-Ticket ausgewählt haben. Die Auftragsanlage würde in im Falle von Schalter auf 0, dann abgebrochen werden. Erst wenn im Zammad-Ticket eine zum Kunden zugehörige Maschine ausgewählt wurde, wird es zur Auftragsanlage kommen.

Zum Schalter „FremdschluesselAnlegenBeiErfolgreicherSuche“:

Ablauf: Im Zammad-Ticket wird eine Maschine zum Kunden ausgewählt und das Ticket aktualisiert. Es kommt über den CO-Webservice zur Auftragsanlage. Wenn allerdings kein Fremdschlüssel zu der von Zammad übermittelten Firmen-ID vorliegt, dann wird der Kunde über die mitgegebene Maschine ermittelt. Wenn der Schalter auf 1 (true) gesetzt ist, dann wird nach Abgleich des Kontaktes (Siehe Schalter ToleranteKontaktPruefung) dauerhaft der entsprechende Fremdschlüssel auf der Datenbank angelegt.

Zum Schalter „InternalMessageIgnorieren“:

Wenn auf 1 gestellt (true), dann werden interne Zammad-Ticket-Nachrichten insofern ignoriert, dass keine Auftragspositionen durch diese entstehen.

Zum Schalter „NullZeitenErlauben“: Wenn auf 1 gestellt (true), dann werden Zammad-Ticket-Nachrichten die keine Zeiterfassung haben, also Zeit=0 Minuten, nicht als Auftragspositionen im Auftrag angelegt.

Über das Zusammenspiel von Zammad -Triggern und -Webhooks, sowie dem Concept-Office MsgQ-Server ist es möglich, automatisiert Serviceaufträge aus Tickets zu erstellen, sowie Informationen aus dem Serviceauftrag wieder in das Zammad-Ticket zurückzuspielen.

Es folgt eine Schritt-für-Schritt-Anleitung. Wenn der Arbeitsschritt in Zammad erledigt werden muss, dann beginnt der Paragraph mit [Zammad], entsprechend wenn der Arbeitsschritt Concept Office betrifft, dann beginnt der Paragraph mit [CO]. Die Schritte müssen nicht zwingend in der hier vorliegenden Reihenfolge abgearbeitet werden, jedoch empfiehlt es sich, nur dann von der Reihenfolge abzuweichen, wenn man weiß was man macht.

• [Zammad] Einen Benutzer erstellen, dem Concept Office als Account nutzen kann.
• [Zammad] In den Profil-Einstellungen des soeben erstellten Accounts muss nun ein Access Token generiert werden. Dieses Token bitte notieren.
• [CO] Externes System, mit System-Art „Zammad“ anlegen. Benutzernamen und Passwort spielen keine Rolle, müssen jedoch angelegt werden. Bitte beliebige Platzhalter hinterlegen.

• [CO] Die MsgQ-Protokollierung muss aktiviert werden. Zur Fein-Steuerung bitte das Kapitel „Office.dat“ zu Rate ziehen. Nach Änderungen in der Office.dat bitte Concept Office einmal Neustarten.

• [CO] * Die MsgQueueExport.ini muss angelegt und konfiguriert werden, für nähere Informationen hierzu bitte das gleichnamige Kapitel beachten.

• [CO] Recherchen für die „Custom_Felder“ anlegen. Für weitere Informationen bitte in das Kapitel „Recherchefelder“ schauen.

• [Zammad] Alle Datenfelder, die Zammad von Concept Office entgegennehmen soll, müssen Zammad definiert werden. Hierfür entsprechend an den „Organisations“ und „Users“ die „Objects“ anlegen. Am Beispiel der Ansprechpartner.Street. Manage(Das Zahnrad Symbol unten Links) dann auf Objects und unter dem Reiter „User“ das Feld „street“ anlegen. Wenn der hier gewählte Feldname identisch mit dem von Concept Office übertragenen Feldnamen ist, dann wird das Feld entsprechend befüllt werden.

An dieser Stelle kann der Stammdatenabgleich erfolgen. Das Kapitel „Allgemeines zum Stammdatenabgleich“ gibt nähere Informationen zu diesem Prozess. Es folgt nun die Prozesserklärung zum Stammdatenabgleich. Als erstes sollte man einen Blick in die Tabelle MsgQueueData werfen. Es empfiehlt sich, falls dort Einträge vorhanden sind, diese zu Löschen. Anschließend die Tabelle MsgQueueData mit folgender SQL-Anweisung befüllen:

INSERT INTO MsgQueueData 
( ClientID, ApplicationName, TableName, GUIDString, Operation, OperationDate, UserName, Program, LfdNummer ) 
SELECT Kontakte.Mandant, 'Office', 'kontakte', Kontakte.UniqueId, 1, GETDATE(), 'script', 'script', 0
FROM Kontakte WHERE Mandant = 1 AND Uebernahme = 1 AND IstInteressent = 0 AND IstLieferant = 0 AND IstKunde = 1

Bitte den Mandanten in der SQL-Anweisung beachten! Es können beliebige Einschränkungen, in der WHERE-Bedingung, getroffen werden. Bitte das Kapitel „MsgQueueExport.Ini“ mit beachten. Die dort definierten Schalter sollten mit der WHERE-Bedingung gleich gesetzt werden.

Anschließend das Programm Sc.Co.MsgQServer starten. Der Datenabgleich wird, wenn alles korrekt konfiguriert wurde, sogleich gestartet. Im MsgQ-Log werden Fehleraufzeichnungen protokolliert.

Nach der erfolgreichen Übertragung der Kontakte kann nun die Übertragung der Ansprechpartner folgen. Hierfür bitte folgende SQL-Anweisung anpassen:

INSERT INTO MsgQueueData 
( ClientID, ApplicationName, TableName, GUIDString, Operation, OperationDate, UserName, Program, LfdNummer ) 
SELECT AnsprechPartner.Mandant, 'Office', 'ansprechpartner', AnsprechPartner.UniqueId, 1, GETDATE(), 'script', 'script', 0
FROM AnsprechPartner WHERE Mandant = 1 AND Aktiv = 1

Bitte den Mandanten in der SQL-Anweisung beachten!

Falls der MsgQServer noch am laufen ist, startet dieser auch sogleich mit der Datenübertragung. Ansonsten bitte einmal den MsgQServer starten.

Nach der erfolgreichen Datenübertragung werden ab jetzt alle Datenänderungen der Firmen und Ansprechpartner mit Zammad synchronisiert.

[Zammad] Folgende Ticket-Objects müssen angelegt werden. Der Anzeigename ist frei wählbar, nicht aber der Feldname.

• „maschine“ –> Textfeld –> Default „?“(Das Fragezeichen wird dem Trigger später dazu dienen, zu unterscheiden ob bereits eine Maschine ausgewählt wurde.) (wenn das Feld „maschine“ nicht angelegt wird, dann ist die Auftragsanlage nicht möglich)
• „co_vorgangsnummer“ Textfeld (wenn nicht angelegt, dann kann die Serviceauftragsnummer nicht in das Zammad-Ticket übertragen werden, die Auftragsanlage funktioniert trotzdem)
• „co_schema“ –> single tree select field (wenn nicht angelegt, dann ist die Auftragsanlage nicht möglich) Informationen zum Aufbau des Schemas ist unter dem Kapitel „Serviceaufträge_einlesen.ini“ zu finden.
• „bei_techniker“ –> Boolean (Indikator ob der Serviceauftrag aktuell beim Techniker in Bearbeitung ist)

[Zammad] Für die beiden Endpunkte (Mehr dazu im Kapitel „Allgemeines zur Auftragsanlage“) müssen entsprechende Webhooks angelegt werden. Hierfür unter Manage–> Webhook oben rechts auf „New Webhook“ klicken. Ein Beispiel für den Aufbau:

[Zammad] Als nächstes müssen die Trigger eingerichtet werden, die die Webhooks bedienen. Hier steht es dem Nutzer frei die Bedingungen individuell nach Bedarf zu konfigurieren. Es gilt dabei nur zu beachten, was im Kapitel „Allgemeines zur Auftragsanlage“ über die Aufgabenverteilung der Endpunkte beschrieben ist. Außerdem zu beachten ist, das laut Dokumentation von Zammad, die Trigger in Alphabetischer Reihenfolge abgearbeitet werden.

Eine Beispielkonfiguration der Trigger:

Webhook Maschine zugeordnet:

Webhook Taetigkeit Hinzufuegen

[Zammad] Als Ticket-Object muss das Feld „co_unterbearbeitungsstatus“ als „Single selection field“ angelegt werden. Zu Beachten ist hierbei, dass der Key des jeweiligen Unterbearbeitungsstatus identisch mit dem aus der Concept Office Tabelle „Unterbearbeitungsstatus“ sein muss. Ein Beispiel:

Bei korrekter Einrichtung wird der Unterbearbeitungsstatus des Serviceauftrages durch den MsgQ-Server abgeglichen. Sodass im Idealfall nur wenige Sekunden zwischen der Statusänderung im Serviceauftrag und der Änderung am Zammad-Ticket vergehen.