Skip to main content

AssemblyLine.sessions

List​

Dict​

Any​

Set​

Union​

Optional​

Tuple​

all_variables​

as_datetime​

create_session​

current_context​

DADateTime​

DAFile​

DAFileCollection​

DAFileList​

DALazyTemplate​

DAList​

DAObject​

DASet​

format_time​

get_config​

get_language​

get_default_timezone​

get_session_variables​

interview_menu​

interview_url​

log​

set_parts​

set_session_variables​

set_variables​

url_action​

url_ask​

user_has_privilege​

user_info​

user_logged_in​

validation_error​

word​

text​

safe_json​

serializable_dict​

ALDocument​

ALDocumentBundle​

ALExhibit​

ALExhibitList​

ALStaticDocument​

json​

os​

re​

hashlib​

struct​

__all__​

al_sessions_variables_to_remove: Set​

al_sessions_variables_to_remove_from_new_interview​

system_interviews: List[Dict[str, Any]]​

_package_name​

def _package_name(package_name: Optional[str] = None)

Get package name without the name of the current module, like: docassemble.ALWeaver instead of docassemble.ALWeaver.advertise_capabilities

Arguments​

  • package_name str, optional - The package name to process. If None, will use the existing package name __name__ instead.

Returns​

  • str - The package name without the current module name.

al_session_store_default_filename​

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.

Example​

In an interview code block:

code: |
  is_upload = is_file_like(supporting_document.file)

set_interview_metadata​

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

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

This replaces all metadata already stored under metadata_key_name, including keys such as steps and original_interview_filename that you do not include in data. To change only some keys, use update_session_metadata(). 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".

Example​

With saved_filename and saved_session_id identifying the saved session selected by the user, keep the existing metadata and change the title:

code: |
  saved_metadata = get_interview_metadata(saved_filename, saved_session_id)
  saved_metadata["title"] = "Housing forms"
  set_interview_metadata(saved_filename, saved_session_id, saved_metadata)

get_interview_metadata​

def get_interview_metadata(
        filename: str,
        session_id: str,
        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 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.

Example​

With saved_filename and saved_session_id identifying the saved session selected by the user, in an interview code block:

code: |
  saved_metadata = get_interview_metadata(saved_filename, saved_session_id)

_split_excluded_filenames​

def _split_excluded_filenames(
        exclude_filenames: Optional[List[str]]) -> Tuple[List[str], List[str]]

Separate exact interview filenames from package-prefix exclusions.

_sql_like_prefix​

def _sql_like_prefix(value: str) -> str

Turn a literal string prefix into a parameter for a SQL LIKE clause.

is_session_owned_by_user​

def is_session_owned_by_user(filename: str, session_id: str,
                             user_id: int) -> bool

Return whether a filename/session pair belongs to the specified user.

Arguments​

  • filename str - The filename of the interview.
  • session_id str - The session ID to check.
  • user_id int - The user ID to check ownership for.

Returns​

  • bool - True if the session belongs to the user, False otherwise.

Example​

With saved_filename and saved_session_id identifying the saved session selected by the user, in an interview code block:

code: |
  owns_session = is_session_owned_by_user(saved_filename, saved_session_id, user_info().id)

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

Example​

In an interview code block:

code: |
  answer_sets = get_saved_interview_list(user_id=user_info().id)

find_matching_sessions​

def find_matching_sessions(
    keyword: str,
    metadata_column_names: Optional[Union[Set[str], List[str]]] = None,
    filenames: Optional[Union[Set[str], List[str]]] = None,
    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,
    global_search_allowed_roles: Optional[Union[Set[str], List[str]]] = None,
    metadata_filters: Optional[Dict[str, Tuple[Any, str,
                                               Optional[str]]]] = None
) -> List[Dict[str, Any]]

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. Entries without a : are treated as package prefixes.
  • 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"{current_context().package}:intake.yml", "docassemble.MyPackage:intake.yml"],
        metadata_filters={
            "owner": ("samantha", "ILIKE", None),
            "age": (30, ">=", "int"),
            "status": ("%complete%", "LIKE", None)
        }
    )

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

Example​

In an interview code block:

code: |
  matching_sessions = find_matching_sessions("housing", user_id=user_info().id)

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.

Example​

After asking the user to confirm deletion with a yes/no field named confirmed_delete_sessions, in the deletion action’s code block:

code: |
  if confirmed_delete_sessions:
      delete_interview_sessions(user_id=user_info().id)

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,
                        answers: Optional[List[Dict[str, Any]]] = None) -> 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.
  • 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.

Example​

On a signed-in user’s interview screen:

In question text (Mako):

${ interview_list_html(user_id=user_info().id) }

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.

Example​

Import nice_interview_title explicitly from docassemble.AssemblyLine.sessions before using this example. Given a nonempty saved_sessions list returned by get_saved_interview_list():

In question or Markdown attachment text (Mako):

${ nice_interview_title(saved_sessions[0]) }

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.

Example​

Import pascal_to_zwspace explicitly from docassemble.AssemblyLine.sessions before using this example. In question or Markdown attachment text (Mako):

${ pascal_to_zwspace("HousingCourtForms") }

nice_interview_subtitle​

def nice_interview_subtitle(answer: Dict[str, str],
                            exclude_identical: bool = True,
                            add_zero_width_spaces: bool = 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.
  • add_zero_width_spaces bool, optional - If True, adds word-break opportunities for display. Set to False when using the subtitle as an editable value. Defaults to True.

Returns​

  • str - The human readable interview subtitle.

Example​

Given a nonempty saved_sessions list returned by get_saved_interview_list():

In question or Markdown attachment text (Mako):

${ nice_interview_subtitle(saved_sessions[0]) }

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.

Example​

Import radial_progress explicitly from docassemble.AssemblyLine.sessions before using this example. Given a nonempty saved_sessions list returned by get_saved_interview_list():

In question text (Mako):

${ radial_progress(saved_sessions[0]) }

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.

Example​

Import local_date explicitly from docassemble.AssemblyLine.sessions before using this example. In question or Markdown attachment text (Mako):

${ local_date("2026-01-15 14:30:00") }

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,
        answers: Optional[List[Dict[str, Any]]] = None) -> 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. 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.

Example​

On a signed-in user’s interview screen:

In question text (Mako):

${ session_list_html(user_id=user_info().id) }

rename_interview_answers​

def rename_interview_answers(filename: str,
                             session_id: str,
                             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 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.

Example​

With saved_filename and saved_session_id identifying the saved session selected by the user, in an interview code block:

code: |
  rename_interview_answers(saved_filename, saved_session_id, "My housing forms")

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.

This replaces all metadata already stored for the current session under metadata_key_name. To change only some keys, use update_current_session_metadata().

Arguments​

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

Example​

In an interview code block:

code: |
  set_current_session_metadata({"title": "My housing forms"})

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

Example​

In an interview code block:

code: |
  rename_current_session("My housing forms")

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.

Example​

In an interview code block:

code: |
  saved_session_id = save_interview_answers(metadata={"title": "My household"})

get_filtered_session_variables​

def get_filtered_session_variables(
    filename: Optional[str] = None,
    session_id: Optional[str] = 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.

Example​

In an interview code block:

code: |
  saved_answers = get_filtered_session_variables(additional_variables_to_filter=["temporary_access_code"])

get_filtered_session_variables_string​

def get_filtered_session_variables_string(
        filename: Optional[str] = None,
        session_id: Optional[str] = None,
        variables_to_filter: Union[Set[str], List[str], None] = None,
        additional_variables_to_filter: Optional[Union[Set[str],
                                                       List[str]]] = None,
        indent: int = 4) -> 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.
  • indent int, optional - Number of spaces to indent the JSON string. Defaults to 4.

Returns​

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

Example​

In an interview code block:

code: |
  answers_json = get_filtered_session_variables_string()

load_interview_answers​

def load_interview_answers(
    old_interview_filename: str,
    old_session_id: str,
    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 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.

Example​

With saved_filename and saved_session_id identifying the saved session selected by the user, in an interview code block:

code: |
  load_interview_answers(saved_filename, saved_session_id)

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.

Example​

After the user chooses to import answers_json, in the import action’s code block (this replaces matching answers in the current session):

code: |
  load_interview_json(answers_json)

export_interview_variables​

def export_interview_variables(
    filename: Optional[str] = None,
    session_id: Optional[str] = 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.

Example​

In an interview code block:

code: |
  answers_file = export_interview_variables()

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 valid JSON. Otherwise it calls validation_error(), which raises an exception, so it never returns False.

Example​

Use it as a field validator, so invalid JSON shows an error message on the field:

question: |
  Paste your saved answers
fields:
  - Answers: answers_json
    datatype: area
    validate: is_valid_json

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.

Example​

In question or Markdown attachment text (Mako):

${ config_with_language_fallback("page title") }

get_filenames_having_sessions​

def get_filenames_having_sessions(
    user_id: Optional[Union[int, str]] = None,
    global_search_allowed_roles: Optional[Union[Set[str], List[str]]] = None
) -> List[str]

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.

Example​

In an interview code block, to list filenames with saved sessions for the current logged-in user:

code: |
  saved_filenames = get_filenames_having_sessions(user_id=user_info().id)

get_combined_filename_list​

def get_combined_filename_list(
        user_id: Optional[Union[int, str]] = None,
        global_search_allowed_roles: Optional[Union[Set[str],
                                                    List[str]]] = None,
        exclude_filenames: Optional[List[str]] = None) -> List[Dict[str, str]]

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.
  • exclude_filenames Optional[List[str]], optional - Filenames or package prefixes to exclude. Defaults to None.

Returns​

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

Example​

In an interview code block:

code: |
  interview_choices = get_combined_filename_list(user_id=user_info().id)

update_session_metadata​

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

Upsert session metadata into jsonstorage using a PostgreSQL advisory lock (two-int form) to serialize concurrent upserts on the same (session_id,filename,tags) key.

Arguments​

  • filename - The filename of the interview session to update.
  • session_id - The ID of the session to update.
  • data - A dict of metadata to add or update.
  • metadata_key_name - The tag for the metadata in jsonstorage. Defaults to "metadata".

Example​

With saved_filename and saved_session_id identifying the saved session selected by the user, in an interview code block:

code: |
  update_session_metadata(saved_filename, saved_session_id, {"subtitle": "Ready to review"})

update_current_session_metadata​

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

Updates metadata for the current session without retrieving the data first.

This is a wrapper for update_session_metadata() that uses the current interview's filename and session ID from current_context().

Arguments​

  • data Dict[str, Any] - A dictionary of metadata to add or update.
  • metadata_key_name str, optional - The tag for the metadata in the. jsonstorage table. Defaults to "metadata".

Example​

In an interview code block:

code: |
  update_current_session_metadata({"subtitle": "Ready to review"})