get_forms#

teamworksams.form_main.get_forms(url: str, username: str | None = None, password: str | None = None, option: FormOption | None = None, client: AMSClient | None = None) → pandas.DataFrame[source]#

Fetch a list of forms accessible to the user from an AMS instance.

Retrieves metadata for all forms accessible to the authenticated user, returning a pandas.DataFrame with columns like ‘form_id’, ‘form_name’, and ‘type’ (e.g., event, profile, database). Ideal for auditing or selecting forms for further operations. Supports interactive feedback and caching. See Managing Forms for form management workflows.

Parameters:

  • 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 (e.g., “Retrieved 5 forms”), cache to reuse API responses, raw_output, field_details, and include_instructions (used in other form functions). 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:

Form metadata with columns like ‘form_id’,

’form_name’, ‘type’, and other attributes (e.g., ‘application_id’). Returns an empty DataFrame if no forms are accessible.

Return type:

pandas.DataFrame

Raises:

AMSError – If authentication fails, the API request returns an invalid response, or no accessible forms are found.

Examples

>>> from teamworksams import get_forms, FormOption
>>> df = get_forms(
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = FormOption(interactive_mode = True)
... )
ℹ Requesting list of accessible forms...
✔ Retrieved 5 accessible forms.
>>> print(df)
   form_id    form_name     type
0     2937    Allergies  database
1     1234  Training Log    event
2     5678  Athlete Profile profile

Additional Notes#

  • The returned pandas.DataFrame includes columns like ‘form_id’, ‘form_name’, and ‘type’; use it to filter forms for specific operations (e.g., event forms for get_event_data()).

  • Enable option.interactive_mode=True to confirm the number of forms retrieved, helpful for auditing large AMS instances.

  • Use option.cache=True to optimize performance when repeatedly listing forms in a session.

See Also#