Signicat Forms

3211 views November 30, 2017 May 10, 2020 10

The customer creates 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 responsive signflow, 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.

The 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"/>
PDF document prerequisites

The supplied PDF document must contain interactive form fields (AcroForm fields). The supported field types are:

  • text field
  • checkbox
  • radio button
  • choice

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 prefilled 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>
    <input-param name="first-name" value="James"/>
    <input-param name="last-name" value="Raynor"/>
    <input-param name="email" value=""/>
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 signature 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 prefilled values supplied as part of the signing order. The end-user will not be allowed to complete the signature process if any form fields exceed the character limit.

Creating a form

The screenshots are an example of how to create a form.


End-user signing ceremony

The screenshots are an example of 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 signature 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. 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 prefilled 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=""/>
  <form-output-param name="mood" value="grumpy"/>
  <form-output-param name="drunk" value="yes"/>

Was this helpful?