Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core für Entwickler > agorum core REST-API

agorum core High-level API

Die agorum core High-level API (agorum.hl) bietet die Möglichkeit, agorum core über eine standardisierte REST-Schnittstelle anzubinden. Sie müssen für die Standardservices, die über die High-level API angeboten werden, keinen eigenen CustomService entwickeln.

Die REST-Schnittstelle bietet Services zum Arbeiten mit Objekten, für die Suche, die Vorschau, die Papierkorb-Verwaltung sowie das Arbeiten mit Workflows.

Verwendung

Sie können mit der agorum core HIgh-level API die Arbeit mit agorum core, dem DIGITAL TOOLKIT for Open Source Document Management, automatisieren.

Tipp: Zur einfachen Verwendung der REST-Schnittstelle finden Sie hier eine Postman-Collection, die Sie in Postman laden können, um die Services direkt aufzurufen: undefined>agorum core High-level API.postman_collection

Bearer Token

Zur Verwenden der REST-API benötigen Sie ein JWT-Token. Dieses Token können Sie in agorum core über Administration > Werkzeuge > JWT-Generator erzeugen, siehe JWT-Generator.

Sie müssen das Token bei jeder Anfrage mitgeben.

Basispfad

{{agorum-core-server}}/api/rest/custom/

Verwendung in Postman

Gehen Sie wie folgt vor, um die Collection in Postman zu verwenden:

Installieren Sie Postman.
Laden Sie die Collection herunter.
Importieren Sie die Collection.
Generieren Sie für den agorum core Server, mit dem Sie über die REST-API kommunizieren wollen, ein JSON Web Token (JWT), siehe JWT-Generator bzw. JavaScript-Bibliothek common/jwt.
Editieren Sie die Informationen für die agorum core High-level API in Postman. Tragen Sie unter Variables > url den richtigen Servernamen Ihres agorum core Servers ein.
Tragen Sie unter Authorization > Token (bei vorausgewähltem Auth Type Bearer Token) das soeben generierte Token ein.
Testen Sie die Verbindung mit einer einfachen Anfrage, etwa der Suchanfrage.

Tipp: Sie können sich in Postman die Collection auch als generierte Dokumentation anzeigen lassen, zum Beispiel für die ganze Collection über View complete documentation:

Vollständige Dokumentation der Collection in Postman öffnen

Rückgabewerte

Die REST-API liefert folgende Rückgabewerte analog zu den üblichen HTTP Response Codes:

200 OK: Die Anfrage war erfolgreich und der Server liefert die angeforderten Ressourcen.
400 Bad Request: Die Anfrage war fehlerhaft und der Server kann sie nicht verarbeiten.
401 Unauthorized: Authentifizierung ist erforderlich und die Anfrage wurde nicht authentifiziert.
404 Not Found: Die angeforderte Ressource konnte auf dem Server nicht gefunden werden.
409 Conflict: Es besteht ein Konflikt mit dem aktuellen Zustand der Ressource.
500 Internal Server Error: Der Server hat einen unerwarteten Fehler festgestellt, der die Ausführung der Anfrage verhindert.

Services für die Arbeit mit Objekten

Mit diesen Services können Sie Informationen über Objekte in agorum core abfragen und bestimmte Objekte erstellen, bearbeiten oder löschen.

POST object (folder)

Mit der POST-Anfrage object (folder) können Sie Ordner in agorum core anlegen. Dazu müssen Sie den Typ (Ordner), den Namen des Ordners und den Pfad angeben, wo der Ordner erstellt werden soll.

Anfrage-Body (form-data):

type (String, erforderlich): Der Typ muss den Wert 'folder' haben, um einen Ordner zu erstellen.
name (String, erforderlich): Der Name des Ordners.
target (String, optional): Der Pfad, unter dem der Ordner erzeugt werden soll (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Metadaten, die auf den Ordner gesetzt werden sollen, als Schlüssel-Wert-Paare, Beispiel: {"identifier":"test"}
expirationDays (Ganzzahl, optional): Optionale Festlegung, wenn der Ordner nach einer bestimmten Zeit gelöscht werden soll, hier in Tagen. Beispiel: 1 für ein Löschdatum am nächsten Tag. Alternativ können Sie das Ablaufdatum auch über einen der folgenden Parameter angeben: expirationMillis, expirationSeconds, expirationMinutes, expirationHours, expirationWeeks, expirationMonths, expirationYears.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die UUID des neu erstellten Ordners.

Beispiel für eine zurückgegebene Struktur:

"9c392ab0-15ed-11f0-8281-00007f000101"

POST object (folder, JSON)

Mit der POST-Anfrage object (folder, JSON) können Sie Ordner in agorum core anlegen. Dazu müssen Sie den Typ (folder), den Namen des Ordners und den Pfad angeben, wo der Ordner erstellt werden soll. Die Angabe erfolgt durch eine übergebene JSON-Struktur.

Anfrageparameter (JSON):

type (String, erforderlich): Der Typ muss den Wert 'folder' haben, um einen Ordner zu erstellen.
name (String, erforderlich): Der Name des Ordners.
target (String, optional): Der Pfad, unter dem der Ordner erzeugt werden soll (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Metadaten, die auf den Ordner gesetzt werden sollen, als Schlüssel-Wert-Paare, Beispiel: {"identifier":"test"}
expirationDays (Ganzzahl, optional): Optionale Festlegung, wenn der Ordner nach einer bestimmten Zeit gelöscht werden soll, hier in Tagen. Beispiel: 1 für ein Löschdatum am nächsten Tag. Alternativ können Sie das Ablaufdatum auch über einen der folgenden Parameter angeben: expirationMillis, expirationSeconds, expirationMinutes, expirationHours, expirationWeeks, expirationMonths, expirationYears.

Beispiel für eine in der Anfrage übergebene JSON-Struktur:

{
  "type": "folder",
  "name": "test-folder3",
  "target": "/agorum/roi/Files",
  "metadata": {
    "identifier": "test"
  }
}

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die UUID des neu erstellten Ordners.

Beispiel für eine zurückgegebene Struktur:

"9c392ab0-15ed-11f0-8281-00007f000101"

POST object (structure)

Über die POST-Anfrage object (structure) können Sie eine Struktur auf Basis einer agorum core smart assistant (ASA) Konfiguration für eine Anlage erstellen, siehe Elemente im smart assistant konfigurator anlegen - Anlage. Sie benötigen dafür den Namen der Strukturdefinition im ASA-Konfigurator.

Anfrageparameter (JSON):

type (String, erforderlich): Der Typ muss den Wert 'structure' haben, um eine Ablagestruktur zu erstellen.
name (String, erforderlich): Der Name der Strukturdefinition. Beispiel: agorum.hl.test.structure
target (String, optional): Der Pfad, unter dem der Ordner erzeugt werden soll (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Metadaten, die auf den Ordner gesetzt werden sollen, als Schlüssel-Wert-Paare, Beispiel: {"identifier":"test"}

Hinweis: Ob die Angabe von target und metadata sinnvoll ist, ist abhängig von der Strukturdefinition.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die UUID des neu erstellten Objekts.

Beispiel für eine zurückgegebene Struktur:

"e6224970-204e-11f0-8480-00007f000101"

POST object (upload)

Über die POST-Anfrage object (upload) können Sie Dateien neu in agorum core hochladen. Dazu müssen Sie neben der Datei selbst nur den Zielordner angeben.

Wenn Sie eine vorhandene Datei aktualisieren wollen, verwenden Sie dazu PUT object (form-data).

Anfrage-Body (form-data):

type (String, empfohlen): Der Typ muss den Wert 'file' haben, um eine Datei hochzuladen. Der Wert ist standardmäßig gesetzt.
name (String, empfohlen): Der Name der Datei. Standardmäßig wird der Name der hochgeladenen Datei verwendet.
content (File, erforderlich): Die Datei, die hochgeladen werden soll.
target (String, erforderlich): Der Pfad, in den die Datei hochgeladen werden soll (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Metadaten, die auf die Datei gesetzt werden sollen, als Schlüssel-Wert-Paare, Beispiel: {"identifier":"test"}
expirationYears (Ganzzahl, optional): Optionale Festlegung, wenn die Datei nach einer bestimmten Zeit gelöscht werden soll, hier in Jahren. Beispiel: 1 für ein Löschdatum in einem Jahr. Alternativ können Sie das Ablaufdatum auch über einen der folgenden Parameter angeben: expirationMillis, expirationSeconds, expirationMinutes, expirationHours, expirationDays, expirationWeeks, expirationMonths.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die UUID des neu erstellten Ordners.

Beispiel für eine zurückgegebene Struktur:

"9c392ab0-15ed-11f0-8281-00007f000101"

GET object

Die GET-Anfrage object mit ihren Anfrageparametern dient dazu, Informationen über ein Objekt abzufragen. Für die Abfrage ist nur die Angabe des Objekts über die ID, UUID oder den Pfad erforderlich. Die weiteren Parameter geben an, welche Informationen zusätzlich zur ID des Objekts zurückgeliefert werden sollen.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Sie können angeben, welche Metadaten in der Rückgabe enthalten sein sollen. Dazu können Sie den Parameter mehrfach angeben. Dies entspricht der Funktion metadata().load(). Beispiel-Werte: '~', '~~', '/expiration/i'.
inherited (String, optional): Sie können angeben, ob vererbte Metadaten in der Rückgabe enthalten sein sollen. Dazu können Sie den Parameter mehrfach angeben. Dies entspricht der Funktion metadata.all(). Beispiel-Werte: '~', '~~'.
expirationDays (Boolean, optional): Wenn Sie den Ablaufzeitraum in der Rückgabe erhalten wollen, können Sie dies über expirationDays oder alternativ expirationMillis, expirationSeconds, expirationMinutes, expirationHours, expirationWeeks, expirationMonths, expirationYears angeben.
paths (String, optional): Sie können angeben, ob die Ablagepfade des Objekts zurückgegeben werden sollen. Der Wert gibt an, ab welchem Basispfad der Pfad angegeben werden soll. Sie können den Parameter paths mehrfach angeben, um den Pfad ausgehend von verschiedenen Basispfaden zu erhalten. Beispiel: '/'
property (String, optional): Wenn Sie Informationen über Propertys des Objekts erhalten wollen, können Sie das über die Werte von property angeben. Dazu können Sie den Parameter mehrfach angeben. Beispiele: 'isFolder', 'className'

Beispiel für eine Objektanfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.object?id=/agorum/roi/Files/test-folder&metadata=~&metadata=~~&metadata=/expiration/i&inherited=~~&expirationHours=true&paths=/&paths=/agorum/roi/Files&property=isFolder&property=className

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur mit dem Ergebnis zurück.

Antwortparameter:

id (String): UUID des Objekts
metadata: Liste der angefrageten Metadaten
expirationDays: Anzahl der Tage bis zum Ablaufdatum, wenn die Angabe angefragt wurde. Abhängig von der Anfrage auch expirationMillis, expirationSeconds, expirationMinutes, expirationHours, expirationWeeks, expirationMonths, expirationYears.
paths: Angefragte Pfadangaben.
property: Angefragte Propertys.
inherited: Angefragte vererbte Metadaten.

Beispiel für eine zurückgegebene JSON-Struktur:

{
    "metadata": {
        "identifier": "test",
        "expirationDate": "2025-04-11T09:24:32.104Z"
    },
    "expirationDays": 0,
    "inherited": {
        "area": [
            "Files"
        ],
        "identifier": "test"
    },
    "paths": {
        "/agorum": [
            "/roi/Files/test-folder"
        ]
    },
    "property": {
        "isFolder": true,
        "className": "FOLDEROBJECT"
    },
    "id": "9c392ab0-15ed-11f0-8281-00007f000101"
}

GET object/items

Die GET-Anfrage object/items mit ihren Anfrageparametern dient dazu, Informationen über die Elemente innerhalb eines Objekts abzufragen. Für die Abfrage ist nur die Angabe des Objekts über die ID, UUID oder den Pfad erforderlich. Die weiteren Parameter geben an, welche Informationen zusätzlich zur ID der Elemente zurückgeliefert werden sollen.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Sie können angeben, welche Metadaten in der Rückgabe enthalten sein sollen. Dazu können Sie mehrere Parameter-Wert-Paare angeben. Beispiel-Werte: '~', '~~', 'expiration/i'.
inherited (String, optional): Sie können angeben, ob vererbte Metadaten in der Rückgabe enthalten sein sollen. Sie können den Parameter mehrfach angeben. Beispiel-Werte: '~', '~~'.
expirationDays (Boolean, optional): Wenn Sie den Ablaufzeitraum in der Rückgabe erhalten wollen, können Sie dies über expirationDays oder alternativ expirationMillis, expirationSeconds, expirationMinutes, expirationHours, expirationWeeks, expirationMonths, expirationYears angeben.
paths (String, optional): Sie können angeben, ob die Ablagepfade des Objekts zurückgegeben werden sollen. Der Wert gibt an, ab welchem Basispfad der Pfad angegeben werden soll. Sie können den Parameter paths mehrfach angeben, um den Pfad ausgehend von verschiedenen Basispfaden zu erhalten. Beispiel: '/'
property (String, optional): Wenn Sie Informationen über Propertys des Objekts erhalten wollen, können Sie das über die Werte von property angeben. Dazu können Sie den Parameter mehrfach angeben. Beispiele: 'isFolder', 'className'

Beispiel für eine Anfrage nach Objektelementen:

https://<agorum-core-server>/api/rest/custom/agorum.hl.object/items?id=/agorum/roi/Files&metadata=~&metadata=name&expirationMinutes=true

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur mit dem Ergebnis zurück.

Antwortparameter für jedes Element:

id (String): UUID des Objekts
metadata: Liste der angefrageten Metadaten
expirationDays: Anzahl der Tage bis zum Ablaufdatum, wenn die Angabe angefragt wurde. Abhängig von der Anfrage auch expirationMillis, expirationSeconds, expirationMinutes, expirationHours, expirationWeeks, expirationMonths, expirationYears.
paths: Angefragte Pfadangaben.
property: Angefragte Propertys.
inherited: Angefragte vererbte Metadaten.

Beispiel für eine zurückgegebene JSON-Struktur:

[
    {
        "metadata": {
            "name": "DemoWorkflows"
        },
        "id": "dc7a7530-6c6e-11ef-b01a-00007f000101"
    },
    {
        "metadata": {
            "name": "Demo"
        },
        "id": "24c0cec0-6c6f-11ef-b01a-00007f000101"
    }
]

GET object/history

Die GET-Anfrage object/history mit ihren Anfrageparametern dient dazu, Informationen über die Historie eines Objekts abzufragen. Für die Abfrage ist nur die Angabe des Objekts über die ID, UUID oder den Pfad erforderlich. Die weiteren Parameter geben an, welche Informationen zusätzlich zur ID zurückgeliefert werden sollen.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Sie können angeben, welche Metadaten in der Rückgabe enthalten sein sollen. Dazu können Sie mehrere Parameter-Wert-Paare angeben. Beispiel-Werte: '~', '~~', 'expiration/i'.
inherited (String, optional): Sie können angeben, ob vererbte Metadaten in der Rückgabe enthalten sein sollen. Sie können den Parameter mehrfach angeben. Beispiel-Werte: '~', '~~'.
property (String, optional): Wenn Sie Informationen über Propertys des Objekts erhalten wollen, können Sie das über die Werte von property angeben. Dazu können Sie den Parameter mehrfach angeben. Beispiele: 'createDate', 'lastModifyDate'

Beispiel für eine Objekthistorienanfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.object/history?id=/agorum/roi/Files/test-folder/test-file.txt&metadata=name&property=createDate&property=lastModifyDate

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur mit dem Ergebnis zurück.

Antwortparameter für jeden Eintrag in der Historie:

id (String): UUID des Objekts
metadata: Liste der angefrageten Metadaten
property: Angefragte Propertys.
inherited: Angefragte vererbte Metadaten.

Beispiel für eine zurückgegebene JSON-Struktur:

[
    {
        "metadata": {
            "name": "test.txt"
        },
        "property": {
            "lastModifyDate": "2025-04-10T13:05:39.287Z",
            "createDate": "2025-04-10T13:04:59.113Z"
        },
        "id": "96d140c1-160c-11f0-8281-00007f000101"
    },
    {
        "metadata": {
            "name": "test-file.txt"
        },
        "property": {
            "lastModifyDate": "2025-04-10T13:07:53.925Z",
            "createDate": "2025-04-10T13:04:59.113Z"
        },
        "id": "388f3d30-160e-11f0-8281-00007f000101"
    }
]

GET object/content

Die GET-Anfrage object/content dient dazu, den Inhalt einer Datei abzufragen. Für die Abfrage ist nur die Angabe der Datei über die ID, UUID oder den Pfad erforderlich.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).

Beispiel für eine Dateianfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.object/content?id=/agorum/roi/Files/test-folder/test.txt

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und den Inhalt des angegebenen Objekts zurück.

Beispiel für eine zurückgegebene Datei in Postman:

Anzeige der abgefragten PDF-Datei in Postman

GET object/content/pdf

Die GET-Anfrage object/content/pdf dient dazu, den Inhalt einer Datei nach PDF zu konvertieren und den PDF-Inhalt abzufragen. Für die Abfrage ist nur die Angabe des Objekts über die ID, UUID oder den Pfad erforderlich.

Für die Anfrage ist es notwendig, dass agorum core das entsprechende Dateiformat in das PDF-Format konvertieren kann.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).

Beispiel für die Anfrage einer nach PDF konvertierten Datei:

https://<agorum-core-server>/api/rest/custom/agorum.hl.object/content/pdf?id=/agorum/roi/Files/test-folder/test.txt

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und den Inhalt des angegebenen Objekts im Format PDF zurück.

Beispiel für eine zurückgegebene Datei in Postman:

Anzeige der nach PDF konvertierten Datei in Postman

PUT object (form-data)

Die PUT-Anfrage object (form-data) können Sie verwenden, um die Daten eines in agorum core vorhandenen Objekts zu bearbeiten, zum Beispiel um ein Dokument zu ersetzen oder um weitere Metadaten hinzuzufügen oder vorhandene Metadaten zu ändern. Sie müssen dazu das Objekt angeben, das Sie verändern wollen, sowie die zu verändernden Daten.

Anfrage-Body (form-data):

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Metadaten, die auf das Objekt gesetzt werden sollen, als Schlüssel-Wert-Paare, Beispiel: {"identifier":"test"}
content (File, optional): Die Datei, die hochgeladen werden soll.

Im Erfolgsfall erhalten Sie den Rückgabewert 200, die Objektdaten wurden geändert.

PUT object (JSON, shared lock)

Mit der POST-Anfrage object (JSON, shared lock) können Sie den Sperrstatus eines Objekts in agorum core setzen und optional zusätzlich Metadaten angeben. Zum Sperren oder Entsperren eines Objekts können Sie den Sperrstatus über den Lock-Type angeben.

Anfrageparameter (JSON):

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).
metadata (String, optional): Metadaten, die auf das Objekt gesetzt werden sollen, als Schlüssel-Wert-Paare, Beispiel: {"identifier":"test"}
lock (Objekt, erforderlich):
Sie können einen der folgenden Werte für type angeben, für weitere Informationen siehe Sperrstatus und Besitzer.
- none: Nicht gesperrt
- hard: Hardlock
- session:Gesperrt für Session
- shared: Geteilte Sperre
Der Angabe des identifier ist für den Sperrstatus shared erforderlich. Dieser Status kann von Programmen gesetzt werden, die paralleles Editieren erlauben. Ein Beispielwert ist "onlyoffice". Der Wert gibt an, dass das entsprechende Dokument von einem oder mehreren Benutzern gleichzeitig in OnlyOffice editiert wird. Die Unterstützung für das parallele Editieren muss das externe Programm bieten und den identifier setzen.

Beispiel für eine in der Anfrage übergebene JSON-Struktur:

{
    "id": "/agorum/roi/Files/test-folder",
    "lock": {
        "type": "shared",
        "identifier": "lock.identifier"
    }
}

Im Erfolgsfall erhalten Sie den Rückgabewert 200, der Sperrstatus wurde geändert.

DELETE object

Mit der DELETE-Anfrage object können Sie ein Objekt in agorum core löschen.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID), das gelöscht werden soll.
skipTrash (Boolescher Wert, optional): Wenn Sie den Wert true angeben, wird das angegebene Objekt ohne Papierkorb gelöscht.

Im Erfolgsfall erhalten Sie den Rückgabewert 200, das Objekt wurde gelöscht.

Service für die Suche

GET search

Die search-Anfrage mit ihren Anfrageparametern dient dazu, benutzerdefinierte Suchergebnisse abzurufen. Der query-Parameter mit der Suchanfrage muss angegeben werden. Verwenden Sie hier eine von agorum core unterstützte Suche und berücksichtigen Sie die zu erwartende Zahl an Suchtreffern, um das System nicht zu überlasten.

Anfrageparameter:

query (String´, erforderlich): Die Suchanfrage.
fields (Array von Strings, optional): Die Felder, die in der Antwort enthalten sein sollen.
limit (Ganzzahl, optional): Die maximale Anzahl der zurückzugebenden Ergebnisse.
cursor (String, optional): Der Cursor zur Paginierung der Ergebnisse.
facets (Objekt, optional): Konfiguration für die facettierte Suche.
highlights (Objekt, optional): Konfiguration für die Hervorhebung von Suchergebnissen.
includeHidden (Boolean, optional): Flag, um versteckte Elemente in die Antwort einzubeziehen.
sort (String, optional): Die Sortierkonfiguration für die Ergebnisse.

Beispiel für eine Suchanfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.search?query=*&fields=uuid&fields=name&limit=10&cursor=*&facets={"max":"max(contentsize)","min":"min(contentsize)"}&highlights={"limit":5,"field":["content"]}&includeHidden=true&sort=nameextension asc&sort=name desc

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur mit dem Ergebnis zurück.

Antwortparameter:

nextCursor (String): Der Cursor für den nächsten Satz von Ergebnissen, falls verfügbar.
total (Ganzzahl): Die Gesamtanzahl der Ergebnisse.
highlights (Objekt): Ein Objekt, das hervorgehobene Inhalte für bestimmte Elemente enthält.
rows (Array von Objekten): Enthält die in der Anfrage angeforderten Felder jedes Suchergebnisses.
facetFields (Array von Objekten oder Nullwert): Facettenfelder oder Nullwert, der anzeigt, dass keine Facettenfelder vorhanden sind.
facets (Objekt): Ein Objekt mit den Feldern "min", "max" und "count", die die Facetteninformationen darstellen.

Beispiel für eine zurückgegebene JSON-Struktur:

{
    "nextCursor": "AoMAOMO8YmVyd2FjaHVuZyB1bmQgbWVzc3VuZz8FMjRlMGQ5ZTAtNmM2Zi0xMWVmLWIwMWEtMDAwMDdmMDAwMTAx",
    "total": 43599,
    "highlights": {
        "24e2aea0-6c6f-11ef-b01a-00007f000101": {
            "content": []
        },
        "24e23970-6c6f-11ef-b01a-00007f000101": {
            "content": []
        },
        "24e0d9e0-6c6f-11ef-b01a-00007f000101": {
            "content": []
        }
    },
    "rows": [
        {
            "name": "Überwachung und Messung von Prozessen",
            "uuid": "24e23970-6c6f-11ef-b01a-00007f000101"
        },
        {
            "name": "Überwachung und Messung von Produkten",
            "uuid": "24e2aea0-6c6f-11ef-b01a-00007f000101"
        },
        {
            "name": "Überwachung und Messung",
            "uuid": "24e0d9e0-6c6f-11ef-b01a-00007f000101"
        }
    ],
    "facetFields": null,
    "facets": {
        "min": 0,
        "max": 83759774,
        "count": 43599
    }
}

Services für Preview-Dokumente

GET preview

Die preview-Anfrage liefert Informationen über die Vorschau einer bestimmten Datei, die mit ID (Pfad, UUID oder ID) angegeben werden muss.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner der Datei (vollständiger Pfad, UUID oder ID).
size (Zahl, optional): Die Größe der Vorschau.

Beispiel für eine Preview-Anfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.preview?id=/agorum/roi/Files/Demo/Willkommen.pdf&size=400

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur mit der Anzahl der Seiten in der Dateivorschau zurück.

Beispiel für eine zurückgegebene JSON-Struktur:

{
    "pages": 1
}

GET preview (download)

Die preview (download)-Anfrage liefert den Inhalt der Vorschau einer bestimmten Seite einer Datei als JGP-Image zurück. Die ID der Datei (Pfad, UUID oder ID) und die Seitenzahl müssen angegeben werden.

Anfrageparameter:

id (String, erforderlich): Der eindeutige Bezeichner der Datei (vollständiger Pfad, UUID oder ID).
page (Ganzzahl, erforderlich): Die Seitenzahl der Datei.
size (Zahl, optional): Die Größe der Vorschau.

Beispiel für eine Preview-Anfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.preview?id=/agorum/roi/Files/Demo/Willkommen.pdf&page=1&size=400

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die JPG-Binärdaten zurück.

Services für die Verwaltung von gelöschten Objekten/Papierkorb

GET trash

Die GET-Anfrage trash ermöglicht das Abfragen von gelöschten Objekten aus agorum core.

Anfrageparameter:

limit (Ganzzahl, optional): Begrenzung der Anzahl der abzurufenden Elemente.
fields (Array von Strings, optional): Die Felder, die in der Antwort enthalten sein sollen.
sort (String, optional): Sortierung der Elemente nach dem Löschdatum in absteigender Reihenfolge.

Beispiel für eine Trash-Anfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.trash?limit=10&fields=uuid&fields=deletedinfolder_uuid&fields=name&sort=deletedate desc

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die Ergebnisliste in einer JSON-Struktur zurück.

Antwortparameter:

nextCursor (String): Ein Cursor für die Paginierung, falls zutreffend.
total (Ganzzahl): Gesamtanzahl der Elemente in der Antwort.
rows (Array): Ein Array von Objekten, das die in der Anfrage angeforderten Felder jedes Suchergebnisses enthält.
facetFields (Array von Objekten): Facettenfelder oder Nullwert, der anzeigt, dass keine Facettenfelder vorhanden sind.
facets (Objekt): Ein Objekt mit den Feldern "min", "max" und "count", die die Facetteninformationen darstellen.

Beispiel für eine zurückgegebene JSON-Struktur:

{
    "nextCursor": null,
    "total": 16,
    "highlights": null,
    "rows": [
        {
            "deletedinfolder_uuid": [
                "714f1580-ce62-11e0-b47a-0800276e2399"
            ],
            "name": "test-folder",
            "uuid": "26faf4a0-1452-11f0-8281-00007f000101"
        },
        {
            "deletedinfolder_uuid": [
                "39bde290-6c6f-11ef-b01a-00007f000101"
            ],
            "name": "combi-elements",
            "uuid": "39bf1b10-6c6f-11ef-b01a-00007f000101"
        }
    ],
    "facetFields": null,
    "facets": null
}

POST trash (restore)

Mit der POST-Anfrage trash (restore) können Sie gelöschte Objekte wiederherstellen. Dazu müssen Sie mindestens die ID (UUID, ID oder Pfad) des Objekts angeben, das wiederhergestellt werden soll.

Anfrage-Body (form-data):

id (String, erforderlich): Der eindeutige Bezeichner des Objekts (vollständiger Pfad, UUID oder ID).
target (String, optional): Der eindeutige Bezeichner des Ordners (vollständiger Pfad, UUID oder ID), in dem das Objekt wiederhergestellt werden soll.

Im Erfolgsfall erhalten Sie den Rückgabewert 200, das Objekt wurde wiederhergestellt.

Services für Workflow-Instanzen

POST workflow/start

Mit der POST-Anfrage workflow/start können Sie einen Workflow starten. Dazu müssen Sie mindestens den Workflow angeben, von dem eine Instanz gestartet werden soll.

Anfrage-Body (form-data):

Objekt, das den zu startenden Workflow und optionale Startvariablen enthält.

workflow (String, erforderlich): Der eindeutiger Bezeichner des Workflows. Geben Sie den vollständigen Pfad zu einem Workflow oder die UUID der Workflow-Definition an. Beispiel:
```
/agorum/roi/customers/agorum.hl/test/workflows/agorum.hl.test/definition.acwd
```
variables (Array, optional): Sie können optional eine oder mehrere Variablen für die Workflow-Instanz angeben, als Schlüssel-Wert-Paare, Beispiel: {"variable":"value"}

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die UUID der gestarteten Workflow-Instanz zurück.

POST workflow/run

Mit der POST-Anfrage workflow/run können Sie ebenso wie mit POST workflow/start einen Workflow starten. Der Unterschied besteht darin, dass Sie workflow/run zum Ausführen eines Workflows nur benutzen können, wenn es sich um einen nicht interaktiven Workflow handelt, also wenn der Workflow keine UI-Oberfläche verwendet und kein Workflow-Log notwendig ist. Es werden also nur Workflows unterstützt, die vollständig durchlaufen und alle erzeugten Tokens beenden.

Um den Worklfow auszuführen, müssen Sie mindestens den Workflow angeben, von dem eine Instanz ausgeführt werden soll.

Anfrage-Body (form-data):

Objekt, das den zu startenden Workflow und optionale Startvariablen enthält.

workflow (String, erforderlich): Der eindeutiger Bezeichner des Workflows. Geben Sie den vollständigen Pfad zu einem Workflow oder die UUID der Workflow-Definition an. Beispiel:
```
/agorum/roi/customers/agorum.doc.test/workflows/agorum.doc.test.wftest/definition.acwd
```
variables (Array, optional): Sie können optional eine oder mehrere Variablen für die Workflow-Instanz angeben, als Schlüssel-Wert-Paare, Beispiel: {"variable":"value"}

Im Erfolgsfall erhalten Sie den Rückgabewert 200 zurück, die Workflow-Instanz wurde ausgeführt. Wenn Sie versuchen, einen Workflow mit einer UI-Oberfläche zu starten, erhalten Sie den Rückgabewert 500 mit folgender Meldung: interactive workflows may not be started using workflow.run()

GET workflow/tokens

Mit der GET-Anfrage workflow/tokens können Sie die Tokens einer Workflow-Instanz abfragen. Dazu müssen Sie mindestens die Workflow-Instanz angeben, von der die Tokens zurückgegeben werden sollen.

Anfrage-Body (form-data):

id (String, erforderlich): Eindeutiger Bezeichner der Workflow-Instanz (UUID).

Beispiel für eine Tokens-Anfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.workflow/tokens?id=bb567c90-161f-11f0-8281-00007f000101

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die UUIDs der Workflow-Tokens zurück.

GET workflow

Mit der GET-Anfrage workflow können Sie über die Angabe eines Workflow-Tokens Informationen zum dazugehörigen Workflow abfragen. Dazu müssen Sie mindestens das Workflow-Token angeben, dessen Workflow-Informationen Sie abfragen wollen.

Anfrage-Parameter:

id (String, erforderlich): Eindeutiger Bezeichner des Workflow-Tokens (UUID).

Beispiel für eine Workflow-Anfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.workflow?id=691683a3-7a7c-4d04-bb3e-b998564d9045

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und Informationen zum Workflow nach folgendem Muster zurück:

{
  "sys_acw_trigger": true,
  "sys_acw_interaction": "ui",
  "sys_acw_processName": "agorum.hl.test",
  "sys_acw_stepDisplayName": "ui",
  "sys_acw_processId": "18ae3eb5-be00-4437-9d50-8df0b17b3a0c",
  "sys_acw_stepDescription": "",
  "sys_acw_attachments": [],
  "sys_acw_stepName": "ui",
  "_sys_acw_parameters": {
    "version_interaction_assign": 1
  },
  "sys_acw_internal": {

  }
}

Services für Workflow-Token

GET workflow/instance

Mit der GET-Anfrage workflow/instance können Sie die Workflow-Instanz zu einem Workflow-Token abfragen. Dazu müssen Sie mindestens das Workflow-Token angeben, dessen Workflow-Instanz Sie abfragen wollen.

Anfrage-Parameter:

id (String, erforderlich): Eindeutiger Bezeichner des Workflow-Tokens (UUID).

Beispiel für eine Instanz-Anfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.workflow/instance?id=2fda394b-edb5-439b-aafa-b1b369e548cc

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und die UUID der Workflow-Instanz zurück.

GET workflow

Anfrage-Parameter:

id (String, erforderlich): Eindeutiger Bezeichner des Workflow-Tokens (UUID).

Beispiel für eine Instanz-Anfrage:

https://<agorum-core-server>/api/rest/custom/agorum.hl.workflow?id=2fda394b-edb5-439b-aafa-b1b369e548cc

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und Informationen zum Workflow nach folgendem Muster zurück.

Beispiel für eine zurückgegebene JSON-Struktur:

{
    "writeReleasedStateMap": {
        "escalation": "escalation",
        "notReleased": "notReleased",
        "released": "released"
    },
    "sys_acw_processName": "agorum.workflow.releaseXEyes",
    "sys_acw_stepDisplayName": "agorum.workflow.translation.auto.agorum_workflow_releaseXEyes.uiReleaseInfo.displayName",
    "sys_acw_processId": "f5abb5cb-d6e0-439d-86e4-90ef2c6703a5",
    "sys_acw_attachments": [],
    "writeReleasedStateTo": "agorum_workflow_releasexeyes_releasedState",
    "notReleaseRecipient": [],
    "sys_acw_assignee": "714614d0-ce62-11e0-b47a-0800276e2399",
    "releaseId": "2fda394b-edb5-439b-aafa-b1b369e548cc",
    "stepsList": [
        {}
    ],
    "sys_acw_substitutes": [
        "1291800"
    ],
    "sys_acw_stepDescription": "",
    "sys_acw_acls": [
        "20654f60-0fab-11f0-8281-00007f000101"
    ],
    "_sys_acw_parameters": {
        "autoAcquire": true,
        "aguila": "4e368190-0fa9-11f0-8281-00007f000101"
    },
    "escalationRecipient": [],
    "sys_acw_internal": {
        "viewers": [],
        "substitutes": [
            {
                "attachmentPermission": "read",
                "id": "714614d0-ce62-11e0-b47a-0800276e2399"
            }
        ],
        "assignees": [
            {
                "attachmentPermission": "read",
                "id": "714614d0-ce62-11e0-b47a-0800276e2399"
            }
        ]
    },
    "creator": "714614d0-ce62-11e0-b47a-0800276e2399",
    "sys_acw_interaction": "ui",
    "releaseRecipientAttachmentPermission": "read",
    "stepRecipientAttachmentPermission": "read",
    "escalationRecipientAttachmentPermission": "read",
    "releaseRecipient": [],
    "notReleaseRecipientAttachmentPermission": "read",
    "sys_acw_stepName": "uiReleaseInfo",
    "sys_acw_attachmentPermissionRead": [
        "206109a0-0fab-11f0-8281-00007f000101",
        "206109a0-0fab-11f0-8281-00007f000101"
    ],
    "sys_acw_processDisplayName": "agorum.workflow.translation.auto.agorum_workflow_releaseXEyes.workflow.displayName",
    "sys_acw_assignees": [
        "1291800"
    ]
}

PUT workflow

Mit der PUT-Anfrage workflow können Sie Variablen für eine Workflow-Instanz setzen oder aktualisieren.

Anfrage-Body (form-data):

Der Anfrage-Body muss ein Objekt enthalten, das die ID der Instanz und die zu setzenden Variablen enthält.

id (String, erforderlich): Eindeutiger Bezeichner des Workflow-Tokens (UUID).
variables (Objekt, erforderlich): Ein Objekt mit den Schlüssel-Wert-Paaren der zu setzenden Variablen. Beispiel:
```
{"sys_acw_trace":"true"}
```

Im Erfolgsfall erhalten Sie den Rückgabewert 200 zurück. Die Variablen wurden erfolgreich aktualisiert.

Services für Workflow-UIs

Diese Services bieten Ihnen die Möglichkeit zur Steuerung von Workflows entsprechend den Funktionen der JavaScript-Bibliothek agorum.dev/js/lib/workflow.

POST workflow/acquire

Mit der POST-Anfrage workflow/acquire können Sie einen Workflow-Schritt mit einem UI-Knoten annehmen und übernehmen und damit sperren.

Anfrage-Body (form-data):

Objekt, das die ID des Knotens/Tokens und eine optionale 'force'-Option enthält.

id (String, erforderlich): Token-ID des übernommenen Tokens.
force (Boolescher Wert, optional): Erzwingt ggf. die Übernahme von einem abweichenden Benutzer.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und den Status true zurück: Der UI-Knoten ist für die weitere Bearbeitung durch Sie gesperrt. Wenn der Knoten durch einen anderen Benutzer gesperrt ist, erhalten Sie den Rückgabewert 409 mit zusätzlichen Informationen.

POST workflow/release

Mit der POST-Anfrage workflow/release können Sie einen zuvor gesperrten UI-Knoten wieder freigeben.

Anfrage-Body (form-data):

Objekt, das die ID des Knotens/Tokens enthält, der freigegeben werden soll.

id (String, erforderlich): Token-ID des Tokens/Knotens, dessen Sperre aufgehoben werden soll.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und den Status true zurück. Der UI-Knoten ist für die Bearbeitung wieder freigegeben.

POST workflow/save

Mit der POST-Anfrage workflow/save können Sie die Variablen eines gesperrten UI-Knotens speichern, ohne den Knoten zu verlassen.

Anfrage-Body (form-data):

Objekt, das die ID des Knotens/Tokens und die zu speichernden Variablen enthält.

id (String, erforderlich): Token-ID des Tokens/Knotens, dessen Variablen gespeichert werden sollen.
variables (Objekt, erforderlich): Ein Objekt mit den Schlüssel-Wert-Paaren der zu setzenden Variablen. Beispiel:
```
{"structureTaskComment": "bearbeitet von roi"}
```

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und den Status true zurück. Die Variablen wurden gespeichert.

POST workflow/leave

Mit der POST-Anfrage workflow/leave können Sie einen UI-Knoten über ein Outlet verlassen und optional Variablen speichern. Das ist vergleichbar mit dem Bearbeiten und Beenden der UI durch einen Benutzer. Der Workflow wird dadurch fortgesetzt.

Anfrage-Body (form-data):

Objekt, das die ID, das Outlet und optional zu speichernde Variablen enthält.

id (String, erforderlich): Token-ID des Tokens/Knotens, dessen Variablen gespeichert werden sollen.
outlet (String, erforderlich): Name des Outlets, über das der Knoten verlassen wird.
variables (Objekt, optional): Ein Objekt mit den Schlüssel-Wert-Paaren der zu setzenden Variablen. Beispiel:
```
{"structureTaskComment": "bearbeitet!"}
```

Service für delay/wait

POST workflow/trigger

Mit der POST-Anfrage workflow/trigger können Sie einen Workflow über das Workflow-Token triggern, damit der Workflow fortgesetzt wird, wenn der Workflow einen delay-Knoten enthält.

Anfrage-Body (form-data):

Objekt, das die ID des auszulösenden Knotens/Tokens enthält.

id: Token-ID des Tokens, das angestoßen werden soll.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und einen Booleschen Wert, der angibt, ob der Workflow erfolgreich angestoßen werden konnte.