TIPCommon.utils

The TIPCommon.utils module serves as a foundational toolkit for integration developers. It provides essential helpers for string manipulation, secure type casting, OData query construction, and environment-specific checks to ensure that integrations run smoothly across different platform versions and execution states.

Data cleaning and type casting

These functions handle the "pre-processing" of data, ensuring variables are in the correct format before being used in logic or sent to external APIs.

Function	Parameters	Description & Returns
camel_to_snake_case()	string: (str) Target camelCase string.	Returns: str Converts camelCase or PascalCase strings to snake_case. Essential for normalizing API responses to Pythonic naming conventions.
cast_keys_to_int()	data: (dict) Dictionary with numeric string keys.	Returns: dict Creates a new dictionary where all keys are cast to integers. Often used when processing JSON data that represents IDs as strings.
clean_result()	value: (str) Target string.	Returns: str Strips leading and trailing whitespace. A svital utility for cleaning user input from integration parameters.
none_to_default_value()	value_to_check: (Any) Input value. value_to_return_if_none: (Any) Fallback.	Returns: Any Checks if a value is None. If so, returns the default fallback; otherwise, returns the original value.
safe_cast_bool_value_from_str()	default_value: (Any) The value to evaluate.	Returns: bool | Any Converts string booleans (like "true") to actual booleans. Returns the default_value if casting fails.
safe_cast_int_value_from_str()	default_value: (Any) The value to evaluate.	Returns: int | Any Attempts to cast a value to an integer. Returns the default_value if the cast is unsuccessful.

Environment and execution logic

These utilities allow scripts to identify their runtime context, such as whether they are running as a test, an asynchronous action, or on a specific version of the platform.

Function	Parameters	Description & Returns
is_first_run()	sys_argv: (list) Arguments from sys.argv.	Returns: bool Determines if an action is being executed asynchronously for the first time. Used to manage state in polling actions.
is_test_run()	sys_argv: (list) Arguments from sys.argv.	Returns: bool Identifies if the script is running in "Test" mode within the IDE. Use this to bypass real API calls during development.
is_overflowed()	siemplify: (SiemplifyConnectorExecution) alert_info: (AlertInfo) is_test_run: (bool)	Returns: bool Checks if an alert meets the platform's overflow criteria. Essential for connectors to prevent redundant alert ingestion.
is_python_37()	None	Returns: bool Checks if the current Python version is at least 3.7. Useful for toggling between legacy and modern language features.
platform_supports_1p_api()	None	Returns: bool Checks if the instance supports First-Party (1P) unified APIs. Enables dynamic fallback logic for multi-platform support.
platform_supports_db()	siemplify: (ChronicleSOAR) SDK object.	Returns: bool Determines if the environment supports DataStreams. If False, the integration should fall back to file-based state.

Data validation and filtering

Utilities for ensuring data integrity, performing set operations, and retrieving values from complex JSON structures.

Function	Parameters	Description & Returns
escape_odata_literal()	value: (Any) The raw query value.	Returns: Any Doubles single quotes in a string for OData compliance. Important: This prevents query injection and syntax errors in $filter expressions.
get_unique_items_by_difference()	item_pool: (Iterable) The source items. items_to_remove: (Iterable) Exclusion list.	Returns: list Calculates the set difference (Pool - Remove) and returns unique items as a list. Useful for filtering processed alerts.
get_value_from_json()	data: (dict) JSON data to search. *keys: (str) Ordered fallback keys. default: (Any) Fallback value.	Returns: Any Retrieves values from nested JSON using a "waterfall" of keys. Returns the default if none of the keys exist.
is_empty_string_or_none()	data: (str) String to check.	Returns: bool Returns True if the input is None or only contains an empty string "". Essential for safety-checks on API responses.
is_valid_email()	email_addr: (str) String to check.	Returns: bool Validates an email address format using standard regular expression. Useful for pre-validating parameters before external API calls.
is_valid_uuid()	string: (str) String to check.	Returns: bool Ensures a string is a valid UUID version 4. Prevents 400 errors when passing IDs to platform endpoints.

System and file utilities

Helpers for interacting with the operating system, managing temporary files, and handling entity metadata.

Function	Parameters	Description & Returns
create_and_write_to_tempfile()	content: (str | bytes) Data to write.	Returns: Path Writes content to a secure temporary file. Useful for actions that require passing data to command-line tools.
get_entity_original_identifier()	entity: (Entity) Target entity object.	Returns: str Retrieves the original identifier for an entity, ensuring accurate mapping back to source alerts.
get_function_arg_names()	func: (Callable) Target function.	Returns: list Uses reflection to retrieve all argument names defined in a function. Essential for building dynamic wrappers.
get_sdk_api_uri()	chronicle_soar: (ChronicleSOAR) SDK instance.	Returns: str Retrieves the base API URI for the current environment. Vital for constructing custom REST calls outside standard wrappers.
safe_json_for_204()	response: (Response) HTTP response object. default_for_204: (Any) Fallback value.	Returns: list | dict | Any Safely handles 204 (No Content) responses. Returns an empty list or the default_for_204 value instead of crashing during JSON parsing.
temporarily_remove_header()	header_name: (str) Header to suppress.	Returns: callable Decorator: Temporarily removes a header (like 'Prefer') from a session for the duration of a single call.