Assembling documents in the background

Assembly Line 3.2.0 and later introduce a background processing option to the ALDocumentBundle class.

Background processing:

• Is safer when your user may generate large documents that take more than 60 seconds to assemble or convert to PDF
• Prevents frustrating 504 gateway timeout errors

Negatives include:

• Requires more care from the developer
• Usually prevents you from using an "edit" button on the final screen
• Means assembling documents will always take at least 10 seconds

If your users currently have to wait a long time to get their finished documents, or if your users ever see an error screen because the downloads took too long to make, you should use background processing.

If you have only a few small documents and there is no user-provided content (like photos or other uploaded exhibits), you should try without using background processing first.

Adding background processing to your interview

Background processing is a built-in feature of the ALDocumentBundle class. Using it involves:

1. Starting the built-in background assembly task in your interview order block
2. Setting conditions on when to display a waiting screen
3. Editing the download screen so it makes use of the background assembled documents

In most cases, when you use background processing, you should also:

1. Disable the preview screen
2. Show a review screen in-line before the download screen.

Editing your interview order block

Find the line in your interview order block where you would like to start the background assembly. In most cases, this should be just before the download screen.

Add a line like this:

  if not al_user_bundle.generate_downloads_with_docx_task.ready():
    al_download_waiting_screen

Make sure all required variables are defined

Background assembly requires that all of the logic required to assemble your documents was triggered before the background processing starts. You cannot have any undefined variables that are needed for the document to generate.

Note that if you use skip undefined this isn't usually a problem.

In some cases, you may want to start the background assembly earlier than just before the download screen. For example, you may want to show the user instructions, or get information for a task that will not change the documents, such as eFiling.

Editing the download screen

On the download screen, edit the reference to download_list_html() to let it use the background assembled documents. Using cached files is disabled by default.

---
id: download
event: download_screen
question: |
  Download the documents
subquestion: |
  Your documents are ready for download.

  If you need to make any changes, click the "Undo" button and click the button to edit
  the answer you want to change.

  ${ al_user_bundle.download_list_html(use_previously_cached_files=True, include_full_pdf=True) }

And don't forget

• Remove the preview screen. A waiting screen before the preview isn't a good user experience for most interviews.
• Add the review screen to your interview order block. The user will not be able to click the "edit answers" button on the download screen.

Customizing the user experience

What happens in the background task

You may want to provide a non-default set of options to the file generation step.

Override al_user_bundle.generate_downloads_with_docx_task or define a task with your own name. The default contents of this task are:

---
generic object: ALDocumentBundle
event: x.create_downloads_with_docx
code: |
  download_response = x.get_cacheable_documents(key="final", pdf=True, docx=True, include_full_pdf=True)
  background_response_action(x.attr_name('save_downloads'), download_response=download_response)

The waiting screen

Override al_download_waiting_screen, or define a screen with your own name. The default contents of this question block are:

---
id: waiting screen
question: |
  Please wait while we make your documents
subquestion: |
  This can take a few minutes.
  <div class="spinner-border text-primary d-flex justify-content-center" role="status">
      <span class="sr-only">Making documents...</span>
  </div>
event: al_download_waiting_screen
reload: True

The default screen uses standard Bootstrap components to create the spinning circle. You can put anything you like here, although an animation is recommended.

If you would like the screen to reload more often than every 10 seconds, you can set it as low as 4 seconds.

Key methods and built-in task names

al_download_waiting_screen is a Assembly Line provided example of a generic waiting screen.

generate_downloads_task is the name of a background task object defined in the standard includes as an attribute of each ALDocumentBundle. It triggers a task to produce a full PDF of the bundle using the final key, a full ZIP, and it will not generate DOCX versions of the items, only downloadable (PDF) versions.

create_downloads is an event defined in the Assembly Line standard includes as an attribute for each ALDocumentBundle. This event is triggered by generate_downloads_task.

generate_downloads_with_docx_task is an alternative to generate_downloads_task that does produce the DOCX as well as PDF version of each document. You can safely use this even if you do not always want to display the DOCX on the download screen.

In turn, generate_downloads_with_docx_task triggers the event create_downloads_with_docx

get_cacheable_documents() is a new method that generates all enabled documents in the bundle and returns a list, where each item is a tuple of the DOCX and PDF versions of the document.

Optionally, it will also produce a .ZIP and a .PDF version of the full bundle.

This is called from a YAML block in the Assembly Line standard include files to define the _downloadable_files attribute of a bundle.

download_list_html() has an optional parameter, use_previously_cached_files which must be set to True to make use of the _downloadable_files attribute of the bundle.

Troubleshooting

If your background process has an error, the details of the error (typically a missing or undefined variable) will be found in the worker.log file