Survey123 Tricks of the Trade: Signatures

IsmaelChivite · ‎11-16-2021

In some workflows, signatures matter. Signatures are used as consent, as the means to express agreement or as proof that someone certifies the contents of a form. Here are some specific examples:

As part of a city code violation report form, a city employee collects a signature as proof that the signee was notified in-person of the violation
A construction inspection form requires both the auditor and property owner to sign. The signatures are used to signify agreement from both parties
An asbestos removal form requires a signature from the inspector to certify all the work done
A safety compliance form requires the respondent to sign before work commences

Using Survey123, you can collect one or more signatures as part of a form. Signatures are supported in both the Survey123 field and web apps. End users sign by drawing a signature using their finger or electronic pen, if using a touch screen, or the mouse cursor if using a desktop computer. Signatures are stored in ArcGIS as attachments. They can be visualized within a Survey123 form, through a web map popup and included in Survey123 reports.

In this article I will describe how you can design forms with signatures in them. I will cover the basics with Survey123 designer and show you some more advanced techniques with Survey123 Connect.

Adding signatures to your form using Survey123 designer

The library of question types in Survey123 designer includes a signature question type. Simply drag and drop it into your form design as shown in the animation below.

Designer Signature.gif

You can set a label, hint and even an inline description into the signature question. The inline description is useful if you want to include in the signature box some disclaimer of agreement test. For example, “By signing here I agree to the terms above”, or “I agree that I was present during the inspection”. You can also make the signature question required. This will ensure that the form is not submitted without a signature.

Signatures in XLSForm. The basics

According to the XLSForm specification, signatures are modeled in smart forms using the signature appearance in an image question type. Here is a simple example:

Collecting multiple signatures

There are several ways to collect multiple signatures in a form. The most common, is to add as many signature questions as you need. In the screenshot below, I added one for the inspector and one for the owner of the property.

Since each image has a unique name in the XLSForm design, it is possible later to differentiate one signature attachment from the other. For example, the signature of the inspector, versus the signature attachment corresponding to the property owner. This is useful for attachments handled through workflow automation using the Survey123 connector for Integromat and Microsoft Power Automate as well as for Survey123 reports.

You can alternatively use the multiline appearance in your image question. This allows you to collect multiple signature attachments under a single question.

Another approach is to add a signature, along with other questions, to a repeat block. You would never want to use a repeat to just have a signature question in it. If that were the case, you would want to use the multiline appearance instead. However, using a repeat block would make sense if you want to collect the signature and some additional data. For example:

In the example above, we want to collect information about every operator in the field crew. We collect, their name, safety checklist, and finally a signature.

Controlling the size and dimensions of signature images

Signatures collected with Survey123 are stored in ArcGIS as file attachments in .png format. The dimensions of the image file vary depending on the device used to sign. The more screen resolution, the bigger the image: A signature collected on a tablet with a high-resolution display will be bigger than one collected on a smartphone.

While a signature file is typically very small (measured in KBs), particularly if you compare it with a photo (measured in MBs), you may want to cap the maximum size of a signature file.

Controlling the exact dimensions of signature images is also important if you plan to include signatures in a Survey123 report. You will want to control their size (for quality) and the aspect ratio, so you can best position your signatures within your printed report.

If you want to control the size and dimensions of the signature images, you can use a couple of approaches:

Use the max-pixels parameter: The max-pixels parameter is applied to the parameters XLSForm column. For a signature question, it defines the maximum width of the image.

Set a background image: When you define a background image, the user signs on top of it. For this reason, the user’s signature will always have the same height and width dimensions as the background image. You can also use the background image to include some inline text to the signature box or use to apply some cosmetic effects.

To add a custom background image, copy the image file into the survey’s media folder, then reference your image from the default XLSForm column.

Modelling approve or deny workflows

Signatures are often used in approve or deny workflows. In this workflow, a form is submitted by one person and then reviewed by a second. The reviewer can add comments, change the status of the record, and sign it. For example, a demolition permit is submitted by the owner of a building. A city employee reviews an approves or denies the request.

This type of workflow can be modeled using two separate forms targeting the same layer. The first one is used to submit the request, and the second one to review it. To review the request, you can use the Survey123 field app inbox or load the request into the Survey123 web app in edit mode.

Alternatively, you can model this workflow using a single form. In this case, you would configure the reviewer’s questions (including the signature), to only appear when the form is in review (edit mode).

Here is an example. Note how the body::esri:visible column is used to control the visibility of all the questions relevant to the review process.

To learn how to load existing records into the Survey123 web app in edit mode, check:

You can also open records in edit mode using the Survey123 field app using the inbox.