diff --git a/docs/components/AssemblyLine/background_assembly.md b/docs/components/AssemblyLine/background_assembly.md new file mode 100644 index 000000000..b4a4ffd65 --- /dev/null +++ b/docs/components/AssemblyLine/background_assembly.md @@ -0,0 +1,169 @@ +--- +id: background_assembly +title: | + Assembling documents in the background +sidebar_label: | + Assembling documents in the background +slug: background_assembly +--- + +Assembly Line `3.2.0` and later introduce a background processing option to the [ALDocumentBundle](al_document.md) +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 +1. Setting conditions on when to display a waiting screen +1. 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 +1. 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: + +```python + if not al_user_bundle.generate_downloads_with_docx_task.ready(): + al_download_waiting_screen +``` + +:::warning 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. + +```yaml +--- +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: + +```yaml +--- +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. + +event: al_download_waiting_screen +reload: True +``` + +The default screen uses [standard Bootstrap components](https://getbootstrap.com/docs/5.2/components/spinners/) +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](https://docassemble.org/docs/modifiers.html#reload). + +## 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](https://docassemble.org/docs/background.html#background_action) 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()](al_document.md#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()](al_document.md#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](https://docassemble.org/docs/admin.html#logs) \ No newline at end of file