Deleting Data#

This vignette provides a guide to deleting event data in Teamworks AMS using teamworksams, covering delete_event_data() and delete_multiple_events(). It outlines safe workflows for removing single or multiple events from AMS Event Forms, with Python/pandas examples. emphasizing safety features like confirmation prompts and integration with get_event_data() for event ID retrieval. See Functions and Classes for detailed documentation and Getting Started with teamworksams if you haven’t already.

Overview#

teamworksams supports event deletion with two key functions:

These functions are used for data cleanup, removing outdated or erroneous events. Deletion is permanent, so the delete_event_option() provides interactive confirmation prompts for safety. Examples use the placeholder URL https://example.smartabase.com/site and credentials in a .env file.

Prerequisites#

Ensure teamworksams is installed and credentials are configured, as in Getting Started with teamworksams. Use a .env file:

.env#
AMS_URL=https://example.smartabase.com/site
AMS_USERNAME=username
AMS_PASSWORD=password

Load credentials:

from dotenv import load_dotenv
load_dotenv()

Dependencies (installed with teamworksams): pandas, requests, python-dotenv, tqdm. Use get_event_data() to retrieve valid event IDs.

Deleting a Single Event#

Use delete_event_data() to remove a single event by its ID:

Retrieving Event ID

Fetch event IDs from an Event Form:

import pandas as pd
from teamworksams import get_event_data, EventOption
event_df = get_event_data(
    form="Training Log",
    start_date="01/01/2025",
    end_date="31/01/2025",
    url="https://example.smartabase.com/site",
    option=EventOption(interactive_mode=True)
)
event_id = event_df["event_id"].iloc[0]

Deleting the Event

Delete the event with confirmation:

from teamworksams import delete_event_data, DeleteEventOption
result = delete_event_data(
    event_id=event_id,
    url="https://example.smartabase.com/site",
    option=DeleteEventOption(interactive_mode=True)
)
print(result)

Output:

Are you sure you want to delete event '134273'? (y/n): y
ℹ Deleting event with ID 134273...
✔ SUCCESS: Deleted 134273
SUCCESS: Deleted 134273

See delete_event_data() and delete_event_option() for details.

Deleting Multiple Events#

Use delete_multiple_events() to remove multiple events by their IDs:

Retrieving Event IDs

Filter events to delete (e.g., specific user or date):

event_df = get_event_data(
    form="Training Log",
    start_date="01/01/2025",
    end_date="01/01/2025",
    url="https://example.smartabase.com/site",
    option=EventOption(interactive_mode=True)
)
event_ids = event_df["event_id"].head(3).tolist()

Deleting the Events

Delete multiple events with confirmation:

from teamworksams import delete_multiple_events, DeleteEventOption
result = delete_multiple_events(
    event_ids=event_ids,
    url="https://example.smartabase.com/site",
    option=DeleteEventOption(interactive_mode=True)
)
print(result)

Output:

Are you sure you want to delete 3 events with IDs [134273, 134274, 134275]? (y/n): y
ℹ Deleting 3 events with IDs [134273, 134274, 134275]...
✔ SUCCESS: Deleted 3 events
SUCCESS: Deleted 3 events

See delete_multiple_events() and delete_event_option() for details.

Error Handling#

Deletion functions raise AMSError with descriptive messages:

delete_event_data(event_id=999999, url="https://example.smartabase.com/site")

Output:

Are you sure you want to delete event '999999'? (y/n): y
✖ Failed to delete event with ID 999999: Invalid event ID
AMSError: Invalid event ID...

Common errors include: - Invalid or non-existent event_id. - User cancellation in interactive mode. - Authentication or API failures.

Best Practices#

  • Validate Event IDs: Use get_event_data() to ensure event_id values are valid before deletion.

  • Use Confirmation: Enable option.interactive_mode=True to prompt for confirmation, preventing accidental deletions.

  • Batch Deletion: Prefer delete_multiple_events() for efficiency when removing multiple events.

  • Log Results: Capture returned messages for auditing deletion outcomes.

  • Test First: Filter events with get_event_data() to review before deleting.

Next Steps#