Skip to content

Commit 932469b

Browse files
nonprofittechynonprofittechy
authored
Merge pull request #523 from SuffolkLITLab/document-signature-flow
Document signature flow
2 parents 97f266f + b7b1e6a commit 932469b

File tree

4 files changed

+169
-0
lines changed

4 files changed

+169
-0
lines changed

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,9 @@ yarn-error.log*
2323
target/
2424
.vscode/
2525
.obsidian/
26+
27+
yarn.lock
28+
.yarn
29+
.yarn/
30+
.pnp.cjs
31+
.pnp.loader.mjs

‎docs/components/AssemblyLine/magic_variables.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,18 @@ code: |
322322
al_form_requires_digital_signature = False
323323
```
324324

325+
### `al_typed_signature_prefix`
326+
327+
Defaults to `/s/`. Controls the prefix when user decides to use a typed signature.
328+
329+
### `al_typed_signature_font`
330+
331+
Defaults to `"/usr/share/fonts/truetype/google-fonts/BadScript-Regular.ttf"`.
332+
333+
Can be the exact path to a font installed on the server. If it is not an exact path,
334+
the font name will be searched for in `/usr/share/fonts` and `/var/www/.fonts`, with `.ttf`
335+
appended to the filename.
336+
325337
### `al_form_type`
326338

327339
`al_form_type` is used to control some dynamic questions to give more specific

‎docs/components/AssemblyLine/signatures.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
id: signatures
3+
title: Collecting signatures
4+
sidebar_label: Signatures
5+
slug: signatures
6+
---
7+
8+
## Triggering the gathering of a signature
9+
10+
In the AssemblyLine, you can gather signatures by triggering the variable
11+
`basic_questions_signature_flow`. This sets off a gathering process which
12+
allows the user to decide how they want to sign and then to gather a list of
13+
signatures, one at a time.
14+
15+
Typically, this variable is mentioned in the `interview order` or `main order`
16+
block of your interview. Make sure to mention it somewhere in the interview's
17+
mandatory logic.
18+
19+
Example:
20+
21+
```yaml {12}
22+
---
23+
###################### Main order ######################
24+
comment: |
25+
This block includes the logic for standalone interviews.
26+
Delete mandatory: True to include in another interview
27+
mandatory: True
28+
code: |
29+
al_intro_screen
30+
satisfaction_of_judgment_intro
31+
interview_order_satisfaction_of_judgment
32+
signature_date
33+
basic_questions_signature_flow
34+
satisfaction_of_judgment_download
35+
```
36+
37+
## Deciding which signatures to gather
38+
39+
The AssemblyLine looks for the definition of a `list` of `strings` named
40+
`signature_fields` to decide which variable names to gather during the signature flow.
41+
42+
Example:
43+
44+
```yaml
45+
code: |
46+
signature_fields = ["users[0].signature"]
47+
```
48+
49+
You do not need to know the definition in advance. You can make use of
50+
normal Python logic to help build this list. The `attr_name()` method might
51+
be especially helpful. For example:
52+
53+
```yaml
54+
code: |
55+
signature_fields = [p.attr_name("signature") for p in people]
56+
```
57+
58+
Creates a list of strings like `["people[0].signature", "people[1].signature"]`
59+
60+
:::note
61+
62+
The signature fields must be listed as strings, not as plain Python variables.
63+
64+
:::
65+
66+
## Customizing the kind of signature to gather
67+
68+
The `basic_questions_signature_flow` can trigger 4 kinds of signatures:
69+
70+
* Signature on a phone, with an option to text the user a link to sign or use a QR code.
71+
* Signature on the same device by drawing it with a mouse.
72+
* Signature by adding /s/, using a customizable font.
73+
* No signature--that is, letting the user print and add a signature manually.
74+
75+
By default, the AssemblyLine requires the user to add a digital
76+
signature when the `basic_questions_signature_flow` is triggered.
77+
78+
If you do not want to require a digital signature, you can set `al_form_requires_digital_signature`
79+
to `False`. This lets the user sign after printing.
80+
81+
The `/s/` option is currently always offered.
82+
83+
You can make further customizations by making your own version of the
84+
[`id: signature choice`](https://github.com/SuffolkLITLab/docassemble-AssemblyLine/blob/f4d50140cf6e274a8c5ad12d3f484762d8989a2f/docassemble/AssemblyLine/data/questions/ql_baseline.yml#L1417)
85+
screen.
86+
87+
:::note
88+
89+
The AssemblyLine's text to sign feature can be handy for remote signing, but it only allows
90+
you to text one person a link to sign the document. It is also "blocking."
91+
You won't get notified when a signature is added, and if you click continue
92+
before the signature is added, you'll see the signature screen yourself.
93+
94+
:::
95+
96+
### Limitation of `/s/` signature variable name
97+
98+
Currently, the AssemblyLine only provides a way to define a `/s/` signature when the variable name ends with
99+
`signature`.
100+
101+
You can directly call `docassemble.AssemblyLine.sign.create_signature()` if you need a `/s/` signature
102+
with a different variable name.
103+
104+
### Customizing `/s/` font or changing `/s/` to a different prefix
105+
106+
You can customize the simulated signature for jurisdiction-specific reasons, or
107+
change the font by redefining `al_typed_signature_prefix` and `al_typed_signature_font`.
108+
109+
`al_typed_signature_prefix` defaults to `/s/`, and `al_typed_signature_font` defaults to
110+
`"/usr/share/fonts/truetype/google-fonts/BadScript-Regular.ttf"`.
111+
112+
A custom font can be given as the exact path to a font installed on the server. If it is not a path,
113+
the font name will be searched for in `/usr/share/fonts` and `/var/www/.fonts`, with `.ttf` appended
114+
to the filename.
115+
116+
## Using the signature inside a template
117+
118+
Signatures are always `DAFile` objects: even the `/s/` signature variation. This makes it easy
119+
to have only one way to use them.
120+
121+
In a DOCX file, simply enclose the variable in Jinja2 tags, like: `{{ users[0].signature }}`. You may need to adjust spacing
122+
for it to look right. A table can be helpful. For slightly
123+
better safety, and any time that you have `skip undefined: False`, you can use `{{ users[0].signature_if_final(i) }}` to skip
124+
rendering the signature on the preview page.
125+
126+
In a PDF document: make sure that the field where you want to add the digital signature is a [digital signature field](https://helpx.adobe.com/sign/authoring/fields/e-signature.html).
127+
Then, add the field normally, like:
128+
129+
```yaml
130+
attachment:
131+
...
132+
fields:
133+
...
134+
- "users1_signature": ${ users[0].signature_if_final(i) }
135+
```
136+
137+
You can test whether you have the right kind of field by using the AssemblyLine Weaver tool. The preview it makes of your uploaded form will
138+
have John Hancock in place of the correct kind of signature field.
139+
140+
:::note
141+
142+
Adobe has changed the name of the "digital signature field" several times, but the functionality still exists when you
143+
click around. It's in different places in different versions of Acrobat.
144+
[Gavel.io/pdf](https://gavel.io/pdf) makes the right kind of field and has only the one option.
145+
146+
:::
147+
148+
## Docassemble's documentation
149+
150+
* [Gathering the user’s signature into a file variable](https://docassemble.org/docs/fields.html#signature)

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ module.exports = {
122122
'components/AssemblyLine/translation',
123123
'components/AssemblyLine/error_actions',
124124
'components/AssemblyLine/background_assembly',
125+
"components/AssemblyLine/signatures",
125126
"components/AssemblyLine/al_general",
126127
"components/AssemblyLine/al_courts",
127128
"components/AssemblyLine/al_document",

0 commit comments

Comments
 (0)