When you log in to a docassemble server, the options available to you in the menu in the upper-right corner will depend on what privileges have been enabled for your account.
There are four special privileges built in to docassemble.
admin: for people who need complete control over the server.
developer: for people who need to use the server to develop, test, and debug interviews, but do not need to be able to access user data.
advocate: for people who need to be able to use the Monitor to provide remote assistance to users, or use interviews or APIs that provide access to user data.
trainer: for people who need to be able to train machine learning models.
By default, when a new user account is created, the user is given only
the privilege of
user. This is the “lowest” level of privilege; a
user without the
user privilege can do everything a user with
privileges can do.
A user with privileges of
admin can control the privileges of other
users using the User List screen.
Menu items for users with special privileges
The Monitor is a feature of docassemble’s Live Help system
that allows the user to chat with or share a screen with an active
user. Users with privileges of
advocate can access the
The “Train” menu item allows the user to train machine learning
models. This is part of docassemble’s machine learning system.
Users with privileges of
trainer can access it.
The “Package Management” screen allows the user to install, update, or uninstall Python packages that exist on the server. It has three parts:
- Upgrade docassemble
- Install or update a package
- Update or uninstall an existing package
Python packages play an important role in docassemble. The core
functionality of docassemble resides in two Python packages:
docassemble.base. (There is also a
“namespace” package called
docassemble, which is necessary but
contains no substantive code.) Python packages are the mechanism by
which docassemble interviews are published and shared. Also, if
any of your interviews needs to perform a non-standard function, you
can install a third-party Python package that provides that
functionality. For example, suppose you wanted your interview to
integrate with your organization’s Slack server. You could install
the Python package called
slackclient, and then use an
imports block to incorporate the functionality of
into your interview.
The “Package Management” screen is where users with
developer privileges can manage Python packages. The screen
effectively serves as a front end to Python’s pip utility.
Under the “Upgrade docassemble” part, you can see what version of docassemble you are running. If a new version of docassemble is available, it will also show you current version. You can press the “Upgrade” button to upgrade to the latest version of docassemble from PyPI.
This updates only docassemble’s Python packages. It does not upgrade any of the system files that docassemble uses. A few times a year, you may see a notification on the screen saying:
A new docassemble system version is available. If you are using Docker, install a new Docker image.
This means that non-Python files in the docassemble system have been upgraded. If you are using Docker with persistent storage, then you should then upgrade your container.
Install or update a package
Under the “Install or update a package” part, you can install a new Python package on the system.
There are three ways you can provide a package to docassemble:
- ZIP file
PyPI is the standard place on the internet where Python packages are published. However, some Python packages are hosted directly on GitHub, and some are distributed as ZIP files.
When you provide a URL to a GitHub repository, you can choose which branch of that repository you wish to install.
The Playground allows you to package one or more docassemble interviews as a Python package and publish it on GitHub, publish it on PyPI, or save it as a ZIP file. Thus, you can use the Playground on a development server to create and publish a package, and then use “Package Management” on a production server to install the package.
If you do not want your package to be available for anyone in the world to read, you can store it in a private repository on GitHub, and then use GitHub to obtain a special URL for the repository that embeds an “OAuth” authentication code. These URLs can be used in the “Github URL” field of “Package Management.”
Update or uninstall an existing package
In this part of the “Package Management” screen, you can see a list of all of the Python packages that are installed on your system already.
You can click “Uninstall” to remove a package, and you can click “Update” to update a package to the latest version. However, be careful; some of the listed packages are dependencies for other packages, and those other packages may depend on a specific older version of the package. Thus, you could break your system if you click “Update” on the wrong package.
However, if the only packages you “Update” or “Uninstall” are docassemble extension packages, or dependency packages that you installed originally, then there is little risk that you will cause a problem with your system.
The “Logs” screen provides a web interface to some of the log files on the underlying system. In a multi-server arrangement, log messages are consolidated from all servers, and “Logs” provides a way to see all of them together.
The log messages shown in the box on the screen are just the tail end of the actual log file. To see the complete log file, you will need to download it.
Note that the log files are managed by logrotate. Generally, the
current log file for the
docassemble.log file is simply
docassemble.log, and the next most recent is
docassemble.log.2, etc. As a result, the log messages you
want to view may not be in
docassemble.log, but could be in
docassemble.log.1. Also, given the way log rotation interacts with
open file handles, note that the very most recent log messages may be
docassemble.log.1 rather than
Here is a summary of what the different log files represent.
access.logcontains entries for every request made to the web server.
docassemble.logcontains log messages and most errors generated by the web application.
error.logcontains error messages generated by the web server. Most error messages in docassemble are trapped before they can be raised by the web server, so
docassemble.logshould generally be the first place you look for an error. If you get an “500 Internal Server Error” in the browser, however, the error message is likely in
worker.logcontains log messages and error messages generated by background tasks.
In unusual situations, you may need to review other log files. For more information about how to find other log files, see the troubleshooting section.
The Playground is an area where users who have privileges of
developer can develop and test interviews using the web browser.
Interviews can also be developed “off-line” by assembling a package
containing YAML files and other files in the appropriate locations.
Documentation for the Playground can be found in the Playground section.
The “Utilities” screen provides two miscellaneous services that do not
fit in anywhere else. They are available to users with
Get list of fields from PDF/DOCX template
If you are assembling a document using the
pdf attachment file
docx attachment file options, you can use this utility to
generate a first draft of a
question that fills in all of the
fields referenced in the PDF or Word file.
If you have a Word file that you are referencing with
attachment file, you probably do not need to use this utility,
because your template can be populated directly using variables in
your interview. Populating the template with a list of fields is
This utility is primarily useful when you are using the
field code, or
in which the keys are the names of fields in the underlying PDF file.
This utility provides a handy way of obtaining the list of fields.
If your PDF field names use non-ASCII characters such as characters with accent marks, the various software packages that docassemble uses to fill PDF forms may not be able to fill those fields properly. If you find that some fields are being filled and others are not, check to see if the fields that are not being filled have accented characters. In the PDF template, try replacing the accented characters with non-accented characters, and see if you get a better result.
Translate system phrases into another language
The second utility on the “Utilities” screen is helpful if your site does not use English, or you are developing multi-lingual interviews.
There are many words and phrases that appear to the user on various
screens and in various circumstances. By default, docassemble
only provides these words and phrases in English. However,
docassemble allows you to map each English word or phrase to a
word or phrase in another language. For more information about how
this feature works, see the
This utility will produce a draft YAML, XLSX, or XLIFF file that
you can then edit, store within a package, and reference from the
words directive of your Configuration.
To use this utility, provide a language in the form of a lowercase
ISO-639-1 code (e.g.,
fr for French) and press “Translate.” If
you choose “YAML” as the file format, you will be provided with a text
box containing a YAML data structure that you can copy and paste
into a text file. If you choose “XLSX,” “XLIFF 1.2,” or “XLIFF 2.0”,
you will be provided with a file download.
If you have configured a Google
api key inside your
If you have already configured a
words directive, this utility
will pass through all of the words defined in existing
files, and will only try to translate phrases that do not already
exist in existing
Download an interview phrase translation file
The third utility on the “Utilities” screen is helpful if you are
developing multi-lingual interviews. It allows you to download an
Excel spreadsheet for side-by-side translation of the phrases used in
a given interview. Once translated, the spreadsheet can be included
in a package and mentioned in a
translations block. Then
docassemble will use the translations in the file when it needs a
translation of a given phrase.
To download a translation file from the “Utilities” screen, you need
to provide the name of an interview (e.g.,
docassemble.demo:data/questions/questions.yml) and the target
language in ISO-639-1 or ISO-639-3 format (e.g.,
fr for French).
The resulting spreadsheet will contain a row for each unique phrase used in the interview file, including interview files incorporated by reference.
The columns of the spreadsheet are:
- interview: the name of the YAML file containing the question that contained the phrase.
- question_id: the
idof the question the phrase, or the generic name of the question (which could change if the interview changes).
- index_num: an number that indexes the phrase within a given question.
- hash: an MD5 hash of the phrase (which can be used to test whether the text in the “orig_text” column was edited, which it should not be)
- orig_lang: the original language of the phrase, as indicated by the
languagespecifier of the
question. If the
questiondoes not specify a
language, the default language of the YAML file as indicated by the
default languageblock will be used to determine the language of the
question. If no
default languageis specified, the
default languagespecifier in the interview
metadatawill be used. If no such specifier exists in the
metadata, the default language of the server (as indicated by the
langaugeConfiguration directive) will be used.
- tr_lang: the language into which the phrase should be translated.
- orig_text: the text of the phrase
- tr_text: the translated phrase (which is blank if the phrase has not yet been translated.
You can then give the spreadsheet to a translator who will fill in the “tr_text” column with a translation of the text in the “orig_text” column.
The spreadsheet with the completed translations can then be uploaded
to the sources folder of a package and included in the interview
translations block. If the target language of the
spreadsheet is French (
fr), then the French translations of phrases
will be used if the current language in the interview (as determined
set_language() function is French.
If the interview contains a
translations block, the file or files
referenced in the
translations block will be scanned and the
translations specified in those files will be included as default
If the files referenced in the
translations block contain phrases
that are not present in the interview, perhaps because they used to be
present but are no longer present, these extra phrases will be listed
at the end of the interview and their “index_num” values will be
numbered starting with 1000.
When using interview phrase translation files, it is important to set
default language specifier in the interview
Word add-in manifest XML file
The fourth utility is “Download Office add-in manifest file.” You will need this if you want to enable a Playground-like task pane inside Microsoft Word.
In Microsoft Office, third party add-ins are enabled through XML “manifest” files. Through this utility, you can download a manifest file that is customized for your server. You need to download this XML file and then install it in your Microsoft Office setup.
For more instructions on how to do this, see the Word add-in section.
The “User List” is available to users with
admin privileges. It
lists all of the user accounts on the system and allows you to edit a
When you click the “Edit” button for a user account, you can edit that user’s profile. Under the “Menu,” you can “Add a user,” “Invite a user,” or “Edit privileges.”
Edit a user profile
When you are editing a user profile, you can disable the user’s account by unchecking the “Active” checkbox.
You can edit a user’s privileges. Note that the selector is a
multi-select; you can assign more than one privilege to a user.
Privileges are additive; a user who has
privileges can do anything a developer can do and everything an
advocate can do.
The profile fields that you can edit include:
- E-mail: this must be unique; no two users can have the same e-mail address.
- First name
- Last name
- Country code: an uppercase ISO 3166 country code
- Language: a lowercase ISO-639-1 or ISO-639-3 language code representing the user’s language.
The words “State,” “County,” and “Municipality” are actually
translated phrases defined in
docassemble.base:data/sources/us-words.yml, which is included as a
words file in the default Configuration:
You can use the
set_user_info() function to
retrieve and set the user profile attributes, where the state, county,
and municipality are known by these attributes:
Under “Other settings,” you have the option to “Delete account but keep shared sessions.” This will delete the user’s account and all of their data. However, if any of the user’s sessions are multi-user interview that had been joined by another user, those sessions will not be deleted.
You also have the option under “Other settings” to “Delete account and shared sessions.” This will delete the user’s account and all of their data, including any multi-user interview the user had joined.
These account deletion options can be turned off using the
delete account directive in the Configuration.
Add a user
On the “Add a user” page, you can create a new user account by entering an e-mail address and password. Optionally, you can set the user’s first and last names. You can also select the user’s privileges with a multiselect selector.
Note that when a user is added using this tool, the user is not notified that an account has been created.
Invite a user
On the “Invite a user” page, you can send an e-mail invitation to a prospective new user. The privileges of the prospective user can be set in advance. The e-mail will contain a link with an embedded code. Visiting the link will start the process of registration; until that process is completed, no user account will actually exist.
The “Edit privileges” page allows you to manage the privileges that
exist on the system. The built-in privileges (
trainer) cannot be removed.
There is one built-in privilege,
customer, which has no special
docassemble itself, so you are able to delete it.
You can create custom privileges using “Edit privileges,” assign them
to users, and then use the
user_privileges() in your interviews to do different things
depending on what privileges the user has.
User privilege assignment can be controlled by:
- Manually editing a user’s profile from the User List page.
- Calling the
set_user_info()function with the
privilegeskeyword parameter (calling this function requires
- Calling the
For example, you may wish to use the privileges system to keep track of which user accounts are paying customers, or to keep track of different tiers of paying customers.
The “Configuration” page allows a user with
admin privileges to edit
the server Configuration. It provides a YAML text editor in the
browser. When the Configuration is saved, the services on the
server that depend on the Configuration are restarted.
The configuration file for a given server is found at
/usr/share/docassemble/config/config.yml. If you are using
cloud-based data storage, the
config.yml file is also stored in
the cloud whenever the Configuration is saved. If you are using
persistent volumes, the configuration is copied to the persistent
volume when the server shuts down. Then, when the server starts, the
config.yml file is restored from storage.
Menu items for all logged-in users
The following menu items are available to all logged-in users regardless of privileges.
The “Available Interviews” page, which is at the URL
/list, shows a
list of interviews that users can run. The list can be configured
dispatch directive in the Configuration. If there is
dispatch directive, this page will redirect to the system’s
default interview, which can be configured using the
interview directive in the Configuration.
By default, the “Available Interviews” menu item is not shown. It can
be enabled by setting
show dispatch link to
True in the
If an interview is listed under
dispatch, but the
the interview contains the specifier
unlisted set to
the interview will not be listed in the
/list, although it will
still be usable with a
The URL parameter
tag can be used to filter the list of available
interviews. For example, if you set
tag=estates, then the only
interviews that will be listed are those that have
estates as one of
tags in the interview
You can use the
required privileges specifier in the
of each interview listed under
dispatch to control whether the
interview should appear in the list, depending on the privileges of
For information about how to customize the “Available Interviews”
page, see the Configuration directives that begin with
page, or configure the
start page template, or replace the page
with an interview using
The “My Interviews” page, which is at the URL
/interviews, shows a
list of the user’s existing interview sessions.
For more information about how sessions work in docassemble, see the subsections on how you run a docassemble interview and leaving an interview and coming back.
The “My Interviews” menu item can be hidden from the menu using the
show interviews link directive in the Configuration.
For information about how to customize the “My Interviews” page, see
the Configuration directives that begin with
interview page, or
interview page template, or replace the page with an
session list interview.
The “Profile” page allows the user to edit their user account profile. The following fields can be changed:
- First name
- Last name
If the user registered using the phone login method, the user can also edit his or her e-mail address. However, users who registered with other methods cannot edit their e-mail address.
In addition, users with privileges of
developer can edit
the following fields:
- Country code: an uppercase ISO 3166 country code
- Language: a lowercase ISO-639-1 or ISO-639-3 language code representing the user’s language.
- PyPI Username
- PyPI Password
From the “Other settings” menu, the user can:
- Change their password
- Configure Google Drive synchronization
- Configure OneDrive synchronization
- Configure multi-factor authentication
- Configure GitHub integration
- Manage API keys
- Manage their account
Whether these commands are available depends on the Configuration.
The “Manage account” setting allows the user to delete their account.
To disable this, edit the
user can delete account directive in the
The “Sign Out” menu item logs the user out and expires the user’s session cookies. If the user was in the process of using an interview, the interview session will not be deleted.
Endpoints for monitoring
If you call
/health_check, it will return the text
OK if the web
app is operating. If you call
/health_check?ready=1, it will return
OK only if the web app is operating and the Docker
initialization process has completed, meaning that associated services
have been started. If the initialized process has not completed, a
400 response will be returned.
If you call
/health_status, it will return a JSON object with the
ok- indicates that the Docker initialization process has completed.
server_start_time- indicates the timestamp (in epoch seconds) at which the web app last started. This changes after each server restart.
version- indicates the version of docassemble running on the system.
For tips on troubleshooting your docassemble system, see the troubleshooting subsection in the Docker section.