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
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 parameter names are not available for use as URL parameters because they are used for other purposes by docassemble:
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.