Probleme in der Codenica API

Die Arbeit mit Problemen über die Codenica API beginnt mit der Erstellung eines Schlüssels in den Codenica-Einstellungen. Wenn noch kein Schlüssel erstellt wurde, öffnen Sie Codenica API - Einführung in einem neuen Tab. Dort finden Sie die gemeinsamen Regeln für die Ausstellung von Schlüsseln, die Speicherung des Secrets und die Authentifizierung.

Der technische Modulname lautet problems, der Typ eines einzelnen Objekts lautet problem. Ein Problem dient dazu, die Ursache oder Quelle wiederkehrender Vorfälle zu erfassen. Neben beschreibenden Daten enthält es die Diagnosefelder isKnown, symptoms, rootCause und impactInfo.

Die folgenden Abschnitte behandeln die Adresse, Scopes, das Schema, Listen, Filter, Erstellung, Bearbeitung, ETag, Batch-Vorgänge, Beziehungen, Benutzer, Dateien, Workflow-Aktionen, Eskalation, Genehmigung und Löschung von Problemen.

Die Beispiele verwenden das Präfix PUBLIC-API-PROBLEM-20260905131727. Ersetzen Sie es in Ihrer Integration durch einen eigenen Bezeichner und passen Sie E-Mail-Adressen, IDs und Feldwerte an die Daten in Ihrer Datenbank an.

Probleme - API-Adresse und Bereitstellungsmodell

Alle Routen für Probleme beginnen mit:

{BASE_URL}/api/v1/problems

Verwenden Sie in der Codenica Cloud die öffentliche Domain, die der entsprechenden Installation zugewiesen ist:

export BASE_URL="https://twoja-firma.codenica.com"

In der standardmäßigen On-Premise-Installation lautet die lokal von Codenica Discovery registrierte Adresse:

export BASE_URL="http://codenica.local:5150"

Wenn ein Administrator die Installation unter einer Unternehmensdomain, hinter einem Reverse Proxy, mit HTTPS oder an einem anderen Port bereitgestellt hat, verwenden Sie die für diese Installation mitgeteilte genaue Adresse:

export BASE_URL="https://api.twoja-firma.example"

Verwenden Sie localhost nicht, wenn die Integrationssoftware auf einem anderen Computer als die API läuft. Übergeben Sie tenantId weder im Body noch im Query-String. Die richtige Datenbank wird anhand der Hostadresse ausgewählt, mit der sich die Integration verbindet.

Probleme - API-Schlüssel und Lizenzlimits

Erstellen Sie einen API-Schlüssel in Codenica unter Einstellungen - API - API Keys. Das Secret wird nur einmal angezeigt, unmittelbar nach der Erstellung oder Rotation des Schlüssels. Speichern Sie dann Client ID und Client Secret im sicheren Speicher Ihrer Integration.

Die Codenica API ist mit den Lizenzen Plus und Enterprise verfügbar. Plus erlaubt bis zu 50 aktive Schlüssel, Enterprise bis zu 100. Starter bietet keinen Zugang zur Codenica API. Erstellen Sie für jede Anwendung und jede Umgebung einen eigenen Schlüssel, damit Sie Scopes, Secret-Rotation und Zugriff unabhängig voneinander verwalten können.

Lizenz
Codenica API
Aktive Schlüssel
Starter
nicht verfügbar
0
Plus
verfügbar
maximal 50
Enterprise
verfügbar
maximal 100

Die Standardgültigkeit eines Schlüssels beträgt 90 Tage, sofern Sie im Panel kein anderes Datum festlegen. Die maximale Gültigkeitsdauer beträgt 5 Jahre. Abgelaufene oder inaktive Schlüssel belegen keinen aktiven Slot, bleiben aber sichtbar, bis Sie Löschen verwenden. Das Löschen des Datensatzes ist endgültig.

Probleme - Authentifizierung und sichere Anfragen

Authentifizieren Sie jede Anfrage an die Codenica API mit den beiden Schlüssel-Headern:

export CLIENT_ID="cna_twoj_client_id"
export CLIENT_SECRET="cns_twoj_client_secret"

curl --request GET --url "$BASE_URL/api/v1/problems?page=1&pageSize=25" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Eine externe Integration benötigt weder das JWT des Administrators noch Cookies aus dem Codenica-Panel. Legen Sie den Schlüssel nicht in einem Repository, in Browsercode, in einer URL, in der Befehls-Historie oder in Logs ab. Verwenden Sie außerhalb lokaler Tests HTTPS.

Speichern Sie meta.requestId aus der Antwort. Es hilft bei der Diagnose einer bestimmten Anfrage, ersetzt aber nicht die Problem-ID und darf nicht als Secret verwendet werden.

Probleme - Verbindungskontext prüfen

Rufen Sie den Kontext vor dem ersten Schreibvorgang ab. So prüfen Sie, ob die Adresse zur richtigen Datenbank führt und der gewählte Schlüssel die erforderlichen Scopes besitzt:

curl --request GET --url "$BASE_URL/api/v1/context" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Prüfen Sie in der Antwort:

  • data.apiVersion und data.contractVersion;
  • data.tenant.id, data.tenant.name und data.tenant.resolvedDomain;
  • data.caller.authentication mit dem Wert api_key;
  • das Vorhandensein von problems in data.capabilities.resources;
  • die dem Schlüssel zugewiesenen Scopes;
  • Seiten-, Batch-, Datei- und Anfrage-Limits.

Wenn der Kontext auf eine andere Datenbank verweist oder ein erforderlicher Scope fehlt, stoppen Sie die Integration und korrigieren Sie Adresse oder Schlüssel. Scopes können nicht für eine einzelne Anfrage vergeben werden.

Probleme - Berechtigungs-Scopes

Die vollständige Unterstützung von Problemen erfordert Scopes, die den verwendeten Vorgängen entsprechen:

problems:read
problems:write
problems:delete
problems:schema
problems:stats
problems:relationships:read
problems:relationships:write
problems:users:read
problems:users:write
problems:files:read
problems:files:write
problems:technical:read
problems:technical:write
problems:pin:write
problems:spam:write
problems:reopen:write
problems:rating:write
problems:escalation:write
problems:approval:write

Für normale Lesevorgänge genügt problems:read. Schema und Statistiken benötigen die separaten Scopes problems:schema und problems:stats. Das Lesen von Beziehungen, Benutzern und Dateien erfordert die jeweiligen Read-Scopes. Schreibvorgänge verwenden die entsprechenden :write-Scopes.

Beziehungen zu anderen Modulen erfordern außerdem Lesezugriff auf das Zielmodul, zum Beispiel assets:read, documents:read, tickets:read oder solutions:read. Für die Erstellung und Entscheidung einer Genehmigung fügen Sie die Scopes hinzu, die das Modul approvals selbst benötigt. Vergeben Sie Scopes nach dem Prinzip der geringsten Berechtigung.

Probleme - Schema und Diagnosefelder

Das Schema zeigt, welche Felder in einer bestimmten Datenbank gelesen und geschrieben werden können. Rufen Sie es vor der Erstellung eines Formulars oder Mappings ab:

curl --request GET --url "$BASE_URL/api/v1/problems/schema" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Prüfen Sie für jedes Feld unter anderem readable, writable, required, technical, unique und maxLength. Das Schema liefert außerdem Wörterbücher und verfügbare Beziehungsziele.

Zum Schreiben eines Problems sind derzeit mindestens subject und requesterEmail erforderlich. Probleme besitzen eine eigene Diagnosegruppe:

Gruppe
Felder
Verwendung
Grunddaten
subject, requesterEmail, description, comments
Problembeschreibung und meldende Person
Klassifizierung
type, status, priority, impact, urgency, severity
Vorgehensweise und Bedeutung des Problems
Diagnose
isKnown, symptoms, rootCause, impactInfo
bekanntes Problem, Symptome, Ursache und Auswirkung
Integration
source, services, tags, externalNumber, referenceNumber
Verknüpfung mit einem anderen System

Die Felder pin und isSpam sind technisch und werden über eigene Aktionen geändert. Systemfelder und schreibgeschützte Felder, darunter Bewertungs- und Eskalationsdaten, sollten nicht in einem normalen PATCH gesendet werden. Probleme unterstützen nicht die aus anderen Modulen bekannten Kostenfelder currency, estimatedCost und totalValue.

Probleme - grundlegende Endpoints

Die am häufigsten verwendeten Problem-Routen sind:

  • GET /api/v1/problems - Problemliste;
  • GET /api/v1/problems/{id} - einzelnes Problem;
  • POST /api/v1/problems - Erstellung;
  • PATCH /api/v1/problems/{id} - teilweise Bearbeitung;
  • DELETE /api/v1/problems/{id} - Löschung;
  • GET /api/v1/problems/schema - Feld- und Beziehungsschema;
  • GET /api/v1/problems/stats - Statistiken;
  • GET /api/v1/problems/values - in Filtern verwendete Werte;
  • POST /api/v1/problems:batch - Create-, Update- und Delete-Vorgänge.

Beziehungen, Benutzer, Dateien, Workflow-Aktionen und Genehmigungen haben eigene Routen. So kann die Integration genau die Berechtigungen erhalten, die sie tatsächlich benötigt.

Probleme - Listen und Paginierung

Rufen Sie die Liste seitenweise ab. Auch bei wenigen Datensätzen sollten Sie Seitennummer und Seitengröße ausdrücklich angeben:

curl --request GET --url "$BASE_URL/api/v1/problems?page=1&pageSize=25" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort enthält data.items sowie die Angaben page, pageSize, totalItems, totalPages und hasNextPage. Rufen Sie weitere Seiten ab, solange hasNextPage den Wert true hat:

curl --request GET --url "$BASE_URL/api/v1/problems?page=2&pageSize=25&sort=dateUpdated&direction=desc" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Für die Synchronisierung ist die Sortierung nach dateUpdated zusammen mit dem Merken der zuletzt verarbeiteten Datensätze meist am praktischsten. Setzen Sie pageSize nicht höher als das im Kontext zurückgegebene Limit.

Probleme - Suche, Filter und Sortierung

Sie können Listenparameter miteinander kombinieren. Das folgende Beispiel sucht nach einem Bezeichner, begrenzt das Ergebnis auf den Typ problem und bekannte Probleme und sortiert anschließend nach dem Aktualisierungsdatum:

curl --get --url "$BASE_URL/api/v1/problems" \
  --data-urlencode "itemType=problem" \
  --data-urlencode "customId=PUBLIC-API-PROBLEM-20260905131727-SOURCE" \
  --data-urlencode "isKnown=true" \
  --data-urlencode "sort=dateUpdated" \
  --data-urlencode "direction=desc" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=25" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Für die tägliche Synchronisierung sind außerdem die Parameter search, status, priority, subject, requesterEmail, source, externalNumber, referenceNumber, symptoms, rootCause, impactInfo, createdAfter, createdBefore, updatedAfter und updatedBefore nützlich, sofern sie im aktuellen Schema verfügbar sind.

Ein strukturierter Filter hat das Format field:operator:value. Verfügbare Operatoren sind eq, ne, in, contains, startsWith, endsWith, empty, notEmpty, gt, gte, lt und lte:

curl --get --url "$BASE_URL/api/v1/problems" \
  --data-urlencode "filter=status:eq:Closed" \
  --data-urlencode "filter=rootCause:contains:connection" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=25" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Kodieren Sie Textwerte und Datumsangaben nach den URL-Regeln. Gehen Sie nicht davon aus, dass ein Wörterbuch in zwei Datenbanken identisch ist.

Probleme - Feldauswahl und eingeschlossene Daten

Mit dem Parameter fields begrenzen Sie die Antwort auf die von der Integration benötigten Felder. Der Parameter include fügt verknüpfte Daten hinzu:

curl --get --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}" \
  --data-urlencode "fields=subject,requesterEmail,status,priority,isKnown,symptoms,rootCause,impactInfo" \
  --data-urlencode "include=files,relationships,users" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Für das vollständige Modell können Sie fields=* verwenden. Das Einschließen von Dateien, Beziehungen und Benutzern erfordert die entsprechenden Read-Scopes. fields umgeht weder die Zugriffskontrolle noch macht es technische Felder sichtbar, für die der Schlüssel keine Berechtigung besitzt.

Achten Sie in der Antwort auf data.id, data.itemType, data.attributes und data.meta. Lesen Sie technische Felder wie pin oder isSpam, ändern Sie sie aber über die weiter unten beschriebenen eigenen Aktionen.

Probleme - Statistiken und Wörterbuchwerte

Mit Statistiken können Sie beispielsweise Probleme nach dem Feld isKnown zählen. Dies ist ein Lesevorgang und ändert keine Datensätze:

curl --get --url "$BASE_URL/api/v1/problems/stats" \
  --data-urlencode "field=isKnown" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Werte des Feldes rootCause, die Sie für Vorschläge oder Filter benötigen, rufen Sie separat ab:

curl --get --url "$BASE_URL/api/v1/problems/values" \
  --data-urlencode "field=rootCause" \
  --data-urlencode "search=connection" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Rufen Sie zuerst das Wörterbuch ab und senden Sie erst danach den Wert im Body. Das ist besonders wichtig für status, priority, type und Diagnosefelder, die in der jeweiligen Datenbank konfiguriert sind.

Probleme - Datensatz erstellen

Erstellen Sie ein neues Problem mit POST /api/v1/problems. Geben Sie den technischen Typ problem im Body und schreibbare Felder in attributes an. Das Beispiel enthält beschreibende Daten, Klassifizierung, Integrationsangaben und die vollständige Diagnosegruppe:

export IDEMPOTENCY_KEY="public-api-problem-create-20260905131727"

curl --request POST --url "$BASE_URL/api/v1/problems" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-raw '{
    "itemType": "problem",
    "attributes": {
      "customId": "PUBLIC-API-PROBLEM-20260905131727-SOURCE",
      "subject": "Integrationsproblem der Codenica API",
      "requesterEmail": "[email protected]",
      "description": "Durch die Codenica API-Integration erstelltes Problem.",
      "comments": "Diagnosebeispiel für das Modul Problems.",
      "source": "Codenica API",
      "type": "Standard",
      "status": "Closed",
      "priority": "High",
      "impact": "Medium",
      "urgency": "High",
      "severity": "High",
      "services": "Codenica API",
      "tags": "codenica-api,problem",
      "externalNumber": "EXT-CODENICA-API-PROBLEM-20260905131727",
      "referenceNumber": "REF-CODENICA-API-PROBLEM-20260905131727",
      "isKnown": true,
      "symptoms": "Benutzer können die Synchronisierung nicht abschließen.",
      "rootCause": "Verbindungsfehler beim externen Dienst.",
      "impactInfo": "Die Synchronisierung der betroffenen Datengruppe ist verzögert."
    },
    "customValues": [
      {
        "name": "description",
        "valuePattern": "[problem-test] PUBLIC-API-PROBLEM-20260905131727"
      }
    ]
  }'

Mindestens erforderlich sind subject und requesterEmail, sofern das Schema keine weiteren Anforderungen stellt. Eine erfolgreiche Erstellung liefert HTTP 201, den Bezeichner data.id sowie einen ETag im Header und in data.meta.etag. Das Secret des Schlüssels ist nicht Teil der Objektantwort.

Probleme - idempotente Erstellung

Die Wiederholung derselben Anfrage mit demselben Idempotency-Key sollte dasselbe logische Ergebnis liefern und kein zweites Problem erstellen:

curl --request POST --url "$BASE_URL/api/v1/problems" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-problem-create-20260905131727" \
  --data-binary @problem.json

Nach einem unsicheren Netzwerkergebnis können Sie denselben Schlüssel nur für genau diese Anfrage sicher wiederholen. Verwenden Sie einen Schlüssel nicht für zwei verschiedene Vorgänge. Erzeugen Sie für einen neuen Body einen neuen Schlüssel.

Idempotency-Key ist für jede datenändernde Anfrage erforderlich, auch für Bearbeitung, Beziehungen, Dateien, Workflow-Aktionen und Löschung. Die Wiederverwendung desselben Schlüssels mit einer anderen Route oder einem anderen Body führt zu einem Idempotenzkonflikt.

Probleme - Lesen und ETag

Lesen Sie ein einzelnes Problem mit eingeschlossenen Daten wie folgt:

curl --get --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}" \
  --data-urlencode "fields=*" \
  --data-urlencode "include=files,relationships,users" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Speichern Sie den ETag aus dem Antwort-Header. Er sollte data.meta.etag und meta.etag in der Antwort-Hülle entsprechen. Rufen Sie nach jedem erfolgreichen Schreibvorgang, jeder Aktion, jeder Beziehungsänderung und jedem Dateivorgang den neuen ETag ab oder lesen Sie ihn erneut.

Ein ETag repräsentiert die Version eines bestimmten Problems. Verwenden Sie keinen ETag, der für ein Problem abgerufen wurde, um ein anderes zu ändern.

Probleme - Bearbeitung mit If-Match

Die Bearbeitung erfolgt teilweise. Senden Sie nur die Felder, die geändert werden sollen:

curl --request PATCH --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-update-20260905131727" \
  --data-raw '{
    "attributes": {
      "description": "Beschreibung durch die Integration aktualisiert.",
      "status": "Closed",
      "priority": "High",
      "isKnown": false,
      "symptoms": "Symptome nach erneuter Beobachtung.",
      "rootCause": "Aktualisierte Analyse der Ursache.",
      "impactInfo": "Auswirkung nach Anwendung der Umgehungslösung."
    }
  }'

Ändern Sie schreibgeschützte Felder wie rating, dateRating, dateFeedback, dateReopened und dateEscalated nicht mit einem normalen PATCH. Pin, Spam, Reopen, Rating, Eskalation und Approval haben eigene Endpoints.

Nach einer erfolgreichen Bearbeitung erhalten Sie HTTP 200 und einen neuen ETag. Speichern Sie ihn vor dem nächsten Vorgang.

Probleme - Kontrolle eines veralteten If-Match

Jede Mutation außer der Erstellung erfordert den aktuellen ETag. Ein fehlender Header und ein veralteter Wert werden abgewiesen:

curl --request PATCH --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-problem-missing-if-match-20260905131727" \
  --data-raw '{"attributes":{"isKnown":false}}'

Fehlt If-Match, wird HTTP 428 mit dem Code if_match_required zurückgegeben. Wenn Sie einen älteren ETag senden, erhalten Sie HTTP 412 mit dem Code if_match_failed. Eine abgewiesene Anfrage sollte das Problem nicht ändern.

Rufen Sie nach HTTP 412 den Datensatz erneut ab, lesen Sie den neuen ETag und entscheiden Sie erst dann, ob die Bearbeitung wiederholt werden kann. Überschreiben Sie Änderungen eines anderen Benutzers oder Prozesses nicht blind.

Probleme - Batch-Vorgänge

Batch dient zur Verarbeitung mehrerer unabhängiger Elemente. Eine Anfrage kann Vorgänge für create, update und delete enthalten:

curl --request POST --url "$BASE_URL/api/v1/problems:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-problem-batch-20260905131727" \
  --data-raw '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "problem",
          "attributes": {
            "customId": "PUBLIC-API-PROBLEM-20260905131727-BATCH-A",
            "subject": "Batch-Problem A",
            "requesterEmail": "[email protected]",
            "source": "Codenica API",
            "type": "Standard",
            "status": "Open",
            "priority": "Medium",
            "isKnown": true,
            "symptoms": "Symptome von Problem A",
            "rootCause": "Ursache von Problem A",
            "impactInfo": "Auswirkung von Problem A"
          }
        }
      },
      {
        "operation": "update",
        "id": "PROBLEM_UUID",
        "ifMatch": "\"CURRENT_ETAG\"",
        "update": {
          "attributes": {
            "isKnown": false,
            "rootCause": "Neue Analyse der Ursache"
          }
        }
      },
      {
        "operation": "delete",
        "id": "OTHER_PROBLEM_UUID",
        "ifMatch": "\"OTHER_CURRENT_ETAG\""
      }
    ]
  }'

Verwenden Sie bei Batch update und delete den ETag des jeweiligen Datensatzes. Der Idempotenzschlüssel identifiziert die gesamte Batch-Anfrage und nicht ein einzelnes Element. Prüfen Sie die Antwort Element für Element anhand von Index, Status, Bezeichner und Fehler. Vollständiger Erfolg liefert normalerweise HTTP 200, ein Teilergebnis HTTP 207 Multi-Status. Ein Batch ist keine All-or-Nothing-Transaktion.

Probleme - Beziehungen mit Objekten

Verfügbare Beziehungsziele werden von /api/v1/problems/schema zurückgegeben. Der aktuelle Vertrag kann unter anderem Folgendes enthalten:

assets
documents
changes
tickets
problems
solutions
releases
notes
approvals
worktasks
requesteditems

Das Vorhandensein eines Ziels im Schema bedeutet nicht, dass in der jeweiligen Datenbank ein für den Benutzer zugänglicher Datensatz existiert. Prüfen Sie vor dem Hinzufügen einer Beziehung die ID, targetDataSet, targetItemType und die Leseberechtigung für das Ziel.

Für assets, documents, problems, changes, tickets, solutions und releases verwenden Sie einen laut Schema zulässigen relationshipType, zum Beispiel related. Für notes, approvals, worktasks und requesteditems lassen Sie relationshipType auf null. Erzwingen Sie related nicht, wenn es nicht unterstützt wird.

Mehrere Beziehungen hinzufügen:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-relationships-20260905131727" \
  --data-raw '{
    "add": [
      {
        "targetId": "ASSET_UUID",
        "targetDataSet": "assets",
        "targetItemType": "computer",
        "relationshipType": "related"
      },
      {
        "targetId": "DOCUMENT_UUID",
        "targetDataSet": "documents",
        "targetItemType": "invoice",
        "relationshipType": "related"
      },
      {
        "targetId": "NOTE_UUID",
        "targetDataSet": "notes",
        "targetItemType": "note",
        "relationshipType": null
      }
    ],
    "remove": []
  }'

Die HTTP-200-Antwort enthält die Zähler added, removed und skipped. skipped ist kein Transportfehler. Rufen Sie deshalb nach dem Vorgang die Beziehungssammlung ab und prüfen Sie ihren Inhalt.

Probleme - Beziehungen lesen und entfernen

Rufen Sie die Beziehungsliste wie folgt ab:

curl --request GET --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/relationships?page=1&pageSize=100" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Entfernen Sie eine einzelne Beziehung mit dem aktuellen ETag des Quellproblems. Bei einem Ziel, das relationshipType speichert, geben Sie den Wert im Query-String an:

curl --request DELETE --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/relationships/tickets/{TICKET_ID}?relationshipType=related" \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-relationship-delete-20260905131727"

Bei einem Ziel wie notes, für das das Schema keinen Beziehungstyp vorsieht, lassen Sie den Parameter relationshipType weg. Sie können eine Beziehung auch durch eine teilweise Bearbeitung entfernen:

curl --request PATCH --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-relationship-patch-20260905131727" \
  --data-raw '{
    "relationshipsToRemove": [
      {
        "targetId": "TICKET_UUID",
        "targetDataSet": "tickets",
        "targetItemType": "ticket",
        "relationshipType": "related"
      }
    ]
  }'

Das Entfernen einer Beziehung löscht nicht den Datensatz, der ihr Ziel war. Rufen Sie nach jeder Änderung die Sammlung erneut ab und speichern Sie den neuen ETag des Problems.

Probleme - Beziehungen mit Benutzern

Ein Problem kann folgende Benutzerbeziehungen besitzen:

  • agent - für die Bearbeitung verantwortliche Person;
  • watcher - Beobachter;
  • appUserRequester - anfordernder Anwendungsbenutzer.

Gehen Sie bei Problems nicht von einer Beziehung clientRequester aus. Ziele sind aktive Benutzer und unterliegen den Zugriffskontrollen für Standort und Abteilung.

Agent zuweisen:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/user-relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-agent-20260905131727" \
  --data-raw '{
    "targetId": "USER_UUID",
    "targetDataSet": "users",
    "relationshipType": "agent"
  }'

Beobachter per Batch hinzufügen:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/user-relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-watcher-20260905131727" \
  --data-raw '{
    "add": [
      {
        "targetId": "WATCHER_USER_UUID",
        "targetDataSet": "users",
        "relationshipType": "watcher"
      }
    ],
    "remove": []
  }'

Beziehungen lesen und entfernen:

curl --request GET --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/user-relationships?page=1&pageSize=100" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

curl --request DELETE --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/user-relationships/users/{USER_ID}?relationshipType=agent" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-agent-delete-20260905131727"

Sie können einen Beobachter auch per Batch entfernen, indem Sie add leer lassen und den Eintrag in remove setzen. Lesen Sie nach jeder Änderung den neuen ETag.

Probleme - Dateien

Lesen Sie vor einem Dateivorgang das aktuelle Problem und seinen ETag. Für den Upload ist eine Anfrage mit multipart/form-data erforderlich:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/files?relationshipType=documentation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-file-one-20260905131727" \
  --form "[email protected];type=text/plain"

Dateiliste:

curl --request GET --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/files?page=1&pageSize=100" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Ein Listenelement enthält unter anderem id, name, fileName, contentType, size, relationshipType, isMain und downloadUrl. Behandeln Sie downloadUrl als API-Pfad und nicht als öffentlichen anonymen Link. Bei Problems ist isMain immer false.

Laden Sie den Inhalt als Binärdaten herunter:

curl --request GET --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/files/{FILE_ID}/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output problem-evidence.txt

Eine vorhandene Datei kann an ein anderes Problem angehängt werden. Der ETag gehört dann zum Zielproblem:

curl --request POST --url "$BASE_URL/api/v1/problems/{OTHER_PROBLEM_ID}/files/{FILE_ID}?relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $OTHER_PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-file-attach-20260905131727"

Datei löschen:

curl --request DELETE --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/files/{FILE_ID}" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-file-delete-20260905131727"

Lesen Sie das Dateigrößenlimit vor dem Upload aus context. Laden Sie keine große Datei in den Speicher, bevor Sie das Limit geprüft haben.

Probleme - Anheften, Spam und erneutes Öffnen

Anheften, als Spam markieren und erneutes Öffnen sind getrennte Aktionen. Jede Aktion erfordert den aktuellen ETag und einen neuen Idempotenzschlüssel.

Problem anheften:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/pin" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-pin-20260905131727" \
  --data-raw '{"pin":2}'

Der Wert von pin kann laut Schema eine Zahl von 0 bis 3 oder null sein. Als Spam markieren und Markierung zurücknehmen:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/spam" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-spam-on-20260905131727" \
  --data-raw '{"isSpam":true}'

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/spam" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-spam-off-20260905131727" \
  --data-raw '{"isSpam":false}'

Geschlossenes Problem erneut öffnen:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/reopen" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-reopen-20260905131727"

Die erforderlichen Scopes sind problems:pin:write, problems:spam:write und problems:reopen:write. Rufen Sie das Problem nach jeder Aktion erneut ab und speichern Sie den neuen ETag.

Probleme - Bewertung und Eskalation

Speichern Sie eine Bewertung über einen eigenen Endpoint. Sie können damit eine Eskalationsanfrage verbinden:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/rating" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-rating-20260905131727" \
  --data-raw '{
    "rating": 4,
    "feedback": "Bewertung aus der Codenica API-Integration.",
    "isEscalationRequested": true,
    "escalationRequestReason": "Das Problem erfordert eine Analyse durch das Second-Level-Team."
  }'

Die Bewertung reicht von 0 bis 5 und erfordert den Scope problems:rating:write. Eine Eskalationsanfrage erfordert zusätzlich problems:escalation:write und die entsprechende Benutzerberechtigung. Wenn Sie nur eine Bewertung speichern, lassen Sie die Eskalationsfelder weg. Lesen Sie nach dem Speichern unter anderem rating, feedback, die Bewertungsdaten und escalationRequestReason.

Probleme - Genehmigung und Entscheidung

Sie können eine Genehmigung als separates approval-Objekt erstellen und über eine Beziehung mit dem Problem verbinden. Die in approverId angegebene Person muss zur Entscheidung berechtigt sein:

curl --request POST --url "$BASE_URL/api/v1/approvals" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-problem-approval-create-20260905131727" \
  --data-raw '{
    "itemType": "approval",
    "approverId": "APPROVER_USER_UUID",
    "attributes": {
      "customId": "PUBLIC-API-PROBLEM-20260905131727-APPROVAL",
      "category": "Codenica API",
      "description": "Genehmigung der Problemanalyse."
    },
    "relationships": [
      {
        "targetId": "PROBLEM_UUID",
        "targetDataSet": "problems",
        "targetItemType": "problem"
      }
    ]
  }'

Lesen Sie die Genehmigung nach der Erstellung aus und speichern Sie die Entscheidung über die Problemroute. APPROVAL_ID ist die ID der Genehmigung und nicht die eines Benutzers:

curl --request POST --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}/approvals/{APPROVAL_ID}" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-approval-decision-20260905131727" \
  --data-raw '{
    "approve": true,
    "remark": "Durch die Codenica API-Integration genehmigt."
  }'

Eine Ablehnung erfolgt mit approve gleich false und einem eigenen Kommentar. Lesen Sie die Genehmigung danach erneut und prüfen Sie Status oder Entscheidungsdatum. Aktualisieren Sie anschließend das Problem, da die Entscheidung seinen ETag und den Prozessstatus ändern kann.

Probleme - Datensatz löschen

Rufen Sie das Problem vor dem Löschen erneut ab und verwenden Sie seinen aktuellen ETag:

curl --request DELETE --url "$BASE_URL/api/v1/problems/{PROBLEM_ID}" \
  --header "Accept: application/json, application/problem+json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $PROBLEM_ETAG" \
  --header "Idempotency-Key: public-api-problem-delete-20260905131727"

Führen Sie nach HTTP 200 einen Kontroll-GET mit derselben UUID aus. Erwarten Sie HTTP 404 mit dem Code problem_not_found oder dem im Vertrag genannten passenden Code. Wenn das Problem Beziehungen, Dateien oder eine Genehmigung besitzt, prüfen Sie vor dem Vorgang die Folgen im Schema und die Anforderungen Ihrer Datenbank.

Das Löschen eines Problems sollte die Archivierung der Historie nicht ersetzen. Wenn der Datensatz in der Dokumentation erhalten bleiben soll, ändern Sie seinen Status oder übertragen Sie die Daten in ein für die Historie vorgesehenes System.

Probleme - Fehler, Limits und Sicherheit

Fehler werden im Format application/problem+json zurückgegeben. Beispielantwort:

{
  "type": "https://docs.codenica.com/errors/problem_not_found",
  "title": "Problem not found.",
  "status": 404,
  "detail": "The problem does not exist or is outside the caller's access scope.",
  "instance": "/api/v1/problems/PROBLEM_UUID",
  "code": "problem_not_found",
  "requestId": "request-id-from-response"
}

Verwenden Sie in der Integrationslogik vor allem status und code. Das Feld detail richtet sich an Menschen und sein Wortlaut kann sich ändern.

HTTP
Bedeutung
Reaktion
400
ungültige Daten oder Feld außerhalb des Schemas
Feldfehler lesen und Mapping korrigieren
401
fehlende oder ungültige Authentifizierung
Host und Schlüssel prüfen
403
fehlender Scope oder Datenbankzugriff
Schlüssel-Scope oder Benutzerberechtigungen ändern
404
Problem, Datei oder Beziehungsziel existiert nicht oder ist nicht sichtbar
UUID und Installationsadresse prüfen
409
Daten-, Versions- oder Idempotenzkonflikt
ohne Analyse keinen zweiten Datensatz erstellen
412
veralteter ETag
Problem und neuen ETag abrufen
413
Body oder Datei ist zu groß
Limit im Kontext prüfen
422
Body oder Feldwerte sind ungültig
Payload gemäß Schema korrigieren
428
If-Match oder Idempotency-Key fehlt
passenden Header hinzufügen
429
Anfragelimit überschritten
Backoff und Retry-After verwenden

Lesen Sie die Header X-RateLimit-Limit und X-RateLimit-Remaining. Verwenden Sie nach 429 ein ansteigendes Backoff und beachten Sie ein mögliches Retry-After. Protokollieren Sie Methode, Endpoint, Status und requestId, aber niemals das Client Secret oder vollständige Authentifizierungs-Header.

Problemdaten können betriebliche, personenbezogene und diagnostische Informationen enthalten. Begrenzen Sie die Feldauswahl, verwenden Sie HTTPS und beschränken Sie den Zugriff der Integration auf die betreffende Datenbank.

Probleme - Integrationsablauf

  1. Setzen Sie BASE_URL für die richtige Cloud- oder On-Premise-Installation.
  2. Erstellen Sie unter Einstellungen - API - API Keys einen eigenen Schlüssel und wählen Sie die minimalen Scopes.
  3. Legen Sie Client ID und Client Secret in einem sicheren Speicher ab.
  4. Senden Sie GET /api/v1/context und prüfen Sie Datenbank, Caller und Limits.
  5. Rufen Sie GET /api/v1/problems/schema ab und ordnen Sie die Diagnosefelder zu.
  6. Rufen Sie die Problemliste ab oder erstellen Sie mit POST und einem eindeutigen Idempotency-Key einen neuen Datensatz.
  7. Speichern Sie die Problem-UUID und den zugehörigen ETag.
  8. Aktualisieren Sie den ETag vor jeder Mutation und verwenden Sie einen neuen Idempotenzschlüssel.
  9. Fügen Sie Beziehungen, Benutzer und Dateien erst hinzu, nachdem Sie ihre Ziele im Schema geprüft haben.
  10. Führen Sie Pin, Spam, Rating, Eskalation, Reopen und Approval-Entscheidungen als getrennte Vorgänge aus.
  11. Rufen Sie bei 412 den Datensatz ab, lösen Sie den Konflikt und wiederholen Sie den Vorgang bewusst.
  12. Prüfen Sie bei Batch das Ergebnis jedes Elements, da ein Teilfehler erfolgreiche Vorgänge nicht unbedingt zurücksetzt.
  13. Behandeln Sie 429, protokollieren Sie requestId ohne Secrets und löschen Sie den Schlüssel, wenn die Integration nicht mehr verwendet wird.
  14. Bestätigen Sie vor dem Löschen den aktuellen ETag und prüfen Sie danach HTTP 404.

Mit diesem Ablauf können Sie Probleme und ihre Analyse mit einem anderen System synchronisieren, ohne von der internen Struktur der Datenbank abhängig zu sein. Wenn sich Feldkonfiguration, Installationsadresse oder Schlüssel-Scopes ändern, lesen Sie Kontext und Schema erneut.