FIM-Konverter

Pro API-Schlüssel gelten zwei Grenzen:

Wird eine Grenze überschritten, antwortet die API mit 429 und setzt den Header Retry-After auf die Anzahl Sekunden bis zur nächsten erlaubten Anfrage. Die Grenzen gelten für beide Endpoints gemeinsam.

{
  "bpmn": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<definitions …>…</definitions>",
  "warnings": []
}

Zuordnung der FIM-Daten

<subProcess id="_27356b24-7f40-4bcd-b2c4-3453c37494e8" name="Fristwahrung prüfen">
  <extensionElements>
    <fim:id>05</fim:id>
    <fim:name>Fristwahrung prüfen</fim:name>
    <fim:referenzaktivitaetengruppeTyp code="3"
      listURI="urn:xoev-de:fim:codeliste:referenzaktivitaetengruppe"
      listVersionID="20230301"/>
    <fim:handlungsgrundlage>
      <fim:name>§ 5 (1) 21. BImSchV</fim:name>
      <fim:art code="111" listURI="urn:xoev-de:fim:codeliste:handlungsgrundlagenart" listVersionID="20230301"/>
      <fim:uri>https://www.gesetze-im-internet.de/bimschv_21/__5.html</fim:uri>
    </fim:handlungsgrundlage>
  </extensionElements>
</subProcess>

xmlns:fim="http://fim-bpmn.org/schema/1.0"

Die Umwandlung ist wiederholbar: Dieselbe Eingabe erzeugt dieselbe Ausgabe. Eine erneute Befüllung bereits konvertierter Daten verändert nichts.

curl -X POST \
  -H "X-API-Key: DEIN_SCHLUESSEL" \
  -H "Content-Type: application/xml" \
  --data-binary @prozess.xprozess.xml \
  https://api.fimtek.dev/fim-konverter/v1/triples

Der Körper ist reines Turtle, kein JSON. Etwaige Warnungen stehen als Kommentarzeilen am Anfang und stören keinen Turtle-Parser:

# [empty-value] Das Element <gueltigkeitszeitraum> ist leer und wird uebersprungen.

Aufbau des Graphen

Prozess und Aktivitätengruppen bekommen eigene IRIs unter der Basis https://fim-bpmn.org/id/. Die Prädikate stammen aus demselben Namespace, der auch im BPMN verwendet wird, mit # als Trenner:

@prefix fim: <http://fim-bpmn.org/schema/1.0#>

Beispielausgabe (gekürzt)

@prefix fim: <http://fim-bpmn.org/schema/1.0#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.

<https://fim-bpmn.org/id/prozess/99063072261000>
    a fim:Prozess;
    rdfs:label "Anlage zur Betankung von Kraftfahrzeugen";
    fim:id "99063072261000";
    fim:version "01.00.00";
    fim:aktivitaetengruppe <https://fim-bpmn.org/id/aktivitaetengruppe/_27356b24>.

<https://fim-bpmn.org/id/aktivitaetengruppe/_27356b24>
    a fim:Aktivitaetengruppe;
    rdfs:label "Fristwahrung prüfen";
    fim:subProcessId "_27356b24";
    fim:handlungsgrundlage _:b63.

_:b63 fim:name "§ 5 (1) 21. BImSchV";
    fim:art <urn:xoev-de:fim:codeliste:handlungsgrundlagenart#111>.

<urn:xoev-de:fim:codeliste:handlungsgrundlagenart#111>
    a fim:Code;
    fim:code "111";
    fim:codeliste <urn:xoev-de:fim:codeliste:handlungsgrundlagenart>;
    fim:listVersionID "20230301".

Abbildungsregeln

• Einfache Werte werden zum Elementinhalt eines Literals.
• Codelisten-Werte werden zu eigenen Ressourcen, gebildet aus listURI und dem Code. Dadurch lassen sie sich später mit der offiziellen Codeliste verknüpfen, ohne die Daten erneut zu konvertieren.
• Verschachtelte Strukturen werden zu Blank Nodes.
• Mehrfach vorkommende Felder ergeben mehrere Tripel. Ihre Reihenfolge geht dabei verloren, weil RDF keine Reihenfolge kennt.
• fim:subProcessId bleibt als Literal erhalten und ist die Brücke zum BPMN-Ergebnis aus /convert.

Die Referenzdatei ergibt 445 Tripel: ein Prozess, zehn Aktivitätengruppen und 41 beschriebene Codelisten-Werte aus zwölf Listen.

Die Fehlerantworten sind dieselben wie bei /convert und kommen als JSON, auch wenn der Erfolgsfall Turtle liefert.

Warnungen brechen die Umwandlung nicht ab. Für programmatische Reaktionen ist "code" maßgeblich; der Meldungstext kann sich ändern.

{
  "code": "empty-value",
  "message": "Das Element <gueltigkeitszeitraum> ist leer und wird uebersprungen.",
  "path": ["zustandsangaben", "gueltigkeitszeitraum"]
}

Alle Fehlerantworten haben dieselbe Form:

{ "error": "Beschreibung des Problems" }

Bei 400 nennt die Meldung die Ursache so genau wie möglich, einschließlich Zeile und Spalte. Bei 500 bleibt sie bewusst unspezifisch.

Typische 400er

• Körper leer
• XML nicht wohlgeformt
• Keine XProzess-2.0-Datei
• Kein eingebettetes BPMN