suffolklitlab / docassemble-assemblyline

Quickly go from a paper court form to a runnable, guided, step-by-step web application powered by Docassemble. Swap out branding and pre-built questions to meet your needs.

Suffolk LIT Lab Document Assembly Line

The Assembly Line Project is a collection of volunteers, students, and institutions who joined together during the COVID-19 pandemic to help increase access to the court system. Our vision is mobile-friendly, easy to use guided online forms that help empower litigants to access the court remotely.

Our signature project is CourtFormsOnline.org.

We designed a step-by-step, assembly line style process for automating court forms on top of Docassemble and built several tools along the way that you can use in your home jurisdiction.

This package contains runtime code and pre-written questions to support authoring robust, consistent, and attractive Docassemble interviews that help complete court forms.

Read more on our documentation page.

Related repositories

• https://github.com/SuffolkLitLab/docassemble-ALWeaver
• https://github.com/SuffolkLitLab/docassemble-ALMassachusetts
• https://github.com/SuffolkLitLab/docassemble-MassAccess
• https://github.com/SuffolkLitLab/docassemble-ALThemeTemplate
• https://github.com/SuffolkLitLab/EfileProxyServer

Documentation

https://suffolklitlab.org/docassemble-AssemblyLine-documentation/

Installation

Menu-driven installation

The recommended installation method is with the guided installation script.

Manual installation

Normally you do not need to manually install the Assembly Line. Use the installation script if you can. The instructions below are for your optional reference.

This package depends on the following configuration changes on your Docassemble server:

• Ensure that font-awesome is enabled (this may be on by default:

default icons: font awesome

• Add a Google API key that has access to:
  • Google Places API
  • Google Geocoding API
• Add a VoiceRSS API key
• Add a Twilio API key for SMS support
• Add an email account: Mailgun or SendGrid recommended for email support
• To show package update time and to enable the feedback form, add a GitHub Private Access token to your config.yml file, like this:

# Needs access to create new issues on repositories
github issues:
  username: "suffolklitlab-issues"
  token: "12345"
# Does not need any special access to public repositories  
github readonly:
  username: "suffolklitlab-issues"
  password: "45678"
  type: "basic"

• If you are also using the Assembly Line Weaver, you may want to set up a Docassemble API key in your config.yml file to allow you to install packages automatically, like this:

install packages api key: 12345

Migration

See discussion here

ALDocument class

Purpose

The ALDocument class is a small utility library that makes it simpler to use the following features in an interview:

• Conditional assembly of multiple, optional documents that are triggered in different ways in your interview
• An addendum for PDF files that makes it simple to deal with overflow text
• A customizable download screen that lists the documents in a neat table
• A customizable "send" button that allows the user to email the final forms to a location of their choice

Here is a small snippet that you can copy and modify that shows how to use the most important features of the ALDocument class.

---
objects:
  - CRA_Motion_to_Dismiss_attachment: ALDocument.using(filename="CRA_Motion_to_Dismiss", title="Motion to Dismiss CRA", enabled=True, has_addendum=True, default_overflow_message="[See addendum]")  
---
objects:
  - al_user_bundle: ALDocumentBundle.using(elements=[CRA_Motion_to_Dismiss_attachment], title="Forms to download and deliver to court", filename="motion_to_dismiss_CRA.pdf")
  - al_court_bundle: ALDocumentBundle.using(elements=[CRA_Motion_to_Dismiss_attachment], title="Forms to download and deliver to court", filename="motion_to_dismiss_CRA.pdf")
---
generic object: ALDocument
attachment:
  variable name: x.addendum
  docx template file: docx_addendum.docx
---
code: |
  CRA_Motion_to_Dismiss_attachment.overflow_fields['reasons_for_request'].overflow_trigger = 640
  CRA_Motion_to_Dismiss_attachment.overflow_fields['reasons_for_request'].label = "Reasons for request"
  CRA_Motion_to_Dismiss_attachment.overflow_fields.gathered = True
  
---
attachment:
    variable name: CRA_Motion_to_Dismiss_attachment[i]
    name: CRA Motion to Dismiss
    filename: CRA_Motion_to_Dismiss
    skip undefined: True
    pdf template file: CRA_Motion_to_Dismiss.pdf
    fields: 
      - "court_county": ${ trial_court.address.county }
      - "docket_number": ${ docket_number }
      - "user_signature": ${ users[0].signature_if_final(i) }
      - "signature_date": ${ signature_date }

It is very common to have a contingent document in ALDocument. If your document is contingent, remove the enabled=True from the object declaration, and use some other method to "turn on" the attachment.

E.g.,

code: |
  CRA_Motion_to_Dismiss_attachment.enabled = condition1 and condition2

Changelog

See CHANGELOG.MD

docassemble-assemblyline's Issues

Linter: a tool to report on usability issues in a completed interview YAML

It might check for things like:

• italics
• headlines that are too long
• Reading grade level
• number of fields on each screen

and produce a report about where you think it could be improved.

De-duplicate the feedback form footer

docassemble-AssemblyLine/docassemble/AssemblyLine/data/questions/al_visual.yml

Lines 49 to 53 in c9607e1

	% if get_config('debug'):
	Feedback, suggestions, or comments? [Complete this survey](${ interview_url(i="docassemble.MAVirtualCourt:feedback.yml", github_repo=github_repo_name, github_user='suffolklitlab', variable=user_info().variable, question_id=user_info().question_id, package_version=package_version_number, local=False,reset=1) } ){:target="_blank"}.
	% else:
	Feedback, suggestions, or comments? [Complete this survey](${ interview_url(i="docassemble.MAVirtualCourt:feedback.yml", github_repo=github_repo_name, github_user='suffolklitlab', variable=user_info().variable, question_id=user_info().question_id, package_version=package_version_number, local=False,reset=1) } ){:target="_blank"}.
	% endif

Both if get_config('debug'): and its else: seem to use the same code. If that's correct, we can get rid of the if.

Move the feedback form footer into AssemblyLine

docassemble-AssemblyLine/docassemble/AssemblyLine/data/questions/al_visual.yml

Line 50 in c9607e1

Feedback, suggestions, or comments? [Complete this survey](${ interview_url(i="docassemble.MAVirtualCourt:feedback.yml", github_repo=github_repo_name, github_user='suffolklitlab', variable=user_info().variable, question_id=user_info().question_id, package_version=package_version_number, local=False,reset=1) } ){:target="_blank"}.

It currently uses docassemble.MAVirtualCourt:feedback.yml

Attachment download table still needs some work

The buttons look fine vertically aligned, but without a description the placement of the form name is not quite right.

1. The name of the file should be top aligned and a bit larger
2. There needs to be something to fill the whitespace--could make the buttons horizontal again as one solution.

There could be other fixes to this page too. It just feels a bit awkward still.

Modify general_cover_page.docx so it works with stock AssemblyLine

Right now it depends on objects from MACourts. See also: #8

Add a "permalink" button, perhaps in a footer

We don't use the screen parts: footer element yet, but this might work there.

I think this could solve two problems: one is to let individual promote the tool to friends. The second is to allow outside entities to link to the form correctly. Right now people tend to copy/paste the URL from the URL bar. That leads to a /run/interview URL, which resumes the last place someone was in the form. That's not so ideal since there's no easy way to restart.

If we do this, we might also want a few other related tasks:

1. Share the link to your interview session
2. Send an email or text to tell someone about the tool
3. Restart/new session button that prompts you to create an account first if you are not already logged in.

Add a feedback.yml file and point default survey link to it

Write a README for the `questions` folder that describes what's in each file there.

Integrate back in a general version of the Github Feedback form

Add name of sought variable to some part of the DOM in the development environment

Somewhere on the developer HUD seems most appropriate.

Investigation: assembling documents seems slow

Using the ALDocument class seems to slow down document assembly. Maybe something to do with it raising more exceptions than normal attachment assembly would?

Can we find a way to test if this is correct and speed it up if it really is a problem?

Create dummy user instructions page that works w/o our custom courts object

This is mostly helpful for the al_question_test.yml file, but it should also be a good model of how this template will work.

In practice, we want the wizard to create a template of the next steps instruction file. SuffolkLITLab/docassemble-ALWeaver#98

Add way for someone to tell us they do not have an address

This is linked to providing a method of collecting international addresses

Create variable placeholders for new ALDocument class

See: SuffolkLITLab/docassemble-ALWeaver#139

`courts` is deprecated but we should consider handling it here

SuffolkLITLab/docassemble-ALWeaver#314

One possible solution is to just make it a list with one item--trial_court

Integrate back in a general version of id debug code

Consider adding metadata to specify default country/use of country field for address fields

We could use this in the ql_baseline

General: create method on ALIndividual to handle impounded addresses

should be like address_block() method, but:

1. Handle impounded address by printing "Address impounded"
2. Handle optionally impounded phone_number

Integrate ALDocument class

https://github.com/SuffolkLITLab/docassemble-ALDocument

Add a question for bbo

This is Massachusetts specific, but we're okay with that for now. In the future--link this to MA-specific version of the wizard.

We could make the MassAccess package have a list of reserved keywords as a way to make this more flexible in the future. The wizard could choose the organization repo and then select the file which has the right list of reserved keywords in it.

Spacing on download and email buttons is cramped

It feels like we need more whitespace around the buttons and rows to make this legible, especially when you have both a download button and an email button.

Add some strategic color

Our pages are still very stolid. It's been shown that adding images/cartoons/graphics has a big impact on users' comfort with using online tools. I would like to have a stronger visual identity for our forms.

One solution is to add some images from: https://www.flaticon.com/

General: create way to validate phone number entry fields

Need to think about this carefully. People may intentionally annotate phone number fields or put text in that field, but it can help avoid errors too.

User: part of the form was confusing (ported from AffidavitofIndigencyMAVC)

Original link: SuffolkLITLab/docassemble-AffidavitofIndigencyMAVC#14

Question ID	email status
What was confusing	I wasn’t able to edit the “Enclosed:” portion of the cover page and I believe that this makes my request look less professional.
Other information
Variable being sought	email_status
Package version	0.0.17

Verify that the `if i=='final'` logic still works when downloading a form on the final page

It looks like this is not working correctly in the wizard-generated code on 2/12. Need to investigate this.

If a PeopleList `xyz` has target_number=1, we should not ask for "name of the first xyz"

It should just say "name of the xyz" instead

Figure out a way and place to add "freshness" labels to court forms

All forms should have a last-updated date somewhere.

Create a method on ALDocument or a function that accepts an ALDocument to handle delivery to the court

Right now, we have the send to court code inside the interview YAML. This can and should move to a .py file. That will better abstract it and make it simpler to eventually migrate from email filing to ECF v4 filing via API.

Make the "Review your answers" link (section) work on mobile

We turned off the feature that shows section headings on mobile

Add Address attribute for "mailing_address" to the ALIndividual class

Add type hints for attributes in the ALDocument class

We can make type hints without assigning a value, like this:

class MyClass(DAObject):
  someattribute:str
  def init(self):
    pass

Some way to differentiate between the person/people who's filling out the form and the individuals listed on the form (often the main party/parties)

Example: A form where the person filling out the information could be the filer themselves or an attorney.

We need to also be able to identify who's using the form. It affects things like:

• Where to say 'you' vs. a name
• Which fields a name should go in

Are we looking for a new variable to use? Are we looking to add a role to the different individuals in the interview? This wasn't initially standardized, but most of the current forms treat users as the person who is listed on the form as the main party (not sure of that wording legally), so we can't use that.

What I've understood of our thinking so far:

1. We're going to try to phase out users and start using user_parties instead
2. We will not re-use users so that old interviews will remain stable

set_info

We are looking into using https://docassemble.org/docs/functions.html#set_info:

set_info(user=user_parties[0])
#or
set_info(user=attorneys[0])

Pros

1. It's already used in docassemble to help frame questions correctly, so it will have an added use (e.g., saying "you" on certain screens where we say the person's full name instead now).
2. It's a stable variable that you can poll and that exists regardless of which Individual objects you initialized in the interview. That makes it simpler to check than scanning all of the potential Individual objects to see which one have the flag set on them.
3. You can store these as objects instead of trying to juggle docassemble intrinsic names.
4. It's an existing, albeit slightly obscure convention.

Cons

1. It's slightly obscure.
2. It's different than how we do other things currently

Outstanding questions

1. Can this be used in a template? If so, how? Jonathan designed this to be part of multi-user interviews where two people participate at different times.

A flag

I assume an attribute such as .types on the Individual

Pros

1. It's a syntax we've used before

Cons

1. Whenever we need this piece of information, it requires scanning all of the potential Individual objects to see which ones have the flag set on them

Some other state object

I think this is what one version might look like:

---
code: |
  if is_attorney:
    state['attorney'] = 'users[0]'
    state['plaintiff'] = 'plaintiffs[0]'
  else:
    state['attorney'] = 'attorneys[0]'
    state['plaintiff'] = 'users[0]'
---
"plaintiff_name": ${ showifdef( value( state['plaintiff'] ) }

Pros

1. It's a syntax we've used before

Cons

1. It would lose the built-in advantages the set_info object has
2. It might need to be done in each individual interview, bringing more opportunities for mistakes
3. The particular method shown requires going through extra boilerplate code to be able to trigger the right intrinsic names

Create a demo YAML file that shows to use a user cover page and a court cover page

Style: add a scrubber to the audio playback button; don't display any audio controls until the new one is rendered

See #29 for longer discussion.

I think we have just two fixes left to make:

1. Add a scrubber/way to reposition the audio playback. We discussed having this be something that only shows when the screen is being read aloud. It would display/collapse like an accordion.
2. Right now the old audio UI shows for a few seconds before the new one is rendered. It would be nice to have the old audio control start out hidden.

Style: consider making file upload target smaller

The current Docassemble upload widget overwhelms the page. My feeling is that it would be easier to read other text on the page if we made it much smaller. Hopefully this is just CSS.

Style: improve the look of the read aloud / "playback" button

There are some examples of more unobtrusive widgets that do this around the web. We should be able to style this better.

MLRI's is one good example:

What I like about this is that it has a label and icon that more clearly conveys what it does and that the button does not take the full width of the CSS box.

Display the version number somewhere on the production server. We need an "about" screen somewhere?

Add a method on ALIndividual that conditionally displays the signature

This would replace:

{%p if i=='final' %}
{{ users[0].signature }}
{%p endif %}

In the DOCX file.

Likely method signature:
users[0].signature_if_final(i)

Discussion: Revisit how we broke up different YAML files when we have had some time to get used to them

Maybe in April?

Modify send to court code to use al_court_bundle object

One annoying thing: we want to include the al_cover_page ALDocument for all court documents, but the natural way to specify the list of files is in the interview itself. The only solution I see if we want the cover page to be in the bundle is to use boilerplate code or always expect the end developer to include the cover page manually. That seems an unnecessary place to risk errors.

Some courts might want one file to print, and some might want to separate the court cover page from the substantive file(s).

Do we want court_bundle to include the cover page, or just always send the cover page when we send the file to the court? It might make the most sense to attach the cover page at sending time, rather than making it part of the bundle.

Fix visual appearance of review screens

Right now, the "Edit" button is styled float: right which makes it very far away from the text you are editing. float: left with a margin-right: 1em looks a bit better, but if the text is multi-line the margin shifts to the left which is a bit weird.

I suspect someone can play around with this and make it better than it is now.

Need to properly define `business_name_text` to be translatable

docassemble-AssemblyLine/docassemble/AssemblyLine/al_general.py

Line 97 in e2beba1

{"label": self.business_name_text, "field": self.attr_name('name.first')}

is asking for an attribute that doesn't exist.

docassemble-AssemblyLine/docassemble/AssemblyLine/al_general.py

Line 104 in e2beba1

"choices": [{"Person": "ALIndividual"}, {"Business or organization": "business"}],

is the right text to use

When you click the "make changes" button on the final screen, the documents should all be regenerated

Currently you get a stale PDF/Word document.

Hopefully this can be fixed in the ALDocument class. It might need to be fixed in the wizard.

Discuss where info about the files in the `questions` folder should be

Set up to allow dependencies

So that projects that pul the repos into new servers will be able to add the necessary packages too.

Allow downloading ALDocumentBundle as a .ZIP file

The "download" button for an ALDocumentBundle should have an option of downloading as a .ZIP file when there is more than one attachment in the bundle.

Start thinking about how to represent the form's data in a reusable way--not just as a PDF

We eventually want to be able to store the information captured in the interview in a structured way, that captures all of the same information that goes onto the PDF. We may want to do this two different ways: a version with all of the data, and an anonymized version with just a summary for running reports.

Some ideas: extend the ALDocument class so that it also assembles a "shadow" JSON file. We could both send this to the court and store in database in searchable JSONB format. This would let us capture the information at the same time we generate the final document for the user/court.

We may also want to format and structure this data to match the fields in ECFv4 or v5; align with the profileMe hackathon experiment; look to NCSC and Schema.org.

At this point: we just need to start thinking about the problem and try to design our classes to allow room for this expansion.

Adjust html downloads page table

Only thing I am not sure about is the icons--they are a little busy. Perhaps removing even just one of the three icons across the row and changing the weight of the document title would be enough to make it more legible. On the backend we might shuffle around the way the CSS etc. works, but I think we can easily adjust that without breaking code that runs through the wizard.

We can possibly use bootstrap classes to take care of some of these pain points instead of making our own css. That will come with advantages like a dark theme, etc. if that's something da can offer. [Sorry that didn't occur to me sooner.]

Email documents UI

Transfer email capabilities from https://github.com/SuffolkLITLab/docassemble-ALDocument/tree/email_docs with some adjustments. As an alternative to needing to include a .yml file with an event block in it:

If you would like an HTML button to run Python code, how are you able to abstract that?
This is for triggering an action on a custom object. Specifically, sending an email with the contents of that object.
It looks like with action_perform() and url_action(), docassemble will look for the definition of an event. I'd like the event to be enclosed in the module itself, so an interview author can use the code without having to include a YAML file or to write their own email-sending event.
something like:

subquestion: |
  ${ my_docs.send_email_button() }

to run the send_email() function in the module itself.
Can an event be defined in a module? Weird question since iirc the event itself is never defined. Alternatively: is there a way to trigger an action that is not a docassemble event via JavaScript?
Maybe by using @property on a method in the class definition

☝️ Confirmed

whatever method you currently have of sending data to an event block in YAML could similarly be used in a method of the object. the @property decorator makes the method look like an attribute to outside code that interacts with it.
you might have seen that pattern to use a function to define the complete attribute of an object for a list

Search for @property at https://docassemble.org/docs/groups.html

The javascript that listens for the event and detects the state of the checkbox and the value of the input

will need to be either part of the HTML, or a JS dependency. i assume that would be handled by an interview-wide JS dependency

Change the upper back button to "undo" to match the one next to the "next" button

Also do this on MAVirtualCourt repo