update_event_data#

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

Update existing event records in an AMS Event Form.

Processes a pandas.DataFrame containing data with an ‘event_id’ column, maps user identifiers to user IDs, validates the data, constructs an API payload, and sends it to the AMS API to update existing events in the specified Event Form. Supports table fields via the UpdateEventOption, 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 update workflows.

Parameters:

  • df (pandas.DataFrame) – A pandas DataFrame containing the event data to update. Must include an ‘event_id’ column with valid integer IDs of existing events, and other columns for field names with values to update. Must not be empty.

  • form (str) – The name of the AMS Event Form to update data in. 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 (UpdateEventOption, optional) – Configuration options for the update, 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 UpdateEventOption. 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 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 ‘event_id’, or invalid IDs), the payload cannot be built, the API request fails, or the user cancels the 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 update_event_data, UpdateEventOption
>>> df = pd.DataFrame({
...     "event_id": [67890, 67891],
...     "username": ["john.doe", "jane.smith"],
...     "duration": [65, 50],
...     "intensity": ["High Updated", "Medium Updated"]
... })
>>> update_event_data(
...     df = df,
...     form = "Training Log",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = UpdateEventOption(id_col = "username", interactive_mode = True)
... )
ℹ Updating 2 events for 'Training Log'
Are you sure you want to update 2 existing events in 'Training Log'? (y/n): y
✔ Processed 2 events for 'Trainin gLog'
ℹ Form: Training Log
ℹ Result: Success
ℹ Records updated: 2
ℹ Records attempted: 2

Additional Notes#

  • The df must include ‘event_id’ with valid integer IDs; invalid IDs raise AMSError. Use get_event_data() to retrieve IDs.

  • Set option.require_confirmation=True to prompt for confirmation before updating, preventing accidental changes in interactive mode.

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

See Also#