get_form_schema#

teamworksams.form_main.get_form_schema(form: str, url: str, username: str | None = None, password: str | None = None, option: FormOption | None = None, client: AMSClient | None = None) → str | Dict[source]#

Fetch and summarize the schema of a specific form from an AMS instance.

Retrieves the schema for a specified AMS form, detailing sections, required fields, default-to-last-value fields, linked fields, and item types. Returns a formatted string summary for console output (ideal for Jupyter notebooks) or the raw API response as a dictionary if option.raw_output is True. Supports interactive feedback and detailed output options. See Managing Forms for form management workflows.

Parameters:

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

  • 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.

  • option (FormOption, optional) – Configuration options, including interactive_mode for status messages, cache to reuse API responses, raw_output for raw API data, field_details for field options/scores, and include_instructions for section/field instructions. Defaults to None (uses default FormOption).

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

Returns:

If option.raw_output is True, returns the raw API response as a

dictionary containing the form schema. Otherwise, returns a formatted text string summarizing the form schema, including: - Form details (name, ID, type). - Sections (count, names). - Required fields (count, names). - Fields that default to the last known value (count, names). - Linked fields (count, names). - Form item types (count of unique types, count per type, field names per type). - Optionally, field instructions and details (options, scores, date selection) if enabled in option.

Return type:

Union[str, Dict]

Raises:

AMSError – If the form_name is empty, the form is not found, authentication fails, or the API request returns an invalid response.

Examples

>>> from teamworksams import get_form_schema, FormOption
>>> summary = get_form_schema(
...     form = "Allergies",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = FormOption(interactive_mode = True, field_details = True)
... )
... ℹ Fetching summary for form 'Training Log' (ID: 5285, Type: event)...
... ✔ Retrieved summary for form 'Training Log'.
...
... Form Schema Summary: RPE Training Log
... =====================================
...
... Form Details
... ------------
... - Form Name: RPE Training Log
... - Form ID: 5285
...
... Sections
... --------
... - Total: 5
... • Session Details
... • Summary Calculations
... • User Account Details
... • Day of the Week
... • Profile Details
...
... Required Fields
... ---------------
... - Total: 0
... - No required fields found.
...
... Defaults to Last Known Value
... ----------------------------
... - Total: 0
... - No fields default to the last known value.
...
... Linked Fields
... -------------
... - Total: 7
...    • Sport
...    • Position
...    • Height
...    • Dominant Hand
...    • Dominant Foot
...    • Preferred Language
...    • Season
...
... Form Item Types
... ---------------
... - Total Unique Types: 14
... - Dropdown: 1 field(s)
...     • Session Type
... - Number: 1 field(s)
...     • Duration
... - Single Selection: 1 field(s)
...     • Rate your Perceived Exertion (RPE)
... - Calculation: 5 field(s)
...     • RPE
...     • Session Load
...     • Index
...     • ACWR
...     • Total ACWR

Additional Notes#

  • The formatted string output is ideal for console display in Jupyter notebooks; use option.raw_output=True for programmatic access to the raw schema dictionary.

  • Ensure form matches an existing AMS form exactly (case-sensitive); invalid names raise AMSError.

  • Use option.field_details=True to include field options (e.g., dropdown values), crucial for understanding form requirements before data operations.

See Also#