IMPORT-GRCRESULTS-Befehl

Konzept-Informationen

Daten aus der Diligent One-Ergebnisse-App importieren

Erstellt eine Analytics-Tabelle, indem eine Tabelle aus der Diligent One-Ergebnisse-App oder eine Interpretation importiert wird.

Syntax

IMPORT GRCRESULTS TO Tabelle Importdateiname PASSWORD Zahl FROM Pfad_der_Ergebnisressource <FIELD Name AS Anzeigename <...n>> <CHARMAX max_Feldlänge>

Parameter

Name Beschreibung
TO Tabelle

Der Name der Analytics-Tabelle, in welche die Daten importiert werden sollen.

Hinweis

Tabellennamen sind auf 64 alphanumerische Zeichen beschränkt. Der Name kann den Unterstrich beinhalten ( _ ), aber keine anderen Sonderzeichen oder Leerzeichen. Er kann nicht mit einer Ziffer beginnen.

Importdateiname

Der Name der zu erstellenden Analytics-Datendatei.

Geben Sie Importdateiname als in Anführungszeichen gesetzte Zeichenfolge mit der Dateierweiterung „.FIL“ an. Zum Beispiel: „Rechnungen.FIL“.

Standardmäßig wird die Datendatei (.FIL) in den Ordner mit dem Analytics-Projekt gespeichert.

Verwenden Sie entweder einen absoluten oder relativen Dateipfad, um die Datendatei in einen anderen bestehenden Ordner zu speichern:

  • "C:\Daten\Rechnungen.FIL"
  • "Daten\Rechnungen.FIL"
PASSWORD Zahl

Die zu verwendende Kennwortdefinition.

Sie verwenden nicht PASSWORD Zahl, um ein tatsächliches Kennwort abzurufen oder festzulegen. Die Kennwortdefinition bezieht sich auf ein vorher angegebenes oder ein mit dem PASSWORD-, dem SET-PASSWORD-Befehl oder dem PASSWORD-Analysetag festgelegtes Kennwort.

Zahl bezieht sich auf die Zahl der Kennwortdefinition. Wenn beispielsweise zuvor zwei Kennwörter in einem Skript angegeben bzw. festgelegt wurden oder falls ein Analyseskript geplant wurde, wird mit PASSWORD 2 angegeben, dass das zweite Kennwort verwendet wird.

Weitere Informationen über die Angabe oder das Festlegen von Kennwörtern finden Sie unter:

Das benötigte Kennwort ist ein Diligent One-Zugriffstoken. Weitere Informationen finden Sie unter Eine Kennwortdefinition erstellen und ein Kennwort festlegen.

Abhängig von der Umgebung, in der das Skript ausgeführt wird, kann PASSWORD Zahl notwendig sein oder auch nicht.

Umgebung, in der das Skript ausgeführt wird Anforderung PASSWORD Zahl
Analytics

(Online-Aktivierung)

PASSWORD Zahl ist nicht erforderlich.

Es wird automatisch der Diligent One-Zugriffstoken des aktuellen Benutzers verwendet, der in der Windows-Registrierung gespeichert ist.
Analytics

(Offline-Aktivierung)

PASSWORD Zahl ist erforderlich.
Robots

FROM Pfad_der_Ergebnisressource

Der Pfad auf die zu importierenden Daten.

Das Format des Pfads ist je nach den zu importierenden Daten unterschiedlich. Einzelheiten hierzu finden Sie unter Pfad in der Ergebnisse-App.

Hinweis

Das Format des Ergebnisse-App-Pfads wird durch ein API bereitgestellt und unterliegt Veränderungen. Am einfachsten und verlässlichsten erhalten Sie die korrekte und aktuelle Syntax des Pfads, indem Sie einen manuellen Import der Zieldaten durchführen und den Pfad dann aus dem Befehlsprotokoll kopieren.
FIELD Name AS Anzeigename <...n>

Optional

Individuelle Felder in den zu importierenden Quelldaten. Geben Sie den Namen ein.

Wenn Sie FIELD auslassen, werden alle Felder importiert.

Name

Name muss dem physischen Feldnamen in der Ergebnisse-App-Tabelle genau entsprechen, was die Groß-/Kleinschreibung einbezieht. Um den physischen Feldnamen anzuzeigen, gehen Sie anhand einer der folgenden Methoden vor:

  • In der Ergebnisse-App klicken Sie in der Tabellenansicht auf einen Spaltentitel. Der physische Feldname wird nach dem Feldname angezeigt.
  • Wenn Sie eine Ergebnisse-App-Tabelle in Analytics importieren, erscheint der physische Feldname in Klammern nach dem Anzeigename im Dialogfeld, das Ihnen die Auswahl von Feldern gestattet.

Hinweis

Der physische Feldname in der Ergebnisse-App ist nicht der Anzeigename, der für die Spaltentitel in der Tabellenansicht verwendet wird.Results

Hierzu siehe auch Überlegungen zu Feldnamen beim Importieren und Exportieren von Daten aus Ergebnisse.

Anzeigename

Anzeigename (alternativer Spaltentitel) ist der Anzeigename für das Feld in der Ansicht der neuen Analytics-Tabelle. Sie müssen einen Anzeigenamen für jeden Namen von FIELD angeben. Geben Sie den Anzeigenamen als in Anführungszeichen gesetzte Zeichenfolge an.

Verwenden Sie zwischen den Wörtern ein Semikolon (;), wenn Sie die Zeilen in dem Spaltentitel umbrechen möchten.

Im Gegensatz zu anderen IMPORT-Befehlen in Analytics können Sie keinen leeren Anzeigenamen angeben, um den FIELD-Namen als Anzeigenamen zu verwenden.Analytics
CHARMAX maximale_Feldlänge

Optional

Die maximale Länge in Zeichen für jedes Feld in der Analytics-Tabelle, dessen Ursprung Zeichendaten in der Ergebnistabelle oder -interpretation sind.

Daten in der Ergebnistabelle oder -interpretation, die die maximale Feldlänge übersteigen, werden beim Import in Analytics abgeschnitten.

Durch die Fähigkeit, Felder abzukürzen, wird verhindert, dass die Gesamt-Datensatzlänge aufgrund langer Werte die vom Importprozess unterstützten Werte überschreitet:

  • 32.767 Zeichen (Nicht-Unicode-Analytics)

  • 16.383 Zeichen (Unicode-Analytics)

Beispiele

Festgelegte Felder von einer Tabelle in die Ergebnisse-App importieren

Sie importieren festgelegte Felder von einer Tabelle in der Ergebnisse-App in eine Analytics-Tabelle namens Spesenausnahmen:ResultsAnalytics

IMPORT GRCRESULTS TO Spesenausnahmen „C:\Sekundäre Analyse\Spesenausnahmen.fil" PASSWORD1 FROM "results/api/orgs/11594/control_tests/185699/exceptions" FIELD "metadata.status" AS "Status" FIELD "Mitnr" AS "Mitarbeiternummer" FIELD "DATE" AS "Datum" FIELD "CARDNUM" AS "Kartennummer" FIELD "CODES" AS "Händlercodes" FIELD "AMOUNT" AS "Betrag" FIELD "DESCRIPTION" AS "Beschreibung"

Alle Felder von einer Tabelle in die Ergebnisse-App importieren

Sie importieren alle Felder von einer Tabelle in der Ergebnisse-App in eine Analytics-Tabelle namens Spesenausnahmen:ResultsAnalytics

IMPORT GRCRESULTS TO Spesenausnahmen „C:\Sekundäre Analyse\Spesenausnahmen.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions"

Feldlänge beim Import aus einer Tabelle in Ergebnisse begrenzen

Sie importieren alle Felder von einer Tabelle in der Ergebnisse-App in eine Analytics-Tabelle namens Spesenausnahmen. Sie begrenzen die Feldlänge mit dem CHARMAX-Parameter.

IMPORT GRCRESULTS TO Spesenausnahmen "C:\Sekundäre Analyse\Spesenausnahmen.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions" CHARMAX 200

In der resultierenden Analytics-Tabelle werden alle Felder, die als Zeichendaten aus Ergebnisse stammen, auf die angegebene Länge von 200 Zeichen begrenzt. Alle Feldwerte, die das Limit überschreiten, werden auf 200 Zeichen abgekürzt.

Daten von einer Interpretation in die Ergebnisse-App importieren

Sie importieren eine Interpretation in der Ergebnisse-App in eine Analytics-Tabelle namens Spesenausnahmen_gefiltert:ResultsAnalytics

IMPORT GRCRESULTS TO Spesenausnahmen_gefiltert "C:\Sekundäre Analyse\Spesenausnahmen_gefiltert.fil" FROM "results/api/orgs/11594/control_tests/185699/interpretations/22699/exceptions"

Bemerkungen

Weitere Informationen über die Funktionsweise dieses Befehls finden Sie unter Daten aus der Diligent One-Ergebnisse-App importieren.

Sortierfolge und Filter beibehalten

Wenn Sie Daten aus der Ergebnisse-App importieren, bleiben alle Datenanpassungen, wie Sortieren oder Filtern, in der entstehenden Analytics-Tabelle erhalten bzw. werden ignoriert. Dies hängt davon ab, wie Sie die Daten importieren:

  • Tabelle importieren Datenanpassungen werden ignoriert. Alle Daten in der Tabelle werden importiert, mit Ausnahme von Feldern, die Sie auslassen möchten.
  • Interpretation importieren Datenanpassungen werden beibehalten.

Pfad in der Ergebnisse-App

Hinweis

Das Format des Ergebnisse-App-Pfads wird durch ein API bereitgestellt und unterliegt Veränderungen. Am einfachsten und verlässlichsten erhalten Sie die korrekte und aktuelle Syntax des Pfads, indem Sie einen manuellen Import der Zieldaten durchführen und den Pfad dann aus dem Befehlsprotokoll kopieren.

Der Ergebnisse-App-Pfad im Parameter FROM weist das folgende allgemeine Format auf:Results

FROM "results<-Regionskennung>/api/orgs/<Org-ID>/control_tests/<Kontrolltest-ID>/exceptions

Beispiel:

FROM "results/api/orgs/11594/control_tests/4356/exceptions"

Die Org-ID wird in der Adressleiste des Browsers angezeigt, wenn Sie sich an Launchpad anmelden. Die Kontrolltest-ID und die Interpretations-ID sehen Sie in der Adressleiste, sobald Sie diese Tabellen in der Ergebnisse-App anzeigen.

Die folgende Tabelle enthält alle Varianten des Ergebnisse-App-Pfads.

Für den Import: Verwenden Sie dieses Format des Ergebnisse-App-Pfads:
Kontrolltestdaten (Tabelle) 
FROM "results/api/orgs/11594/control_tests/4356/exceptions"
Kontrolltestdaten (Tabelle) Prüfungspfad 
FROM "results/api/orgs/11594/control_tests/4356/audit_trail"
Kontrolltestdaten (Tabelle) Kommentare 
FROM "results/api/orgs/11594/control_tests/4356/comments"
Interpretation 
FROM "results/api/orgs/11594/control_tests/4356/interpretations/1192/exceptions"
Daten aus einer Diligent One-Region, die von der Standardregion, Nordamerika (US), abweicht
  • Afrika (Südafrika)
    FROM "results-af/api/orgs/11594/control_tests/4356/exceptions"
  • Asien-Pazifik (Australien)
    FROM "results-au/api/orgs/11594/control_tests/4356/exceptions"
  • Asien-Pazifik (Singapur)
    FROM "results-ap/api/orgs/11594/control_tests/4356/exceptions"
  • Asien/Pazifik (Tokio) 
    FROM "results-ap/api/orgs/11594/control_tests/4356/exceptions"
  • Europa (Deutschland)
    FROM "results-eu/api/orgs/11594/control_tests/4356/exceptions"
  • Nordamerika (Kanada)
    FROM "results-ca/api/orgs/11594/control_tests/4356/exceptions"
  • Südamerika (Brasilien)
    FROM "results-sa/api/orgs/11594/control_tests/4356/exceptions"

Systemerstellte Informationsspalten

Wenn Sie Daten aus der Ergebnisse-App importieren, haben Sie die Option, auch eine oder mehrere der unten aufgelisteten systemerstellten Informationsspalten zu importieren.

Vom System generierte Spalten sind entweder

  • ein Bestandteil der Ergebnisse-App-Tabellen und beinhalten Verarbeitungsinformationen in Bezug auf einzelne Datensätze oder
  • zusätzliche Informationen wie Sammlungsname, Tabellenname oder Datensatzkennung

Sie müssen die Feldnamen der systemerstellten Spalten genau wie unten dargestellt angeben. Es gelten die Standardanzeigenamen, wenn Sie aus der Ergebnisse-App über die Analytics-Benutzeroberfläche importieren. Wenn Sie den Importvorgang über ein Skript durchführen, können Sie die Anzeigenamen abändern.

Feldname

Standardanzeigename

metadata.priority

Priorität

metadata.status

Status

metadata.publish_date

Veröffentlicht

metadata.publisher

Name des Herausgebers

metadata.assignee

Empfänger
metadata.group Gruppe
metadata.updated_at Aktualisiert
metadata.closed_at Geschlossen
extras.collection Sammlung
extras.results_table Ergebnistabelle
extras.record_id Datensatz-ID

Überlegungen zu Feldnamen beim Importieren und Exportieren von Daten aus Ergebnisse

If you are round-tripping data between Ergebnisse and Analytics, you need to ensure that all field names in the Ergebnisse table meet the more stringent Analytics field name requirements. If you do not, you risk misaligning your Analytics and Ergebnisse data.

For example, any special characters in Ergebnisse field names are automatically converted to underscores when they are imported into Analytics, which means the field names no longer match the original names in Ergebnisse. If you then export the Analytics data back to the original table in Ergebnisse, fields are no longer correctly matched.

To avoid this problem with data that you intend to round-trip, make sure that before you upload the data to Ergebnisse from CSV or Excel files it meets these Analytics field name requirements:

  • no special characters or spaces
  • does not start with a number
  • contains only alphanumeric characters, or the underscore character ( _ )

Eine Kennwortdefinition erstellen und ein Kennwort festlegen

Wenn Sie ein Skript in Robots ausführen, das eine Diligent One-Ergebnistabelle oder -interpretation importiert, müssen Sie eine Kennwortdefinition in den IMPORT GRCRESULTS-Befehl aufnehmen. Dieselbe Anforderung gilt auch für Skripts, die in Analytics ausgeführt werden, wenn Sie die Offline-Aktivierung verwendet haben.

Unabhängig von Ihrer verwendeten Methode beim Erstellen einer Kennwortdefinition handelt es sich bei dem erforderlichen Kennwortwert um einen Diligent One-Zugriffstoken, den Sie in Launchpad erstellen können. Weitere Informationen finden Sie unter Diligent One-Zugriffstoken beantragen.

Kennwortdefinitionsmethoden

Methode Beschreibung

PASSWORD-Analysetag

(Für Skripts, die in Robots ausgeführt werden)

Wenn Sie das PASSWORD-Analysetag verwenden, um die nummerierte Kennwortdefinition für die Verbindung zu Diligent One anzulegen, wird kein Wert für das Kennwort im Skript angegeben. Beim Erstellen einer Aufgabe zur Ausführung des Skripts in Robots können Sie oder andere Benutzer in einem Eingabefeld im Aufgaben-Designer das tatsächliche Kennwort angeben.

Weitere Informationen finden Sie unter PASSWORD-Analysetag.

PASSWORD-Befehl

(Für Skripts, die in Analytics ausgeführt werden, Offline-Aktivierung)

Wenn Sie den PASSWORD-Befehl verwenden, um die nummerierte Kennwortdefinition für die Verbindung zu Diligent One anzulegen, wird kein Wert für das Kennwort im Skript angegeben. Beim Herstellen der Skriptverbindung wird eine Aufforderung zur Eingabe des Kennworts angezeigt.

Weitere Informationen finden Sie unter PASSWORD-Befehl.

SET PASSWORD-Befehl

(Für Skripts, die in Analytics ausgeführt werden, Offline-Aktivierung)

Wenn Sie den SET PASSWORD-Befehl verwenden, um die nummerierte Kennwortdefinition für die Verbindung mit Diligent One anzulegen, wird ein Wert für das Kennwort im Skript angegeben. Deshalb wird keine Kennwortaufforderung angezeigt. Dieser Ansatz eignet sich für Skripts, die ohne Benutzereingriff ausgeführt werden sollen, stellt aber ein echtes Kennwort in Klartext im Skript dar. Je nach Situation kann das ungeeignet sein.

Weitere Informationen finden Sie unter SET-PASSWORD-Befehl.

Diligent One-Zugriffstoken beantragen

Achtung

Der generierte Zugriffstoken entspricht dem Konto, das zur Anmeldung bei Diligent One verwendet wurde. Es empfiehlt sich unter Umständen nicht, als Skriptautor in einem Skript Ihren eigenen Zugriffstoken festzulegen, wenn das Skript durch andere Personen benutzt wird.

Schützen Sie Zugriffstoken genauso wie Ihr Kontokennwort.

Verwenden Sie einen bereits bestehenden Token, solange es keinen Grund gibt, einen neuen zu erstellen. Erstellen Sie einen neuen Token, falls der existierende Token nicht funktioniert. Wenn Sie bestehende Token verwenden, müssen Sie eine geringere Anzahl von Token verwalten.

  1. Führen Sie einen der folgenden Schritte aus:

    • Wählen Sie aus dem Analytics-Hauptmenü Extras > Diligent One-Zugriffstoken.

    • Im Skript-Editor klicken Sie mit der rechten Maustaste und wählen Einfügen > Diligent One-Token.

    Die Seite API-Token verwalten wird in Ihrem Browser geöffnet. Möglicherweise müssen Sie sich zuerst bei Diligent One anmelden.

    Sie können ganz einfach über Analytics auf die Seite API-Token verwalten zugreifen. Sie können sich aber auch ohne Analytics über Ihr Benutzerprofil bei Diligent One anmelden und die Seite aufrufen.

  2. Führen Sie einen der folgenden Schritte aus:

    • Bestehenden Token verwenden

      1. Klicken Sie in der Spalte Token auf die teilweise verborgene Version des gewünschten Tokens.

      2. Geben Sie Ihr Diligent One-Kennwort ein und klicken Sie auf Bestätigen.Diligent One

        Der Token wird nicht verborgen angezeigt.

      3. Klicken Sie auf Kopieren, um den Token zu kopieren.

        Tipp

        Schließen Sie das Dialogfeld mit dem Token nicht, bevor Sie den Token erfolgreich eingefügt haben.

    • Neuen Token erstellen

      1. Klicken Sie auf Token hinzufügen > Analytics.

      2. Geben Sie im Seitenbereich Neuer Analytics-Token die folgenden Informationen ein:

        Feld oder Option Beschreibung
        Beschreibung

        Geben Sie eine Beschreibung ein, die nützliche Informationen enthält, wie beispielsweise:

        • Der Zweck des Tokens
        • Wo der Token verwendet wird – zum Beispiel den Namen und Ort des Analytics-Skripts oder den Namen und Ort der Robot-Aufgabe
        Token-Ablauf
        • Aktiviert der Token läuft nach der von Ihnen angegebenen Anzahl von Tagen ab
        • Deaktiviert der Token läuft niemals ab

        Hinweis

        Möglicherweise gilt in Ihrer Organisation eine Sicherheitsrichtlinie, die verlangt, dass Token nach einer gewissen Zeitdauer ablaufen. Die Erstellung von Token mit einer Ablauffrist ist eine gute Praxis. Diligent One sendet Ihnen vor dem Ablaufdatum eine automatisierte E-Mail-Benachrichtigung.
        Läuft ab in Geben Sie die Anzahl der Tage an, bevor das Token abläuft (1 bis 365).
        Kennwort Geben Sie das Kennwort für Ihr Diligent One-Konto ein.

      3. Klicken Sie auf Token generieren.

      4. Klicken Sie auf Kopieren, um den Token zu kopieren.

        Tipp

        Schließen Sie den Seitenbereich mit dem Token nicht, bevor Sie den Token erfolgreich eingefügt haben.

  3. Führen Sie einen der folgenden Schritte aus, je nach Ihrer Kennwortdefinitionsmethode:

    • PASSWORD-Analysetag Fügen Sie im Aufgaben-Designer in einem ACL-Robot den kopierten Token in ein Kennwort-Parameterfeld ein.ACL robot

    • PASSWORD-Befehl Fügen Sie in Analytics den kopierten Token in eine Kennwortaufforderung ein, die bei der Skriptausführung angezeigt wird.Analytics

    • SET PASSWORD-Befehl Fügen Sie in Analytics den kopierten Token an der geeigneten Stelle des Skripts in der SET PASSWORD-Befehlssyntax ein.Analytics

  4. Schließen Sie in Launchpad das Dialogfeld oder den Seitenbereich mit dem Token.

    Nachdem Sie einen neuen Token erstellt haben, wird eine teilweise verborgene Version des Tokens am Anfang Ihrer Tokenliste hinzugefügt.

    Weitere Informationen finden Sie unter Diligent One-Zugriffstoken erstellen und verwalten.

Debugfunktion für Importe

Für Importe aus Diligent One gibt es eine einfache Debugfunktion.

Die importierten Daten werden vorübergehend in einer JSON-Zwischendatei im Ordner gespeichert, der das Analytics-Projekt enthält. In jedem Ordner mit einem Analytics-Projekt können Sie eine Textdatei erstellen, die sicherstellt, dass die JSON-Datei beibehalten und nicht nach dem Datenimport in Analytics gelöscht wird.

  • JSON-Datei ist vorhanden Wenn der Import aus Diligent One scheitert, die JSON-Datei jedoch auf Ihrem Computer vorhanden ist, wissen Sie, dass das Problem bei Analytics und nicht bei Diligent One zu suchen ist.Diligent OneAnalyticsDiligent One
  • JSON-Datei ist nicht vorhanden Wenn der Import aus Diligent One scheitert und die JSON-Datei auf Ihrem Computer nicht vorhanden ist, wissen Sie, dass das Problem bei Diligent One zu suchen ist.Diligent OneDiligent One

Diese Informationen können Ihnen bei der Fehlersuche helfen.

Aufbewahrung der JSON-Zwischendatei konfigurieren

Erstellen Sie im Ordner, der das Analytics-Zielprojekt enthält, eine leere Textdatei mit diesem Namen: _grc_import_debug.txtAnalytics

Wenn Sie aus der Ergebnisse- oder Projekte-App in Diligent One importieren, wird die JSON-Zwischendatei mit dem Namen results.json beibehalten. Durch jeden späteren Import aus Diligent One wird die Datei überschrieben.

Große Tabellen importieren

Tables that have a large number of fields may not successfully import using a single IMPORT GRCRESULTS command. If you need to work with a single table containing a large number of fields outside of Ergebnisse, use one of the following approaches:

  • Split the table use two or more IMPORT GRCRESULTS commands to import a subset of fields and then join the resulting tables in Analytics using the JOIN command
  • Export the table to file use the export to CSV format and then import the resulting file into Analytics using the IMPORT DELIMITED command