Skip to main content

AssemblyLine.sessions

is_file_like​

def is_file_like(obj: Any) -> bool

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​

def set_interview_metadata(filename: str,
session_id: int,
data: Dict,
metadata_key_name="metadata") -> None

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 int - 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​

def get_interview_metadata(
filename: str,
session_id: int,
metadata_key_name: str = "metadata") -> Dict[str, Any]

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 int - 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​

def get_saved_interview_list(
filename: Optional[str] = al_session_store_default_filename,
user_id: Union[int, str, None] = None,
metadata_key_name: str = "metadata",
limit: int = 50,
offset: int = 0,
filename_to_exclude: str = "",
exclude_current_filename: bool = True,
exclude_filenames: Optional[List[str]] = None,
exclude_newly_started_sessions: bool = False) -> List[Dict[str, Any]]

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

Returns:

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

delete_interview_sessions​

def delete_interview_sessions(
user_id: Optional[int] = None,
filename_to_exclude: str = al_session_store_default_filename,
exclude_current_filename: bool = True) -> None

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​

def interview_list_html(filename: str = al_session_store_default_filename,
user_id: Union[int, str, None] = None,
metadata_key_name: str = "metadata",
exclude_newly_started_sessions=False,
date_label: str = word("Date"),
details_label: str = word("Details"),
actions_label: str = word("Actions"),
delete_label: str = word("Delete"),
view_label: str = word("View"),
load_action: str = "al_sessions_fast_forward_session",
delete_action: str = "al_sessions_delete_session",
view_only: bool = False,
limit: int = 50,
offset: int = 0,
display_interview_title: bool = True,
show_view_button: bool = True) -> str

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.

Returns:

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

nice_interview_title​

def nice_interview_title(answer: Dict[str, str]) -> str

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​

def pascal_to_zwspace(text: str) -> str

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​

def nice_interview_subtitle(answer: Dict[str, str],
exclude_identical=True) -> str

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​

def radial_progress(answer: Dict[str, Union[str, int]]) -> str

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​

def local_date(utcstring: Optional[str]) -> DADateTime

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​

def session_list_html(
filename: Optional[str] = None,
user_id: Union[int, str, None] = None,
metadata_key_name: str = "metadata",
filename_to_exclude: str = al_session_store_default_filename,
exclude_current_filename: bool = True,
exclude_filenames: Optional[List[str]] = None,
exclude_newly_started_sessions: bool = False,
name_label: str = word("Title"),
date_label: str = word("Date modified"),
details_label: str = word("Progress"),
actions_label: str = word("Actions"),
delete_label: str = word("Delete"),
rename_label: str = word("Rename"),
rename_action: str = "interview_list_rename_action",
delete_action: str = "interview_list_delete_session",
copy_action: str = "interview_list_copy_action",
clone_label: str = word("Copy as answer set"),
show_title: bool = True,
show_copy_button: bool = True,
limit: int = 50,
offset: int = 0) -> str

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

Returns:

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

rename_interview_answers​

def rename_interview_answers(filename: str,
session_id: int,
new_name: str,
metadata_key_name: str = "metadata") -> None

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 int - 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​

def set_current_session_metadata(data: Dict[str, Any],
metadata_key_name: str = "metadata") -> None

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​

def rename_current_session(new_name: str,
metadata_key_name: str = "metadata") -> None

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​

def save_interview_answers(filename: str = al_session_store_default_filename,
variables_to_filter: Union[Set[str], List[str],
None] = None,
metadata: Optional[Dict] = None,
metadata_key_name: str = "metadata",
original_interview_filename=None,
source_filename=None,
source_session=None,
additional_variables_to_filter=None) -> str

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​

def get_filtered_session_variables(
filename: Optional[str] = None,
session_id: Optional[int] = None,
variables_to_filter: Optional[Union[Set[str], List[str]]] = None,
additional_variables_to_filter: Optional[Union[Set[str], List[str]]] = None
) -> Dict[str, Any]

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​

def get_filtered_session_variables_string(
filename: Optional[str] = None,
session_id: Optional[int] = None,
variables_to_filter: Union[Set[str], List[str], None] = None,
additional_variables_to_filter: Optional[Union[Set[str], List[str]]] = None
) -> str

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.

Returns:

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

load_interview_answers​

def load_interview_answers(
old_interview_filename: str,
old_session_id: int,
new_session: bool = False,
new_interview_filename: Optional[str] = None,
variables_to_filter: Optional[List[str]] = None,
additional_variables_to_filter: Optional[List[str]] = None
) -> Optional[Union[int, bool]]

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 int - 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​

def load_interview_json(
json_string: str,
new_session: bool = False,
new_interview_filename: Optional[str] = None,
variables_to_filter: Optional[List[str]] = None) -> Optional[int]

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​

def export_interview_variables(
filename: Optional[str] = None,
session_id: Optional[int] = None,
variables_to_filter: Union[Set, List[str], None] = None,
output: DAFile = None,
additional_variables_to_filter: Union[Set, List[str],
None] = None) -> DAFile

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​

def is_valid_json(json_string: str) -> bool

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​

def config_with_language_fallback(
config_key: str,
top_level_config_key: Optional[str] = None) -> Optional[str]

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.