How to Guides

Detailed callbacks on specific events

You can define per envelope the callbacks for specific events. For example, if a workstep was created, a workstep was opened or a signature was applied. Please note, these events typically are not required for the most use cases and you should have a look at the eSAW Callbacks and eSAW Status callbacks: API Reference and Callbacks

You can forward all eventtyps to your callback url or use a

  • blacklist: all events, except the events in the blacklist, are fired
  • whitelist: only the events in the whitelist are fired
  • empty blacklist/whitelist: all events are fired

Do not use blacklist and withlist at the same time! If you only want to use the event callbacks, use an empty envelope callback in the configuration (<callbackUrl />)

The following placeholders are defined:

  • ##WorkstepId## – workstep of current action
  • ##EventType## – type of event (see list of types below)
  • ##Source## – internal (eSAW)  or external (Viewer)
  • ##Time## – time when the action occurred
  • ##Description## – textual description of the event
  • ##RecipientEmail## – emailadress of current recipient
  • ##EnvelopeId## – current envelope id
  • ##RecipientOrder## – index of current recipient

Definition without black-/whitelist:

<envelope>
   ...
   <workstepEventCallback>
        <url>http://www.mycallback.at?envelopeId=##EnvelopeId##&amp;recipientEmail=##RecipientEmail##&amp;recipientOrder=##RecipientOrder##</url>
   </workstepEventCallback>
   <steps>
      ...
   </steps>
</envelope>

Blacklist-Definition

<workstepEventCallback>
	<url>http://www.mycallback.at?envelopeId=##EnvelopeId##&amp;recipientEmail=##RecipientEmail##&amp;recipientOrder=##RecipientOrder##</url>
	<blacklist>
		<event>SomeEventName</event>
		<event>SomeDifferentEventName</event>
	</blacklist>
</workstepEventCallback>

Whitelist-Definition

<workstepEventCallback>
	<url>http://www.mycallback.at?envelopeId=##EnvelopeId##&amp;recipientEmail=##RecipientEmail##&amp;recipientOrder=##RecipientOrder##</url>
	<whitelist>
		<event>SomeEventName</event>
		<event>SomeDifferentEventName</event>
	</whitelist>
</workstepEventCallback>

Please note:These events are fired by the Workstep Controller (internal component) and are fired before the data in eSAW is complete updated (some postprocessing is required). Therefore this event callbacks are used only in rare integrations. Please have a look at the eSAW Callbacks and Status Callbacks in the API Reference.

Available Event Types

ConfirmTransactionCode – A transaction code was sent
DefaultEventType – Not specially defined event type
AgreementAccepted – The user accepted the agreement
AgreementRejected – The user rejected the agreement
RequestPrepareAuthenticationInformationSuccess – The request for additional authentication infos was requested
PrepareAuthenticationSuccess – The prepare authentication process succeeded
AuthenticationFailed – The user failed to authenticate
AuthenticationRejected – The user rejected the authentication process
AuthenticationSuccess – The user succeeded to authenticate
ReAuthenticationFailed – The reauthentication process failed
AuditTrailRequested – The audittrail was requested
AuditTrailXmlRequested – The audittrail XML was requested
CalledPage – The viewer site was requested
WhoIsInformation
DocumentDownloaded – The document download was requested
FlattenedDocumentDownloaded – The flattened document download was requested
AddedAnnotation – An annotation was added
AddedAttachment – An attachment was added
AppendedDocument – A document was appended
FormsFilled – A form field was filled
ConfirmReading – A reading task was completed
PageViewChanged – The user scrolled
SendTransactionCode – This event is raised, when a TransactionCode for a signature with type TransactionCode* has been sent using the IdentityServer or the TransactionCodeSenderPlugin
PrepareSignWorkstepDocument – A signature is prepared for signing
SignWorkstepDocument – Try to sign a signature
UndoAction – An action was undone
WorkstepCreated – A workstep was created
WorkstepFinished – A workstep was finished
WorkstepRejected – A workstep was rejected
DisablePolicyAndValidityChecks
EnablePolicyAndValidityChecks
AppendFileToWorkstep – A file was appended to the workstep
AppendTasksToWorkstep – A task was added to the workstep
SetOptionalDocumentState – A optional document became either active or inactive
StartBatch – A batch signing process started
EndBatch – A batch signing process ended
PreparePayloadForBatch – The payload is getting prepared for batch signing

How to use Advanced Tags

Download - HowTo Advanced Tags

Download a ZIP with resources for this HowTo: Example-PDF, AdHocWorkstepConfig.xml, PrepareSendEnvelopeSteps_Request.xml, PrepareSendEnvelopeSteps_Result.xml, SendEnvelope_Request.xml

This will show you how to use the advanced tags via API. The useage is basically the following:

  1. Place the tags in your PDF document (be aware to avoid line breaks)
  2. Upload the PDF document
  3. Let eSignAnywhere parse your document to locate the tags
  4. Prepare the envelope for sending

1. Prepare the PDF

Use the advanced tags in the document for signatures or form fields (e.g. Checkboxes). This guide uses a simple PDF with a checkbox and a signature field for one reciepient.

2. Upload the PDF

Use the uploadTemporarySspFile for uploading the BASE64 converted file. As result you will receive the file id.

3. Prepare the document

The next step is to let eSignAnywhere parse the document for the tags. Therefore you have to call the PrepareSendEnvelope function.

This function required in additon to the authentication the following parameters:

  • File ID (from  uploading the document)
  • AdHoc Workstep Configuration (see Download to get a minimum AdHocWorkstepConfiguration)
  • Descriptor with settings for parsing
    This contains currently only one parameter: clearFieldMarkupString. This defines if the advanced tags are removed from the PDF or not.
<prepareSendEnvelopeStepsDescriptor>
  <clearFieldMarkupString>0|1</clearFieldMarkupString>
</prepareSendEnvelopeStepsDescriptor>

As result you receive a part of the envelope XML, based on the recipients found in the tags, and the preconfigured workstep configurations, based on the AdHoc configuration.

<workstepConfiguration /> contains a generated workstepConfiguration for the document
<steps> contains the <steps> part of the envelope XML, based on the tags found in the document. For each found recipient one <step> is created and the fields (e.g. chechboxes, signature fields, etc.) are created in their workstepconfigurations.
<addFormFields> is also for the envelope XML, which is telling eSignAnywhere which signature fields have to be created.

Sample Response (of Example)

<prepareSendEnvelopeStepsResult>
  <workstepConfiguration skipThirdPartyChecks="0">
	<WorkstepLabel />
	<SmallTextZoomFactorPercent>100</SmallTextZoomFactorPercent>
	<WorkstepTimeToLiveInMinutes>10</WorkstepTimeToLiveInMinutes>
	<FinishAction />
	<signatureTemplate>
	  <version>1.2.0.2</version>
	  <positionUnits>PdfUnits</positionUnits>
	  <positionReferenceCorner>Lower_Left</positionReferenceCorner>
	</signatureTemplate>
	<pdfForms isEditingAllowed="1" />
	<PictureAnnotationTaskInfo>
	  <MinResolution>100</MinResolution>
	  <MaxResolution>300</MaxResolution>
	  <ColorDepth>Color16M</ColorDepth>
	</PictureAnnotationTaskInfo>
	<ViewerPreferences>
	  <SendVisibleArea allowedDomain="*">0</SendVisibleArea>
	</ViewerPreferences>
	<Policy version="1.1.0.0">
	  <GeneralPolicies>
		<AllowSaveDocument>1</AllowSaveDocument>
		<AllowSaveAuditTrail>0</AllowSaveAuditTrail>
		<AllowRotatingPages>1</AllowRotatingPages>
		<AllowAppendFileToWorkstep>0</AllowAppendFileToWorkstep>
		<AllowAppendTasksToWorkstep>0</AllowAppendTasksToWorkstep>
		<AllowEmailDocument>0</AllowEmailDocument>
		<AllowPrintDocument>0</AllowPrintDocument>
		<AllowFinishWorkstep>1</AllowFinishWorkstep>
		<AllowRejectWorkstep>1</AllowRejectWorkstep>
		<AllowRejectWorkstepDelegation>0</AllowRejectWorkstepDelegation>
		<AllowUndoLastAction>1</AllowUndoLastAction>
		<AllowColorizePdfForms>0</AllowColorizePdfForms>
		<AllowAdhocPdfAttachments>1</AllowAdhocPdfAttachments>
		<AllowAdhocSignatures>1</AllowAdhocSignatures>
		<AllowAdhocStampings>1</AllowAdhocStampings>
		<AllowAdhocFreeHandAnnotations>1</AllowAdhocFreeHandAnnotations>
		<AllowAdhocTypewriterAnnotations>1</AllowAdhocTypewriterAnnotations>
		<AllowAdhocPictureAnnotations>0</AllowAdhocPictureAnnotations>
		<AllowAdhocPdfPageAppending>1</AllowAdhocPdfPageAppending>
	  </GeneralPolicies>
	  <WorkstepTasks SequenceMode="SequenceOnlyRequiredTasks" originalSequenceMode="SequenceOnlyRequiredTasks" />
	  <AdhocPolicies>
		<AllowModificationsAfterSignature>1</AllowModificationsAfterSignature>
	  </AdhocPolicies>
	</Policy>
	<timeCreated>2018-01-24T08:07:46.0787271Z</timeCreated>
	<signaturePluginConfiguration>
				<PdfSignatureProperties_V1>
					<PdfAConformant>0</PdfAConformant>
					<PAdESPart4Compliant>0</PAdESPart4Compliant>
					<IncludeSigningCertificateChain>0</IncludeSigningCertificateChain>
					<SigningCertificateRevocationInformationIncludeMode>DoNotInclude</SigningCertificateRevocationInformationIncludeMode>
				</PdfSignatureProperties_V1>
				<PdfSignatureCryptographicData_V1>
					<SignatureHashAlgorithm>Sha1</SignatureHashAlgorithm>
					<SigningCertificateDescriptor>
						<Identifier>DDED02DC192573B722E8C027F0E47E63152EB822</Identifier>
						<Type>Sha1Thumbprint</Type>
						<Csp>Default</Csp>
					</SigningCertificateDescriptor>
				</PdfSignatureCryptographicData_V1>
			</signaturePluginConfiguration>
	<TransactionCodeConfigurations>
	  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId">
		<!--Message used to send a transaction code to the client. The message has to contain the placeholder '{tId}' for the transactionId and the placeholder '{Token}' for the token.-->
		<Message>Please authenticate yourself for the access to the envelope with the transactionId {tId}. Your code is: {Token}</Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="en">
		<Message>Please authenticate yourself for the access to the envelope with the transactionId {tId}. Your code is: {Token}</Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="de">
		<Message>Bitte authentifizieren Sie sich für den Zugriff auf die Dokumentenmappe der Transaktion {tId}. Ihre TAN lautet: {Token}</Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="it">
		<Message>Con riferimento alla transazione {tId}, per autenticarsi si prega di inserire il seguente CODICE {Token}</Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText">
		<Message>Please confirm the issuance of your disposable certificate and signature, referenced by transactionId {tId}, with the OTP: </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="en">
		<Message>Please confirm the issuance of your disposable certificate and signature, referenced by transactionId {tId}, with the OTP: </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="de">
		<Message>Bitte bestätigen Sie die Ausstellung des Einwegzertifikats und die Signatur, referenziert durch die TransaktionsID {tId}, mit dem Einmalpasswort: </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="it">
		<Message>Conferma l'emissione del tuo certificato disposable, con riferimento alla transazione {tId}, e della firma con l´OTP </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText">
		<Message>Please sign the document, referenced by transactionId {tId}, using the OTP: </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="en">
		<Message>Please sign the document, referenced by transactionId {tId}, using the OTP: </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="de">
		<Message>Bitte signieren Sie das Dokument, referenziert durch die Transaktions {tId}, mit dem Einmalpasswort: </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="it">
		<Message>Firma il documento, con riferimento alla transazione {tId}, usando l´OTP </Message>
		<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
	  </TransactionCodeConfiguration>
	</TransactionCodeConfigurations>
  </workstepConfiguration>
  <steps>
	<step>
	  <emailBodyExtra></emailBodyExtra>
	  <orderIndex>1</orderIndex>
	  <recipientType>Signer</recipientType>
	  <workstepConfiguration skipThirdPartyChecks="0">
		<WorkstepLabel />
		<SmallTextZoomFactorPercent>100</SmallTextZoomFactorPercent>
		<WorkstepTimeToLiveInMinutes>10</WorkstepTimeToLiveInMinutes>
		<FinishAction />
		<PictureAnnotationTaskInfo>
		  <MinResolution>100</MinResolution>
		  <MaxResolution>300</MaxResolution>
		  <ColorDepth>Color16M</ColorDepth>
		</PictureAnnotationTaskInfo>
		<ViewerPreferences>
		  <SendVisibleArea allowedDomain="*">0</SendVisibleArea>
		</ViewerPreferences>
		<Policy version="1.1.0.0">
		  <GeneralPolicies>
			<AllowSaveDocument>1</AllowSaveDocument>
			<AllowSaveAuditTrail>0</AllowSaveAuditTrail>
			<AllowRotatingPages>1</AllowRotatingPages>
			<AllowAppendFileToWorkstep>0</AllowAppendFileToWorkstep>
			<AllowAppendTasksToWorkstep>0</AllowAppendTasksToWorkstep>
			<AllowEmailDocument>0</AllowEmailDocument>
			<AllowPrintDocument>0</AllowPrintDocument>
			<AllowFinishWorkstep>1</AllowFinishWorkstep>
			<AllowRejectWorkstep>1</AllowRejectWorkstep>
			<AllowRejectWorkstepDelegation>0</AllowRejectWorkstepDelegation>
			<AllowUndoLastAction>1</AllowUndoLastAction>
			<AllowColorizePdfForms>0</AllowColorizePdfForms>
			<AllowAdhocPdfAttachments>1</AllowAdhocPdfAttachments>
			<AllowAdhocSignatures>1</AllowAdhocSignatures>
			<AllowAdhocStampings>1</AllowAdhocStampings>
			<AllowAdhocFreeHandAnnotations>1</AllowAdhocFreeHandAnnotations>
			<AllowAdhocTypewriterAnnotations>1</AllowAdhocTypewriterAnnotations>
			<AllowAdhocPictureAnnotations>0</AllowAdhocPictureAnnotations>
			<AllowAdhocPdfPageAppending>1</AllowAdhocPdfPageAppending>
		  </GeneralPolicies>
		  <AdhocPolicies>
			<AllowModificationsAfterSignature>1</AllowModificationsAfterSignature>
		  </AdhocPolicies>
		  <WorkstepTasks originalSequenceMode="NoSequenceEnforced" SequenceMode="NoSequenceEnforced">
			<Task id="c38ec7f8-5145-4cb6-8b34-500ee45f5a92" DocRefNumber="1" enabled="1" completed="0" type="FillFormsGroup" required="1" displayName="" />
			<Task type="SignField" DocRefNumber="1" id="1#XyzmoDuplicateIdSeperator#sigField1" internalCompleted="0" finishPercentage="0" completed="0" enabled="1" displayName="Signature 1" required="1" />
		  </WorkstepTasks>
		</Policy>
		<timeCreated>2018-01-24T08:07:46.0787271Z</timeCreated>
		<signaturePluginConfiguration>
				<PdfSignatureProperties_V1>
					<PdfAConformant>0</PdfAConformant>
					<PAdESPart4Compliant>0</PAdESPart4Compliant>
					<IncludeSigningCertificateChain>0</IncludeSigningCertificateChain>
					<SigningCertificateRevocationInformationIncludeMode>DoNotInclude</SigningCertificateRevocationInformationIncludeMode>
				</PdfSignatureProperties_V1>
				<PdfSignatureCryptographicData_V1>
					<SignatureHashAlgorithm>Sha1</SignatureHashAlgorithm>
					<SigningCertificateDescriptor>
						<Identifier>DDED02DC192573B722E8C027F0E47E63152EB822</Identifier>
						<Type>Sha1Thumbprint</Type>
						<Csp>Default</Csp>
					</SigningCertificateDescriptor>
				</PdfSignatureCryptographicData_V1>
			</signaturePluginConfiguration>
		<TransactionCodeConfigurations>
		  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId">
			<!--Message used to send a transaction code to the client. The message has to contain the placeholder '{tId}' for the transactionId and the placeholder '{Token}' for the token.-->
			<Message>Please authenticate yourself for the access to the envelope with the transactionId {tId}. Your code is: {Token}</Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="en">
			<Message>Please authenticate yourself for the access to the envelope with the transactionId {tId}. Your code is: {Token}</Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="de">
			<Message>Bitte authentifizieren Sie sich für den Zugriff auf die Dokumentenmappe der Transaktion {tId}. Ihre TAN lautet: {Token}</Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="it">
			<Message>Con riferimento alla transazione {tId}, per autenticarsi si prega di inserire il seguente CODICE {Token}</Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText">
			<Message>Please confirm the issuance of your disposable certificate and signature, referenced by transactionId {tId}, with the OTP: </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="en">
			<Message>Please confirm the issuance of your disposable certificate and signature, referenced by transactionId {tId}, with the OTP: </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="de">
			<Message>Bitte bestätigen Sie die Ausstellung des Einwegzertifikats und die Signatur, referenziert durch die TransaktionsID {tId}, mit dem Einmalpasswort: </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="it">
			<Message>Conferma l'emissione del tuo certificato disposable, con riferimento alla transazione {tId}, e della firma con l´OTP </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText">
			<Message>Please sign the document, referenced by transactionId {tId}, using the OTP: </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="en">
			<Message>Please sign the document, referenced by transactionId {tId}, using the OTP: </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="de">
			<Message>Bitte signieren Sie das Dokument, referenziert durch die Transaktions {tId}, mit dem Einmalpasswort: </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		  <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="it">
			<Message>Firma il documento, con riferimento alla transazione {tId}, usando l´OTP </Message>
			<hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
		  </TransactionCodeConfiguration>
		</TransactionCodeConfigurations>
		<pdfForms isEditingAllowed="0">
		  <pdfFormsGroup id="c38ec7f8-5145-4cb6-8b34-500ee45f5a92">
			<checkBox id="chk1">
			  <DocRefNumber>1</DocRefNumber>
			  <isRequired>1</isRequired>
			  <positionPage>1</positionPage>
			  <positionX>71</positionX>
			  <positionY>615</positionY>
			  <width>10</width>
			  <height>10</height>
			</checkBox>
		  </pdfFormsGroup>
		</pdfForms>
		<TypewriterAnnotationTaskInfo />
		<attachmentFields />
		<signatureTemplate>
		  <version>1.2.0.2</version>
		  <positionReferenceCorner>Lower_Left</positionReferenceCorner>
		  <positionUnits>PdfUnits</positionUnits>
		  <sig id="1#XyzmoDuplicateIdSeperator#sigField1">
			<TaskDisplayName>Signature 1</TaskDisplayName>
			<positionPage>1</positionPage>
			<DocRefNumber>1</DocRefNumber>
			<positionX>70.8239974975586</positionX>
			<positionY>492.220001220703</positionY>
			<width>100</width>
			<height>30</height>
			<param name="completed">0</param>
			<param name="positioning">onPage</param>
			<param name="req">1</param>
			<param name="enabled">1</param>
			<param name="fd" />
			<AllowedSignatureTypes>
			  <sigType id="8511412a-13d5-4860-acaf-dced4a9762ee" type="Picture">
				<allowedCapturingMethods>Click2Sign</allowedCapturingMethods>
			  </sigType>
			</AllowedSignatureTypes>
		  </sig>
		</signatureTemplate>
	  </workstepConfiguration>
	  <recipients>
		<recipient>
		  <eMail>placeholder1@placeholder1.com</eMail>
		  <emailBodyExtra></emailBodyExtra>
		  <firstName>placeholder1</firstName>
		  <lastName>placeholder1</lastName>
		  <languageCode>en</languageCode>
		  <disableEmail>false</disableEmail>
		  <skipExternalDataValidation>false</skipExternalDataValidation>
		  <addAndroidAppLink>false</addAndroidAppLink>
		  <addIosAppLink>false</addIosAppLink>
		  <addWindowsAppLink>false</addWindowsAppLink>
		  <allowDelegation>false</allowDelegation>
		  <authentications />
		</recipient>
	  </recipients>
	</step>
  </steps>
  <addFormFields>
	<document docRef="1">
	  <checkBox name="chk1" readOnly="false" required="true" x="70.8239974975586" y="615.25" width="10" height="10" page="1">
		<isChecked>false</isChecked>
	  </checkBox>
	</document>
  </addFormFields>
</prepareSendEnvelopeStepsResult>

4. Envelope XML

Based on the result of the prepareSendEnvelope call you can easily build your request for SendEnvelope and extend it (e.g. with authentication for recipients). See the How To Package for details.

TIP: for checkboxes there a  parameter available to allow only checked-status of the checkbox to finish the document. Therefore, you force a customer to check it for finishing the document. The download-example have in the SendEnvelope the value set to IsChecked to force a checked checkbox.

Workstepconfiguration parameter for forcing a checked checkbox on finishing of the document.

<workstepconfiguration>
  ..
  <pdfForms>
    ..
    <pdfFormGroups>
      ..
      <checkBox>
        ..
        <!--Defines how a required Checkbox should be evaluated. 
            Possible values: 'None': no check is done; 'IsChecked': The checkbox
            has to be checked-->
        <requiredEvalPolicy>IsChecked</requiredEvalPolicy>
        ..
      </checkBox>
    </pdfFormGroups>
  </pdfForms>
</workstepconfiguration>

Reading Tasks

Reading Tasks can be defined in the workstepConfiguration of an envelope. With the reading task a recipient must confirm reading of the document to have the evidence that he/she was reading it.

You have to create a Task (workstepConfiguration\Policy\WorkstepTasks\Task) and the Reading-Task itself.

Step 1: Set in the WorkstepConfiguration (for a recipient) the following Task (in workstepConfiguration\Policy\WorkstepTasks):

<Task enabled="1" completed="0" required="1" id="847a3d4a-da2c-46f4-8c8c-a9edaa06c29b" displayName="your text for this task" DocRefNumber="1" type="ConfirmReading" />

The task must be the first and required!

Step 2: Then you have to create the ReadingTaskInfo (directly in the WorkstepConfiguration) with attribute AllDocuments=”1″:

<ReadingTaskInfo positionUnit="PdfUnits" positionReferenceCorner="Upper_Left">
	<ReadingTask id="847a3d4a-da2c-46f4-8c8c-a9edaa06c29b" pageNumber="1" DocRefNumber="1" AllPages="0" AllDocuments="1" />
</ReadingTaskInfo>

Audit Trail XML Structure

Structure

The following sample shows the structure of the audit trail xml:

<?xml version="1.0" encoding="utf-8"?>
<AuditTrail Version="1" CreationDate="2018-10-01T13:07:21.2795797Z">
  <EnvelopeId>[Envelope ID]</EnvelopeId>
  <EnvelopeName>[Envelope Name]</EnvelopeName>
  <EnvelopeStatus>[Envelope Status - possible values: Completed]</EnvelopeStatus> <!-- note: at the moment, the Audit Trail is only generated for completed envelopes -->
  <EnvelopeCreationDate>[Create Date, e.g. 2018-10-01T13:05:10.927Z]</EnvelopeCreationDate>
  <EnvelopeSendDate>[Send Date, e.g. 2018-10-01T13:06:21.13Z]</EnvelopeSendDate>
  <EnvelopeExpirationDate>[Expiration Date, e.g. 2018-10-29T13:06:21.13Z]</EnvelopeExpirationDate>
  <Sender>
    <FirstName>[Sender First Name]</FirstName>
    <LastName>[Sender Last Name]</LastName>
    <EMail>[Sender E-Mail]</EMail>
  </Sender>
  <ElectronicDisclosures>
    <!-- list of "Disclosure" elements (see below) -->
  </ElectronicDisclosures>
  <Recipients>
    <!-- list of "Recipient" elements (see below) -->
  </Recipients>
  <Notifications>
    <!-- list of "Notification" elements (see below) -->
  </Notifications>
  <SendFinishedDocuments>[true|false]</SendFinishedDocuments> 
  <PreventMailSending>[true|false]</PreventMailSending>
</AuditTrail>

Electronic Disclosures

<Disclosure Culture="[language ISO code, e.g. de, de-AT]">
  <Subject>[Message Subject]</Subject>
  <Text>[Message Body]</Text>
</Disclosure>

Recipients

General
<Recipient Id="[Recipient ID]" OrderIndex="[Recipient OrderIndex]" EMail="[Recipient E-Mail]" Deleted="[true|false]">
  <FirstName>[Recipient FirstName]</FirstName>
  <SealingProfileName />
  <LastName>[Recipient LastName]</LastName>
  <Type>[Recipient Type, possible values see below]</Type>
  <FinishDate>[Finish Date, e.g. 2018-10-01T14:01:32.6354943Z]</FinishDate>
  <Status>[Recipient Status, possible values see below]</Status>
  <RejectReason>[Reject/Delegate reason]</RejectReason>
  <WorkstepId>[Workstep ID]</WorkstepId>
  <History>
    <!-- list of "Entry" elements (see below) - info about previous changes of this recipients -->
  </History>
  <AuthenticationMethods>
    <!-- list of "AuthenticationMethod" elements (see below) -->
  </AuthenticationMethods>
  <MailSubject>[Mail Message Subject]<MailSubject>
  <MailContent>[Mail Message Content]<MailContent>
  <DelegatorId>[OPTIONAL: Recipient ID of the delegator recipient]</DelegatorId>
  <DelegateeId>[OPTIONAL: Recipient ID of the delegatee recipient]</DelegateeId>
  <WorkStepInformation><!-- OPTIONAL: Workstep Information XML - details see below --></WorkStepInformation>
  <auditTrail><!-- OPTIONAL: Workstep Audit Trail XML - details see below --></auditTrail>
  <PreventMailSending>[true|false]</PreventMailSending>
</Recipient>

Values for Type:

  • Signer
  • CC
  • Acknowledge
  • Pkcs7Signer
  • Automatic

Values for Status

  • NotSigned
  • Signed
  • Rejected
  • Delegated
  • DelegatedAutomated
History
<Entry ValidFrom="[When was this recipient setting valid? e.g. 2018-10-01T14:00:41.54Z]" ValidTo="[When was this recipient setting valid? e.g. 9999-12-31T23:59:59.9999999Z]">
  <FirstName>[FirstName]</FirstName>
  <LastName>[LastName]</LastName>
  <EMail>[E-Mail]</EMail>
  <Modifications>
    <!-- List of "Modification" elements -->
    <Modification>[Modification]</Modification>
  </Modifications>
</Entry>

Values for Modification:

  • RenameEmail
  • RenameRecipientName
  • RestartEnvelope
  • RenameRecipientFirstName
  • RenameRecipientLastName
  • RenameRecipientMessage
  • ChangeAuthenticationSms
  • ChangeAuthenticationLive
  • ChangeAuthenticationPin
  • AddedAuthenticationSms
  • AddedAuthenticationLive
  • AddedAuthenticationPin
  • RemovedAuthenticationSms
  • RemovedAuthenticationLive
  • RemovedAuthenticationPin
  • ChangeRecipientCulture
  • ChangedRecipientDisposableCertificateData
  • ChangedRecipientRemoteSignatureData
  • ChangeAuthenticationOAuth
  • AddedAuthenticationOAuth
  • RemovedAuthenticationOAuth
  • RecipientDeleted
  • ChangeAuthenticationSaml
  • AddedAuthenticationSaml
  • RemovedAuthenticationSaml
  • ChangedRecipientOtpSignatureData
  • ChangedRecipientPkcs7SignerData
  • ChangedRecipientSwissComCertificateData
Authentication
<AuthenticationMethod>[Authentication Method]</AuthenticationMethod>

Values for AuthenticationMethod:

  • Pin
  • Sms
  • WindowsLive
  • CustomOAuthProvider
  • CustomSamlProvider

Notifications

<Notification Type="[Notification Type - possible values see below]" Added="[Added Date, e.g. 2018-10-01T14:01:32.6354943Z]" Sent="[Added Date, e.g. 2018-10-01T14:01:32.6354943Z]" Recipient="[OPTIONAL - Recipient ID">
  <ExtraInformation />
</Notification>

Values for Type

  • SendSignNotificationToRecipient
  • SendAcknowledgeNotificationToRecipient
  • RecipientChanged
  • EnvelopeFinished
  • SendCcDocs
  • SendCcDocsWithDownloadLink
  • SendCcDocsNoLink
  • SendCcDocsNoLinkWithDownloadLink
  • EnvelopeParallelSigned
  • DelegationAutomatic
  • DelegationManual
  • SendSignNotificationToRecipientWithDelegation,
  • AutomatedDelegationNotification