d) Integration Document and Envelope Viewer

Owned by Dennis Machowetz
Last updated: Oct 29, 2024 by Leonard Schubert
6 min read

This page describes the different viewer types, the integration of viewers and the creation of viewer urls.

There are two types of viewers:

  • envelope viewer: contains one or several documents and conditions
  • document viewer: contains a single document.

The viewers are integrated in the GUI (logged in user) or are opened with a time limited viewer link (integration see below). The link is either automatically created by websignature office and send per email or created with the tyrservice (see Time Limited Viewer URL creation).

Time Limited Viewer URL creation

Time limited viewer URLs forward to the document or envelope viewer and valid till a defined timestamp. The link is specific for a document or envelope and a associated signer. To build the link via tyrservice, admin priviliges are required.

KeyDescription
x

viewer name:

  • tldv: time limited document viewer
  • tlev: time limited envelope viewer
uuser_id: The user id of the signer
ttimestamp: unix timestamp till the link is valid
d/e

the id:

  • e: envelope id for envelope viewer
  • d: document id for document viewer
localeoptional: language of the viewer. "de" or "en". If not present, german viewer will be used.

There are two formats for the time limited viewer:

  • viewer url with the parameters and an encrypted signature parameter "xx"
  • viewer url with all parameters encrypted in parameter "xen"

URL with urlSignature

The viewer link with url signature is deprecated. It contains the parameters "x", "u", "t", "d"/"e" and "xx". 

  • time limited document viewer: https://host.com/process?x=tldv&u=2&t=1710370800000&d=1000&xx=piQA-jwlzblZaNWrsWnQshbAha8O_3AEkfeyyg
  • time limited envelope viewer: https://host.com/process?x=tlev&u=2&t=1710370800000&e=1000&xx=piQA-jwlzblZaNWrsWnQshbAha8O_3AEkfeyyg

The url signature ("xx") is created with the tyrservice method getUrlSignature:

 TyrService getUrlSignature requests
time limited document viewer: getUrlSignature request
<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getUrlSignature</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited document viewer -->
    <param>
      <value>tldv</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>d</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
time limited envelope viewer: getUrlSignature request
<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getUrlSignature</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited envelope viewer -->
    <param>
      <value>tlev</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>e</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
getUrlSignature response
<?xml version="1.0" encoding="UTF-8"?><methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <params>
	<!-- URL signature -->
    <param>
      <value>piQA-jwlzblZaNWrsWnQshbAha8O_3AEkfeyyg</value>
    </param>
  </params>
</methodResponse>

URL with encrypted parameters

Using URLs with encrypted parameters is the preffered and safer method. The values ("x", "u", "t", "d"/"e") are encrypted with the tyrservice method getEncryptedParameters. The URL only contains the parameter "xen" (and optional parameters):

Time limited document or envelope viewer:

  • https://host.com/process?xen=yJtSth3pkHcE...


 TyrService getEncryptedParameters requests

The request payload is identical to the payload of getUrlSignature:

time limited document viewer: getEncryptedParameters request
<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getEncryptedParameters</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited document viewer -->
    <param>
      <value>tldv</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>d</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
time limited envelope viewer: getUrlSignature request
<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getEncryptedParameters</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited envelope viewer -->
    <param>
      <value>tlev</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>e</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>
getUrlSignature response
<?xml version="1.0" encoding="UTF-8"?><methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <params>
	<!-- encrypted parameters "xen" -->
    <param>
      <value>yJtSth3pkHcE...</value>
    </param>
  </params>
</methodResponse>


Integration

If you want to integrate the webSignatureOffice viewer / document URL into your existing web application (browser), there are basically two options available:
a) Display of the document viewer in a separate browser tab.
b) Display of the document viewer within your own browser page, integrated via iFrame (see example below)


iFrame Test
<!DOCTYPE html>
<html>

	<head>
				 
		<meta charset="utf-8">
				
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
	
		<title>Viewer iFrame Test</title>

		<!-- JS -->
		<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
		<script>
			jQuery(document).ready(function(urlFromBackend) 
			{
				// URL from Backend
				var url = urlFromBackend; //Response from Tyrservice method calls; example URL = https://host.com/process?xen=yJtSth3pkHcE...
	        jQuery('.iframe iframe').attr('src', url);
			});
		</script>

		<!-- CSS -->
		<style>
			body
			{
				font-family: arial !important;
				font-size: 16px;
				line-height: 22px;
			}

			header
			{
				padding:15px;

				background-color: #23406b;
				color: #fff;
			}

			header .logo
			{
				display: inline-block;
				vertical-align: middle;
			}

			header nav
			{
				display: inline-block;
				vertical-align: middle;

				margin-left: 50px;
			}

			header nav a
			{
				margin-left: 10px;
				color: #fff;
			}
			header nav a:hover
			{
				opacity: 0.7;
			}

			footer
			{
				padding:10px;

				background-color: #23406b;
				color: #fff;
			}


			/* example for iframe styling */
			iframe
			{
				width: 100%;
				height:calc(100vh - 250px);
			}
		</style>
		
	</head>

	<body>
		<header>
			<div class="logo">Logo</div>
			<nav>
				<a href="#">Menu 1</a>
				<a href="#">Menu 2</a>
				<a href="#">Menu 3</a>
				<a href="#">Menu 4</a>
			</nav>
		</header>

		<main>
			<div class="intro">
				<h1>Beispielhafte Anbindung webSignatureOffice Viewer</h1>
			</div>

			<!-- iFrame start -->
			<div class="iframe">
				<iframe src="" name="iFrame" title="iFrame" allowfullscreen></iframe>
			</div>
			<!-- iFrame end -->
		</main>

		<footer><p>Footer</p></footer>
		
	</body>
</html>

Webhooks

The viewer posts messages to the parent when the user finished his signatures or clicks buttons:

eventpost message
click "finish" or "save and quit" ("X")viewerExit
finish all own signatures in a document/envelope (signatures of other users are left, the status is "waiting")finishedOwnSignatures
all signatures of all users are finished in document/envelope finishedSigning