Variables set by docassemble
There are some special variables that docassemble sets in every interview’s variable store.
_internal is a Python dictionary that is used by docassemble
but that is not intended to be used in interviews.
nav is an object that is used to keep track of sections in your
interview. This is relevant if you are using the navigation bar
feature. For information about how to use it, see the documentation
session_local is a type of
DAObject that can be used to store
information that is specific to the current browser session. The
“current browser session” is distinct from the “session.”
In docassemble, a “session” is a particular instance of a person
going through an interview. The interview is identified by an
interview filename, like
docassemble.example_inc:data/questions/survey.yml, and the set of
interview answers for the session in that interview is identified by a
session id like
The “browser session” is a different concept; it refers to a “session within a session.” If the user starts up their web browser, and enters a docassemble session, that is one “browser session.” If the user closes their web browser, then re-enters the same docassemble session, that is another “browser session.” Or, if the user uses a different device, or a different web browser application, and enters the docassemble session with it, that constitutes a separate “browser session.”
The special variable
session_local is a type of
DAObject, and you
can treat it as a
DAObject, but its attributes will always be
dependent on the “browser session.” If the user switches to a
different browser session, the attributes of
session_local that were
defined during the first browser session will not be present during
the second browser session.
session_local variable works using a browser cookie that is
deleted (“expires”) when the user closes the web browser application
or logs out of docassemble.
device_local variable is similar to
session_local, except that
it is tied not to a browser session, but to a device (a web browser).
If the user closes the browser application and then opens the same
browser application and enters the session again, the
object will be the same as before. However, if the user connects with
a different browser application, or switches from using a laptop to
using a smartphone, the
device_local object will be different.
Also, if the user opens an incognito tab, this will also appear as
device_local variable works using a browser cookie that is not
deleted when the when the user closes the web browser application
or logs out of docassemble.
user_local variable is similar to
device_local, except that the variable is tied to a specific user.
It works when the user is not logged in, but when the user is
not logged in, it functions much like
session_local because the
identity of an anonymous user only lasts as long as a session.
user_local object can be useful in situations where you have a
multi-user interview with logged-in users. For example:
Any time you want to refer to the user, you can refer to
user_local.person. This may be an alias for
adverse_party, or it may have the intrisic name of
url_args is a Python dictionary that is used to access parameters
passed via URL.
Users start an interview by going to a URL. A basic URL would look like this:
Here, the only parameter is
i, the interview file name.
It is possible to use the URL to pass special parameters to the interview code. For example, if the user started the interview by clicking on the following link:
then the interview would load as usual, and the interview code could
access the value of the
from parameter by looking in the
variable in the variable store. For example, the interview could
contain the following code:
You can test this out by trying the following links:
As soon as the interview loads, the parameters will no longer appear
in the browser’s location bar. Nevertheless, the parameters remain
available in the
url_args dictionary for the life of the interview.
Moreover, you can set new
url_args at any time during the course of
the interview. For example:
You can test this out by trying the following link: https://demo.docassemble.org/interview?i=docassemble.demo:data/questions/testurlarg2.yml&from=wild blue yonder.
The following URL parameters
have special meaning in docassemble. All others are available for
you to use and to retrieve with
i: indicates the interview file to use
session: indicates the key of the stored dictionary to use
action: used by the
filename: used for retrieving documents
question: used for retrieving documents
format: used for retrieving documents
cache: used to clear the interview evaluation cache
reset: used to restart an interview session
new_session: used to start a new interview session
index: used for retrieving documents
from_list: indicates that interview was launched from the Interview List page
idmatching the given value.
utm_content: if you have enabled an
analytics idin your
If you use the multi-user interview feature and the user reaches a
point in the interview where input is needed from a different user
before proceeding, docassemble will look for a
offers to sets
role_event, and ask that question. docassemble
will set the variable
role_needed to a list of roles capable of
answering the next question in the interview.
Variables used when finding blocks to set variables
The following variables are set by docassemble in the course of searching for blocks that will define variables.
You should never set these variables yourself; they will be set for you before your blocks are used.
Variables that interviews can set
If this special variable is set to
True, docassemble will
present the user with an HTML5 audio control at the top of the page.
When the user clicks it, docassemble will access the VoiceRSS
web service to convert the text of the question to an audio file and
then play that audio back for the user. This requires enabling the
voicerss setting in the configuration.
Since the VoiceRSS service costs money above the free usage tier, docassemble does not send the request to VoiceRSS until the user presses “Play” on the audio control. It also caches the results and reuses them whenever possible.
If set to
True, the web app will attempt to obtain the user’s
position, based on GPS or any other geolocation feature enabled in the
user_lat_lon() functions can be used to retrieve the information.
The most common way to use this feature is as follows:
This will cause
track_location to be true initially, but once an
attempt has been made to gather the location, it will be set to false.
The user’s location can subsequently be obtained by accessing the
If you want to use the multi-user interview feature, you need to set
True. This is usually done in a “mandatory” or
“initial” code block.
multi_user is set to
True, docassemble will not encrypt
the interview answers (the interview session dictionary). This is
necessary so that different people can access the same interview
session. When the interview answers are encrypted (which is the
default), only the user who started the interview session can access
the interview session dictionary.
multi_user variable can be changed dynamically over the course
of an interview. For example, at a certain point in the interview,
you could ask the user:
multi_user is set to
True, then the next time the interview
answers are saved, encryption will not be used. Later in the
interview, you can turn encryption back on again by setting
Interviews can add entries to the menu within the web app.
menu_items is set to a Python list, docassemble will add
entries to the menu based on the items in the list.
Each item in the list is expected to be a Python dictionary with
url. Typically, these entries are generated using
action_menu_item() function, which creates a menu item that
runs an “action.” (See the
sections of the functions page for more information about what
“actions” are in docassemble, and for documentation for the
Alternatively, you can set items manually:
Since menu items are controlled with
code blocks, you can turn them
on and off during the course of the interview as necessary.
This variable should be set to
True if you want to allow the server
to run scheduled tasks from your interview.
Variables that stand in for events
docassemble interviews ask questions or run code when required by interview logic and also when caused to do so by events and actions. These events and actions are identified using variables, which may not ever be defined by an interview.
There are some built-in variable names with special meaning:
incoming_emailis used to indicate a
codeblock that should be run when an e-mail is received.
role_eventis used to present a special screen when the roles system requires a change in the interview role.
cron_hourlyis used by the scheduled tasks system. This event is triggered in the background, every hour, by the server. (This requires that
allow_cronbe set to
cron_dailyis similar, except runs on a daily basis.
cron_weeklyis similar, except runs on a weekly basis.
cron_monthlyis similar, except runs on a monthly basis.
The following variables are set internally by docassemble. If you try to use these reserved names for your own purposes, you will experience errors or unexpected results.
_internal: used internally by docassemble for various purposes, including keeping track of the progress bar, storing the answers to multiple-choice questions, and tracking which questions have already been answered.
cron_daily: a special variable that is used as part of the scheduled tasks system.
cron_hourly: a special variable that is used as part of the scheduled tasks system.
cron_monthly: a special variable that is used as part of the scheduled tasks system.
cron_weekly: a special variable that is used as part of the scheduled tasks system.
caller: within Mako the variable
callerhas a special meaning.
loop: within a Mako “for” loop, this variable has special meaning.
n: used as iterators when dictionaries or lists are used.
incoming_email: a special variable that is used as part of the background processes system.
menu_items: used to add items to the menu.
multi_user: a special variable that is used as part of the roles system.
nav: used to keep track of sections in the interview.
role: used to store the role of the current user for purposes of the roles system.
role_event: a special variable that is used as part of the roles system.
role_needed: a special variable that is used as part of the roles system.
row_index: used with tables.
row_item: used with tables.
self: has a special meaning in Python.
speak_text: used to indicate whether the web app should offer audio versions of each question, generated by text-to-speech synthesis.
STOP_RENDERING: used in Mako templates to end a template early.
track_location: used to indicate whether the web app should attempt to determine the user’s latitude and longitude.
url_args: a dictionary available to interview code that contains values encoded in the URL with which the interview was initially loaded.
user_dict: if you use this as a name in an interview, your interview will not behave properly.
allow_cron: a special variable that is used as part of the scheduled tasks system.
x: used as a reference to the underlying object when generic objects are defined.
The following names are imported automatically:
In addition, Python uses the following names as part of the language. If you use any of these as your own variable names, you may encounter an error or an unexpected problem.
In addition, you should never use a variable name that begins with an
_internal is the only variable in the variable
store that begins with an underscore, the docassemble web app uses
names that begin with underscores to communicate information between
the browser and the server, and if your variable names conflict with
these names, you may experience errors or unexpected results. These
internal names include: