Document Exporter Word Add-In

Document Exporter Word Add-In

Einführung

Das Document Exporter Word Add-In ist ein Werkzeug, dass Ihnen die Arbeit mit Document Exporter for ServiceNow erleichtern soll. Es unterstützt bei der Word-basierten Erstellung von Vorlagen für den Export von Datensätzen aus ServiceNow.

Mit Hilfe des Add-Ins können Platzhalter für Felder sowie Platzhalter zur Steuerung der Ausgabe wie z.B. Schleifen an der aktuellen Cursorposition in das Dokument eingefügt werden. Durch eine Verbindung zur ServiceNow Instanz können Tabellen und Felder einfach ausgewählt und deren interne Namen per Klick als Platzhalter in das Dokument übernommen werden. Dadurch entfällt das manuelle Ermitteln der internen Namen sowie das Nachschlagen der genauen Syntax für Steuercodes in Platzhaltern.

Ausprobieren, kaufen und installieren

Document Exporter Word Add-In können Sie kostenlos und einfach über Microsoft AppSource unter Document Exporter Word Add-in im Microsoft App-Store beziehen. Auch über den Store-Button in Word ist das Add-In erhältlich.

Im folgenden Video erhalten Sie Informationen darüber, wie Sie ein Add-In in Word aktivieren können.

Weitere Informationen zum Microsoft App-Store finden Sie unter appsource.microsoft.com.

Voraussetzungen

Das Add-In funktioniert mit folgenden Versionen von Microsoft Word:

• Word 2016 und neuer für Windows und Mac
• Word Online
• Word für iOS (iPad)

Ihre Firewall muss folgende Zugriffe erlauben:

• https://instanzname.service-now.com/api/now/table (GET)
• https://cdn.syscovery.com/docexporter (GET)
• https://docs.syscovery.com/docexporter (GET)
• https://appsforoffice.microsoft.com (GET)
• https://code.jquery.com (GET)

Zusätzlich muss in Ihrer ServiceNow-Instanz eine CORS-Regel eingetragen sein. Diese Regel muss von einem Administrator in ServiceNow unter System-Webservices -> REST -> CORS-Regeln in folgender Form angelegt werden:

Damit wird der Zugriff des Add-Ins auf die ServiceNow Instanz technisch ermöglicht.

Der Zugriff erfolgt mit den Berechtigungen des Benutzerkontos, das vom Anwender innerhalb des Add-Ins eingegeben wird. Dieses Benutzerkonto muss lesenden Zugriff auf die Tabellen „Tabellen (sys_db_object)“ und „Dictionary (sys_dictionary)“ haben und darf keine Multi-Faktor Authentifizierung nutzen.

Sollte die Multi-Faktor-Authentifizierung (MFA) für die Benutzer aktiviert sein, so kann ein Dienstkonto für diesen Zugriff in ServiceNow ohne MFA angelegt und dessen Benutzername / Kennwort dem Anwender übergeben werden. Das Dienstkonto benötigt nur lesenden Zugriff auf die beiden oben genannten Tabellen. Aus Sicherheitsgründen sollte zudem im Benutzerkonto der Zugriff nur per Webservice erlaubt werden:

Somit kann sich niemand mit diesem Benutzer interaktiv bei der ServiceNow Instanz anmelden.

Bedienung

Das Add-In wird nach der Installation im Word aus dem Ribbon „Start“ über den entsprechenden Button geöffnet:

Es öffnet sich dann ein Bereich in dem die einzelnen Funktionen über Bedienpanels erreichbar sind:

Im Folgenden werden die einzelnen Funktionen näher erläutert.

Hilfe zur Benutzung

Über diesen Bereich kann die Onlinehilfe des Add-Ins aufgerufen werden. Unterhalb des Buttons zum Aufruf der Hilfe wird noch die aktuelle Version des Add-Ins ausgegeben.

Verbindung zu ServiceNow

Dieser Bereich wird automatisch nach dem Start des Add-Ins eingeblendet. Hier werden die Zugangsdaten zur ServiceNow Instanz angegeben, damit die anderen Funktionen Tabellen- und Feldnamen aus ServiceNow abrufen können.

Der Name der Instanz ist der reine Instanzname ohne die Domain. D.h. wenn die Instanz unter der Url https://firmenname.service-now.com zu erreichen ist, dann ist der Teil firmenname der Name der Instanz welcher hier eingetragen werden muss.

Bei Benutzername und Passwort sind die Daten eines Benutzers aus ServiceNow anzugeben, der Lese-Zugriff auf die Tabellen „Tabellen (sys_db_object)“ und „Dictionary (sys_dictionary)“ haben muss. Für diesen Benutzer darf keine Multi-Faktor-Authentifizierung (MFA) aktiviert sein. Gegebenenfalls ist ein eigens dafür angelegtes Dienstkonto zu verwenden (siehe Kapitel „Voraussetzungen“).

Felder einfügen

In diesem Bereich können Platzhalter für Feldinhalte aus ServiceNow in das Dokument eingefügt werden. Dazu muss zunächst über den Button „Lade Tabellen“ die Liste der in der ServiceNow Instanz verfügbaren Tabellen geladen werden. Anschließend erscheint eine Auswahlbox zur Auswahl der Tabelle. Sofern nur eine Fehlermeldung mit dem Text „error“ erscheint, prüfen Sie bitte ob im Abschnitt „Verbindung zu ServiceNow“ der Instanzname korrekt (und ohne den Zusatz .service-now.com) angegeben wurde und ob in der Instanz die CORS Regel (siehe Kapitel „Voraussetzungen“) korrekt angelegt wurde.

Da die Auswahl der Tabellen sehr umfangreich ist, ist es empfehlenswert, zumindest den Anfang des Tabellennamens einzugeben um die Selektion zur vereinfachen. In der Klammer hinter dem Titel der Tabelle steht der interne Name, da in manchen Fällen mehrere Tabellen mit dem gleichen Anzeigenamen existieren.

Nachdem eine Tabelle ausgewählt wurde erscheint darunter eine Auswahlbox zur Selektion des Felds in der Tabelle:

Über den Button „Feld einfügen“ direkt unter der Auswahlbox wird das ausgewählte Feld an der aktuellen Cursorposition im Dokument als Platzhalter eingefügt.

Sofern das ausgewählte Feld ein Referenzfeld ist, erscheint automatisch darunter eine weitere Feldauswahl:

In obigem Beispiel ist „Department“ ein Referenzfeld auf die Tabelle der Abteilungen. Das darin befindliche Feld „Department Head“ ist wiederum ein Referenzfeld auf die Benutzertabelle. Durch Anklicken des Buttons „Feld einfügen“ direkt unter einem Feld wird dieses Feld in als Platzhalter in das Dokument eingefügt. Der erste Button würde also die Abteilung eines Benutzers einfügen, der zweite Button fügt den Namen des Abteilungsleiters ein und mit dem letzten Button würde die Telefonnummer des Abteilungsleiters der Abteilung eingefügt. Alle Felder beziehen sich jeweils auf die Daten des beim Export übergebenen Datensatzes aus der Basistabelle.

Mehrere Datensätze

Die Document Exporter App ist auch in der Lage, mehrere Datensätze aus einer Basistabelle gemeinsam in ein Dokument zu exportieren. Die Dokumentvorlage muss dafür in der Vorlagentabelle in ServiceNow mit dem Typ „Mehrere Datensätze“ gespeichert werden.

Mehrere Datensätze können als einfache Liste untereinander, innerhalb einer Tabelle oder in ein mehrseitiges Dokument (z.B. ein Datensatz pro Seite) ausgegeben werden. Dies ist lediglich von dem Aufbau der Dokumentvorlage abhängig.

Der Bereich ist wie folgt aufgebaut:

Alles, was pro Datensatz wiederholt werden soll, muss sich innerhalb einer Schleife befinden. Dazu markiert man im Dokument den kompletten zu wiederholenden Bereich mit der Maus und klickt anschließend im Add-In auf den Button „Schleife einfügen“. Dadurch wird der Platzhalter welcher den Beginn der Schleife festlegt am Anfang des markierten Bereichs und der Platzhalter für das Ende der Schleife am Ende des markierten Bereichs eingefügt.

Beispiel für eine Tabelle. Die Tabelle wurde mit zwei Zeilen in das Dokument eingefügt. Die erste Zeile enthält die Spaltenüberschriften, in der zweiten Zeile wurden wie im vorigen Kapitel beschrieben Felder aus der Benutzertabelle eingefügt. Anschließend wurde die zweite Zeile mit der Maus vollständig markiert:

Durch einen Klick auf den Button „Schleife einfügen“ im Add-In wird nun die Schleife in der zweiten Zeile ergänzt:

Das Ergebnis nach dem Export ist dann wie folgt:

Wurde die Schleife versehentlich falsch platziert, so müssen die Platzhalter {#Records} und {/Records} zunächst aus dem Dokument entfernt werden bevor die Schleife erneut eingefügt wird.

Beispiel für ein mehrseitiges Dokument. Die Felder wurden frei auf der Seite platziert und ein manueller Seitenumbruch am Ende eingefügt. Anschließend wurde alles, was wiederholt werden soll (einschließlich dem Seitenumbruch) mit der Maus markiert:

Die Word Steuerzeichenanzeige wurde mit dem Button       Im Ribbon „Start“ aktiviert um die Steuerzeichen sichtbar zu machen.

Nachdem der Inhalt wie oben angegeben markiert wurde klickt man im Add-In auf den Button „Schleife einfügen“ um die Platzhalter für die Schleife einzufügen:

Auch der Seitenumbruch wird nun für jeden Datensatz wiederholt. Somit auch für den letzten Datensatz was eine in der Regel ungewollte leere Seite am Ende zur Folge hat. Um dies zu verhindern gibt es Bedingungen, die während der Ausführung der Schleife geprüft werden:

• Wenn erste Seite
• Wenn nicht erste Seite
• Wenn letzte Seite
• Wenn nicht letzte Seite

Alles was zwischen dem Start- und Ende-Platzhalter dieser Bedingung steht, wird nur entsprechend der Bedingung ausgegeben. Somit kann man den Seitenumbruch markieren und auf den Button „Wenn nicht letzte Seite“ klicken:

Damit wird der Seitenumbruch bei allen Seiten mit Ausnahme der letzten Seite ausgegeben.

Das Ergebnis nach dem Export ist dann wie folgt:

Verbundene Daten

Dieser Bereich bietet Unterstützung zum Hinzufügen von Daten aus anderen Tabellen als der Basistabelle. Diese Daten müssen sich über einen einfachen Feldvergleich (Inhalt Basistabellenfeld = Inhalt Feld aus verbundener Tabelle) verbinden lassen. Auch hier werden, wie im vorherigen Kapitel, die Daten der verbundenen Tabelle innerhalb einer Schleife ausgegeben.

Sollte das Laden der Tabellen nur mit der Fehlermeldung „error“ quittiert werden, prüfen Sie bitte ob im Abschnitt „Verbindung zu ServiceNow“ der Instanzname korrekt (und ohne den Zusatz .service-now.com) angegeben wurde und ob in der Instanz die CORS Regel (siehe Kapitel „Voraussetzungen“) korrekt angelegt wurde.

Im Bereich „Verbundene Daten“ können nach dem Laden der Tabellen durch Klick auf den Button „Lade Tabellen“ folgende Einstellungen vorgenommen werden:

Beschreibung der Eingabefelder:

Basistabelle des Dokuments

Hier wird die Basistabelle ausgewählt. Das ist die Tabelle, aus welcher der Datensatz in ServiceNow exportiert werden soll.

Felder

Auswahl des zu verknüpfenden Felds in der Basistabelle. Dieses Feld wird per „=“ Operator mit dem Feld aus der verbundenen Tabelle verknüpft.

Verbundene Tabelle

Auswahl der mit der Basistabelle zu verbindenden Tabelle.

Felder

Hier wird das zu verknüpfende Referenzfeld aus der verbundenen Tabelle angegeben. Dieses Feld wir per „=“ Operator mit dem Feld der Basistabelle verknüpft.

Abfrage

Optionale Angabe einer zusätzlichen Abfrage auf die verbundene Tabelle um nicht alle verknüpften Datensätze auszugeben. Hier können mehrere Filterkriterien im Standard-Abfrageformat von ServiceNow angegeben werden. Die Abfrage kann einfach erstellt werden, indem man in ServiceNow bei der verbundenen Tabelle in der Listenansicht einen Filter setzt, und anschließend per Rechtsklick auf den Filter den Abfragetext in die Zwischenablage kopiert:

Sortiere nach

Optionale Auswahl eines Felds in der verbundenen Tabelle nach dem die gefundenen Datensätze sortiert werden sollen (sofern mehrere gefunden wurden).

Aufsteigend sortieren

Ist der Haken gesetzt, dann werden die gefundenen Datensätze der verbundenen Tabelle nach dem zuvor angegebenen Feld aufsteigend sortiert, ansonsten werden sie absteigend sortiert.

Um die Daten aus der verbundenen Tabelle im Dokument auszugeben müssen noch Platzhalter für die Felder der verbundenen Tabelle platziert werden. Hierfür wird in der Regel eine Tabelle in Word verwendet. Das Einfügen der Platzhalter geschieht auf die gleiche Weise wir im Kapitel „Felder einfügen“ beschrieben.

Anschließend ist der für jeden Datensatz aus der verbundenen Tabelle zu wiederholende Bereich zu markieren. Ein Klick auf den Button „Schleife einfügen“ fügt dann die Platzhalter mit den Steuerbefehlen entsprechend der getroffenen Einstellungen ein.

Sollte die Schleife an der falschen Stelle oder mit falschen Einstellungen eingefügt worden sein, so müssen alle zugehörigen Platzhalter manuell wieder entfernt werden bevor die Schleife erneut eingefügt wird.

Es werden folgende Platzhalter verwendet:

• Beginn der Schleife:

  {#%Ttabellenname}

• Ende der Schleife:
  {/%Ttabellenname}

• Feldverknüpfung:

  {%MfeldBasistabelle:feldVerbundeneTabelle}

• Optionale Abfrage:

  {%Qabfrage}

• Optionale Sortierung (aufsteigend):

  {%OAfeldname}

• Optionale Sortierung (absteigend):

  {%ODfeldname}

Beispiel: Ausgabe eines Benutzerdatensatzes (Basis) mit den aktiven Incidents, die dem Benutzer zugeordnet sind (verbundene Daten):

Die Felder der Basistabelle wurden in das Dokument eingefügt. Ebenso eine Tabelle mit den Platzhaltern für die Felder aus der verbundenen Tabelle Incidents. Die Zeile mit den Feldern der verbundenen Tabelle wurde in Word mit der Maus markiert.

Die Einstellungen wurden wie folgt vorgenommen:

Ein Klick auf den Button fügt die Platzhalter in der Tabelle ein:

Das Ergebnis nach dem Export sieht dann wie folgt aus: