Free trial

OneSpan Sign How To: Customizing the Signing Ceremony

eSignature developers
Haris Haidary,
Thumbnail

With OneSpan Sign, you have the ability to customize several aspects of the signing ceremony to fit your application’s needs. This allows you to more seamlessly integrate eSignLive’s signing experience within your application. In this blog, I will show you how to customize the signing ceremony with the Java SDK, .NET SDK, and REST API.

Document Package Level Settings

Before getting into the code, I will give you a brief description of each available package and ceremony layout settings. It is important to note that it is not required to specify any of these settings. They will default to the values shown below if not specified. Document Package Settings [table id=3 /] Ceremony Layout Settings Below is OneSpan Sign’s default signing ceremony layout. Each of the sections is labeled for convenience.  

Document Package Settings

Setting Name Document Package Settings Method Description
In-person withInPerson Whether all documents in a package have to be signed on the same device.
withoutInPerson (default)
Opt-Out withOptOut (default) Allow a signer not to participate in the signing ceremony.
withoutOptOut
Opt-Out Reason withOptOutReason If a signer decides to opt-out, he/she can select a reason for their withdrawal.
Language Dropdown withLanguageDropdown (default) Whether the language drop down menu from the signing ceremony page is displayed.
withoutLanguageDropdown
Owner in-person dropdown hideOwnerInPersonDropdown When in-person is enabled, decide whether the package is owner is present in the signer dropdown.
showOwnerInPersonDropdown (default)
First Affidavit disableFirstAffidavit When in-person is enabled, decide whether the first affidavit page is shown when switching signers from the dropdown.
enableFirstAffidavit (default)
Second Affidavit disableSecondAffidavit When in-person is enabled, decide whether the second affidavit page is shown when switching signers from the dropdown.
enableSecondAffidavit (default)
Decline withDecline Whether a signer can decline the document package.
withoutDecline (default)
Watermark withWatermark (default) Whether the signed documents are stamped with the OneSpan Sign logo with each signature.
withoutWatermark
Capture text withCaptureText Whether the signed documents are being stamped with the date, time, and signer’s name at each location they were signed.
withoutCaptureText (default)
Hand-over link withHandOverLinkHref Replaces the continue button in the signing ceremony. The user will be redirected to a URL you specify.
withHandOverLinkText The text that will appear on the handover button.
withHandOverLinkTooltip The text that will appear when hovering over the handover button.
Download Button withDocumentToolbarDOwnloadButton (default) Whether the download button is available.
withoutDocumentToolbarDownloadButton
Dialog on complete withoutDialogOnComplete (default)
withDialogOnComplete Whether the completion dialog, which asks the signers if they want to review the documents or leave the system, is shown after signing.

Ceremony Layout Settings

Below is OneSpan Sign’s default signing ceremony layout. Each of the sections is labeled for convenience.

esl_overview

Setting Name Ceremony Layout Settings Method Description
Navigator withNavigator (default) Show the navigator. It directs the signer to the next available signature.
withoutNavigator
Global Navigation withGlobalNavigation (default) Show the global navigation.
withoutGlobalNavigation
Bread Crumbs withBreadCrumbs (default) Show the bread crumbs.
withoutBreadCrumbs
Session Bar withSessionBar (default) Show the session bar.
withoutSessionBar
Title withTitle (default) Show the title
withoutTitle
Progress Bar withProgressBar (default) Show the progress bar.
withoutProgressBar
IFrame withIFrame Whether the signing ceremony is embedded in an iFrame.
withoutIFrame (default)
Logo withLogoSource Replaces the default OneSpan Sign logo with a custom logo. A valid URL to custom logo needs to be passed as argument.
Global Confirm Button withGlobalConfirmButton (default) Show confirm button in the global actions area.
withoutGlobalConfirmButton
Download Button withGlobalDownloadButton (default) Show the download button in the global actions area.
withoutGlobalDownloadButton
Save As Layout Button withGlobalSaveAsLayoutButton (default) Show the “Save As Layout” button in the global actions area.
withoutGlobalSaveAsLayoutButton

The Code

As I mentioned above, I will show you how to customize the signing ceremony with the Java SDK, .NET SDK, and REST API. Go ahead and skip to the section which applies to your method. I will cover the same information in each segment. Full code for this blog can be found in the Developer Community Code Share: Java, .NET, and REST.

OneSpan Developer Community

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today

Java SDK

I will start with the Java SDK. The sample code below shows you how to edit the settings block. If you need a comparison to the basic document object creation or if this is the first time creating a package with the Java SDK, see this previous blog.

.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
			.withInPerson()
			.withOptOut()
			.withOptOutReason("Decline terms.")
			.withoutLanguageDropDown()
			.hideOwnerInPersonDropDown()
			.disableFirstAffidavit()
			.disableSecondAffidavit()
			.withDecline()
			.withoutWatermark()
			.withCaptureText()
			.withHandOverLinkHref("http://www.google.com")
			.withHandOverLinkText("Exit to site")
			.withHandOverLinkTooltip("You will redirected to Google homepage")
			.withDocumentToolbarDownloadButton()
			.withDialogOnComplete()							
.withCeremonyLayoutSettings(CeremonyLayoutSettingsBuilder.newCeremonyLayoutSettings()
				.withNavigator()
				.withoutGlobalNavigation()
				.withoutBreadCrumbs()
				.withSessionBar()
				.withTitle()
				.withProgressBar()
				.withIFrame()
				.withGlobalConfirmButton()
				.withoutGlobalDownloadButton()
				.withoutGlobalSaveAsLayoutButton()
				.withLogoSource("http://www.logo-maker.net/images/common/company-logo8.gif")))

.NET SDK

Next, I will cover the .NET SDK. The sample code below shows you how to edit the settings block. If you need a comparison to the basic document object creation or if this is the first time creating a package with the .NET SDK, see this previous blog.

.WithSettings(DocumentPackageSettingsBuilder.NewDocumentPackageSettings()
                        .WithInPerson()
                        .WithOptOut()
                        .WithOptOutReason("Decline terms.")
                        .WithoutLanguageDropDown()
                        .HideOwnerInPersonDropDown()
                        .DisableFirstAffidavit()
                        .DisableSecondAffidavit()
                        .WithDecline()
                        .WithoutWatermark()
                        .WithCaptureText()
                        .WithHandOverLinkHref("http://www.google.com")
                        .WithHandOverLinkText("Exit to site")
 			.WithHandOverLinkTooltip("You will redirected to Google homepage")
                        .WithoutDocumentToolbarDownloadButton()
                        .WithoutDialogOnComplete()
              .WithCeremonyLayoutSettings(CeremonyLayoutSettingsBuilder.NewCeremonyLayoutSettings()
                                .WithNavigator()
                                .WithoutGlobalNavigation()
                                .WithoutBreadCrumbs()
                                .WithSessionBar()
                                .WithTitle()
                                .WithProgressBar()
                                .WithIFrame()
                                .WithGlobalConfirmButton()
                                .WithoutGlobalDownloadButton()
                                .WithoutGlobalSaveAsLayoutButton()
                                .WithLogoImageSource("http://www.logo-maker.net/images/common/company-logo8.gif")))

REST API

Finally, I will cover the REST API. The sample JSON below shows you how to edit the settings object. I included that will create a new document package with example settings for convenience. If you need a comparison to the basic document object creation or if this is the first time creating a package with the REST API, see this previous blog.

{
  "settings": {
    "ceremony": {
      "events": {
        "complete": {
          "dialog": true,
          "redirect": ""
        }
      },
      "inPerson": true,
      "declineButton": true,
      "declineReasons": [],
      "disableDeclineOther": false,
      "disableDownloadForUncompletedPackage": false,
      "disableFirstInPersonAffidavit": true,
      "disableInPersonAffidavit": false,
      "disableOptOutOther": false,
      "disableSecondInPersonAffidavit": true,
      "documentToolbarOptions": {
        "downloadButton": true
      },
      "handOver": {
        "title": "You will be redirected to Google homepage",
        "href": "http://www.google.com",
        "text": "Exit to site"
      },
      "hideCaptureText": false,
      "hideLanguageDropdown": true,
      "hidePackageOwnerInPerson": true,
      "hideWatermark": true,
      "maxAuthFailsAllowed": 3,
      "optOutButton": true,
      "optOutReasons": [
        "Decline terms."
      ],
      "style": null,
      "layout": {
        "footer": {},
        "iframe": true,
        "navigator": true,
        "brandingBar": {
          "logo": {
            "src": "/sites/default/files/blog/images/company-logo8.gif",
            "link": ""
          }
        },
        "header": {
          "feedback": true,
          "globalActions": {
            "confirm": true,
            "download": false,
            "hideEvidenceSummary": false,
            "saveAsLayout": false
          },
          "titleBar": {
            "title": true,
            "progressBar": true
          },
          "breadcrumbs": false,
          "globalNavigation": false,
          "sessionBar": true
        }
      }
    }
  },
  "type": "PACKAGE",
  "status": "DRAFT",
  "name": "Customizing Signing Ceremony"
}

Running Your Code

You can now go ahead and run your code. Depending on the settings you chose, your end result might be different from mine. If you followed my example, below is a screenshot of what you might expect:

results

There you go. You have successfully customized the signing ceremony.

If you have questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the developer community forums:

https://developer.onespan.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.

Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter

Haris Haidary
Go To Top
Share