# Signicat forms
It is possible to create a signing order containing a PDF document with an interactive form. The signing order specifies that the interactive form should be taken into consideration. Optionally, the customer can specify initial values for some or all fields.
When the signing order is accessed in the signing interface, the PDF document is presented to the end-user in the browser. Each form field in the PDF is accessible via an HTML input element of the relevant type superimposed on the presentation of the PDF.
The end-user fills out the relevant fields, the values are merged into the original PDF and form flattening is performed. The end-user completes the signing ceremony as normal and will then be able to download the signed document. The generated/merged PDF is the one that is covered by the electronic signature.
After the signing ceremony is completed, the customer can retrieve the original PDF containing the interactive form, the generated/merged/flattened version and the signed result, as well as the values used in the merging/flattening.
# Detailed description
# Creating the signing order
In order to activate the Forms functionality, there are some prerequisites to both the specification of the signing order and the PDF document that have to be fulfilled.
# Signing order prerequisites
The document element must contain the
form element for the given document to be treated as a document containing a form. In other words, even though a PDF containing an interactive form is supplied, the form will be ignored if the
form element is not included.
id attribute of the
form element must be set to the string
interactive. Optionally, the form element may contain one or more
input-param elements. This is detailed further down.
# Document with form
<document id="doc-1" type="provided-document" mime-type="application/pdf"> <description>Simple form document</description> <data>[REMOVED FOR BREVITY]</data> <form id="interactive"/> </document>
# PDF document prerequisites
The supplied PDF document must contain interactive form fields (AcroForm fields). The supported field types are:
- text field
- radio button
All fields must be “empty”, i.e. text fields must be empty, checkboxes and radio buttons must be unchecked and choice fields cannot have an initial option set as selected. In order to set initial values, form input params (as described below) must be used.
Fields can be marked as read-only, in which case the end-user will not be able to edit the field. This should typically be combined with a form input parameter, to avoid empty read-only fields.
# Optional form input parameters
Fields can have an initial value set by supplying it as a form input parameter. This is done by adding an input-param element to the form element for the given field.
The name of the field is given in the name attribute and the value is given in the value attribute. These values will be pre-filled in the given fields when the PDF is presented to the end-user.
The end-user will be able to change these values before submitting/saving the form, unless the field is marked as read-only.
# Input parameters
<document id="doc-1" type="provided-document" mime-type="application/pdf"> <description>Form document with input params</description> <data>[REMOVED FOR BREVITY]</data> <form> <input-param name="first-name" value="James"/> <input-param name="last-name" value="Raynor"/> <input-param name="email" value="firstname.lastname@example.org"/> </form> </document>
# Form validation
Form fields can be specified as
required in the PDF. If a document contains one or more required form fields, the end-user will not be allowed to complete the signing process before the required fields have been filled out.
Form fields can contain up to 256 characters. This applies both to fields completed by the end-user and to pre-filled values supplied as part of the signing order. The end-user will not be allowed to complete the signing process if any form fields exceed the character limit.
# Creating a form
The below screenshots show an example for how to create a form.
# End-user signing ceremony
The below screenshots show an example for an end-user signing ceremony where a form is filled out and signed with Norwegian BankID and Signed statement. The last screenshot is an example of the flattened result.
# Retrieving the result
As with any other signing order, once the end-user has completed the signing process, the result can be obtained via a
getStatus call. The response will, for each document, contain URLs for both the original document as well as the SDO (signed data object).
In addition, if the document is a form document, all form parameters used in the flattening process will be returned as
output-param elements. This way, the customer can obtain the data values that the end-user has supplied in a structured format for further processing.
Values supplied by the end-user will take precedence over pre-filled values supplied by the customer.
# Output parameters
<document-status id="doc-1"> <original-uri>[URL TO ORIGINAL DOCUMENT]</original-uri> <result-uri>[URL TO SIGNED DATA OBJECT]</result-uri> <form-output-param name="first-name" value="James"/> <form-output-param name="last-name" value="Raynor"/> <form-output-param name="email" value="email@example.com"/> <form-output-param name="mood" value="grumpy"/> <form-output-param name="drunk" value="yes"/> </document-status>