upload_and_attach_to_events#

teamworksams.file_main.upload_and_attach_to_events(mapping_df: pandas.DataFrame, file_dir: str, user_key: str, form: str, file_field_name: str, url: str, username: str | None = None, password: str | None = None, option: FileUploadOption | None = None, client: AMSClient | None = None, mapping_col: str = 'attachment_id') → pandas.DataFrame[source]#

Upload files and attach them to events in an AMS Event Form.

Matches the provided pandas.DataFrame to users and events using user_key and mapping_col (default ‘attachment_id’), uploads valid files from file_dir, and attaches them to the specified file_field_name in the AMS Event Form using file references (e.g., file_id|server_file_name). Preserves existing event fields during updates. Returns a pandas.DataFrame with upload and attachment results, including successes and failures. See Uploading Files for detailed workflows.

Parameters:

  • mapping_df (pandas.DataFrame) – DataFrame with columns: - user_key (str): User identifier (e.g., ‘username’, ‘email’, ‘about’, ‘uuid’). - file_name (str): File name in file_dir (e.g., ‘doc1.pdf’). - mapping_col (str): Matches the event form’s field (e.g., ‘attachment_id’). Used for mapping files to events. Must not be empty.

  • file_dir (str) – Directory path containing files to upload (e.g., ‘/path/to/files’). Must be a valid directory.

  • user_key (str) – Column name in mapping_df for user identification. Must be one of ‘username’, ‘email’, ‘about’, or ‘uuid’.

  • form (str) – Name of the AMS Event Form (e.g., ‘Document Store’). Must exist and contain file_field_name.

  • file_field_name (str) – File upload field in the form (e.g., ‘attachment’). Must be a valid file field.

  • mapping_col (str) – Column name in mapping_df and event form for matching events to files (e.g., ‘attachment_id’). Defaults to ‘attachment_id’.

  • 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 (FileUploadOption, optional) – Configuration options for interactive feedback (e.g., progress bars), caching, and saving results to a CSV. Defaults to None (uses default FileUploadOption with interactive_mode=True).

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

Returns:

Results with columns:

  • user_key (str): The user identifier from mapping_df.

  • file_name (str): The file name from mapping_df.

  • event_id (str): Matched event ID (None if failed).

  • user_id (str): Matched user ID (None if failed).

  • file_id (str): Uploaded file ID (None if failed).

  • server_file_name (str): Server-assigned file name (None if failed).

  • status (str): ‘SUCCESS’ or ‘FAILED’.

  • reason (str): Failure reason (None if successful).

Return type:

pandas.DataFrame

Raises:

AMSError – If: - file_dir is not a valid directory. - User data retrieval fails (e.g., invalid credentials, API errors). - No users are found in the AMS instance. - Event data retrieval fails (e.g., invalid form name, API errors). - No events are found for the specified form and users. - The event form lacks an ‘attachment_id’ field. - File validation fails (e.g., unsupported file type). - File upload or event update fails (e.g., network issues, server errors).

Example

>>> import pandas as pd
>>> from teamworksams import upload_and_attach_to_events, FileUploadOption
>>> mapping_df = DataFrame({
...     "username": ["user1", "user2"],
...     "file_name": ["doc1.pdf", "doc2.pdf"],
...     "attachment_id": ["ATT123", "ATT456"]
... })
>>> results = upload_and_attach_to_events(
...     mapping_df = mapping_df,
...     mapping_col = "attachment_id",
...     user_key = "about",
...     file_dir = "/path/to/files",
...     form = "Document Store",
...     file_field_name = "attachment",
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "password",
...     option = FileUploadOption(interactive_mode = True, save_to_file = "results.csv")
)
ℹ Fetching all user data from site to match provided files...
ℹ Retrieved 50 users.
ℹ Fetching all event data from 'Document Store' to match provided files...
ℹ Retrieved 500 events.
ℹ Merged 500 rows from mapping_df with 1500 events from 'Document Store', resulting in 1500 matched records.
ℹ Found 450 valid files in directory matching 500 mapping_df records.
ℹ Finding a match for 2 events from mapping_df...
ℹ Identified and mapped 2 events from mapping_df.
ℹ Uploading 450 files...
Uploading files: 100%|██████████| 450/450 [00:02<00:00,  1.00s/it]
ℹ Preparing to update 500 events corresponding to 450 uploaded files for 'Document Store'.
ℹ Updating 500 events for 'Document Store'
✔ Processed 500 events for 'Document Store'
ℹ Form: Document Store
ℹ Result: Success
ℹ Records updated: 500
ℹ Records attempted: 500
✔ Successfully attached 450 files to 500 events.
ℹ Saved results to 'results.csv'
>>> print(results.head())
   username file_name event_id user_id file_id server_file_name status reason
0   user1   doc1.pdf  123456  78901   94196 doc1_1747654002120.pdf SUCCESS None
1   user2   doc2.pdf  123457  78902   94197 doc2_1747654003484.pdf SUCCESS None

Additional Notes#

  • The mapping_df must include user_key, file_name, and mapping_col (e.g., ‘attachment_id’); missing columns or invalid files raise AMSError.

  • Valid file types include .pdf, .doc, .docx, .txt, .csv, .png, .jpg, .jpeg, .gif, .xls, .xlsx, and .heic; others are skipped with failure reasons.

  • Ensure the AMS form has a file field (file_field_name) and mapping_col (e.g., ‘attachment_id’) to match events correctly.

  • Use option.save_to_file to save results for troubleshooting, as the function performs multiple steps (user mapping, event matching, upload, update).

See Also#