Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

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

NORA | 360° REST-API

Das Plugin NORA | 360° (Projekt agorum.smartorga) wird mit einer REST-Schnittstelle ausgeliefert, die den kompletten Funktionsumfang der NORA | 360° AI Tools auch für externe Systeme über HTTP verfügbar macht

Verwendung der NORA | 360° REST-API

Mit der REST-API können Sie:

Tipp: Zur einfachen Verwendung der REST-Schnittstelle finden Sie im Projektverzeichnis unter doc/NORA 360 REST-API.postman_collection.json eine Postman-Collection, die Sie direkt in Postman importieren können. Sie enthält alle Endpunkte mit Beispiel-Anfragen und -Bodies.

Bearer Token

Zur Verwendung der REST-API benötigen Sie ein JWT-Token. Dieses Token können Sie in agorum core über den JWT-Generator (Administration > Werkzeuge > JWT-Generator) erzeugen oder programmatisch über die JavaScript-Bibliothek common/jwt.

Sie müssen das Token bei jeder Anfrage im HTTP-Header Authorization mitgeben:

Authorization: Bearer <jwt-token>

Basispfad

Die Schnittstelle ist erreichbar unter:

{{agorum-core-server}}/api/rest/custom/agorum.smartorga.<service>

Beispiel: https://mein-server/api/rest/custom/agorum.smartorga.search

Verwendung in Postman

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

  1. Installieren Sie Postman.
  2. Laden Sie die Collection herunter.
  3. Importieren Sie die Collection.
  4. 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.
  5. 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.
  6. Tragen Sie unter Authorization > Token (bei vorausgewähltem Auth Type Bearer Token) das soeben generierte Token ein.
  7. 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 HTTP-Statuscodes:

Erfolgreiche Anfragen liefern in der Regel eine JSON-Struktur zurück. Anlage- und Update-Operationen antworten stets mit einer minimalen Struktur:

{
  "uuid": "<uuid-des-objekts>",
  "name": "<object.name>"
}

 

Hinweis zum name-Feld: Der zurückgegebene name entspricht dem object.name nach dem Speichern. Das ist je nach Objekttyp ein unterschiedlicher Wert:

Verlassen Sie sich in Skripten daher immer auf die zurückgegebene uuid, wenn Sie das erzeugte Objekt später wieder ansprechen wollen. Wollen Sie den Anzeigenamen einer Person oder Firma programmatisch ermitteln, verwenden Sie im Anschluss GET object/metadata.

Übersicht der NORA | 360° Services

Die REST-API besteht aus den folgenden Services:

Suche in NORA-Objekten

GET search

Mit der GET-Anfrage agorum.smartorga.search können Sie NORA-Objekte per Solr suchen. Alle Kriterien sind optional und werden mit UND verknüpft. Die Suche bezieht sich immer auf den agorum core Root (inpath:9999).

Hinweis: Die zu suchenden NORA-Objekttypen müssen im System deployt sein. Der aufrufende Benutzer sieht nur Objekte, für die er entsprechende ACL-Berechtigungen und NORA-Suchberechtigung (_search) besitzt.

Anfrageparameter:

GET <agorum-core-server>/api/rest/custom/agorum.smartorga.search
    ?identifier=agorum.smartorga.task
    &metadata=%7B%22agorum_smartorga_status%22%3A%22agorum.smartorga.status.todo%22%7D
    &properties=acso2_name
    &properties=acso2_number
    &limit=20
    &sort=lastmodifydate%20desc

Beispiel – Antwort:

{
  "total": 3,
  "query": "inpath:9999 identifier_ci:\"agorum.smartorga.task\" agorum_smartorga_status:agorum.smartorga.status.todo",
  "rows": [
    { "uuid": "...", "acso2_name": "Angebot prüfen", "acso2_number": "T-0001" },
    { "uuid": "...", "acso2_name": "Termin bestätigen", "acso2_number": "T-0002" },
    { "uuid": "...", "acso2_name": "Rechnung freigeben", "acso2_number": "T-0003" }
  ]
}

Beispiel – Nur die Trefferzahl abfragen:

GET <agorum-core-server>/api/rest/custom/agorum.smartorga.search?identifier=agorum.smartorga.customer&total=true
{
  "total": 42,
  "query": "inpath:9999 identifier_ci:\"agorum.smartorga.customer\""
}

Beispiel – Alle Kunden unterhalb eines bestimmten Ablagebereichs mit einer freien Solr-Abfrage:

GET <agorum-core-server>/api/rest/custom/agorum.smartorga.search
    ?identifier=agorum.smartorga.crm.customer
    &parent=e13f6820-8128-11f1-8046-02420a0a0012
    &query=acso2_name%3AMuster*

 

NORA-Objekte anlegen, aktualisieren und Metadaten lesen

Der Service agorum.smartorga.object deckt drei Operationen ab: Anlegen (POST), Aktualisieren (PUT) und Lesen von Metadaten (GET /metadata).

POST object (create)

Mit der POST-Anfrage agorum.smartorga.object legen Sie ein neues NORA-Objekt eines beliebigen Typs an.

Voraussetzungen:

Anfrage-Body (JSON):

Beispiel – Neue Aufgabe anlegen:

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.object
Content-Type: application/json

{
  "identifier": "agorum.smartorga.task",
  "target": "<uuid-der-task-area>",
  "acso2_name": "Angebot prüfen",
  "data": {
    "agorum_smartorga_status": "agorum.smartorga.status.todo",
    "agorum_smartorga_priority": "agorum.smartorga.priority.03"
  }
}

Beispiel – Antwort:

{
  "uuid": "7f929a00-fb8d-11f0-a330-02420a0a0013",
  "name": "Angebot prüfen (TSK113)"
}

Hinweis: Der zurückgegebene name entspricht dem endgültigen object.name nach dem Speichern, inklusive der vergebenen Nummer (z. B. (TSK113)). Er weicht damit typischerweise vom übergebenen acso2_name ab.

PUT object (update)

Mit der PUT-Anfrage agorum.smartorga.object aktualisieren Sie die Metadaten eines vorhandenen NORA-Objekts.

Voraussetzung: Der Benutzer, mit dem das JWT ausgestellt wurde, benötigt Schreibzugriff auf das Objekt.

Anfrage-Body (JSON):

Beispiel – Aufgabe abschließen:

PUT <agorum-core-server>/api/rest/custom/agorum.smartorga.object
Content-Type: application/json

{
  "id": "7f929a00-fb8d-11f0-a330-02420a0a0013",
  "data": {
    "agorum_smartorga_status": "agorum.smartorga.status.done"
  }
}

Beispiel – Antwort:

{
  "uuid": "7f929a00-fb8d-11f0-a330-02420a0a0013",
  "name": "Angebot prüfen (TSK113)"
}

GET object/metadata

Mit der GET-Anfrage agorum.smartorga.object/metadata lesen Sie die Metadaten eines NORA-Objekts. Intern wird das JavaScript-API metadata().load() verwendet.

Anfrageparameter:

Beispiel – Alle NORA-Metadaten eines Objekts abfragen:

GET <agorum-core-server>/api/rest/custom/agorum.smartorga.object/metadata
    ?id=7f929a00-fb8d-11f0-a330-02420a0a0013
    &metadata=%2F%5Eagorum_smartorga_%2F
    &metadata=acso2_name
    &metadata=acso2_number

Beispiel – Antwort:

{
  "id": "7f929a00-fb8d-11f0-a330-02420a0a0013",
  "metadata": {
    "acso2_name": "Angebot prüfen",
    "acso2_number": "T-0001",
    "agorum_smartorga_status": "agorum.smartorga.status.done",
    "agorum_smartorga_priority": "agorum.smartorga.priority.03"
  }
}

 

NORA-Objekte aus Vorlagen erstellen

Der Service agorum.smartorga.template stellt zwei Endpunkte bereit: einen zum Abfragen der Feldinformationen einer Vorlage (GET) und einen zum Anlegen eines Objekts aus der Vorlage (POST).

GET template (info)

Mit der GET-Anfrage agorum.smartorga.template fragen Sie ab, welche Felder eine NORA-Vorlage beim Erstellen erwartet. Dieser Aufruf ist nützlich, bevor Sie ein Objekt aus einer Vorlage erstellen. So wissen Sie, welche Schlüssel Sie in data mitgeben müssen und welche davon Pflicht sind.

Voraussetzung: Die Vorlage muss zuvor über die NORA-Vorlagen-Verwaltung angelegt und für den Benutzer sichtbar sein.

Anfrageparameter:

Beispiel:

GET <agorum-core-server>/api/rest/custom/agorum.smartorga.template?template=<uuid-der-vorlage>

Antwort:

{
  "uuid": "<uuid-der-vorlage>",
  "name": "Neukunden-Prozess",
  "fields": [
    { "key": "Titel",           "required": true,  "type": "agorum.composite.form.element.text" },
    { "key": "Ansprechpartner", "required": false, "type": "agorum.composite.form.element.text" },
    { "key": "Deadline",        "required": false, "type": "agorum.composite.form.element.date" }
  ],
  "usage": "Call nora_create_from_template with the template, the target (UUID/path of the target folder) and a data object. In data, use each field \"key\" as the property name and provide a value. All required fields must be provided."
}

Hinweis: Das Feld usage ist ein interner Hilfstext, der für das gleichnamige NORA AI Tool nora_create_from_template gedacht ist. 

POST template (create from template)

Mit der POST-Anfrage agorum.smartorga.template erstellen Sie ein NORA-Objekt aus einer Vorlage. Platzhalter in der Vorlage (${variable}) werden mit den Werten aus data ersetzt.

Voraussetzungen und Verhalten:

Anfrage-Body (JSON):

Beispiel – Objekt aus Vorlage erstellen:

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.template
Content-Type: application/json

{
  "template": "<uuid-der-vorlage>",
  "target": "<uuid-des-zielordners>",
  "acso2_name": "Neukunde Mustermann",
  "data": {
    "Titel": "Neukunde Mustermann",
    "Ansprechpartner": "Max Mustermann"
  }
}

Antwort:

{
  "uuid": "<uuid-des-neuen-objekts>",
  "name": "Neukunde Mustermann (PRC17)"
}

Tipp: Praxis-Workflow: Rufen Sie zuerst GET template auf, um zu ermitteln, welche Felder Sie ausfüllen müssen. Erst dann rufen Sie POST template mit den passenden Werten auf. Der zurückgegebene name enthält das vom Save-Handler ausgegebene Nummer-Suffix des Wurzelobjekt-Typs (z. B. (PRC17) für einen Vorgang).

Kontaktpersonen anlegen und aktualisieren

Der Service agorum.smartorga.person legt Kontaktpersonen im NORA-Adresssystem an oder aktualisiert sie.

POST person (create)

Mit der POST-Anfrage agorum.smartorga.person legen Sie eine neue Kontaktperson unterhalb eines Business-Objekts (Kunde, Partner, Lieferant) an.

Voraussetzung: Das target muss ein NORA-Business-Objekt (Kunde, Partner, Lieferant) sein. Die Person wird direkt als Kind dieses Business-Objekts angelegt (Metadatum acso2_parent = target). Anders als bei POST/PUT address findet keine automatische Auflösung zur verknüpften Firmenadresse (agorum_smartorga_business_company_address) statt.

Anfrage-Body (JSON):

Beispiel – Ansprechpartner zu einem Kunden anlegen:

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.person
Content-Type: application/json

{
  "target": "<uuid-des-kunden>",
  "salutation": "mr",
  "givenName": "Max",
  "familyName": "Mustermann",
  "title": "Dr.",
  "description": "Ansprechpartner Einkauf"
}

Antwort:

{
  "uuid": "<uuid-der-person>",
  "name": "D4WADDRESSCONTAINER_<interne-nummer>"
}

Hinweis zum name-Feld: Der zurückgegebene name ist ein interner Bezeichner der Form D4WADDRESSCONTAINER_<nummer> und nicht der Anzeigename der Person (Anrede, Titel, Vor-/Nachname). Der eigentliche Anzeigename wird von den zugehörigen Metadaten der Person abgeleitet und ist über GET object/metadata auslesbar. Verlassen Sie sich in Skripten deshalb auf die zurückgegebene uuid.

PUT person (update)

Mit der PUT-Anfrage agorum.smartorga.person aktualisieren Sie eine vorhandene Kontaktperson. Alle Felder außer id sind optional; nur explizit übergebene Felder werden verändert.

Anfrage-Body (JSON):

Beispiel:

PUT <agorum-core-server>/api/rest/custom/agorum.smartorga.person
Content-Type: application/json

{
  "id": "<uuid-der-person>",
  "title": "Prof.",
  "description": "Geschäftsführer"
}

Antwort:

{
  "uuid": "<uuid-der-person>",
  "name": "D4WADDRESSCONTAINER_<interne-nummer>"
}

 

Adressbausteine verwalten

Der Service agorum.smartorga.address legt Adressbausteine (Adressdaten, Telefonnummern, E-Mail-Adressen und Web-Links) an oder aktualisiert sie. Der Bausteintyp wird immer über den Parameter addressType gesteuert.

Mögliche Werte für addressType:

Voraussetzung: Ist das target ein NORA-Business-Objekt (Kunde, Partner, Lieferant), wird intern automatisch die verknüpfte Firmenadresse (Metadatum agorum_smartorga_business_company_address) aufgelöst und der Adressbaustein an dieser angelegt. Existiert am Business-Objekt noch keine Firmenadresse, wird der Baustein direkt am Business-Objekt selbst angelegt. Sie können alternativ auch direkt die UUID einer Firmenadresse oder einer Kontaktperson als target angeben.

Feldnamen der data-Struktur: Die Felder unterhalb von data werden 1:1 an die agorum core JavaScript-API address/objects durchgereicht. Die zulässigen Felder pro addressType sind daher identisch mit zu address/objects beschriebenen Feldern, siehe Verwendbare Objekte. Die in dieser Doku gezeigten Feldnamen (street1, houseNumber1, zip, phoneNumber, mailAddress, link, ...) sind die tatsächlich unterstützten Namen.

POST address (create)

Anfrage-Body (JSON):

Beispiel – Adressdaten zu einem Kunden anlegen (target = Business-Objekt, wird automatisch aufgelöst):

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.address
Content-Type: application/json

{
  "addressType": "data",
  "target": "<uuid-des-kunden>",
  "data": {
    "street1": "Musterstraße",
    "houseNumber1": "42",
    "zip": "70173",
    "city": "Stuttgart",
    "state": "Baden-Württemberg",
    "country": "de"
  }
}

Beispiel – Festnetznummer als Standard anlegen:

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.address
Content-Type: application/json

{
  "addressType": "phone",
  "target": "<uuid-des-kunden>",
  "data": {
    "type": "telephone",
    "defaultNumber": true,
    "phoneNumber": "+49 711 12345-0"
  }
}

Beispiel – E-Mail-Adresse anlegen:

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.address
Content-Type: application/json

{
  "addressType": "mail",
  "target": "<uuid-des-kunden>",
  "data": {
    "mailAddress": "info@testfirma.de",
    "defaultMailAddress": true
  }
}

Beispiel – Firmenwebsite als Link anlegen:

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.address
Content-Type: application/json

{
  "addressType": "link",
  "target": "<uuid-des-kunden>",
  "data": {
    "link": "https://www.testfirma.de",
    "defaultLink": true,
    "subject": "Firmenwebsite"
  }
}

PUT address (update)

Mit der PUT-Anfrage agorum.smartorga.address aktualisieren Sie einen vorhandenen Adressbaustein. Der Baustein wird über seine UUID (id) referenziert; der addressType muss dem Typ des vorhandenen Bausteins entsprechen.

Anfrage-Body (JSON):

Beispiel – Telefonnummer ändern:

PUT <agorum-core-server>/api/rest/custom/agorum.smartorga.address
Content-Type: application/json

{
  "addressType": "phone",
  "id": "<uuid-des-telefon-bausteins>",
  "data": {
    "phoneNumber": "+49 89 98765-0"
  }
}

Antwort (bei Erfolg): Die dokumentierte Struktur ist:

{
  "uuid": "<uuid-des-telefon-bausteins>",
  "name": "<interne-container-id>"
}

Hinweis: Der name eines Adressbausteins ist ein interner Container-Bezeichner (z. B. D4WADDRESSPHONE_2551132, D4WADDRESSDATA_2551329, D4WADDRESSEMAIL_2551137, D4WADDRESSLINK_2551142), nicht der formatierte Anzeigetext. Verlassen Sie sich in Skripten deshalb auf die zurückgegebene uuid.

Notizen anlegen

POST note (create)

Mit der POST-Anfrage agorum.smartorga.note legen Sie eine Notiz (agorum core Notiz-Objekt) an einem beliebigen Objekt an und stellen sie optional den angegebenen Empfängern (Benutzer oder Gruppen) in deren Eingang zu.

Voraussetzungen:

Anfrage-Body (JSON):

Beispiel – Notiz an einer Aufgabe anlegen und an einen Benutzer und eine Gruppe zustellen:

POST <agorum-core-server>/api/rest/custom/agorum.smartorga.note
Content-Type: application/json

{
  "target": "<uuid-der-aufgabe>",
  "content": "<p>Bitte prüfen Sie diesen Vorgang bis morgen.</p>",
  "recipients": [
    "user:demo",
    "group:GRP_Vertrieb"
  ]
}

Antwort:

{
  "uuid": "<uuid-der-notiz>",
  "name": "NOTEOBJECT_<interne-nummer>.html"
}

Hinweise: 

  • Der zurückgegebene name einer Notiz ist ein interner, generierter Objektname der Form NOTEOBJECT_<nummer>.html und nicht der Notiztext. Verlassen Sie sich in Skripten deshalb auf die zurückgegebene uuid.
  • Wird recipients weggelassen oder leer übergeben, wird die Notiz nur am Zielobjekt abgelegt, ohne einem Empfänger in dessen Eingang zugestellt zu werden.

Praxisbeispiel: Neuen Kunden mit Adresse, Ansprechpartner und Notiz anlegen

Das folgende Beispiel zeigt einen typischen End-to-End-Ablauf, wie ein externes System über die REST-API einen neuen Kunden komplett anlegen kann. Alle Aufrufe verwenden dasselbe JWT-Bearer-Token im Authorization-Header (hier der Übersicht halber weggelassen).

Schritt 1 – Kunden anlegen (POST object):

POST /api/rest/custom/agorum.smartorga.object
{
  "identifier": "agorum.smartorga.crm.customer",
  "target": "<uuid-der-kunden-storage-area>",
  "acso2_name": "Testfirma GmbH"
}

=> { "uuid": "<kunde-uuid>", "name": "Testfirma GmbH (CST<nummer>)" }

Schritt 2 – Adresse hinzufügen (POST address, addressType=data):

POST /api/rest/custom/agorum.smartorga.address
{
  "addressType": "data",
  "target": "<kunde-uuid>",
  "data": {
    "street1": "Musterstraße",
    "houseNumber1": "42",
    "zip": "70173",
    "city": "Stuttgart",
    "country": "de"
  }
}

Schritt 3 – Telefonnummer und E-Mail-Adresse hinzufügen:

POST /api/rest/custom/agorum.smartorga.address
{
  "addressType": "phone",
  "target": "<kunde-uuid>",
  "data": {
    "type": "telephone",
    "defaultNumber": true,
    "phoneNumber": "+49 711 12345-0"
  }
}

POST /api/rest/custom/agorum.smartorga.address
{
  "addressType": "mail",
  "target": "<kunde-uuid>",
  "data": {
    "mailAddress": "info@testfirma.de",
    "defaultMailAddress": true
  }
}

Schritt 4 – Ansprechpartner (Kontaktperson) anlegen (POST person):

POST /api/rest/custom/agorum.smartorga.person
{
  "target": "<kunde-uuid>",
  "salutation": "mr",
  "givenName": "Max",
  "familyName": "Mustermann",
  "description": "Ansprechpartner Einkauf"
}

=> { "uuid": "<person-uuid>", "name": "D4WADDRESSCONTAINER_<interne-nummer>" }

Schritt 5 – Notiz am neuen Kunden hinterlegen und an einen Kollegen zustellen:

POST /api/rest/custom/agorum.smartorga.note
{
  "target": "<kunde-uuid>",
  "content": "<p>Neuer Kunde angelegt. Bitte im nächsten Meeting besprechen.</p>",
  "recipients": [ "user:demo" ]
}

Schritt 6 – Verifikation per Suche:

GET /api/rest/custom/agorum.smartorga.search
    ?identifier=agorum.smartorga.crm.customer
    &name=Testfirma*
    &properties=acso2_name
    &properties=acso2_number
    &limit=5

=> {
     "total": 1,
     "query": "...",
     "rows": [
       { "uuid": "<kunde-uuid>", "acso2_name": "Testfirma GmbH", "acso2_number": "<automatisch-vergebene-nummer>" }
     ]
   }