SetPrimitiveValue@1

Der Node SetPrimitiveValue@1 setzt primitive Werte an angegebenen Pfaden im Data Context. Er konvertiert einen konfigurierten Wert in einen angegebenen primitiven Typ und weist ihn einem Zielpfad zu; damit ist er unverzichtbar für Datenanreicherung, das Setzen von Standardwerten und die Injektion von Metadaten.

Adapter-Voraussetzungen

• Allgemeine Verfügbarkeit: Alle Adapter unterstützen diesen Node-Typ.

Node-Konfiguration

Zu den Feldern targetPath, targetValueWriteMode und targetValueKind siehe Überblick.

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.status                 # Path where the value will be stored
  value: "pending"                     # The value to set (static)
  valueType: String                    # Target primitive type for conversion
  # OR use valuePath for dynamic values:
  # valuePath: $.config.defaultStatus  # Path to retrieve value from data context

Parameter

Erforderliche Parameter

Parameter	Typ	Beschreibung
targetPath	string	JSONPath, an dem der konvertierte Wert gespeichert wird
valueType	enum	Primitiver Zieltyp für die Wertkonvertierung

Parameter der Wertquelle

Entweder value oder valuePath muss angegeben werden, aber nicht beides.

Parameter	Typ	Erforderlich	Beschreibung
value	any	Nein*	Statischer Quellwert, der konvertiert und zugewiesen wird
valuePath	string	Nein*	JSONPath, um den Wert dynamisch aus dem Data Context abzurufen

Unterstützte Werttypen

Werttyp	Beschreibung	Beispielwerte
String	Textwerte	"hello", "123", "true"
Int	32-Bit-Ganzzahlen	42, "123"
Int64	64-Bit-Ganzzahlen (long)	9223372036854775807, "123456789"
Double	Gleitkommazahlen doppelter Genauigkeit	3.14159, "3.14"
Boolean	Boolesche true/false-Werte	true, "false", "True"
DateTime	Datums- und Zeitwerte	"2023-12-25T00:00:00Z"
TimeSpan	Werte für Zeitdauern	"01:30:00", "1.12:00:00"
Binary	Byte-Werte	255, "128"
StringArray	Arrays von Strings	["item1", "item2"]
IntArray	Arrays von Ganzzahlen	[1, 2, 3]

Nicht unterstützte Typen

Die folgenden komplexen Typen werden nicht unterstützt und führen zu Fehlern:

• Record
• RecordArray
• Enum
• DateTimeOffset
• GeospatialPoint
• BinaryLinked

Wertquellen

Sie können den Quellwert auf zwei Arten angeben:

1. Statischer Wert: Verwenden Sie den Parameter value, um einen festen Wert anzugeben.
2. Dynamischer Wert: Verwenden Sie den Parameter valuePath, um einen Wert aus dem Data Context abzurufen.

Vorrang der Wertquelle

• Wird valuePath angegeben, hat er Vorrang vor value.
• Wird valuePath angegeben, aber an diesem Pfad kein Wert gefunden, wird ein Fehler ausgelöst.
• Es sollte nur eines von value oder valuePath angegeben werden.

Wertkonvertierung

• Automatische Typkonvertierung: Werte werden automatisch in den angegebenen Zieltyp konvertiert.
• Kulturunabhängiges Parsen: Double-Werte werden mit der invarianten Kultur (invariant culture) geparst, um Konsistenz zu gewährleisten.
• String-Repräsentationen: Die meisten primitiven Typen können aus String-Repräsentationen konvertiert werden.
• Array-Unterstützung: Die Typen StringArray und IntArray unterstützen Array-Eingabewerte.

Beispiele

Beispiel 1: Setzen eines String-Status

Einen Standardstatus zu Datensätzen hinzufügen:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.status
  value: "pending"
  valueType: String

Eingabe:

{
  "orderId": "12345",
  "customerName": "John Doe"
}

Ausgabe:

{
  "orderId": "12345",
  "customerName": "John Doe",
  "status": "pending"
}

Beispiel 2: Setzen eines numerischen Werts

Einen Steuersatz als Double hinzufügen:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.pricing.taxRate
  value: "0.0875"
  valueType: Double

Eingabe:

{
  "productId": "WIDGET-001",
  "price": 100.0
}

Ausgabe:

{
  "productId": "WIDGET-001",
  "price": 100.0,
  "pricing": {
    "taxRate": 0.0875
  }
}

Beispiel 3: Setzen eines Boolean-Flags

Ein Feature-Flag hinzufügen:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.features.premiumEnabled
  value: true
  valueType: Boolean

Eingabe:

{
  "userId": "user123"
}

Ausgabe:

{
  "userId": "user123",
  "features": {
    "premiumEnabled": true
  }
}

Beispiel 4: Setzen eines DateTime-Zeitstempels

Einen Verarbeitungszeitstempel hinzufügen:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.metadata.processedAt
  value: "2023-10-15T14:30:00Z"
  valueType: DateTime

Eingabe:

{
  "data": "sample content"
}

Ausgabe:

{
  "data": "sample content",
  "metadata": {
    "processedAt": "2023-10-15T14:30:00Z"
  }
}

Beispiel 5: Setzen eines Integer-Zählers

Einen Zähler initialisieren:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.metrics.processCount
  value: 0
  valueType: Int

Eingabe:

{
  "jobId": "job-456"
}

Ausgabe:

{
  "jobId": "job-456",
  "metrics": {
    "processCount": 0
  }
}

Beispiel 6: Setzen eines Array-Werts

Tags als String-Array hinzufügen:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.tags
  value: ["important", "urgent", "customer-facing"]
  valueType: StringArray

Eingabe:

{
  "ticketId": "TICKET-789"
}

Ausgabe:

{
  "ticketId": "TICKET-789",
  "tags": ["important", "urgent", "customer-facing"]
}

Beispiel 7: Setzen mit String-zu-Zahl-Konvertierung

String-Eingabe in einen numerischen Wert konvertieren:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.quantity
  value: "42"
  valueType: Int

Eingabe:

{
  "productCode": "ABC123"
}

Ausgabe:

{
  "productCode": "ABC123",
  "quantity": 42
}

Beispiel 8: Setzen mehrerer Werte

Mehrere Nodes verwenden, um mehrere primitive Werte zu setzen:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.metadata.version
  value: "1.0"
  valueType: String
- type: SetPrimitiveValue@1
  targetPath: $.metadata.created
  value: "2023-10-15T10:00:00Z"
  valueType: DateTime
- type: SetPrimitiveValue@1
  targetPath: $.metadata.priority
  value: "5"
  valueType: Int

Eingabe:

{
  "title": "Sample Document"
}

Ausgabe:

{
  "title": "Sample Document",
  "metadata": {
    "version": "1.0",
    "created": "2023-10-15T10:00:00Z",
    "priority": 5
  }
}

Beispiel 9: Dynamischer Wert mit ValuePath

Einen Wert mithilfe von ValuePath von einem Ort an einen anderen kopieren:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.customer.displayName
  valuePath: $.customer.fullName
  valueType: String

Eingabe:

{
  "customer": {
    "id": "CUST123",
    "fullName": "John Smith",
    "email": "john@example.com"
  }
}

Ausgabe:

{
  "customer": {
    "id": "CUST123",
    "fullName": "John Smith",
    "email": "john@example.com",
    "displayName": "John Smith"
  }
}

Beispiel 10: Konfigurationsbasierte Werte

Im Data Context gespeicherte Konfigurationswerte verwenden:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.order.taxRate
  valuePath: $.config.defaultTaxRate
  valueType: Double
- type: SetPrimitiveValue@1
  targetPath: $.order.currency
  valuePath: $.config.baseCurrency
  valueType: String

Eingabe:

{
  "config": {
    "defaultTaxRate": 0.19,
    "baseCurrency": "EUR"
  },
  "order": {
    "id": "ORD-001",
    "amount": 100.0
  }
}

Ausgabe:

{
  "config": {
    "defaultTaxRate": 0.19,
    "baseCurrency": "EUR"
  },
  "order": {
    "id": "ORD-001",
    "amount": 100.0,
    "taxRate": 0.19,
    "currency": "EUR"
  }
}

Beispiel 11: Kopieren eines berechneten Werts

Einen berechneten Wert an einen standardisierten Ort kopieren:

transformations:
- type: SetPrimitiveValue@1
  targetPath: $.summary.totalItems
  valuePath: $.analytics.calculatedTotals.itemCount
  valueType: Int

Eingabe:

{
  "analytics": {
    "calculatedTotals": {
      "itemCount": 42,
      "totalValue": 1250.00
    }
  },
  "items": ["item1", "item2", "..."]
}

Ausgabe:

{
  "analytics": {
    "calculatedTotals": {
      "itemCount": 42,
      "totalValue": 1250.00
    }
  },
  "items": ["item1", "item2", "..."],
  "summary": {
    "totalItems": 42
  }
}

Anwendungsfälle

• Standardwerte: Standardwerte für optionale Felder in Datensätzen setzen
• Metadaten-Injektion: Verarbeitungszeitstempel, Versionsnummern oder Systemkennungen hinzufügen
• Datenanreicherung: Konfigurationskonstanten oder berechnete Basiswerte injizieren
• Statusinitialisierung: Anfängliche Status-Flags oder Zustandsindikatoren setzen
• Hinzufügen von Konstanten: Systemweite Konstanten oder Konfigurationswerte hinzufügen
• Feldinitialisierung: Berechnete Felder mit Startwerten initialisieren
• Audit-Informationen: Audit-Trails mit Benutzer-IDs, Zeitstempeln oder Kennungen des Quellsystems hinzufügen
• Feature-Flags: Boolesche Flags für Feature-Toggles oder bedingte Verarbeitung setzen
• Wertkopie: Werte innerhalb desselben Data Context von einem Ort an einen anderen kopieren
• Konfigurationsverwaltung: Zentral im Data Context gespeicherte Konfigurationswerte verwenden
• Standardisierung berechneter Felder: Berechnete Werte an standardisierte Ausgabeorte verschieben

Fehlerbehandlung

Der Node wirft Fehler, wenn:

• Der angegebene valueType nicht unterstützt wird (komplexe Typen)
• Die Wertkonvertierung aufgrund inkompatibler Typen oder eines ungültigen Formats fehlschlägt
• Ungültige JSONPath-Ausdrücke für targetPath oder valuePath verwendet werden
• valuePath angegeben wird, an diesem Pfad aber kein Wert gefunden wird
• Weder value noch valuePath angegeben wird

Konvertierungsbeispiele

String-zu-Zahl-Konvertierung

value: "123.45"
valueType: Double
# Result: 123.45 (double)

Boolean-String-Konvertierung

value: "true"
valueType: Boolean
# Result: true (boolean)

Kulturunabhängiges Double-Parsen

value: "3.14159"  # Always uses dot as decimal separator
valueType: Double
# Result: 3.14159 (consistent regardless of system locale)

Dynamischer Wert aus JSONPath

valuePath: "$.metadata.userId"  # Extract value from data context
valueType: String
# Result: Value at $.metadata.userId converted to string

Hinweise

• Kulturunabhängig: Double-Werte werden mit der invarianten Kultur geparst, um regionale Formatierungsprobleme zu vermeiden.
• Typsicherheit: Werte werden für Typsicherheit in exakte primitive Typen konvertiert.
• Pfaderstellung: Zielpfade werden erstellt, falls sie nicht existieren (unter Beachtung von targetValueWriteMode).
• Überschreibverhalten: Bestehende Werte können je nach targetValueWriteMode überschrieben oder beibehalten werden.
• Array-Unterstützung: Sowohl String- als auch Integer-Arrays werden für listenbasierte Daten unterstützt.
• Null-Behandlung: Null-Werte werden gemäß den Null-Behandlungsregeln des Zieltyps verarbeitet.
• ValuePath-Vorrang: Werden sowohl value als auch valuePath angegeben, hat valuePath Vorrang.
• Dynamische Auflösung: ValuePath wird zur Laufzeit gegen den aktuellen Data Context ausgewertet.
• Fehler bei fehlendem Pfad: Wird valuePath angegeben, existiert an diesem Pfad aber kein Wert, wird ein Fehler ausgelöst.

Verwandte Nodes

• WriteJson@1: Komplexe JSON-Strukturen in die Datenpipeline schreiben
• Math@1: Mathematische Operationen an numerischen Werten durchführen
• If@1: Werte bedingt anhand von Datenbedingungen setzen