# TIPCommon.smp_io

The **TIPCommon.smp_io** module provides a standardized interface for managing
stateful data within connectors. It facilitates the reading and writing of alert
IDs and general content to persistent storage, supporting both file-based and
database-backed data streams to ensure consistency across connector executions.

## State management

These functions are primarily used by connectors to track processed alerts and
maintain execution state. They handle the complexity of JSON serialization,
default value assignment, and data repair to prevent regressions.

The following table provides the technical specifications for each I/O utility,
organized for quick parameter reference:

| Function | Parameters | Description \& Returns |
|---|---|---|
| `read_and_repair_existing_ids()` | - `siemplify`: (SiemplifyConnectorExecution) SDK instance. - `default_value_to_return`: (Any) Fallback if new. Defaults to `[]`. - `identifier`: (str) Connector identifier. - `ids_file_name`: (str) Defaults to `ids.json`. - `db_key`: (str) Defaults to `ids`. | Returns: `list` Reads existing alert IDs and automatically converts them from a dictionary to a list format to avoid legacy regressions. |
| `read_content()` | - `siemplify`: (SiemplifyConnectorExecution) SDK instance. - `file_name`: (str) File to validate. - `db_key`: (str) DB key to validate. - `default_value_to_return`: (Any) Fallback if new. Defaults to `{}`. - `identifier`: (str) Connector identifier. | Returns: `dict` Retrieves the general content of a `ConnectorStream` object. Content is automatically parsed using `json.loads` before returning. |
| `read_ids()` | - `siemplify`: (SiemplifyConnectorExecution) SDK instance. - `default_value_to_return`: (Any) Fallback if new. Defaults to `[]`. - `identifier`: (str) Connector identifier. - `ids_file_name`: (str) Defaults to `ids.json`. - `db_key`: (str) Defaults to `ids`. | Returns: `list` Reads a list of processed IDs from the state storage. Content is parsed using `json.loads` before returning. |
| `read_ids_by_timestamp()` | - `siemplify`: (SiemplifyConnectorExecution) SDK instance. - `offset_in_hours`: (int) Time limit. Defaults to `72`. - `convert_to_milliseconds`: (bool) Seconds to ms conversion. - `cast_keys_to_integers`: (bool) Cast dictionary keys. - `offset_is_in_days`: (bool) Toggle for day-based offsets. | Returns: `list` Retrieves IDs falling within a specific time window, typically used for lookback verification of recently seen alerts. |
| `write_content()` | - `siemplify`: (SiemplifyConnectorExecution) SDK instance. - `content_to_write`: (dict\|list\|str) Data to persist. - `file_name`: (str) Target filename. - `db_key`: (str) Target DB key. - `default_value_to_set`: (Any) Initial value for new streams. | Returns: `None` Persists arbitrary content into a `ConnectorStream` for cross-execution state management. |
| `write_ids()` | - `siemplify`: (SiemplifyConnectorExecution) SDK instance. - `ids`: (list\|str) IDs to persist. - `stored_ids_limit`: (int) Max IDs to keep. Defaults to `1,000`. - `ids_file_name`: (str) Target filename. - `db_key`: (str) Target DB key. | Returns: `None` Saves a list of IDs while enforcing a limit to prevent the state file from growing indefinitely. |
| `write_ids_with_timestamp()` | - `siemplify`: (SiemplifyConnectorExecution) SDK instance. - `ids`: (dict\|list\|str) IDs and timestamps to write. - `ids_file_name`: (str) Target filename. - `db_key`: (str) Target DB key. | Returns: `None` Saves IDs along with associated timestamps, enabling time-aware retrieval for lookback logic. |