upsert_event_data#

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

Insert and update event records in an AMS Event Form.

Performs an upsert operation on a pandas.DataFrame, splitting it into records with an ‘event_id’ (for updates) and without (for inserts). Processes each group separately, mapping user identifiers to user IDs, validating the data, constructing API payloads, and sending them to the AMS API to update existing events or insert new ones in the specified Event Form. Supports table fields via the UpsertEventOption, which allows configuration of user identifier mapping, caching, and interactive feedback. In interactive mode, prompts for confirmation before updating and provides status updates. See Importing Data for upsert workflows.

Parameters:

  • df (pandas.DataFrame) – A pandas DataFrame containing the event data to upsert. Records with an ‘event_id’ column are updated; those without are inserted. 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 upsert 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 (UpsertEventOption, optional) – Configuration options for the upsert, including id_col (column for user identifiers, e.g., ‘user_id’, ‘username’), interactive_mode (for status messages and confirmation), cache (for API response caching), and table_fields (list of table field names). If None, uses default UpsertEventOption. 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 updates and inserts events in 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 for inserts or ‘event_id’ for updates), the payload cannot be built, the API request fails, or the user cancels the update operation in interactive mode.

  • 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 upsert_event_data, UpsertEventOption
>>> df = pd.DataFrame({
...     "event_id": [67890, None],
...     "username": ["john.doe", "jane.smith"],
...     "start_date": ["01/01/2025", "02/01/2025"],
...     "duration": [65, 45],
...     "intensity": ["High Updated", "Medium"]
... })
>>> upsert_event_data(
...     df = df,
...     form = "Training Log",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = UpsertEventOption(id_col = "username", interactive_mode = True)
... )
ℹ Updating 1 existing events for 'Training Log'
Are you sure you want to update 1 existing events in 'Training Log'? (y/n): y
ℹ Inserting 1 new events for 'Training Log'
✔ Processed 2 events for 'Training Log'
ℹ Form: Training Log
ℹ Result: Success
ℹ Records upserted: 2
ℹ Records attempted: 2

Additional Notes#

  • Records with ‘event_id’ are updated; those without require ‘start_date’ and are inserted. Splitting is automatic based on ‘event_id’ presence.

  • Use option.require_confirmation=True to prompt for update confirmation, ensuring safe operations in interactive mode.

  • Enable option.cache=True to reuse a AMSClient() for both insert and update operations, improving performance.

See Also#