Jump to main content

# Using eSignature and Acroform fields

The ESignatureAndFieldSupport output type element allows users to configure the following eSignature functionality in transaction-based Ancillary Output elements.

## eSignature feature overview

Features/elements available within the ESignatureAndFieldSupport element:

- eSignatureCoordinatesOnly: if set to "true," eSignature fields are suppressed on the form and X/Y coordinates are returned.
- eSignatureDateSupport: allows users to enable or disable the date field in an eSignature. Setting the element to "true" enables the date field; setting the element to "false" disables the date field.
  Note: If using an `ESignatureAndFieldSupport` ancillary output > `eSignatureDateSupport` = "false", the resulting date field will not be signable, and the Expere response file will only display a `SignaturePoint` container with an `IncludeDate` = "true".
- eSignatureTooltip: allows users to pass a string as a help popup.
- eSignatureInitialsTooltip: allows users to pass a string as a help popup.
- NonSignatureFieldCoordinatesOnly: if set to "true," other Non-Signatures fillable fields (textboxes and checkboxes) are suppressed on the form and X/Y coordinates are returned.
- eSignatureWKES: by default, this flag is optional.
  - If set to "true:"
    - Initials will be rendered as a fillable field;
    - WKES (previously SDX) naming conventions apply, and the `<FieldName/>` element applies eSignatures for "Initials," "Signature," "Date," and "Checkbox"

      Example naming convention is: `WKES_FieldType_UserEmail_FieldOrder-NavigationOrder_M/O`

    - The `<SignerEmail/>` element and the email address added to the `<FieldName/>` are included in the response;
  - If set to "false:"
    - Initials are rendered as esignable, and current naming convention is used: <`r:FieldName>INI_Borrower_null_homer_false_1_SigField_1</r:FieldName>`; by

## Using SignaturePointSet and eSignatureAndFieldSupport

Previously, `SignaturePointSet` was the only element which controlled passing XY coordinates and suppressing signature fields on the form. We have enhanced the `SignaturePointSet` element and created a new element, `eSignatureAndFieldSupport`. The new element `eSignatureAndFieldSupport` has two flags to control eSignatures and Non-Signature Fillable fields independently.

Below is an explanation of the elements and their flags:

- `SignaturePointSet` (Existing Element)
  - If Passed: XY Coordinates are returned for all fields. Fillable fields are not rendered on the form.
  - If Not Passed: XY Coordinates are returned for all fillable fields and the fields are rendered on the form.
- `eSignatureAndFieldSupport`: this will override the `BSI.Properties` settings if it is passed in.
  - `eSignatureCoordinatesOnly`: child of `eSignatureAndFieldSupport`
    - If true: XY Coordinates are returned for eSignature fields (eSignature and eSignature date); eSignature fields are not rendered on the form.
    - False (Null): XY Coordinates are returned for eSignatures (eSignature only) and eSginature fields; fields are rendered on the form
  - `eSignatureDateSupport` child of `eSignatureAndFieldSupport`.
    - If true: XY Coordinates are returned for eSignature Date fields and are rendered on the form.
    - False (Null): XY Coordinates are not returned; fields are not rendered on the form
  - `NonSignatureFieldCoordinatesOnly`, child of `eSignatureAndFieldSupport`
    - If true: XY Coordinates are returned for non-signature fillable fields; the fields are not rendered on the form.
    - False (Null): XY Coordinates are returned; fields are rendered on the form.

## Self-hosted users: BSI.Properties Considerations

Note the following:

Users can turn on `eSignatureSupport`, `eSignatureDateSupport`, and `acroformSupport` for all transactions in the `BSI.Properties` configuration file. The default values for these properties are:

- eSignatureSupport (existing): "false"
- eSignatureDateSupport (existing): "true"
- acroformSupport (new): "true"

If `SignaturePointSet` is passed in and the properties for `eSignatureSupport`, and `acroformSupport`, in the `BSI.Properties` file are set to "true”; XY Coordinates are returned for all fields (esignatures, esignature dates, and other fillable fields). No fillable fields are rendered on the form.

If `SignaturePointSet` is not passed and the properties for `eSignatureSupport`, and `acroformSupport`, in the `BSI.Properties` file are set to “true”; XY Coordinates are returned for all fillable fields; the fields are rendered on the form.

## Signature Field and SignatureDateField naming for embedded PDF, dynamic, and static REQ files

The following is the naming convention for the `SignatureField` and `SignatureDateField` elements:

- An example `SignatureField` element value could look like this: `SIG_Borrower_1_1_true_1_eSig` or `PurchaserSignatureArea_eSig`. The naming convention must avoid the use of "." (periods / dots).
- `SignatureDateField` elements use the above mentioned `SignatureField` naming convention and "_eSigDate;" for example: `SIG_Borrower_1_1_true_1_eSig_eSigDate` or `PurchaserSignatureArea_eSig_eSigDate`

## Setting a tooltip value with eSignature and Initial fields

By default, Expere will add a set eSignature tooltip value of "Unsigned Signature Field" for every eSignature field in a document. Additionally, all fillable initial fields will contain a default value of "Unsigned Initial Field". Users may override these values and their own custom values through the following means:

- eSignature tooltip: pass in an `eSignatureAndFieldSupport` ancillary output in the transaction with the `<eSignatureTooltip/>` element containing the desired string value.

      <AncillaryOutputsDoc>
      	<AncillaryOutput>
      		<OutputType>ESignatureAndFieldSupport</OutputType>
      		<ESignatureAndFieldSupport>
      			<!-- A boolean value to determine if eSignatures should be repressed in favor of X/Y coordinates. -->
      			<!-- Values: true, false -->
      			<eSignatureCoordinatesOnly>false</eSignatureCoordinatesOnly>
      			<!-- A boolean value to determine if eSignature date is supported. -->
      			<eSignatureDateSupport>true</eSignatureDateSupport>
      			<!-- The text that will be used for the eSignature tooltip -->
      			<eSignatureTooltip>ESignature ToolTip</eSignatureTooltip>
      			<!-- The text that will be used for the eSignature initials tooltip -->
      			<eSignatureInitialsTooltip>ESignature Initials ToolTip</eSignatureInitialsTooltip>
      			<!-- A boolean value to determine if all acroform fields that are not eSignature should be repressed in favor of X/Y coordinates. -->
      			<!-- Values: true, false -->
      			<NonSignatureFieldCoordinatesOnly>false</NonSignatureFieldCoordinatesOnly>
      			<!-- A boolean value to determine if eSignatures initial fields should render as Text fields -->
      			<!-- Values: true, false -->
      			<eSignatureWKES>false</eSignatureWKES>
      		</ESignatureAndFieldSupport>
      	</AncillaryOutput>
      </AncillaryOutputsDoc>

- Initial field tooltip: pass in an `eSignatureAndFieldSupport` ancillary output in the transaction with the `<eSignatureInitialsTooltip/>` element containing the desired string value.

      <AncillaryOutputsDoc>
      	<AncillaryOutput>
      		<OutputType>ESignatureAndFieldSupport</OutputType>
      		<ESignatureAndFieldSupport>
      			<!-- A boolean value to determine if eSignatures should be repressed in favor of X/Y coordinates. -->
      			<!-- Values: true, false -->
      			<eSignatureCoordinatesOnly>false</eSignatureCoordinatesOnly>
      			<!-- A boolean value to determine if eSignature date is supported. -->
      			<eSignatureDateSupport>true</eSignatureDateSupport>
      			<!-- The text that will be used for the eSignature tooltip -->
      			<eSignatureTooltip>ESignature ToolTip</eSignatureTooltip>
      			<!-- The text that will be used for the eSignature initials tooltip -->
      			<eSignatureInitialsTooltip>ESignature Initials ToolTip</eSignatureInitialsTooltip>
      			<!-- A boolean value to determine if all acroform fields that are not eSignature should be repressed in favor of X/Y coordinates. -->
      			<!-- Values: true, false -->
      			<NonSignatureFieldCoordinatesOnly>false</NonSignatureFieldCoordinatesOnly>
      			<!-- A boolean value to determine if eSignatures initial fields should render as Text fields -->
      			<!-- Values: true, false -->
      			<eSignatureWKES>false</eSignatureWKES>
      		</ESignatureAndFieldSupport>
      	</AncillaryOutput>
      </AncillaryOutputsDoc>