Have you registered for Docacon 2019 yet?
Edit this page on GitHub

Special variables

Variables set by docassemble

There are some special variables that docassemble sets in every interview’s variable store.

_internal

_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 for the nav functions.

url_args

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:

http://example.com/interview?i=docassemble.example_inc:data/questions/survey.yml

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:

http://example.com/interview?i=docassemble.example_inc:data/questions/survey.yml&from=web

then the interview would load as usual, and the interview code could access the value of the from parameter by looking in the url_args variable in the variable store. For example, the interview could contain the following code:

---
code: |
  if 'from' in url_args:
    origin_of_interviewee = url_args['from']
  else:
    origin_of_interviewee = 'unknown'
---
mandatory: True
question: You came from the ${ origin_of_interviewee }.
---

Alternatively, you could use Python’s get method to do the same thing in less space:

---
mandatory: True
question: You came from the ${ url_args.get('from', 'unknown') }.
---

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:

---
mandatory: True
question: You came from the ${ url_args.get('from', 'unknown') }.
subquestion: |
  % if url_args.get('fruit', 'apple') == 'apple':
  I think your favorite fruit is an apple, but [click here](?fruit=orange)
  if you disagree.
  % else:
  I see that your favorite fruit is not an apple.
  % endif
---

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:

  • action
  • cache
  • filename
  • format
  • from_list
  • i
  • index
  • new_session
  • question
  • reset
  • session

role_needed

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

  • x
  • i
  • j
  • k
  • l
  • m
  • n

You should never set these variables yourself; they will be set for you before your blocks are used.

Variables that interviews can set

role

If you use the multi-user interview feature, your interview will need to have a default role initial block containing code that sets the variable role to the user’s role.

speak_text

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.

track_location

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 browser. The location_known(), location_returned(), and user_lat_lon() functions can be used to retrieve the information.

The most common way to use this feature is as follows:

---
include:
  - basic-questions.yml
---
initial: True
code: |
  track_location = user.location.status()
---

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 user.location object.

multi_user

If you want to use the multi-user interview feature, you need to set multi_user to True. This is usually done in a “mandatory” or “initial” code block.

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

Setting multi_user to True will reduce security somewhat, but it is necessary for allowing the multi-user interview feature and for allowing third parties to access the interview answers via the API.

The 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:

question: |
  Would you like an attorney to review your answers?
yesno: multi_user

After 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 multi_user to False.

Interviews can add entries to the menu within the web app.

When 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 keys label and url. Typically, these entries are generated using the action_menu_item() function, which creates a menu item that runs an “action.” (See the url_action() and process_action() sections of the functions page for more information about what “actions” are in docassemble, and for documentation for the action_menu_item() function.)

---
mandatory: True
code: |
  menu_items = [ action_menu_item('Review Answers', 'review_answers') ]
---

Alternatively, you can set items manually:

---
mandatory: True
code: |
  menu_items = [ {'url': 'http://google.com', 'label': 'Go to Google!'} ]
---

Since menu items are controlled with code blocks, you can turn them on and off during the course of the interview as necessary.

allow_cron

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:

Reserved names

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 caller has a special meaning.
  • loop: within a Mako “for” loop, this variable has special meaning.
  • i, j, k, l, m, 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, unless you

If you include a modules block including docassemble.base.legal, the above names will be used, as well as the following additional names:

If you include the basic-questions.yml file from docassemble.base, the names included by docassemble.base.legal will be included, and the following names will also be used:

  • advocate
  • blank_signature
  • case
  • client
  • court
  • empty_signature
  • jurisdiction
  • pleading
  • role
  • role_event
  • role_needed
  • spouse
  • user
  • user_understands_how_to_use_signature_feature
  • user_understands_no_attorney_client_relationship

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.

  • ArithmeticError
  • AssertionError
  • AttributeError
  • BaseException
  • BufferError
  • BytesWarning
  • DeprecationWarning
  • EOFError
  • Ellipsis
  • EnvironmentError
  • Exception
  • False
  • FloatingPointError
  • FutureWarning
  • GeneratorExit
  • IOError
  • ImportError
  • ImportWarning
  • IndentationError
  • IndexError
  • KeyError
  • KeyboardInterrupt
  • LookupError
  • MemoryError
  • NameError
  • None
  • NotImplementedError
  • NotImplemented
  • OSError
  • OverflowError
  • PendingDeprecationWarning
  • ReferenceError
  • RuntimeError
  • RuntimeWarning
  • StandardError
  • StopIteration
  • SyntaxError
  • SyntaxWarning
  • SystemError
  • SystemExit
  • TabError
  • True
  • TypeError
  • UnboundLocalError
  • UnicodeDecodeError
  • UnicodeEncodeError
  • UnicodeError
  • UnicodeTranslateError
  • UnicodeWarning
  • UserWarning
  • ValueError
  • Warning
  • WindowsError
  • ZeroDivisionError
  • __debug__
  • __doc__
  • __import__
  • __name__
  • __package__
  • _
  • abs
  • all
  • and
  • any
  • apply
  • as
  • assert
  • basestring
  • bin
  • bool
  • break
  • buffer
  • bytearray
  • bytes
  • callable
  • chr
  • class
  • classmethod
  • cmp
  • coerce
  • compile
  • complex
  • continue
  • copyright
  • credits
  • def
  • del
  • delattr
  • dict
  • dir
  • divmod
  • elif
  • else
  • enumerate
  • eval
  • except
  • exec
  • execfile
  • exit
  • file
  • filter
  • finally
  • float
  • for
  • format
  • from
  • frozenset
  • getattr
  • global
  • globals
  • hasattr
  • hash
  • help
  • hex
  • id
  • if
  • import
  • in
  • input
  • int
  • intern
  • is
  • isinstance
  • issubclass
  • iter
  • lambda
  • len
  • license
  • list
  • locals
  • long
  • map
  • max
  • memoryview
  • min
  • next
  • not
  • object
  • oct
  • open
  • or
  • ord
  • pass
  • pow
  • print
  • print
  • property
  • quit
  • raise
  • range
  • raw_input
  • reduce
  • reload
  • repr
  • return
  • reversed
  • round
  • set
  • setattr
  • slice
  • sorted
  • staticmethod
  • str
  • sum
  • super
  • try
  • tuple
  • type
  • unichr
  • unicode
  • vars
  • while
  • with
  • xrange
  • yield
  • zip

In addition, you should never use a variable name that begins with an underscore. Although _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:

  • _attachment_email_address
  • _attachment_include_editable
  • _back_one
  • _checkboxes
  • _datatypes
  • _email_attachments
  • _files
  • _question_number
  • _question_name
  • _save_as
  • _success
  • _the_image
  • _track_location
  • _tracker
  • _varnames

The following URL parameters have special meaning in docassemble. All others are available for you to use and to retrieve with url_args.

  • i: indicates the interview file to use
  • session: indicates the key of the stored dictionary to use
  • action: used by the url_action() function
  • filename: used for retrieving documents
  • question: used for retrieving documents
  • format: used for retrieving documents
  • index: used for retrieving documents
  • from_list: indicates that interview was launched from the Interview List page
  • js_target: indicates that JavaScript should be returned that places the interview into the element on the screen with an id matching the given value.