Skip to main content

AssemblyLine.sessions

is_file_like​

Return True if the object is a file-like object.

Arguments:

  • obj Any - The object to test

Returns:

  • bool - True if the object is a file-like object.

set_interview_metadata​

Add searchable interview metadata for the specified filename and session ID. Intended to be used to add an interview title, etc. Standardized metadata dictionary:

  • title
  • subtitle
  • original_interview_filename
  • variable_count

Arguments:

  • filename str - The filename of the interview to add metadata for
  • session_id str - The session ID of the interview to add metadata for
  • data Dict - The metadata to add
  • metadata_key_name str, optional - The name of the metadata key. Defaults to "metadata".

get_interview_metadata​

Retrieve the unencrypted metadata associated with an interview. We implement this with the docassemble jsonstorage table and a dedicated tag which defaults to metadata.

Arguments:

  • filename str - The filename of the interview to retrieve metadata for
  • session_id str - The session ID of the interview to retrieve metadata for
  • metadata_key_name str, optional - The name of the metadata key. Defaults to "metadata".

Returns:

Dict[str, Any]: The metadata associated with the interview

get_saved_interview_list​

Get a list of saved sessions for the specified filename. If the save_interview_answers function was used to add metadata, the result list will include columns containing the metadata. If the user is a developer or administrator, setting user_id = None will list all interviews on the server. Otherwise, the user is limited to their own sessions.

Setting exclude_newly_started_sessions to True will exclude any results from the list that are still on "step 1". Note that while this may be useful to filter out interviews that were accidentally started and likely do not need to be resumed, it will also have the side effect of excluding all answer sets from the results. Answer sets generally have exactly one "step", which is the step where information was copied from an existing interview to the answer set.

Arguments:

  • filename str, optional - The filename of the interview to retrieve sessions for. Defaults to al_session_store_default_filename.
  • user_id Union[int, str, None], optional - The user ID to retrieve sessions for. Defaults to None.
  • metadata_key_name str, optional - The name of the metadata key. Defaults to "metadata".
  • limit int, optional - The maximum number of results to return. Defaults to 50.
  • offset int, optional - The offset to start returning results from. Defaults to 0.
  • filename_to_exclude str, optional - The filename to exclude from the results. Defaults to "".
  • exclude_current_filename bool, optional - Whether to exclude the current filename from the results. Defaults to True.
  • exclude_filenames Optional[List[str]], optional - List of filenames to exclude. Defaults to None. If the filename does not contain a : it will be treated as a prefix, allowing you to filter out whole packages (e.g., any path starting with docassemble.ALDashboard or docassemble.playground)
  • exclude_newly_started_sessions bool, optional - Whether to exclude sessions that are still on "step 1". Defaults to False.

Returns:

List[Dict[str, Any]]: A list of saved sessions for the specified filename.

find_matching_sessions​

Get a list of sessions where the metadata for the session matches the provided keyword search terms and metadata filters. This function is designed to be used in a search interface where the user can search for sessions by keyword and specific metadata values. The keyword search is case-insensitive and will match any part of the metadata column values.

Arguments:

  • keyword str - The keyword to search for in the metadata
  • metadata_column_names List[str], optional - The names of the metadata columns to search. If not provided, defaults to ["title", "auto_title", "description"].
  • filenames List[str], optional - The filename or filenames of the interviews to retrieve sessions for.
  • user_id Union[int, str, None], optional - The user ID to retrieve sessions for. Defaults to current user. Specify "all" if you want and have the necessary privileges to search all sessions.
  • metadata_key_name str, optional - The name of the metadata key. Defaults to "metadata".
  • limit int, optional - The maximum number of results to return. Defaults to 50.
  • offset int, optional - The offset to start returning results from. Defaults to 0.
  • filename_to_exclude str, optional - The filename to exclude from the results. Defaults to "".
  • exclude_current_filename bool, optional - Whether to exclude the current filename from the results. Defaults to True.
  • exclude_filenames Optional[List[str]], optional - A list of filenames to exclude from the results. Defaults to None.
  • exclude_newly_started_sessions bool, optional - Whether to exclude sessions that are still on "step 1". Defaults to False.
  • global_search_allowed_roles Union[Set[str],List[str]], optional - A list or set of roles that are allowed to search all sessions. Defaults to {'admin','developer', 'advocate'}. 'admin' and 'developer' are always allowed to search all sessions.
  • metadata_filters Optional[Dict[str, Tuple[Any, str, Optional[str]]]], optional - A dictionary of metadata column names and their corresponding filter tuples. Each tuple should contain (value, operator, cast_type).
    • value: The value to compare against
    • operator: One of '=', '!=', '<', '<=', '>', '>=', 'LIKE', 'ILIKE'
    • cast_type: Optional. One of 'int', 'float', or None for string (default)

Returns:

List[Dict[str, Any]]: A list of saved sessions for the specified filename that match the search keyword and metadata filters

Example:

matching_sessions = find_matching_sessions( "smith", user_id="all", filenames=[f"{user_info().package}:intake.yml", "docassemble.MyPackage:intake.yml"], metadata_filters={

  • "owner" - ("samantha", "ILIKE", None),
  • "age" - (30, ">=", "int"),
  • "status" - ("%complete%", "LIKE", None) } )

Example:

  • \{"owner" - ("samantha", "ILIKE", None), "age": (30, ">=", "int"), "status": ("%complete%", "LIKE", None)}

delete_interview_sessions​

Delete all sessions for the specified user, excluding the current filename and by default, the intentionally saved "answer sets". Created because interview_list(action="delete_all") is both quite slow and because it deletes answer sets.

Arguments:

  • user_id Optional[int], optional - The user ID to delete sessions for. Defaults to None.
  • filename_to_exclude str, optional - The filename to exclude from the results. Defaults to al_session_store_default_filename.
  • exclude_current_filename bool, optional - Whether to exclude the current filename from the results. Defaults to True.

interview_list_html​

Return a string containing an HTML-formatted table with the list of saved answers associated with the specified filename.

Designed to return a list of "answer sets" and by default clicking a title will trigger an action to load the answers into the current session. This only works as designed when inside an AssemblyLine line interview.

exclude_newly_started_sessions should almost always be set to False, because most answer sets are on "page 1" (exactly 1 step was taken to copy the answers and the user isn't able to interact with the answer set itself in a way that adds additional steps)

Arguments:

  • filename str, optional - Name of the file. Defaults to al_session_store_default_filename.
  • user_id Union[int, str, None], optional - User's ID. Defaults to None.
  • metadata_key_name str, optional - Name of the metadata key. Defaults to "metadata".
  • exclude_newly_started_sessions bool, optional - If True, newly started sessions are excluded. Defaults to False.
  • date_label str, optional - Label for the date column. Defaults to translated word "Date".
  • details_label str, optional - Label for the details column. Defaults to translated word "Details".
  • actions_label str, optional - Label for the actions column. Defaults to translated word "Actions".
  • delete_label str, optional - Label for the delete action. Defaults to translated word "Delete".
  • view_label str, optional - Label for the view action. Defaults to translated word "View".
  • load_action str, optional - Name of the load action. Defaults to "al_sessions_fast_forward_session".
  • delete_action str, optional - Name of the delete action. Defaults to "al_sessions_delete_session".
  • view_only bool, optional - If True, only view is allowed. Defaults to False.
  • limit int, optional - Limit for the number of sessions returned. Defaults to 50.
  • offset int, optional - Offset for the session list. Defaults to 0.
  • display_interview_title bool, optional - If True, displays the title of the interview. Defaults to True.
  • show_view_button bool, optional - If True, shows the view button. Defaults to True.
  • answers Optional[List[Dict[str, Any]]], optional - A list of answers to format and display. Defaults to showing all sessions for the current user.

Returns:

  • str - HTML-formatted table containing the list of saved answers.

nice_interview_title​

Return a human readable version of the interview name. Will try several strategies in descending priority order.

  1. Try looking up the interview title from the dispatch directive
  2. Try removing the package and path from the filename and replace _ with spaces.
  3. Finally, return "Untitled interview" or translated phrase from system-wide words.yml

Arguments:

  • answer Dict[str, str] - The answer dictionary to get the interview title from

Returns:

  • str - The human readable interview title

pascal_to_zwspace​

Insert a zero-width space into words that are PascalCased to help with word breaks on small viewports.

Arguments:

  • text str - The text to insert zero-width spaces into

Returns:

  • str - The text with zero-width spaces inserted

nice_interview_subtitle​

Return first defined of the "title" metadata, the "auto_title" metadata, or empty string.

If exclude_identical, return empty string when title is the same as the subtitle.

Arguments:

  • answer Dict[str, str] - The answer dictionary to get the interview subtitle from
  • exclude_identical bool, optional - If True, excludes the subtitle if it is identical to the title. Defaults to True.

Returns:

  • str - The human readable interview subtitle

radial_progress​

Return HTML for a radial progress bar, or the number of steps if progress isn't available in the metadata.

Arguments:

  • answer Dict[str, Union[str, int]] - The answer dictionary to get the interview progress from

Returns:

  • str - the HTML as a string

local_date​

Return a localized date from a UTC string.

Arguments:

  • utcstring Optional[str] - The UTC string to convert to a localized date

Returns:

  • DADateTime - The localized date

session_list_html​

Return a string containing an HTML-formatted table with the list of user sessions. While interview_list_html() is for answer sets, this feature is for standard user sessions. The results exclude the answer set filename by default.

Arguments:

  • filename Optional[str], optional - Name of the file. Defaults to None.

  • user_id Union[int, str, None], optional - User's ID. Defaults to None.

  • metadata_key_name str, optional - Name of the metadata key. Defaults to "metadata".

  • filename_to_exclude str, optional - Name of the file to exclude. Defaults to al_session_store_default_filename.

  • exclude_current_filename bool, optional - If True, excludes the current filename. Defaults to True.

  • exclude_filenames Optional[List[str]], optional - List of filenames to exclude. Defaults to None. If the filename does not contain a : it will be treated as a prefix, allowing you to filter out whole packages (e.g., any path starting with docassemble.ALDashboard or docassemble.playground)

  • exclude_newly_started_sessions bool, optional - If True, excludes newly started sessions. Defaults to False.

  • name_label str, optional - Label for the session name/title. Defaults to translated word "Title".

  • date_label str, optional - Label for the date column. Defaults to translated word "Date modified".

  • details_label str, optional - Label describing the progress of the session. Defaults to translated word "Progress".

  • actions_label str, optional - Label for actions applicable to the session. Defaults to translated word "Actions".

  • delete_label str, optional - Label for the delete action. Defaults to translated word "Delete".

  • rename_label str, optional - Label for the rename action. Defaults to translated word "Rename".

  • rename_action str, optional - Name of the rename action. Defaults to "interview_list_rename_action".

  • delete_action str, optional - Name of the delete action. Defaults to "interview_list_delete_session".

  • copy_action str, optional - Name of the copy action. Defaults to "interview_list_copy_action".

  • clone_label str, optional - Label for the action to copy as an answer set. Defaults to translated word "Copy as answer set".

  • show_title bool, optional - If True, shows the title of the session. Defaults to True.

  • show_copy_button bool, optional - If True, show a copy button for answer sets. Defaults to True.

  • limit int, optional - Limit for the number of sessions returned. Defaults to 50.

  • offset int, optional - Offset for the session list. Defaults to 0.

  • answers Optional[List[Dict[str, Any]], optional - A list of answers to format and display. Defaults to showing all sessions for the current user.

Returns:

  • str - HTML-formatted table containing the list of user sessions.

rename_interview_answers​

Update the 'title' metadata of an interview, as stored in the dedicated metadata column, without touching other metadata that may be present.

Arguments:

  • filename str - The filename of the interview to rename

  • session_id str - The session ID of the interview to rename

  • new_name str - The new name to set for the interview

  • metadata_key_name str, optional - The name of the metadata key. Defaults to "metadata".

    If exception is raised in set_session_variables, this will silently fail but log the error.

set_current_session_metadata​

Set metadata for the current session, such as the title, in an unencrypted database entry.

Arguments:

  • data Dict[str, Any] - The metadata to set
  • metadata_key_name str, optional - The name of the metadata key. Defaults to "metadata".

rename_current_session​

Update the "title" metadata entry for the current session without changing any other metadata that might be present.

Arguments:

  • new_name str - The new name to set for the interview
  • metadata_key_name str, optional - The name of the metadata key. Defaults to "metadata".

save_interview_answers​

Copies the answers from a given session into a new session with a specified interview filename.

Arguments:

  • filename str, optional - The desired filename for the new session. Defaults to al_session_store_default_filename.
  • variables_to_filter Union[Set[str], List[str], None], optional - The "base" list or set of variables to filter out. Defaults to al_sessions_variables_to_remove. There's usually no reason to change this and changing it might break sessions.
  • metadata Optional[Dict], optional - Dictionary containing metadata. Defaults to an empty dictionary.
  • metadata_key_name str, optional - Key name for metadata storage. Defaults to "metadata".
  • original_interview_filename str, optional - Original filename of the interview. Defaults to None.
  • source_filename str, optional - Source filename to get session variables from. Defaults to None.
  • source_session str, optional - Session ID of the source file. Defaults to None.
  • additional_variables_to_filter Union[Set[str], List[str], None], optional - List or set of variables to filter out. Defaults to None.

Returns:

  • str - ID of the new session.

get_filtered_session_variables​

Retrieves a filtered subset of variables from a specified interview and session. If no filename and session ID are given, it will return a filtered list of variables from the current interview.

Arguments:

  • filename Optional[str], optional - Filename of the session. Defaults to None.
  • session_id Optional[int], optional - Session ID to retrieve variables from. Defaults to None.
  • variables_to_filter Union[Set[str], List[str], None], optional - List or set of variables to exclude. Defaults to al_sessions_variables_to_remove.
  • additional_variables_to_filter Union[Set[str], List[str], None], optional - List or set of additional variables to exclude. Defaults to None.

Returns:

Dict[str, Any]: A dictionary of filtered session variables.

get_filtered_session_variables_string​

Returns a JSON string that represents the filtered contents of a specified filename and session ID. If no filename and session ID are provided, the current session's variables will be used.

Arguments:

  • filename Optional[str], optional - Filename of the session. Defaults to None.
  • session_id Optional[int], optional - Session ID to retrieve variables from. Defaults to None.
  • variables_to_filter Union[Set[str], List[str], None], optional - List or set of variables to exclude. Defaults to al_sessions_variables_to_remove.
  • additional_variables_to_filter Union[Set[str], List[str], None], optional - List or set of additional variables to exclude. Defaults to None.
  • indent int, optional - Number of spaces to indent the JSON string. Defaults to 4.

Returns:

  • str - A JSON-formatted string of filtered session variables.

load_interview_answers​

Loads answers from a specified session. If the parameter new_session is set to True, it will create a new session with the provided or current interview filename. Otherwise, it will load the answers into the active session. This function is primarily used for migrating answers between sessions.

Arguments:

  • old_interview_filename str - Filename of the old interview.
  • old_session_id str - Session ID of the old interview.
  • new_session bool, optional - Determines whether to create a new session. Defaults to False.
  • new_interview_filename Optional[str], optional - Filename for the new session. Defaults to None.
  • variables_to_filter Optional[List[str]], optional - List of variables to exclude. Defaults to None.
  • additional_variables_to_filter Optional[List[str]], optional - List of additional variables to exclude. Defaults to None.

Returns:

Optional[Union[int, bool]]: ID of the newly created session if new_session is True, otherwise True or False based on success.

load_interview_json​

Given a JSON string, this function loads the specified variables into a Docassemble session. JSON strings containing annotated class names will be transformed into Docassemble objects. If the new_session argument is not set, the JSON answers will be loaded into the current interview.

Arguments:

  • json_string str - A JSON-formatted string containing session variables.
  • new_session bool, optional - Specifies whether to create a new session or load into the current one. Defaults to False.
  • new_interview_filename Optional[str], optional - Filename for the new session. Defaults to None.
  • variables_to_filter Optional[List[str]], optional - List of variables to exclude. Defaults to None.

Returns:

Optional[Union[int, bool]]: ID of the newly created session if new_session is True, otherwise True or False based on success.

export_interview_variables​

Generates a DAFile containing a JSON representation of a specified session's interview answers. The resultant output is compatible with set_session_variables(process_objects=True) and set_variables(process_objects=True) methods.

Arguments:

  • filename Optional[str], optional - Filename of the session. Defaults to None.
  • session_id Optional[int], optional - Session ID to retrieve variables from. Defaults to None.
  • variables_to_filter Union[Set, List[str], None], optional - List or set of variables to exclude. Defaults to None.
  • output DAFile, optional - DAFile to write the JSON output to. If None, a new DAFile is created.
  • additional_variables_to_filter Union[Set, List[str], None], optional - List or set of additional variables to exclude. Defaults to None.

Returns:

  • DAFile - DAFile with a JSON representation of the answers

is_valid_json​

Checks if the provided string is a valid JSON-formatted string.

Arguments:

  • json_string str - The string to be checked for JSON validity.

Returns:

  • bool - True if the string is a valid JSON, otherwise it raises a validation error and returns False.

config_with_language_fallback​

Returns the value of a config key under assembly line interview list with options to fallback to an alternative key at the top level of the global configuration.

Used in interview_list.yml to allow overriding some of the labels in the interview list with options specified in the global configuration. top_level_config should be reserved to handle backwards compatibility (e.g., changed location of some configuration keys)

Example configuration, showing both the single-string and language-specific string options: assembly line: interview list: title: en: In progress forms es: Formularios en progreso short title: My forms

Arguments:

  • config_key str - The config key to look up. The config can be a single string or a dictionary with language keys.
  • top_level_config_key str, optional - Optional, alternative top-level config key to look up. Defaults to None.

Returns:

  • str - The value of the config key, or the alternative key, or None.

get_filenames_having_sessions​

Get a list of all filenames that have sessions saved for a given user, in order to help show the user a good list of interviews to filter search results.

Arguments:

  • user_id Optional[Union[int, str]], optional - User ID to get the list of filenames for. Defaults to current logged-in user. Use "all" to get all filenames.
  • global_search_allowed_roles Optional[Union[Set[str], List[str]]], optional - Roles that are allowed to search for all sessions. Defaults to admin, developer, and advocate.

Returns:

  • List[str] - List of filenames that have sessions saved for the user.

get_combined_filename_list​

Get a list of all filenames that have sessions saved for a given user. If it is possible to show a descriptive name for the filename (from the main dispatch area of the configuration), it will show that instead of the filename.

The results will be in the form of [{filename: Descriptive name}], which is what the Docassemble radio button and dropdown list expect.

Arguments:

  • user_id Optional[Union[int, str]], optional - User ID to get the list of filenames for. Defaults to current logged in user. Use "all" to get all filenames.
  • global_search_allowed_roles Optional[Union[Set[str], List[str]]], optional - Roles that are allowed to search for all sessions. Defaults to admin, developer, and advocate.

Returns:

List[Dict[str, str]]: List of filenames that have sessions saved for the user.