create_user#

teamworksams.user_main.create_user(user_df: pandas.DataFrame, url: str, username: str | None = None, password: str | None = None, option: UserOption | None = None, client: AMSClient | None = None) → pandas.DataFrame[source]#

Create new users in an AMS instance.

Creates new user accounts using the AMS API’s /api/v2/person/save endpoint. The function processes a DataFrame with required fields (e.g., ‘first_name’, ‘last_name’, ‘username’, ‘email’, ‘dob’, ‘password’, ‘active’) and optional fields (e.g., ‘uuid’, ‘sex’), validates the data, and applies the creations. Returns a DataFrame of failed creations with reasons. Supports interactive feedback and caching. See User and Group Management for user account workflows.

Parameters:

  • user_df (pandas.DataFrame) – DataFrame with user data. Required columns are ‘first_name’, ‘last_name’, ‘username’, ‘email’, ‘dob’, ‘password’, ‘active’. Optional columns include ‘uuid’, ‘known_as’, ‘middle_names’, ‘language’, ‘sidebar_width’, ‘sex’. Must not be empty.

  • 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 environment variable or keyring credentials. Defaults to None.

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

  • option (UserOption, optional) – Configuration options, including interactive_mode to print status messages and cache to reuse a client. Defaults to None (uses default UserOption).

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

Returns:

DataFrame of failed creations with columns ‘user_key’ (username that failed) and ‘reason’ (failure reason). Empty if all creations succeed.

Return type:

pandas.DataFrame

Raises:

  • AMSError – If user_df is invalid, authentication fails, or the API request fails.

  • ValueError – If user_df is empty or contains invalid data.

Examples

>>> import pandas as pd
>>> from teamworksams import create_user, UserOption
>>> user_df = pd.DataFrame({
...     "first_name": ["John", "Jane"],
...     "last_name": ["Doe", "Smith"],
...     "username": ["john.doe", "jane.smith"],
...     "email": ["john.doe@example.com", "jane.smith@example.com"],
...     "dob": ["1980-01-01", "12/02/1985"],
...     "password": ["secure123", "secure456"],
...     "sex": ["Male", "Female"],
...     "uuid": ["025380", "024854"],
...     "active": [True, False]
... })
>>> failed_df = create_user(
...     user_df = user_df,
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = UserOption(interactive_mode = True)
... )
ℹ Creating 2 users...
✔ Successfully created 2 users.

Additional Notes#

  • The user_df must include required columns (‘first_name’, ‘last_name’, ‘username’, ‘email’, ‘dob’, ‘password’, ‘active’) to avoid ValueError. Optional columns like ‘uuid’ or ‘sex’ enhance user profiles.

  • Check the returned DataFrame for failed creations, which lists reasons like “Invalid data” or “API request failed.”

  • Use option.interactive_mode=True to track progress with tqdm progress bars for multiple users.

See Also#