get_event_data#

teamworksams.export_main.get_event_data(form: str, start_date: str, end_date: str, url: str, username: str | None = None, password: str | None = None, filter: EventFilter | None = None, option: EventOption | None = None, client: AMSClient | None = None) → pandas.DataFrame[source]#

Retrieve event data from an AMS Event Form within a date range.

Fetches event data from the specified AMS Event Form for a given date range, returning a pandas.DataFrame with columns like ‘event_id’, ‘user_id’, and form fields. Supports optional filtering by user attributes (e.g., group) or data fields, and downloading attachments if enabled. Provides interactive feedback when option.interactive_mode=True. See Exporting Data for data export workflows.

Parameters:

  • form (str) – Name of the AMS Event Form (e.g., ‘Training Log’). Must be a non-empty string and correspond to a valid form.

  • start_date (str) – Start date for the event range in ‘DD/MM/YYYY’ format (e.g., ‘01/01/2025’). Must be a valid date.

  • end_date (str) – End date for the event range in ‘DD/MM/YYYY’ format (e.g., ‘31/01/2025’). Must be a valid date and not before start_date.

  • url (str) – AMS instance URL (e.g., ‘https://example.smartabase.com/site’). Must include a valid site name.

  • username (Optional[str]) – Username for authentication. If None, uses AMS_USERNAME or keyring credentials. Defaults to None.

  • password (Optional[str]) – Password for authentication. If None, uses AMS_PASSWORD or keyring credentials. Defaults to None.

  • filter (EventFilter, optional) – Filter object to narrow results by user attributes (e.g., ‘group’) or data fields (e.g., ‘intensity=High’). If None, includes all events. Defaults to None.

  • option (EventOption, optional) – Configuration options, including interactive_mode for status messages, download_attachment to fetch attachments, clean_names to standardize column names, guess_col_type to infer data types, convert_dates to parse dates, cache to reuse a client, and attachment_directory for saving attachments. Defaults to None (uses default EventOption).

  • client (AMSClient, optional) – Pre-authenticated client from get_client(). If None, a new client is created. Defaults to None.

Returns:

Event data with columns like ‘event_id’, ‘user_id’,

’start_date’, ‘form’, and form fields (e.g., ‘duration’). Empty with columns [‘user_id’, ‘event_id’, ‘form’, ‘start_date’] if no events are found.

Return type:

pandas.DataFrame

Raises:

  • AMSError – If form is empty, no events/users are found, authentication fails, or the API request fails.

  • ValueError – If start_date or end_date is not in ‘DD/MM/YYYY’ format, or if filter parameters are invalid.

Examples

>>> import pandas as pd
>>> from teamworksams import get_event_data, EventFilter, EventOption
>>> df = get_event_data(
...     form = "Training Log",
...     start_date = "01/01/2025",
...     end_date = "31/01/2025",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     filter = EventFilter(user_key = "group", user_value = "Example Group"),
...     option = EventOption(interactive_mode = True, clean_names = True)
... )
ℹ Requesting event data for 'Training Log' between 01/01/2025 and 31/01/2025
ℹ Processing 10 events...
✔ Retrieved 10 event records for form 'Training Log'.
>>> print(df.head())
   about  user_id  event_id  form         start_date  duration  intensity
0  John Doe    12345    67890  Training Log  01/01/2025        60       High
1  Jane Smith  12346    67891  Training Log  02/01/2025        45     Medium

Additional Notes#

  • The form parameter must match an existing AMS Event Form exactly (case-sensitive).

  • Use option.download_attachment=True to fetch attachments, storing them in option.attachment_directory (defaults to current directory if unset).

  • The filter parameter, when combined with EventFilter(), reduces API load by limiting events to specific users or field values (e.g., ‘intensity=High’).

See Also#