Datenquellen

Eine Datenquelle ist eine Adresse eines Ihrer Systeme, etwa Ihrer Warenwirtschaft oder eines Lieferantenportals, die mit JSON antwortet. Ein Workflow-Skript liest sie mit ctx.sources.get, zum Beispiel um die Kostenstelle eines Lieferanten anhand der Lieferantennummer auf einer Rechnung zu holen. Acriva ruft die Quelle auf, nicht das Skript: nur GET über HTTPS und nur an den eingetragenen Host. Skripte selbst haben kein Netz.

Sie finden die Datenquellen in den Einstellungen unter Ablage › Datenquellen. Für Stammdaten, die Sie in Acriva selbst pflegen, etwa eine Lieferantenliste, nutzen Sie stattdessen eine Datentabelle.

Wer Datenquellen verwaltet

Um die Seite zu sehen, brauchen Sie das Recht Workflow-Vorlagen einrichten und alle Workflows und die Abwesenheiten anderer verwalten.
Um eine Datenquelle anzulegen, zu ändern, zu testen und zu löschen, brauchen Sie Datenquellen verwalten. Die eingebauten Rollen Inhaber und Admin haben es; die Seite nennt Anlegen und Ändern: Inhaber und Admins.
Datenquellen anlegen und ändern gehört zum Add-on Workflow-Designer (siehe Wer den Designer hat). Ohne das Add-on sagt die Seite das: Bestehende Datenquellen können Sie weiter ansehen, löschen und ihr Geheimnis entfernen.

Eine Datenquelle hinzufügen

Wählen Sie Datenquelle hinzufügen.
Geben Sie den Schlüssel ein: den Namen, mit dem Skripte die Quelle aufrufen, etwa erp. Er beginnt mit einem Kleinbuchstaben, enthält nur Buchstaben und Ziffern und hat höchstens 40 Zeichen. Er lässt sich später nicht ändern.
Geben Sie die Basis-URL ein, etwa https://erp.example.com/api. Nur dieser Host ist erlaubt; Pfad und Parameter kommen aus dem Skript.
Wählen Sie die Anmeldung:
- Keine;
- Bearer-Token: Geben Sie das Token ein;
- Basic: Geben Sie Benutzername und Passwort ein;
- API-Schlüssel im Header: Geben Sie den Name des Headers ein, etwa X-API-Key, und seinen Wert.
Legen Sie das Zeitlimit fest: höchstens 5 Sekunden je Aufruf.
Legen Sie den Cache fest: 0 bis 24 Stunden. Gleiche Anfragen kommen in dieser Zeit aus dem Cache; mit Kein Cache wird die Quelle jedes Mal aufgerufen.
Entscheiden Sie, ob Sie Werte vertraulicher Dokumente senden. Ist es aus, wird diese Quelle für vertrauliche Dokumente nicht aufgerufen.
Wählen Sie Speichern.

Ein Arbeitsbereich hat höchstens 20 Datenquellen. Ein Token, ein Passwort oder ein Header-Wert hat mindestens 8 und höchstens 4.096 Zeichen.

Welche Adressen erlaubt sind. Die Basis-URL muss eine vollständige HTTPS-Adresse auf dem Standardport sein, mit einem Hostnamen, der aus dem Internet erreichbar ist: keine IP-Adresse, keine Adresse in Ihrem internen Netz, kein Benutzername in der Adresse, keine Abfrage und kein Fragment. Acriva prüft die Adresse bei jedem Aufruf erneut, auch wenn sich die DNS-Antwort des Hosts ändert, und folgt einer Weiterleitung nur zum selben Host über HTTPS, höchstens dreimal. Eine Adresse, die das nicht erfüllt, wird mit Adresse blockiert. abgelehnt. Beim Speichern prüft Acriva nur die Form der Adresse; ob ein Host in einem internen Netz liegt, zeigt sich bei Testen und bei jedem Aufruf, denn ein Name kann später anders aufgelöst werden.

Geheimnisse sind nur schreibbar. Ein Token, ein Passwort oder ein Header-Wert wird verschlüsselt gespeichert und nie wieder angezeigt; das Formular zeigt nur gesetzt. Mit Ersetzen geben Sie ein neues ein, mit Gespeicherten Wert behalten bleibt das alte. Ändern Sie die Basis-URL auf einen anderen Host oder den Header-Namen eines API-Schlüssels, geben Sie das Geheimnis erneut ein: Ein gespeichertes Geheimnis geht nie an einen anderen Host oder Header.

Die Verbindung testen

Wählen Sie im Menü der Zeile Testen oder im Formular einer gespeicherten Datenquelle Verbindung testen. Acriva ruft die gespeicherte Basis-URL einmal mit GET auf, mit ihrer Anmeldung und ihrem Zeitlimit, und zeigt das Ergebnis, den HTTP-Status, die Dauer und die Größe der Antwort, nie die Antwort selbst. Getestet wird die gespeicherte Fassung, nicht ungespeicherte Änderungen im Formular.

Die Ergebnisse sind Erfolgreich, Blockiert, Zeitüberschreitung, Antwort zu groß, Ungültige Antwort, HTTP-Fehler und Fehlgeschlagen. Sie können höchstens 10-mal je Minute testen.

Die Liste zeigt für jede Datenquelle den Letzter Aufruf, aus einem Workflow, einem Testlauf oder einem Verbindungstest, mit seinem Ergebnis.

Ändern, Geheimnis entfernen, löschen

Bearbeiten ändert eine Datenquelle; die Änderungen gelten ab dem nächsten Aufruf. Hat sie jemand inzwischen geändert, schließen Sie den Dialog und öffnen Sie die Datenquelle erneut.
Geheimnis entfernen entfernt die gespeicherten Anmeldedaten. Acriva ruft die Quelle dann ohne sie auf, bis Sie neue eintragen, und Skripte, die die Quelle nutzen, können fehlschlagen.
Löschen entfernt die Datenquelle. Das geht nicht, solange ein veröffentlichter Workflow oder eine laufende Instanz sie nutzt: Entfernen Sie sie dort zuerst. Die protokollierten Aufrufe bleiben erhalten.

Eine Datenquelle in einem Skript nutzen

Ein Skript darf nur die Datenquellen aufrufen, die sein Schritt als Eingaben nennt. Öffnen Sie im Skript-Schritt Eingaben und wählen Sie unter Datenquellen und Datentabellen Datenquelle hinzufügen; Datenquellen verwalten führt zu dieser Seite. Dann rufen Sie die Quelle unter ihrem Schlüssel auf:

const result = await ctx.sources.get('erp', {
  path: `lieferanten/${ctx.document.fields.lieferantennummer}`,
  query: { felder: 'kostenstelle' },
});
if (!result.ok) {
  ctx.hint(
    `Die Warenwirtschaft hat nicht geantwortet (${result.error}). Bitte kontieren Sie von Hand.`,
  );
  return;
}
ctx.setField('kostenstelle', result.data.kostenstelle);

Acriva setzt den Pfad unter die Basis-URL und kodiert jeden seiner Teile und jeden Abfrageparameter, so dass ein Wert aus dem Dokument den Basispfad nicht verlassen und keinen anderen Host erreichen kann. Die Antwort muss JSON sein (application/json), höchstens 1 MB groß.

Ein Aufruf, der scheitert, beendet den Lauf nicht: ctx.sources.get gibt dann { ok: false, error } zurück, und das Skript entscheidet, was es tut. Der error ist einer dieser:

`error`	Bedeutung
`data-source-blocked`	Die Adresse oder eine Weiterleitung ist nicht erlaubt.
`timeout`	Die Quelle hat nicht in ihrem Zeitlimit geantwortet, oder nicht in der Zeit, die dem Lauf für Datenquellen bleibt.
`too-large`	Die Antwort ist größer als 1 MB.
`invalid-response`	Die Antwort ist kein JSON (`application/json`), oder sie ist komprimiert.
`http-error`	Die Quelle hat mit einem Fehlerstatus geantwortet (in `status`), oder die Verbindung ist gescheitert.
`not-declared`	Der Schritt nennt die Quelle nicht als Eingabe, oder der Arbeitsbereich hat keine Datenquelle mit diesem Schlüssel.
`confidential`	Das Dokument ist vertraulich, und die Quelle erlaubt keine Werte vertraulicher Dokumente.
`limit`	Der Lauf hat seine 10 Aufrufe oder seine 30 Sekunden für Datenquellen schon verbraucht.

Ein Lauf macht höchstens 10 Aufrufe, jeden höchstens so lang wie das Zeitlimit der Quelle, und zusammen höchstens 30 Sekunden; auch eine Antwort aus dem Cache zählt als Aufruf. Ein Testlauf im Editor ruft die Quellen wirklich auf, und seine Aufrufe werden wie die eines Workflows protokolliert.

Datenschutz und Protokoll

Jeder Aufruf wird protokolliert, mit dem Workflow-Lauf: die Quelle, die aufgerufene Adresse, das Ergebnis, der Status, die Dauer und die Größe, nie die Antwort oder das Geheimnis. Die Adresse kann Werte eines Dokuments enthalten, deshalb entfernt Acriva sie 90 Tage nach dem Ende des Workflows (bei einem Test 90 Tage nach dem Aufruf); der Rest des Eintrags bleibt.
Geheimnisse werden je Arbeitsbereich verschlüsselt und aus jeder Antwort entfernt, bevor ein Skript oder ein Protokoll sie sieht.
Vertrauliche Dokumente erreichen nur Quellen, die es erlauben.