Below are some notes I am writing as I learning how to use docassemble.

Setting Variables

Collecting Information

  • single variable on one screen
  • several single variables
  • groups: lists, dictionaries, sets
  • file uploads
  • signatures
  • external data
  • legal modules
  • text message

Manipulating Information

  • code blocks
  • functions

The Interview

  • question blocks
  • initial blocks: features, screen parts
  • interview logic
  • roles
  • background tasks
  • live help

Create Templates

  • plain text templates (using Markdown)
  • docx templates
  • pdf templates

Development Workflows

  • Playground
  • other development workflows
  • debugging

attachment block

The attachment block specifies attachments that users can download or email.



Blocks in YAML Interview

  • question blocks
  • initial blocks: features, screen parts
  • code blocks
  • attachment block

catchall questions

Catchall questions allow you to leave variables undefined. Write use catchall: True in the features block:

 	 use catchall: True



“When writing an interview file, use comments liberally,” recommends Quinten Steenhuis. “They can make your logic easier to read, either for another developer, or more often, you in a few months or a year.”

In docassemble, three ways to make comments in the YAML file that is hidden from the user: (1) Python comment, (2) YAML comment, and (3) docassemble’s comment specifier.


code: |
  # I'm a comment in Python. 


question: |
  # Not me. docassemble treats me as a Markdown heading 
# I'm a comment in YAML. Notice that I'm flush against the left margin. 


You can use docassemble’s special comment specifier:

question: |
comment: |
  I'm a comment using docassemble's special comment specifier.
  • comment: is a “question modifier.”
  • Note: Comments using docassemble’s comment specifier are merely hidden; they are not removed. A user can see the comments by viewing the source of the webpage.


See How to Use Datatypes in Docassemble, YouTube.


There are three types of groups: lists, dictionaries, and sets.

A dictionary assoicates a key with a value. The items in s dictionary are unordered.


feet = {'dog': 4, 'human': 2, 'bird': 2}

feet['dog'] will return 4

>>> feet.keys()
['dog', 'human', 'bird']
>>> feet.values()
[4, 2, 2]
>>> for key, val in feet.items():
...   print("{animal} has {feet} feet".format(animal=key, feet=val))
dog has 4 feet
human has 2 feet
bird has 2 feet



Google Sheets

You can connect docassemble to Google Sheets.


There are three types of group data structures: lists, dictionaries, and sets.



Importance of using HTTPS

It is important for security purposes to deploy docassemble using HTTPS rather than HTTP. If you use HTTP, passwords and security keys will be sent over the network in plain text.

index variables

Index variables are used with lists and dictionaries.

Don’t use index variables with blocks marked mandatory.



Developers create interviews that collect information from users.

An interview developer creates the interview by going to docassemble’s Playground and writing interviews using YAML, which is plain text markup language that humans and machines can read.

Interviews are made up of blocks. Each block is separated by ---, which is a YAML record separator.

Developers can also write comments in interviews that are hidden from users.



There are three types of groups: lists, dictionaries, and sets. A list has a defined order. Elements in a list have an index. The first element is zero.

Lists in docassemble are special objects of type DAList. They mirror Python’s list data type.

(1) Define a list

This is how to define a list in Python:

fruit = ['apple', 'orange', 'pear']

**(2) Return element from list

To return an element from the list, use the list’s name followed by the index number in brackets.

So, fruit[0] returns 'apple':

>>> fruit = ['apple', 'orange', 'pear']
>>> fruit[0]

fruit[1] returns 'orange':

>>> fruit = ['apple', 'orange', 'pear']
>>> fruit[1]

(3) Adding element to list

Add an element to a list by “appending” to the list.

In Python, use the append() function:

>>> fruit = ['apple', 'orange', 'pear']
>>> fruit.append('grape')
>>> fruit
['apple', 'orange', 'pear', 'grape']

In docassemble, use the docassemble-specific appendObject() method.

(4) Sorting a list

To sort a list, use the sorted() function in Python:

>>> fruit = ['apple', 'orange', 'pear', 'grape']
>>> sorted(fruit) 
['apple', 'grape', 'orange', 'pear']

(5) Additional Resources



Use objects to simplify the organization of information.

Steenhuis explains:

an Object is an instance of a Class, with the attributes filled-in to have specific values. . . .

. . .

When you want to refer to an object in your Docassemble code, the Object itself gets its own variable name. Then the attributes of the object are retrieved using dot notation.



person > individual / organization

Define a variable as an individual:

  - person_one: Individual 
  - person_two: Individual 

You can set the name of person_one and person_two using code:

code: | = "John" = "Smith" = "Randy" = "Jones"

You can ask questions about person_one and person_two using generic object:

generic object: Individual
question: |
  Does ${ x } like cats?
yesno: x.likes_cats


The Playground is where developers create interviews.


question blocks

Question Blocks are the screens that users see. The answers users fill in set variables.


  • Question blocks, docassemble.

question modifiers

Question Modifiers make the screen that the user sees do different things.

reusable questions

See Reusable questions: generic object, docassemble.


There are three types of groups: lists, dictionaries, and sets.


variable names

  • Are Python identifiers.
  • Are case sensitive.
  • Cannot start with a number. They cannot have punctuation, but you can use an underscore (_). So, you cannot use a hyphen (-). Instead of naming the variable grantor-age, name the variable grantor_age or GrantorAge. (Writing grantor-age is arithmetic: grantor minus age.)
  • index variables
  • Cannot use Special Variables.


Word templates

For variables in a docx document, docassemble relies on python-docx-template, which uses a Jina2-like syntax. This means creating variables is the docx documents is simple. You simply write the variable in the document. You do not need to download or use macros (as you would if you were using HotDocs).

To create a field that asks for a variable, write then name of the variable, surrounded it a space on each side and curly brackets:

Do not use a hyphen (-) in the name because docassemble interprets that as two variables. So, don’t write . Instead, write or ``.

YAML in docassemble

Developers write interviews using YAML.

--- separates records in YAML.


[Updated 10/25/2020]