insert_event_data#

teamworksams.import_main.insert_event_data(df: pandas.DataFrame, form: str, url: str, username: str | None = None, password: str | None = None, option: InsertEventOption | None = None, client: AMSClient | None = None) → None[source]#

Insert new event records into an AMS Event Form.

Processes a pandas.DataFrame containing event data, maps user identifiers to user IDs, validates the data, constructs an API payload, and sends it to the AMS API to insert new events into the specified Event Form. Supports table fields via the InsertEventOption, which allows configuration of user identifier mapping, caching, and interactive feedback. Provides status updates if interactive mode is enabled, reporting the number of events inserted. See Importing Data for import workflows.

Parameters:

  • df (pandas.DataFrame) – A pandas DataFrame containing the event data to insert. Columns represent field names (including ‘start_date’, ‘user_id’ or another identifier specified by option.id_col), and rows contain values. Must not be empty.

  • form (str) – The name of the AMS Event Form to insert data into. Must be a non-empty string and correspond to a valid event form.

  • url (str) – The AMS instance URL (e.g., ‘https://example.smartabase.com/site’).

  • username (Optional[str]) – The username for authentication. If None, uses the AMS_USERNAME environment variable. Defaults to None.

  • password (Optional[str]) – The password for authentication. If None, uses the AMS_PASSWORD environment variable. Defaults to None.

  • option (InsertEventOption, optional) – Configuration options for the insertion, including id_col (column for user identifiers, e.g., ‘user_id’, ‘username’), interactive_mode (for status messages), cache (for API response caching), and table_fields (list of table field names). If None, uses default InsertEventOption. Defaults to None.

  • client (AMSClient, optional) – A pre-authenticated AMSClient instance. If None, a new client is created using the provided url, username, and password. Defaults to None.

Returns:

The function does not return a value but inserts events into the AMS database

and prints status messages if interactive_mode is enabled.

Return type:

None

Raises:

  • AMSError – If the form is empty, not an event form, authentication fails, the DataFrame is invalid (e.g., empty, missing required fields like ‘start_date’), the payload cannot be built, or the API request fails.

  • ValueError – If option.id_col is invalid or table_fields contains field names not present in the DataFrame.

Examples

>>> import pandas as pd
>>> from teamworksams import insert_event_data, InsertEventOption
>>> df = pd.DataFrame({
...     "username": ["john.doe", "jane.smith"],
...     "start_date": ["01/01/2025", "01/01/2025"],
...     "duration": [60, 45],
...     "intensity": ["High", "Medium"]
... })
>>> insert_event_data(
...     df = df,
...     form = "Training Log",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = InsertEventOption(id_col = "username", interactive_mode = True)
... )
ℹ Inserting 2 events for 'Training Log'
✔ Processed 2 events for 'Training Log'
ℹ Form: TrainingLog
ℹ Result: Success
ℹ Records inserted: 2
ℹ Records attempted: 2

Additional Notes#

  • The df must include ‘start_date’ in ‘DD/MM/YYYY’ format and a user identifier column (specified by option.id_col, e.g., ‘username’). Missing or invalid data raises AMSError.

  • Use option.table_fields to specify table fields in the AMS form, ensuring column names match exactly.

  • Enable option.interactive_mode=True for status messages like “Inserted 2 events,” useful in interactive environments.

See Also#