> ## Content Index
> Fetch the complete content index at: https://www.alt-counsel.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# [Part 3] Do more with docassemble: Getting work done in a background action
- URL: https://www.alt-counsel.com/part-3-do-more-with-docassemble-getting-work-done-in-a-background-action/
- Published: 2022-05-16T14:48:24.000Z
- Updated: 2022-05-28T14:35:39.000Z
- Description: In this part of the docassemble, Google TTS tutorial, I talk about docassemble's background action and why we should use it for this interview.
- Author: Houfu Ang
- Tags: Article, Python, docassemble, Programming, Tutorial

## Introduction

In [Part 2](https://www.alt-counsel.com/part-2-do-more-with-docassemble-start-a-project-and-write-a-few-questions/), we managed to write a few questions and a result screen. Even with all that eye candy, you will notice that you can’t run this interview. There is no `mandatory` block, so docassemble does not know what it needs to do to run the interview. In this part, I will talk about the code block required to run the interview, which forms the foundation of our next steps.

## 1\. The backbone of this interview

In ordinary docassemble interviews, your endpoint is a template or a form. For this interview, the endpoint is a sound file. So let’s start with this code block. It tells the reader how the interview will run. Since it is a pretty important block, we should put it near the top of the interview file, maybe right under the meta block. (In this tutorial, the order of blocks does not affect how the interview will run. Or at least until you get to the bonus section.)

```yaml
mandatory: True
code: |
  tts_task
  final_screen

```

If you recall, the user downloads the audio file in the `final screen`.

So this mandatory code block asks docassemble to “do” the `tts_task` and then show the final screen. Now we need to define `tts_task`, and your interview will be ready to run.

So what should `tts_task` be? The most straightforward answer is that it is the result of the API call to create the sound file. You can write a code block which gets and returns a sound file and then assign it to `tts_task`.

Well, don’t write that code block yet.

## 2\. Introducing the background action

If you’re going to call an API on the other side of the internet, you should know that lots of things can happen along the way. For example, it takes time for your request to reach Google, then for Google to process using its fancy robots, send the result back to your server, and then for your server to send it back to the user. In my experience, Google’s and docassemble’s latency is quite good, but it is still noticeable with large requests.

A user is not supposed to notice that a program lags when the interview runs well. If the user realises that the interview is stuck on the same page for too long, the user might get worried that the interview is broken. The truth is that we are waiting for the file to come back. Get back in your chair and wait for it!

To improve user experience, you should have a waiting screen when you tell the user to hold his horses. While this is happening, the interview should do its work in the background. In this manner, your user is assured everything is well while your interview focuses on getting the file back from Google.

docassemble already provides a mechanism for the docassemble program to carry out background actions. It’s [aptly called background\_action()](https://docassemble.org/docs/background.html?ref=alt-counsel.com#background%5Faction).

Check out a sample of a background action by reading the first example block (”Return a value”) under the Background processes category. Modify our mandatory code block by following the mandatory code block in the example. It should look like this.

```yaml
mandatory: True
code: |
  tts_task
  if tts_task.ready():
    final_screen
  else:
    waiting_screen

```

So now we tell docassemble to do the `tts_task`, our background task. Once it is ready, show the final screen. If the task is not ready, show the waiting screen.

## 3\. Define the background action

Now that we have defined the interview flow, it’s time to do the background action. In the spirit of docassemble, we do this by defining `tts_task`.

The next code block defines the task. Adapt this example into our interview file as follows.

```yaml
code: |
  tts_task = background_action(
    'bg_task', 
    text_to_synthesize=text_to_synthesize, 
    voice=voice, 
    speaking_rate=speaking_rate, 
    pitch=pitch,
  )

```

So we have defined `tts_task` as a background action. The background action function has two kinds of arguments.

The first positional argument (”bg\_task”) is the name of the code block that the background action should execute in the background.

The other keyword arguments are the information you need to pass to this background action like the `text_to_synthesize`, `voice` etc. These are the options you answered earlier during this interview which will now be used for this background action. Defining your variables here in a mandatory block indirectly also ensures that docassemble will look for the answers for these variables before performing this code block.

So why do you need to define all the variables in this way? Don’t forget that the background action is a separate process from the rest of your interview so they don’t share the same variables. To enable these processes to share their information, you pass on the variables from the main interview process to the background action.

## 4\. Perform the background action

We have defined the background action. Now let’s code what happens inside the background action.

The background action is defined in an event called `bg_task`. Now add a new code block as follows:

```yaml
event: bg_task
code: |
  audio = get_text_to_speech(
    action_argument('text_to_synthesize'),
    action_argument('voice'),
    action_argument('speaking_rate'),
    action_argument('pitch'),
  )
  background_response()

```

So in this code block, we say that the audio is obtained by calling a function named `get_text_to_speech`. For `get_text_to_speech` to produce an audio file, it requires the answers to the questions you asked the user earlier. As a background process, it gets access to the variables you defined earlier through the keywords of the `background_action` function by calling `action_argument`.

Once `get_text_to_speech` is completed, we call `background_response()`. Calling background\_response is important for a background action as it tells docassemble that this is the endpoint for the background action. Make sure you don’t leave your background action without it.

## 5\. Provide a waiting screen

Before we leave the example block for background processes, let’s add the question block that tells the user to wait for their audio file. Find the block which defines `waiting_screen`, and adapt it for your interview as follows.

```yaml
event: waiting_screen
question: |
  Hang tight.
  Google is doing its magic.
subquestion: |
  This screen will reload every
  few seconds until the file
  is available.
reload: True

```

![](https://raw.githubusercontent.com/houfu/lovelawrobots-content/master/2022/05/image-4-1.png)

By adding `reload: True` to the block, you tell docassemble to refresh the screen every 10 seconds. This helps the user to believe that they only need to be patient and some “magic” is going on somewhere.

## Conclusion

In the next part of the tutorial, we will dive into `get_text_to_speech`. (What else, right?) We will need to call Google’s Text to Speech API to do this. If you found it easy to follow the code blocks in this part of the tutorial, we will kick this up a notch — the next file we will be working on ends with a “.py”.

👉🏻

**[Go ahead to the next part](https://www.alt-counsel.com/part-4-do-more-with-docassemble-calling-google-text-to-speech/)**

👈🏻

[**Go to the previous part**](https://www.alt-counsel.com/part-2-do-more-with-docassemble-start-a-project-and-write-a-few-questions/)

👈🏻

**[Check out the overview of this tutorial.](https://www.alt-counsel.com/part-1-do-more-with-docassemble-google-text-to-speech/#a-roadmap-of-this-tutorial)**