Edit this page on GitHub

Overview of docassemble administration

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 user 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

Monitor

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 admin or advocate can access the Monitor.

Train

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 admin or trainer can access it.

Package Management

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.webapp and 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 slackclient into your interview.

The “Package Management” screen is where users with admin or developer privileges can manage Python packages. The screen effectively serves as a front end to Python’s pip utility.

Upgrade docassemble

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:

  • GitHub
  • ZIP file
  • PyPI

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

There is a checkbox labeled “Use pip cache.” It is checked by default. You might it helpful to uncheck this checkbox if you are installing and re-installing the same package from PyPI repeatedly over a short period of time. If the checkbox is unchecked, then pip runs with the --no-cache-dir option, which means that pip will always go onto the internet to retrieve a new version of a package instead of looking in its cache.

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.

Logs

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.1, and then 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 in docassemble.log.1 rather than docassemble.log.

Here is a summary of what the different log files represent.

  • access.log contains entries for every request made to the web server.
  • docassemble.log contains log messages and most errors generated by the web application.
  • error.log contains 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.log should 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 error.log.
  • worker.log contains 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.

Playground

The Playground is an area where users who have privileges of admin or 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.

Utilities

The “Utilities” screen provides two miscellaneous services that do not fit in anywhere else. They are available to users with admin or developer privileges.

Get list of fields from PDF/DOCX template

If you are assembling a document using the pdf attachment file or the 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 docx 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 optional.

This utility is primarily useful when you are using the pdf attachment file option. This option requires you to provide a dictionary of fields (or field code, or field variables) 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.

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 provide a YAML dictionary that maps each English word or phrase to a word or phrase in another language. For more information about how this feature works, see the words directive.

This utility will produce a draft YAML 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.” 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 have configured a Google api key inside your google directive in the Configuration, and you have enabled the Google Cloud Translation API inside your Google Developers Console, then docassemble will run each word or phrase through the Google Cloud Translation API.

If you have already configured a words directive, this utility will pass through all of the words defined in existing words files, and will only try to translate phrases that do not already exist in existing words files.

User List

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 user’s information.

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 developer and advocate 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
  • State
  • County
  • Municipality
  • Organization
  • Language: a lowercase ISO-639-1 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:

en:
  First subdivision: State
  Second subdivision: County
  Third subdivision: Municipality

You can use the user_info() and set_user_info() function to retrieve and set the user profile attributes, where the state, county, and municipality are known by these attributes:

  • subdivision_first
  • subdivision_second
  • subdivision_third

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.

Edit privileges

The “Edit privileges” page allows you to manage the privileges that exist on the system. The built-in privileges (user, admin, developer, advocate, cron, and trainer) cannot be removed. There is one built-in privilege, customer, which has no special meaning within 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_has_privilege() and user_privileges() in your interviews to do different things depending on what privileges the user has.

User privilege assignment can be controlled by:

  1. Manually editing a user’s profile from the User List page.
  2. Calling the set_user_info() function with the privileges keyword parameter (calling this function requires admin privileges); or
  3. Calling the /api/user/<user_id>/privileges API.

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.

Configuration

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.

Available Interviews

The “Available Interviews” page, which is at the URL /list, shows a list of interviews that users can run. The list can be configured using the dispatch directive in the Configuration. If there is no dispatch directive, this page will redirect to the system’s default interview, which can be configured using the default 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 Configuration.

For information about how to customize the “Available Interviews” page, see the Configuration directives that begin with start page, or configure the start page template, or replace the page with an interview using dispatch interview.

My Interviews

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 configure the interview page template, or replace the page with an interview using session list interview.

Profile

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 admin or developer can edit the following fields:

  • Country code: an uppercase ISO 3166 country code
  • State
  • County
  • Municipality
  • Organization
  • Language: a lowercase ISO-639-1 language code representing the user’s language.
  • PyPI Username
  • PyPI Password

Sign Out

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.

Troubleshooting

For tips on troubleshooting your docassemble system, see the troubleshooting subsection in the Docker section.