TIPCommon.utils

Das Modul TIPCommon.utils dient als grundlegendes Toolkit für Integrationsentwickler. Sie bietet wichtige Hilfsfunktionen für die Stringbearbeitung, das sichere Typecasting, die Erstellung von OData-Abfragen und umgebungsspezifische Prüfungen, damit Integrationen auf verschiedenen Plattformversionen und in verschiedenen Ausführungsstatus reibungslos ausgeführt werden.

Datenbereinigung und Typumwandlung

Diese Funktionen übernehmen die Vorverarbeitung von Daten und sorgen dafür, dass Variablen das richtige Format haben, bevor sie in der Logik verwendet oder an externe APIs gesendet werden.

Funktion	Parameter	Beschreibung und Retouren
camel_to_snake_case()	string: (str) Ziel-camelCase-String.	Liefert: str Konvertiert camelCase- oder PascalCase-Strings in snake_case. Unerlässlich für die Normalisierung von API-Antworten auf Python-Namenskonventionen.
cast_keys_to_int()	data: (dict) Dictionary mit numerischen Stringschlüsseln.	Liefert: dict Erstellt ein neues Dictionary, in dem alle Schlüssel in Ganzzahlen umgewandelt werden. Wird häufig verwendet, wenn JSON-Daten verarbeitet werden, in denen IDs als Strings dargestellt werden.
clean_result()	value: (str) Zielstring.	Liefert: str Entfernt voran- und nachgestellte Leerzeichen. Ein svital-Dienstprogramm zum Bereinigen von Nutzereingaben aus Integrationsparametern.
none_to_default_value()	value_to_check: (Beliebiger) Eingabewert. value_to_return_if_none: (Beliebig) Fallback.	Liefert: Any Prüft, ob ein Wert None ist. Falls ja, wird der Standard-Fallback zurückgegeben, andernfalls der ursprüngliche Wert.
safe_cast_bool_value_from_str()	default_value: (Beliebig) Der auszuwertende Wert.	Liefert: bool | Any Wandelt boolesche Strings (z. B. „true“) in tatsächliche boolesche Werte um. Gibt default_value zurück, wenn die Umwandlung fehlschlägt.
safe_cast_int_value_from_str()	default_value: (Beliebig) Der auszuwertende Wert.	Liefert: int | Any Versucht, einen Wert in eine Ganzzahl umzuwandeln. Gibt default_value zurück, wenn die Übertragung nicht erfolgreich war.

Umgebung und Ausführungslogik

Mit diesen Dienstprogrammen können Skripts ihren Laufzeitkontext ermitteln, z. B. ob sie als Test, als asynchrone Aktion oder auf einer bestimmten Version der Plattform ausgeführt werden.

Funktion	Parameter	Beschreibung und Retouren
is_first_run()	sys_argv: (Liste) Argumente aus sys.argv.	Liefert: bool Gibt an, ob eine Aktion zum ersten Mal asynchron ausgeführt wird. Wird zum Verwalten des Status in Polling-Aktionen verwendet.
is_test_run()	sys_argv: (Liste) Argumente aus sys.argv.	Liefert: bool Gibt an, ob das Skript in der IDE im Testmodus ausgeführt wird. Damit können Sie während der Entwicklung echte API-Aufrufe umgehen.
is_overflowed()	siemplify: (SiemplifyConnectorExecution) alert_info: (AlertInfo) is_test_run: (bool)	Liefert: bool Prüft, ob eine Benachrichtigung die Überlaufkriterien der Plattform erfüllt. Unerlässlich für Connectors, um die redundante Aufnahme von Benachrichtigungen zu verhindern.
is_python_37()	Keine	Liefert: bool Prüft, ob die aktuelle Python-Version mindestens 3.7 ist. Nützlich zum Umschalten zwischen Legacy- und modernen Sprachfunktionen.
platform_supports_1p_api()	Keine	Liefert: bool Prüft, ob die Instanz einheitliche APIs für eigene Produkte unterstützt. Ermöglicht eine dynamische Fallback-Logik für die Unterstützung mehrerer Plattformen.
platform_supports_db()	siemplify: (ChronicleSOAR) SDK-Objekt.	Liefert: bool Gibt an, ob die Umgebung DataStreams unterstützt. Wenn False, sollte die Integration auf den dateibasierten Status zurückgreifen.

Datenvalidierung und ‑filterung

Dienstprogramme zum Sicherstellen der Datenintegrität, zum Ausführen von Mengenoperationen und zum Abrufen von Werten aus komplexen JSON-Strukturen.

Funktion	Parameter	Beschreibung und Retouren
escape_odata_literal()	value: (Beliebig) Der Rohwert der Abfrage.	Liefert: Any Verdoppelt einfache Anführungszeichen in einem String, um OData-konform zu sein. Wichtig:Dadurch werden Query-Injection und Syntaxfehler in $filter-Ausdrücken verhindert.
get_unique_items_by_difference()	item_pool: (Iterable) Die Quellelemente. items_to_remove: (Iterable) Ausschlussliste.	Liefert: list Berechnet die Differenz der Mengen (Pool – Remove) und gibt eindeutige Elemente als Liste zurück. Nützlich zum Filtern verarbeiteter Benachrichtigungen.
get_value_from_json()	data: (dict) JSON-Daten, die durchsucht werden sollen. *keys: (str) Geordnete Fallback-Schlüssel. default: (Beliebig) Fallback-Wert.	Liefert: Any Ruft Werte aus verschachteltem JSON mithilfe einer „Wasserfall“-Methode von Schlüsseln ab. Gibt default zurück, wenn keiner der Schlüssel vorhanden ist.
is_empty_string_or_none()	data: (str) Der zu prüfende String.	Liefert: bool Gibt True zurück, wenn die Eingabe None ist oder nur einen leeren String "" enthält. Unerlässlich für Sicherheitsprüfungen von API-Antworten.
is_valid_email()	email_addr: (str) Der zu prüfende String.	Liefert: bool Validiert das Format einer E‑Mail-Adresse mithilfe eines standardmäßigen regulären Ausdrucks. Nützlich, um Parameter vor externen API-Aufrufen vorab zu validieren.
is_valid_uuid()	string: (str) Der zu prüfende String.	Liefert: bool Stellt sicher, dass ein String eine gültige UUID der Version 4 ist. Verhindert 400-Fehler beim Übergeben von IDs an Plattformendpunkte.

System- und Dateidienstprogramme

Helfer für die Interaktion mit dem Betriebssystem, die Verwaltung temporärer Dateien und die Verarbeitung von Metadaten für Entitäten.

Funktion	Parameter	Beschreibung und Retouren
create_and_write_to_tempfile()	content: (str | bytes) Zu schreibende Daten.	Liefert: Path Schreibt Inhalte in eine sichere temporäre Datei. Nützlich für Aktionen, bei denen Daten an Befehlszeilentools übergeben werden müssen.
get_entity_original_identifier()	entity: (Entität) Zielentitätsobjekt.	Liefert: str Ruft die ursprüngliche Kennung für eine Entität ab, um eine genaue Zuordnung zu Quellbenachrichtigungen zu ermöglichen.
get_function_arg_names()	func: Aufrufbare Zielfunktion.	Liefert: list Verwendet die Reflektion, um alle in einer Funktion definierten Argumentnamen abzurufen. Unerlässlich für die Erstellung dynamischer Wrapper.
get_sdk_api_uri()	chronicle_soar: SDK-Instanz (ChronicleSOAR).	Liefert: str Ruft die Basis-API-URI für die aktuelle Umgebung ab. Unerlässlich für das Erstellen benutzerdefinierter REST-Aufrufe außerhalb von Standard-Wrappern.
safe_json_for_204()	response: (Antwort) HTTP-Antwortobjekt. default_for_204: (Beliebig) Fallback-Wert.	Liefert: list | dict | Any Sicherer Umgang mit 204-Antworten (No Content). Gibt eine leere Liste oder den default_for_204-Wert zurück, anstatt beim JSON-Parsing abzustürzen.
temporarily_remove_header()	header_name: (str) Header, der unterdrückt werden soll.	Liefert: callable Decorator:Entfernt einen Header (z. B. 'Prefer') vorübergehend aus einer Sitzung für die Dauer eines einzelnen Aufrufs.