There are a variety of ways that you can move information into and out of interview sessions, besides obtaining information from the user.
As explained in the invocation section, when a user starts an
interview, the user visits a URL. This URL can contains parameters of
your own choosing (as long as the names do not conflict with any of
the reserved URL parameters). Data passed using these parameters is
available inside the interview session using the
You can also change the
url_args during an active interview
session. If the user’s browser is logged into a session, and the user
clicks on a hyperlink to the same interview with URL parameters set,
url_args will be updated.
The normal flow of an interview in docassemble is as follows:
- The screen loads, and the user sees whatever
questionis the next step in the interview logic, given the current state of the interview answers.
- The user enters some information (if the screen asks for information) and then presses a button.
- The interview answers are updated with the new information.
- Go back to step 1.
Eventually, the interview will reach a logical endpoint. This flow makes sense for the main path of the interview, but sometimes the user needs to deviate from the main path. For example, they might want to adjust their answers to previous questions.
In docassemble, “actions” are used to trigger deviations from the
main path of the interview logic. For example, suppose that under
the main path of the interview logic, the next piece of
information that is necessary to gather is
interview will show a
question that offers to define
favorite_legume. But suppose you want the user to be able to go
back to the
favorite_vegetable question. (Perhaps a common mistake
is for users to list a legume as their favorite vegetable). You can
allow the user to launch an “action” that causes the interview to seek
(or in this case, re-seeks) the variable
favorite_vegetable instead of
Another type of deviation from the main interview logic is a background action. This is where some code runs on the server, in the background, where the user can’t see anything. This is typically used for code that takes a long time to run, where you don’t want the user to have to wait for the result, or there is a danger that the user’s browser will time out if the server does not respond quickly enough.
Typically, users launch actions by clicking hyperlinks within the docassemble application. However, it is also possible to click hyperlinks outside of the application that run actions inside the session.
For more information about this feature, see the
interview_url_action() function. This function creates a URL that
embeds the session ID.
interview_url_action() function also allows the extraction of
information from an interview. You can call
interview_url_action() with a reference to an
event that runs
json_response() to return selected information in a
machine-readable format. This allows you to create a customizable
“API” for your interview.
If you go through the interview and obtain the URL, you can try loading it in a different browser to verify that another application (not having the same browser cookies) can access the information in JSON format.
You can also manipulate interview sessions using the docassemble API.
This involves generating a special e-mail address using
interview_email(). Any e-mails sent to that address and received
by the server will be processed and made available in the interview
session for retrieval using
You can use the
send_sms() function to send text messages from an
interview session to the outside world. You will first need to
configure your server to
send text messages. Despite the function name (“SMS”), this function
can be used to send messages through Twilio’s WhatsApp API.
The interview answers in an interview session are stored in encrypted form inside of rows in a SQL table. Documents are stored on the server or in a cloud storage system. If a user who is not logged in completes an interview, they will not be able to access their interview session again after closing their browser, because the encryption key will be lost. However, if they log in, their interview session will be tied to their account, and their password will become the decryption key for the session.
The encryption of interview answers makes it impossible for someone
other than the original user to access the data in the interview
session, unless the decryption key (the user’s password) is known.
However, if the interview sets
interview_url_action() can be used to access the data
in the interview as long as the interview session exists.
By default, interview sessions are deleted after 90 days of
inactivity. This feature can be modified or turned off using the
interview delete days configuration directive.
When an interview session is deleted, the files associated with the interview session are also deleted.
If you want a file to continue exist after its associated interview
session has been deleted, you can use the
DAFile object in order to indicate that the file should not
be deleted when the interview session is deleted.
A session’s interview answers are stored in a SQL server, but not in a
way that is easily accessible across interview sessions. Interview
sessions are not persistent; the user can delete a session, and a
session may be deleted due to inactivity (unless the
delete days configuration directive is set to disable automatic
If you want to save information in SQL in a way that will persist
indefinitely and that will not be encrypted, you can use the
store_variables_snapshot() function to store the interview answers
to a special SQL table in a JSON format that allows you to write SQL
queries that access individual variables inside the data structure.
You can also use
read_records() functions to store data (including Python objects)
in SQL records. These methods do not preserve server-side encryption,
It is also possible for
DAObjects to “mirror” rows in a SQL
database. To do this, you need to write custom classes that are
DAObject and the special object
more information, see the documentation for
Your interview can also communicate with the outside world using any Python module that provides the functionality you want.
Here is a simple example that calls the World Clock API to obtain the current time (which you don’t really need an API to do).
get_time() function uses the
requests library. The variable
r represents the response of the World Clock API’s server to the
attempt to your code’s attempt to obtain the contents of the given
URL. This object has a handy method
.json() that converts the
output of the request to a data structure, assuming that the request
returns JSON. The
get_time() function returns the
currentDateTime part of the World Clock API’s response.
Here is an interview that calls the