sync_event_data#

teamworksams.export_main.sync_event_data(form: str, last_synchronisation_time: int, url: str, username: str | None = None, password: str | None = None, filter: SyncEventFilter | None = None, option: SyncEventOption | None = None, client: AMSClient | None = None) → Tuple[pandas.DataFrame, int][source]#

Retrieve event data from an AMS event form modified since the last synchronization time.

Fetches event data from an AMS Event Form using the ‘synchronise’ endpoint, returning only events inserted/updated since last_synchronisation_time (milliseconds since 1970-01-01). Returns a pandas.DataFrame and a new synchronization time for subsequent calls. Supports user filtering and options like user metadata inclusion. Provides interactive feedback when option.interactive_mode=True. See Exporting Data for synchronization 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.

  • last_synchronisation_time (int) – Last synchronization time in milliseconds since 1970-01-01 (e.g., 1677654321000 for 2023-03-01 12:25:21). Must be non-negative.

  • 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 (SyncEventFilter, optional) – Filter object to narrow results by user attributes (e.g., ‘group’). If None, includes all events. Defaults to None.

  • option (SyncEventOption, optional) – Configuration options, including interactive_mode for status messages, include_user_data to add user metadata, include_uuid to add UUIDs, guess_col_type to infer data types, cache to reuse a client, and include_missing_users to include users without events. Defaults to None (uses default SyncEventOption).

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

Returns:

A tuple containing:

  • A DataFrame with event data (columns: ‘event_id’, ‘user_id’, ‘start_date’, ‘form’, etc.). Empty with columns [‘user_id’, ‘event_id’, ‘form’, ‘start_date’] if no new events are found.

  • An integer representing the new synchronization time (milliseconds) for subsequent calls.

Return type:

Tuple[pandas.DataFrame, int]

Raises:

  • AMSError – If form is empty, no users match the filter, authentication fails, or the API request fails.

  • ValueError – If last_synchronisation_time is negative or not an integer.

Examples

>>> from teamworksams import sync_event_data, SyncEventFilter, SyncEventOption
>>> df, new_sync_time = sync_event_data(
...     form = "Training Log",
...     last_synchronisation_time = 1677654321000,
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     filter = SyncEventFilter(user_key = "group", user_value = "Example Group"),
...     option = SyncEventOption(interactive_mode = True, include_user_data = True)
... )
ℹ Requesting event data for form 'Training Log' since last synchronisation time 2023-03-01 12:25:21
✔ Retrieved 5 event records for form 'Training Log' since last synchronisation time 2023-03-01 12:25:21
>>> print(df.head())
   about  user_id  event_id  form         start_date  duration  intensity
0  John Doe    12345    67890  Training Log  01/03/2025        60       High
>>> print(new_sync_time)
1677654400000

Additional Notes#

  • The last_synchronisation_time is in milliseconds since 1970-01-01 (Unix epoch). Use the returned new synchronization time for subsequent calls to avoid duplicate data.

  • Set option.include_user_data=True to append user metadata (e.g., ‘about’) to the pandas.DataFrame, useful for reporting.

  • The DataFrame’s attrs['deleted_event_ids'] contains IDs of deleted events, which can be used to update local datasets.

See Also#