Zum Hauptinhalt springen

Excel-Berichte

Das Reports-Modell ist ein leistungsstarkes Node.js-Modul, das die Verwaltung von Berichten innerhalb Ihrer Anwendung optimiert. Es bietet ein robustes Framework zum Erstellen, Aktualisieren, Planen und Generieren von Berichten. In dieser Dokumentation führen wir Sie durch die wichtigsten Funktionen des Reports-Modells anhand der bereitgestellten Endpunkte.

Für eine einfachere Anleitung gehen Sie zum User Guide

ReportBase​

Es gibt zwei verschiedene Typen von ReportBases.

timeseries: Ein Bericht, der Zeitreihen von abgerufenen Geräten enthält.

statistics: Ein Bericht, der statistische Daten enthält (wie viele Geräte Sie Zugriff haben, zu welcher Organisation Sie gehören und detaillierte Daten über Mitglieder und deren Geräte).

Über unsere REST-API können Sie Anfragen wie das Erstellen/Aktualisieren/Abrufen/Löschen von ReportBases und ReportSchedules senden. Diese Dokumentation soll unsere Swagger-Dokumentation ergänzen, die URL lautet staging.yggio.net/api/report-bases/ und staging.yggio.net/api/report-schedules/. Es wird empfohlen, dafür unsere interaktive API https://staging.yggio.net/swagger zu verwenden.

Diese Endpunkte bieten umfassende Kontrolle über Ihre Berichte im Reports-Modell. Verwenden Sie sie, um Ihre Berichte zu erstellen, zu ändern und zu planen und so eine effiziente Verwaltung und Automatisierung Ihrer Berichtsprozesse sicherzustellen.

Eine ReportBase erstellen​

timeseries-Bericht​

Um eine neue ReportBase zu erstellen, die Zeitreihen für Geräte abruft, führen Sie eine POST-Anfrage an den Endpunkt /report-bases mit folgendem JSON-Payload im Anfrage-Body durch:

  • HTTP-Methode: POST

  • Endpunkt: /report-bases

  • Funktion: Erstellt eine ReportBase

{
  "name": "Test Report",
  "description": "test desc",
  "type": "timeseries",
  "fileName": "Standard-Template",
  "secondsBetweenPoints": 3600,
  "fillMethod": "previous",
  "reportPeriods": ["1w", "1d"], 
  "timeZone": "Europe/Copenhagen",
  "encoding": "en-US",
  "sources": [
    {
      "valueFunction": "sum",
      "query": "contextMap.Asset Type:Pickup Point",
      "includeOnly": ["value_arrivals", "value_departures"],
      "queryParameters": [
        {
          "field": "contextMap.City",
          "name": "City",
          "options": [
            "Copenhagen",
            "Stockholm",
            "Berlin"
          ],
          "isRequired": true
        }
      ],
      "fields": [
        {
          "name": "value_arrivals",
          "prettyName": "Arrival"
        },
        {
          "name": "value_departures",
          "prettyName": "Departure"
        }
      ]
    }
  ]
}

In diesem Beispiel führen wir eine POST-Anfrage aus, um eine ReportBase zu erstellen. Der Anfrage-Body enthält die Konfiguration für die ReportBase. Hier ist eine Erklärung der JSON-Attribute:

  • name: Der Name der ReportBase, in diesem Fall „Test Report“.
  • description: Eine optionale Beschreibung für die ReportBase, hier „test desc“.
  • type: Der Typ der ReportBase, hier „timeseries“.
  • fileName: Der Name der Vorlagendatei in unserem OneDrive, in diesem Fall „Standard-Template“.
  • secondsBetweenPoints: Das Intervall (in Sekunden) zwischen Datenpunkten im Bericht, hier 3600 Sekunden (1 Stunde).
  • fillMethod: Eine optionale Methode, um fehlende Datenpunkte aufzufüllen, verfügbare Optionen sind „previous“ und „linear“
    • previous: Fehlende Datenpunkte mit dem vorherigen Wert auffüllen.
    • linear: Fehlende Datenpunkte mit linearer Interpolation zwischen dem vorherigen und dem nächsten Wert auffüllen.
  • reportPeriods: Legt die vom Bericht abgedeckten Zeiträume fest. Dies sollte ein Array von Zeichenketten sein, wobei jede Zeichenkette dem Format {number}{unit} folgt:
    • {number} ist eine beliebige positive Ganzzahl (z. B. 1, 3, 10).
    • {unit} steht für die Zeiteinheit:
      • d → Tag (z. B. "1d" für 1 Tag, "3d" für 3 Tage).
      • w → Woche (z. B. "1w" für 1 Woche, "2w" für 2 Wochen).
      • m → Monat (z. B. "1m" für 1 Monat, "6m" für 6 Monate).
      • y → Jahr (z. B. "1y" für 1 Jahr, "5y" für 5 Jahre).
  • timeZone: Die für den Bericht verwendete Zeitzone, hier „Europe/Copenhagen“.
  • encoding: Die für die Zeitstempel im Bericht verwendete Kodierung, hier „en-US“.
  • sources: Ein Array von Datenquellen, die zum Abrufen und Verarbeiten von Daten für den Bericht verwendet werden. In diesem Beispiel enthält es eine einzelne Datenquelle:
    • valueFunction: Die zur Datenverarbeitung verwendete Funktion, hier „sum“. (Mögliche Werte sind: „mean“, „max“, „min“, „first“, „last“, „sum“, „count“, „difference“, „firstAndLast“)
    • query: Die Abfrage zum Filtern von Geräten, in diesem Fall „contextMap.Asset Type:Pickup Point“. (Alle Iotnodes, bei denen contextMap.Asset Type auf Pickup Point gesetzt ist, werden in den Bericht aufgenommen.)
    • includeOnly: Ein optionales Array von Feldern, die in den Bericht aufgenommen werden sollen, hier „value_arrivals“ und „value_departures“.
    • queryParameters: Optionale Query-Parameter. Weitere Informationen finden Sie im Unterabschnitt unten. Ist ein Array von Objekten mit folgenden Feldern:
      • field: Der Pfad zum Feld im Gerät.
      • name: Was dem Nutzer über der Eingabe angezeigt wird.
      • options: Wenn der Nutzer aus einer Liste von Optionen auswählen soll, werden diese hier angegeben. Ist ein Array von Zeichenketten.
      • isRequired: Ob der Nutzer dies angeben muss oder nicht.
    • fields: Ein Array von Feldern, die in den Bericht aufgenommen werden sollen, jeweils mit folgenden Attributen:
      • name: Der Feldname, wie „value_arrivals“ und „value_departures“.
      • prettyName: Ein benutzerfreundlicher Anzeigename für das Feld, wie „Arrival“ und „Departure“.

Dieses JSON-Payload wird im Body der POST-Anfrage gesendet, um eine neue ReportBase mit der angegebenen Konfiguration zu erstellen.

Query-Parameter​

Query-Parameter sind zusätzliche Parameter, die der Abfrage hinzugefügt werden. Die Query-Parameter werden in der ReportBase festgelegt, und die Werte können vom Nutzer beim Generieren des Berichts angegeben werden. Wenn Sie zum Beispiel nach einer bestimmten Stadt filtern möchten, können Sie einen Query-Parameter mit dem Feld contextMap.City hinzufügen. Der Nutzer kann dann aus einer Liste von Optionen wählen, und die Abfrage wird aktualisiert, um die ausgewählte Stadt einzubeziehen.

statistics-Bericht​

Um eine neue ReportBase zu erstellen, die Statistiken für einen Nutzer abruft, führen Sie eine POST-Anfrage an den Endpunkt /report-bases mit folgendem JSON-Payload im Anfrage-Body durch:

{
  "name": "Device Count",
  "type": "statistics",
  "description": "Description of the report",
  "fileName": "Device-count-report"
}

In diesem Beispiel führen wir eine POST-Anfrage aus, um eine ReportBase vom Typ „statistics“ zu erstellen. Der Anfrage-Body enthält die Konfiguration für die ReportBase. Hier ist eine Erklärung der JSON-Attribute:

  • name: Der Name der ReportBase, in diesem Fall „Device Count“
  • description: Eine optionale Beschreibung für die ReportBase, hier „Description of the report“
  • type: Der Typ der ReportBase, hier „statistics“
  • fileName: Der Name der Vorlagendatei in unserem OneDrive, in diesem Fall „Device-count-report“.

Office-Auslastungsbericht:

{
    "name": "Office utilization",
    "type": "timeseries",
    "description": "This is a standard office utilization report (08:00 - 17:00).",
    "fileName": "Standard-Office-Utilization",
    "timeZone": "Europe/Copenhagen",
    "secondsBetweenPoints": 3600,
    "fillMethod": "previous",
    "sources": [
        {
            "valueFunction": "max",
            "query": "presence",
            "includeOnly": [
                "contextMap",
                "presence"
            ],
            "fields": [
                {
                    "name": "presence",
                    "prettyName": "Presence"
                }
            ]
        }
    ]
}

Eine ReportBase aktualisieren​

Wenn Sie eine bestehende ReportBase ändern müssen, verwenden Sie folgenden Endpunkt:

  • HTTP-Methode: PUT

  • Endpunkt: /report-bases/:reportBaseId

  • Funktion: Aktualisiert eine ReportBase

Dieser Endpunkt ermöglicht es Ihnen, die Konfiguration Ihrer ReportBase zu ändern und die Berichtserstellungseinstellungen zu aktualisieren.

Eine ReportBase löschen​

Um eine ReportBase zu entfernen, können Sie folgenden Endpunkt verwenden:

  • HTTP-Methode: DELETE

  • Endpunkt: /report-bases/:reportBaseId

  • Funktion: Löscht eine ReportBase

Diese Aktion entfernt die ReportBase-Konfiguration und stoppt die zugehörige Berichtserstellung.

Eine ReportBase abrufen​

Um die Details einer bestimmten ReportBase abzurufen, können Sie folgenden Endpunkt verwenden:

  • HTTP-Methode: GET

  • Endpunkt: /report-bases/:reportBaseId

  • Funktion: Ruft eine ReportBase ab

Dies ermöglicht es Ihnen, die Konfiguration der ReportBase abzurufen und den Status der Berichtserstellung für eine bestimmte ReportBase zu überprüfen.

Eine ReportBase generieren​

Um eine bestimmte ReportBase zu generieren, können Sie folgenden Endpunkt mit folgendem JSON-Payload im Anfrage-Body verwenden:

  • HTTP-Methode: POST

  • Endpunkt: /report-bases/:reportBaseId/generate

  • Funktion: Generiert eine ReportBase

{
  startTime: 1697016949000, // Unix timestamp in milliseconds
  endTime: 1697016949000 // Unix timestamp in milliseconds
}

ReportSchedule​

Ein ReportSchedule erstellen​

Um ein neues ReportSchedule zu erstellen, verwenden Sie folgenden Endpunkt:

  • HTTP-Methode: POST

  • Endpunkt: /report-schedules

  • Funktion: Erstellt ein ReportSchedule

{
  "reportBaseId": "associated-report-base-id",
  "name": "Schedule Name",
  "interval": "daily", // Options: "monthly", "weekly", "daily" - How often to generate and send the report
  "duration": "week", // Options: "month", "week", "day", or a number - How far back in time the data stretches
  "email": {
    "to": "<Contact Id>", // ID from a Contact in the database.
    "cc": "cc@example.com", // Optional
    "title": "Report Title",
    "message": "Additional message text" // Optional
  }
}

In diesem JSON-Anfrage-Body geben Sie die Konfiguration für ein neues ReportSchedule anhand des bereitgestellten Schemas an. Hier ist eine Erklärung der Attribute:

  • reportBaseId: Die ID der zugehörigen ReportBase.
  • name: Ein Name für das ReportSchedule.
  • interval: Gibt an, wie oft der Bericht generiert und gesendet werden soll. Optionen sind „monthly“, „weekly“ oder „daily“.
  • duration: Legt fest, wie weit die Daten zeitlich zurückreichen sollen. Optionen umfassen „month“, „week“, „day“, oder Sie können eine Zahl angeben.
  • email: E-Mail-Konfiguration für den Versand des Berichts, einschließlich:
    • to: ID eines Contacts in der Datenbank.
    • cc: Eine optionale E-Mail-Adresse für die Kopie.
    • title: Der Titel des Berichts in der E-Mail.
    • message: Eine optionale zusätzliche Nachricht, die einbezogen werden soll.

Dieses JSON-Payload wird im Body der POST-Anfrage gesendet, um ein neues ReportSchedule mit der angegebenen Konfiguration zu erstellen. Nutzen Sie diese Funktion, um die Berichtserstellung und -zustellung nach Ihrem gewünschten Zeitplan zu automatisieren.

Ein ReportSchedule aktualisieren​

Wenn Sie ein bestehendes ReportSchedule ändern müssen, verwenden Sie folgenden Endpunkt:

  • HTTP-Methode: PUT

  • Endpunkt: /report-schedules/:reportScheduleId

  • Funktion: Aktualisiert ein ReportSchedule

Dieser Endpunkt ermöglicht es Ihnen, die Zeitplanparameter zu ändern und die automatisierten Berichtserstellungseinstellungen zu aktualisieren.

Ein ReportSchedule löschen​

Um ein ReportSchedule zu entfernen, können Sie folgenden Endpunkt verwenden:

  • HTTP-Methode: DELETE

  • Endpunkt: /report-schedules/:reportScheduleId

  • Funktion: Löscht ein ReportSchedule

Diese Aktion entfernt die Zeitplanparameter und stoppt die automatisierte Berichtserstellung, die mit einem bestimmten ReportSchedule verbunden ist.

Ein ReportSchedule abrufen​

Um die Details eines bestimmten ReportSchedule abzurufen, verwenden Sie folgenden Endpunkt:

  • HTTP-Methode: GET

  • Endpunkt: /report-schedules/:reportScheduleId

  • Funktion: Ruft ein ReportSchedule ab

Dies ermöglicht es Ihnen, die Zeitplanparameter abzurufen und den Status der automatisierten Berichtserstellung für ein bestimmtes ReportSchedule zu überprüfen.