Erstellen Sie eine Datenstromaktion

Freigeben Version: Xanadu

Aktualisiert 1. August 2024

9 Minuten Lesedauer

Erstellen Sie eine wiederverwendbare Aktion, um einen Strom von Antwortdaten innerhalb eines Flows zu verarbeiten.

Vorbereitungen

Richten Sie eine Anwendung in Guided Application Creator ein, um den Inhalt von Workflow-Studio zu speichern.
Deaktivieren Sie alle in Konflikt stehenden Business-Regeln oder Workflows, bevor Sie eine Aktion erstellen.
Erforderliche Rolle: action_designer oder admin

Warum und wann dieser Vorgang ausgeführt wird

Wenn Sie eine anwenderdefinierte Anwendung erstellen, die den Inhalt Workflow-Studio enthält, können Sie sie über das App-Repository oder ServiceNow Storebereitstellen.

Hinweis:

Durch das Löschen einer Option auf einer Konfigurationsseite wird der Schritt aus der Gliederung Datenstrom entfernt, und alle dem Schritt zugeordneten Daten werden gelöscht.

Prozedur

Navigieren zu Alle > Flow Designer > Designer.
Klicken Sie auf die Registerkarte Aktionen, und wählen Sie Datenstromaus.

Füllen Sie die Aktionseigenschaften aus und klicken Sie auf Senden.


Feld	Beschreibung
Aktionsname	Geben Sie einen eindeutigen Namen für Ihre Datenstromaktion ein.
Beschreibung	Beschreibung der Datenstromaktion.
Anwendung	Anwendungsbereich der Datenstromaktion.
Domäne	Domänenbereich der Datenstromaktion. Weitere Informationen zu Domain Separation finden Sie unter Domain separation explained.
Zusätzliche Eigenschaften
Zugänglich von	Zugriff von allen Anwendungsbereichen oder nur innerhalb des angegebenen Anwendungsbereichs.
Kategorie	Definierte Kategorie innerhalb des Anwendungsbereichs für eine Aktion. Ab Release Xanadu können Sie eine anwenderdefinierte Kategorie erstellen, um Ihre Datenstromaktionen zu organisieren.
Schutz	Wählen Sie aus, ob die Datenstromaktion schreibgeschützt ist. Sie können nur einen Wert auswählen, wenn Sie die Datenstromaktion in einem Anwendungsbereich erstellen, den Sie besitzen. Der Standardwert ist "Kein".
Aktionsanmerkung	Hilfetext, der unter dem Titel der Datenstromaktion in Workflow-Studio angezeigt wird, um Autoren von Datenstromaktionen zu helfen zu verstehen, was die Datenstromaktion tut, wenn sie in einem Flow verwendet wird.

Eine leere Datenstrom Aktion wird geöffnet.

Definieren Sie Aktionseingaben, um Daten für die Aktionsschritte verfügbar zu machen.
1. Wählen Sie + Eingabe erstellen und füllen Sie die Felder aus.
  Eingaben werden im rechten Fensterbereich als Data-Pills dargestellt.
Weitere Informationen zu Aktionseingaben finden Sie unter Workflow-Studio : Erstellen von anwenderdefinierten Aktionen.
Klicken Sie in der Gliederung Datenstrom auf Aktion Vorverarbeitung, und konfigurieren Sie die gewünschten Optionen.
1. Wählen Sie Verbindungsinformationen abrufen aus, um den Schritt Verbindungsinformationen abrufen als ersten Schritt in der Aktionsvorverarbeitung hinzuzufügen.
  Im Schritt Verbindungsinformationen abrufen können Sie Verbindungs- und Anmeldeinformationsdetails abrufen, die Sie in Ihrer Aktion verwenden möchten. Weitere Informationen finden Sie unter Get Connection Info step.
2. Wählen Sie Vorverarbeitungsskript für die Ausführung von ein Vorverarbeitungsskript, bevor die Aktion die erste API-Anforderung sendet. Validieren Sie beispielsweise Aktionseingaben, oder legen Sie Standardwerte fest. Die Vorverarbeitung wird einmal pro Aktion vor der ersten API-Anforderung ausgeführt.aktivieren aus.
  
  Durch Auswahl dieser Option wird der Aktion Datenstrom ein Skriptschritt hinzugefügt. Weitere Informationen finden Sie unter Script step.
  
  Wichtig:
  Datenstromaktionen erfordern eine ständige Verbindung zum Antwortstrom. Sie unterstützen keine Vorverarbeitungsskripts, die die Aktion zum Aufrufen eines MID-Server oder zum Warten auf eine Bedingung oder Dauer anhalten. Ein Vorverarbeitungsskript, das die Aktion aus irgendeinem Grund anhält, gibt eine Fehlermeldung zurück.
Klicken Sie in der Gliederung Datenstrom auf Anfordern, und konfigurieren Sie die gewünschten Optionen.
1. Wählen Sie im Feld Wie werden Sie Daten abrufen die Option REST-Schritt, SOAP-Schrittoder JDBC -Schritt aus, um den entsprechenden Schritt zur Aktion Datenstrom hinzuzufügen.
  Weitere Informationen finden Sie unter REST-Schritt, SOAP-Schrittund JDBC-Schritt .
  
  Dieser Abschnitt kann entweder auf der Instanz MID-Server oder auf der Instanz von ausgeführt werden. Die Umgebung wird durch das Feld MID-Server verwenden im zugehörigen Verbindungsdatensatz [sys_connection] festgelegt.
  Hinweis:
  Wenn Sie den JDBC-Schritt verwenden, müssen Sie ihn testen. Nach erfolgreicher Ausführung können Sie das Ergebnis verwenden, um die Schrittausgabe und die Datenstrom-Aktionsausgabe zu erstellen.
  
  Wenn Sie den REST- oder SOAP-Schritt verwenden, müssen Sie die Datenstrom-Aktionsausgabe manuell erstellen.
2. Wählen Sie Paginierung aktivieren, um Ergebnisse in Stapeln. Sobald eine Seite mit Daten verarbeitet wurde, führt die Aktion Datenstrom den Anforderungsabschnitt erneut aus, um den nächsten Ergebnissatz zurückzugeben. anzufordern. Diese Option fügt der Gliederung Datenstrom einen Schritt „Paginierungseinrichtung“ hinzu.
  
  Hinweis:
  Für einen JDBC-Schritt ist die Paginierung nicht anwendbar. Jede Seite kann bis zu 1 GB Daten abrufen, und mit einer Anforderung können bis zu 8 GB Daten abgerufen werden.
3. Wählen Sie Vor jeder Anforderung ein Skript ausführen aus, um vor jeder Anforderung für die nächste Seite ein Skript auszuführen, wenn Sie eine paginierte API aufrufen.
  Schreiben Sie beispielsweise ein Skript, um variable Datentypen aus der ersten Antwort umzuwandeln, bevor eine Anforderung für die nächste Seite gesendet wird.
  
  Durch Auswahl dieser Option wird der Aktion Datenstrom ein Skriptschritt hinzugefügt. Weitere Informationen finden Sie unter Script step.
  
  Hinweis:
  Für einen JDBC-Schritt gilt dies nicht.
  
  Dieser Abschnitt kann entweder auf dem MID-Server oder in der Instanz ausgeführt werden. Die Umgebung wird vom Feld Erforderliche Laufzeit des Skriptschritts bestimmt.
  
  Wichtig:
  Vermeiden Sie es, die Ausführungsumgebung zwischen der Instanz und dem MID-Server mehrmals zu wechseln. Beispielsweise könnten Sie den Anforderungsskriptschritt für die Ausführung auf dem MID-Server konfigurieren, den REST-Schritt jedoch für die Instanz. In diesem Fall wechselt das System die Umgebung für jede Datenseite zwischen der Instanz und dem MID-Server, was die Leistung beeinträchtigen kann.
Wahlweise: Wenn die Paginierung aktiviert ist, konfigurieren Sie den Schritt „Einrichtung der Paginierung“.
Konfigurieren Sie den Schritt „Paginierungseinrichtung“ manuell, oder wählen Sie eine vorgefertigte Vorlage aus, um allgemeine Konfigurationen anzuwenden. Wenden Sie beispielsweise die Vorlage Grenzwert/Offset an, um die Anzahl der pro Seite zurückgegebenen Elemente (Grenze) und die Startnummer für das erste Element (Offset) anzugeben. Aktualisieren Sie nach dem Anwenden einer Vorlage die Werte, um sicherzustellen, dass die Konfiguration den API-Anforderungen entspricht.
1. Erstellen Sie Paginierungsvariablen.
  Wenn beispielsweise die Drittanbieter-API einen Grenzwertparameter in der Anforderung akzeptiert, erstellen Sie die Grenzwertvariable, und legen Sie den Anfangswert fest, um die Anzahl der Ergebnisse pro Seite zu begrenzen. Der Anfangswert wird nur in der ersten Anforderung verwendet. getNextPage ist eine reservierte, schreibgeschützte Variable. Solange die getNextPage-Variable auf „true“ gesetzt ist und die vorherige Seite Daten enthält, sendet die Aktion weiterhin Anforderungen für die nächste Seite.
2. Definieren Sie im Feld Nächster Wert von, wie Paginierungsvariablen einen Wert für nachfolgende Anforderungen erhalten.
  Wählen Sie aus:
  - Skript: Schreiben Sie ein Skript für Paginierungsvariablen, um zu definieren, wie Variablen gefüllt werden. Paginierungsvariablen unterstützen nur den Datentyp Zeichenfolge. Zum Ausführen von mathematischen Operationen müssen Sie den Wert in eine ganze Zahl konvertieren, alle erforderlichen Vorgänge ausführen und sie dann wieder in eine Zeichenfolge konvertieren.
  - Antworttext: Verwenden Sie einen Wert aus der Antwort aus der vorherigen Anforderung, um die Variable zu füllen. Wenn die Antwort im JSON-Format vorliegt, legen Sie Wert extrahieren mithilfe von auf JSONPath-Ausdruck fest, und geben Sie den Pfad zum Wert im Feld Ausdruck an. Wenn die Antwort im XML-Format vorliegt, legen Sie „Wert extrahieren mit “ auf „XPath-Ausdruck“ fest, und geben Sie den Pfad zum Wert an.
In diesem Beispiel hat die Variable getNextPage den Wert true, bis die Variable NextOffset den im API-Antwortheader zurückgegebenen Gesamtanzahlwert erreicht. Solange die getNextPage-Variable auf „true“ gesetzt ist und die vorherige Seite Daten enthält, sendet die Aktion weiterhin Anforderungen für die nächste Seite. Dieses Beispiel enthält eine allgemeine Konfiguration für Grenzwert-/Offset-Paginierung. Die APIs von Drittparteien, mit denen Ihre Aktion Datenstrom interagiert, können ein Seiten-Token oder eine andere Methode verwenden.

Wichtig:
Vermeiden Sie Endlosschleifen in Paginierungsanforderungen, indem Sie eine Bedingung erstellen, die die Variable getNextPage auf „false“ setzt. Brechen Sie Flows mit langer Ausführungszeit ab. Testen Sie Datenstrom-Aktionen immer, bevor Sie sie in der Produktion verwenden.
Klicken Sie in der Gliederung Datenstrom auf Analyse, und konfigurieren Sie die gewünschten Optionen.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
1. Wählen Sie im Feld Wie werden Sie die einzelnen Datensätze identifizieren die Option JSON/XML-Splitter aus, um der Gliederung Datenstrom einen Splitter-Schritt hinzuzufügen.
2. Wählen Sie im Feld Wie werden Sie die einzelnen Elemente in einem Objekt analysieren dieOption Skript -Parser aus, um der Gliederung Datenstrom einen Skript-Parser-Schritt hinzuzufügen.
Konfigurieren Sie den Schritt „Splitter“.

Dieser Schritt identifiziert den übergeordneten Knoten im Antwortstream, der einem komplexen Objekt zugeordnet werden soll. Identifizieren Sie beispielsweise ein Benutzerelement in einer XML-Nutzlast, um für jeden Benutzer im Antwortstream ein komplexes Objekt zu erstellen.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
1. Wählen Sie im Feld Quellformat das Format aus, das vom Abschnitt „Anforderung“ zurückgegeben wird.
  - JSON: Identifiziert Objekte in einem Stream von JSON-Daten. Verwenden Sie einen JSONPath-Ausdruck, um ein JSON-Array zu identifizieren, das wiederholte Daten enthält.
  - XML: Identifiziert Objekte in einem Stream von XML-Daten. Verwenden Sie einen XPath-Ausdruck, um ein XML-Element zu identifizieren, das wiederholte Daten enthält.
2. Definieren Sie im Feld Elementpfad den absoluten Pfad zu dem Element im Datenstrom, das Sie einem Objekt zuordnen möchten.
  
  JSON
  
  Identifizieren Sie den absoluten Pfad zu einem Array von Objekten als JSONPath-Ausdruck. Verwenden Sie beispielsweise $.result, um jedes Element in einem JSON- Ergebnis -Array in einem Ergebnisobjekt zu trennen.
  Hinweis:
  Wenn Sie ein Array am Stammknoten eines JSON-Datenstroms auswählen, zeigt das System den absoluten Pfad in den Ausführungsdetails und Fehlermeldungen als $.* an.
  
  XML
  
  Identifizieren Sie den absoluten Pfad zu einem sich wiederholenden Datenobjekt als XPath-Ausdruck. Verwenden Sie beispielsweise /result, um jede Instanz eines Ergebnis -XML-Elements in ein Ergebnisobjekt zu unterteilen.
  Hinweis:
  Der Splitter-Schritt ignoriert XML-Namespaces.
  Angenommen, der REST-Schritt gibt einen Stream von JSON-Daten zurück. Der Elementpfad $.response.result.companies gibt jedes Element im Unternehmen -Array zurück.
```
{
  "response": {
    "result": {
      "companies": [
        {
          "name": "company1"
        },
        {
          "name": "company2"
        },
        {
          "name": "company3"
        }
      ],
      "metadata": {
        "token": 1558666526
      }
    }
  }
} 
```
  Angenommen, der REST-Schritt gibt einen Stream von XML-Daten zurück. Der Elementpfad /response/result/companies/company gibt jedes Unternehmenselement aus den XML-Daten zurück.
```
<response>
  <result>
    <companies>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <batch>10645C53D4BED73YQ</batch> 
    </companies>
    <metadata>
      <timestamp>1558666526</timestamp>
    </metadata>
  </result>
</response>
```
Verwenden Sie im Schritt Skript-Parser JavaScript und die APIs ServiceNow, um Elemente im Antwortstream einer komplexen Objektausgabe zuzuordnen, die durch das globale Objekt targetObject dargestellt wird.
Ordnen Sie beispielsweise Incident-Datensatzelemente, die im Splitter-Schritt identifiziert wurden, einem komplexen Objekt zu, das Incident-Felder enthält. Wenn der Datenstrom gleichgeordnete Elemente zu dem im Splitter-Schritt identifizierten Element enthält, die keinem komplexen Objekt zugeordnet werden sollen, schließen Sie Bedingungen ein, um diese Elemente auszuschließen.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
Mit dem Objekt „fd_data“ können Sie in Ihrer Datenstromaktion auf Ausgaben aus vorherigen Schritten zugreifen, außer:
- REST- oder SOAP-Schritt-Antworttext, Stream oder Fehlermeldungsausgaben.
- Splitter-Schrittausgaben.
Beispielskript, das eine JSON-Antwort analysiert
```
(function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.id=record.number;
    outputs.targetObject.name=record.short_description;
})(inputs, outputs)
```
Ein Beispielskript, das eine XML-Antwort analysiert
```
(function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.id = xmlDoc.getNodeText("/result/number");
    outputs.targetObject.name = xmlDoc.getNodeText("/result/short_description");
})(inputs, outputs)
```
Wahlweise: Wenn Sie den JDBC-Schritt ausgewählt haben, klicken Sie auf Umwandeln.
Klicken Sie nach dem erfolgreichen Testen des JDBC-Schritts auf Use Result (Ergebnis verwenden), um die Schrittausgabe und die Datenstrom-Aktionsausgabe zu erstellen. Sie können dieses Ergebnis verwenden oder mit dem Transformationsskript anpassen.
1. Aktivieren Sie das Kontrollkästchen Transformationsskript aktivieren, um die Ausgabe des standardmäßigen Datenstroms umzuwandeln und anzupassen.
Erstellen Sie eine komplexe Objektausgabe.

Hinweis:
Für einen JDBC-Schritt gilt dies nicht.
1. Wählen Sie in der Aktionsgliederung die Option Ausgaben aus, und klicken Sie auf +, um eine Ausgabe zu erstellen.
2. Aktualisieren Sie das Feld Bezeichnung, um das Objekt darzustellen.
  Wenn die Aktion beispielsweise einen Stream von Unternehmensdatensätzen analysiert, fügen Sie die Bezeichnung Unternehmen hinzu.
3. Aktualisieren Sie das Feld Typ auf Objekt.
  Dies ist die komplexe Objektausgabe, die vom globalen Objekt targetObject im Schritt „Skript-Parser“ dargestellt wird.
4. Fügen Sie dem komplexen Objekt über das Symbol + untergeordnete Felder hinzu.
5. Machen Sie den Namen jedes untergeordneten Felds anwenderfreundlicher, damit Sie im Skript sinnvoll darauf verweisen können.
  
  Der Wert im Feld Name ist der interne Name, der im Schritt Skript-Parser verwendet wird. Um beispielsweise im Schritt Skript-Parser auf die Ausgabe „Stadt“ zu verweisen, verwenden Sie „ outputs.targetObject.city“.
  
  Warnung:
  Nach dem Speichern der Aktion Datenstrom können Sie die Werte im Feld Name nicht mehr ändern.
Klicken Sie auf Speichern.
Workflow-Studio speichert einen Entwurf der Aktion.

Nächste Maßnahme

Testen Sie eine Datenstrom -Aktion.