upsert_profile_data#

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

Upsert profile data in an AMS Profile Form.

Processes a pandas.DataFrame containing profile data, maps user identifiers to user IDs, validates the data, constructs an API payload, and sends it to the AMS API to update existing profile records or insert new ones in the specified Profile Form. Profile forms allow only one record per user. In interactive mode, prompts for confirmation before upserting and provides status updates.

Parameters:

  • df (pandas.DataFrame) – A pandas DataFrame containing the profile data to upsert. Columns represent field names, and rows contain values. Must include a user identifier column (specified by option.id_col, e.g., ‘user_id’, ‘username’). Must not be empty.

  • form (str) – The name of the AMS Profile Form to upsert data into. Must be a non-empty string and correspond to a valid profile 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), and cache (for API response caching). If None, uses default UpsertProfileOption. 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 profile records

in the AMS database and prints status messages if interactive_mode is enabled.

Return type:

None

Raises:

  • AMSError – If the form is empty, not a profile form, authentication fails, the DataFrame is invalid (e.g., empty, missing required fields), 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.

Examples

>>> import pandas as pd
>>> from teamworksams import upsert_profile_data, UpsertProfileOption
>>> df = pd.DataFrame({
...     "username": ["john.doe", "jane.smith"],
...     "height_cm": [180, 165],
...     "weight_kg": [75, 60]
... })
>>> upsert_profile_data(
...     df = df,
...     form = "Athlete Profile",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = UpsertProfileOption(id_col = "username", interactive_mode = True)
... )
ℹ Upserting 2 profile records for 'Athlete Profile'
Are you sure you want to upsert 2 profile records in 'Athlete Profile'? (y/n): y
✔ Processed 2 profile records for 'Athlete Profile'
ℹ Form: Athlete Profile
ℹ Result: Success
ℹ Records upserted: 2
ℹ Records attempted: 2

Additional Notes#

  • Each user can have only one profile record per AMS Profile Form; upserts overwrite existing profiles for the same user.

  • The df must include a user identifier column (e.g., ‘username’); other columns represent profile fields (e.g., ‘height_cm’).

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

See Also#