| Info | ||
|---|---|---|
| ||
Please note that we announced deprecation of the SOAP API already a while ago in the product release notes. This documentation is therefore marked as DEPRECATED. Nevertheless, the content and structure explained on this page is more or less valid also for the REST API, in REST API Versions v1-v5 even if the format changed from XML to JSON. |
The Envelope XML Guide contains all information about how you can create envelopes with SOAP. Beside the information about how to configure different electronic signature types (e.g. Click2Sign, Draw2Sign) with SOAP, this guide also shows how to configure authentication methods with XML page will teach you about the envelope XML for eSignAnyWhere.
| Table of Contents | ||||
|---|---|---|---|---|
|
Envelope Structure
The envelope XML contains all information about an envelopenecessary for sending out a workflow to different signers or other types of recipients. Basically it consists of the envelope definition and the workflow. The documents itself are not included but referenced. The workflow itself exists of steps and within the steps of the recipients. Signing recipients have to have the workstep configuration. The workstep configuration is the definition of the signing task.
configuration is the definition of the signing task.
The following table shows the different icons for the document status with explanation:
Hello World Tutorial – Envelope XML
| Info | ||
|---|---|---|
| ||
This chapter requires rework. The examples below explain the Envelope XML of the (deprecated) SOAP API. Comparable content and structures apply also for the Envelope JSON structure, which is used in REST API integration scenarios. |
The next lines of code shows
...
the basic structure of the envelope XML:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<envelope>
<!-- META information for envelope: e.g.: Name, eMailSubject, Reminders, Expiration, CallbackURL etc. -->
<steps>
<step>
<!-- Step x in Workflow: Information about recipient(s) and Workstep Configuration -->
<workstepConfiguration />
</step>
<step>
<!-- next step in workflow -->
<workstepConfiguration />
</step>
</steps>
</envelope> |
The following table shows the different icons for the document status with explanation:
Hello World Tutorial – Envelope XML
| Info | ||
|---|---|---|
| ||
This chapter requires rework. The examples below explain the Envelope XML of the (deprecated) SOAP API. Comparable content and structures apply also for the Envelope JSON structure, which is used in REST API integration scenarios. <!-- next step in workflow -->
<workstepConfiguration />
</step>
</steps>
</envelope> |
Let’s have a look at the Hello World Tutorial envelope XML. You can download the XML here.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<envelope>
<name>test</name>
<eMailSubject>Please sign the enclosed envelope</eMailSubject>
<eMailBody>Dear #RecipientFirstName# #RecipientLastName#
#PersonalMessage#
Please sign the envelope #EnvelopeName#
Envelope will expire at #ExpirationDate#</eMailBody>
<enableReminders>true</enableReminders>
<firstReminderDayAmount>5</firstReminderDayAmount>
<recurrentReminderDayAmount>3</recurrentReminderDayAmount>
<beforeExpirationReminderDayAmount>3</beforeExpirationReminderDayAmount>
<daysUntilExpire>28</daysUntilExpire>
<callbackUrl></callbackUrl>
<metaData>Your meta data</metaData>
<statusUpdateCallbackUrl></statusUpdateCallbackUrl>
<displayedEmailSender></displayedEmailSender>
<steps>
<step>
<emailBodyExtra></emailBodyExtra>
<orderIndex>1</orderIndex>
<recipientType>Signer</recipientType>
<useDefaultAgreements>true</useDefaultAgreements>
<documentOptions>
<documentOption docRef="1">
<isHidden>false</isHidden>
</documentOption>
</documentOptions>
<workstepConfiguration skipThirdPartyChecks="0">
<WorkstepLabel>test</WorkstepLabel>
<SmallTextZoomFactorPercent>100</SmallTextZoomFactorPercent>
<WorkstepTimeToLiveInMinutes>43210</WorkstepTimeToLiveInMinutes>
<FinishAction />
<ViewerPreferences>
<SendVisibleArea allowedDomain="*">0</SendVisibleArea>
<FinishWorkstepOnOpen>0</FinishWorkstepOnOpen>
</ViewerPreferences>
<Policy version="1.1.0.0">
<AdhocPolicies>
<AllowModificationsAfterSignature>1</AllowModificationsAfterSignature>
</AdhocPolicies>
<GeneralPolicies>
<AllowAdhocFreeHandAnnotations>0</AllowAdhocFreeHandAnnotations>
<AllowAdhocPdfAttachments>0</AllowAdhocPdfAttachments>
<AllowAdhocPdfPageAppending>0</AllowAdhocPdfPageAppending>
<AllowAdhocPictureAnnotations>0</AllowAdhocPictureAnnotations>
<AllowAdhocSignatures>0</AllowAdhocSignatures>
<AllowAdhocStampings>0</AllowAdhocStampings>
<AllowAdhocTypewriterAnnotations>0</AllowAdhocTypewriterAnnotations>
<AllowEmailDocument>1</AllowEmailDocument>
<AllowFinishWorkstep>1</AllowFinishWorkstep>
<AllowPrintDocument>1</AllowPrintDocument>
<AllowRejectWorkstep>1</AllowRejectWorkstep>
<AllowSaveAuditTrail>1</AllowSaveAuditTrail>
<AllowSaveDocument>1</AllowSaveDocument>
<AllowUndoLastAction>1</AllowUndoLastAction>
<AllowRotatingPages>0</AllowRotatingPages>
<AllowRejectWorkstepDelegation>1</AllowRejectWorkstepDelegation>
</GeneralPolicies>
<WorkstepTasks originalSequenceMode="NoSequenceEnforced" SequenceMode="NoSequenceEnforced">
<Task type="SignField" DocRefNumber="1" id="1#XyzmoDuplicateIdSeperator#Signature_36cff3f5-38b2-cc21-a467-713e8bb2de18" internalCompleted="0" finishPercentage="0" completed="0" enabled="1" displayName="" required="1" />
</WorkstepTasks>
</Policy>
<timeCreated>2019-09-24T09:56:35.5231387Z</timeCreated>
<TransactionCodeConfigurations>
<TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId">
</TransactionCodeConfiguration>
</TransactionCodeConfigurations>
<receiverInformation>
<userInformation>
<firstName>Charly</firstName>
<lastName>Xyzmo</lastName>
<eMail>##EMAIL##</eMail>
</userInformation>
<showNamirialDisposableDisclaimer>1</showNamirialDisposableDisclaimer>
</receiverInformation>
<senderInformation>
<userInformation>
<firstName>Charly</firstName>
<lastName>Xyzmo</lastName>
<eMail>##EMAIL##</eMail>
</userInformation>
</senderInformation>
<pdfForms isEditingAllowed="0" />
<TypewriterAnnotationTaskInfo />
<attachmentFields />
<signatureTemplate>
<version>1.2.0.2</version>
<positionReferenceCorner>Lower_Left</positionReferenceCorner>
<positionUnits>PdfUnits</positionUnits>
<sig id="1#XyzmoDuplicateIdSeperator#Signature_36cff3f5-38b2-cc21-a467-713e8bb2de18">
<TaskDisplayName />
<param name="enabled">1</param>
<positionPage>1</positionPage>
<positionX>72</positionX>
<positionY>525.92</positionY>
<width>190</width>
<height>80</height>
<param name="positioning">onPage</param>
<param name="req">1</param>
<param name="fd" />
<param name="fd_dateformat">dd-MM-yyyy HH:mm:ss</param>
<param name="fd_timezone">datetimeutc</param>
<DocRefNumber>1</DocRefNumber>
<AllowedSignatureTypes>
<sigType id="9e0e5ea9-2ba0-4769-84dc-fe7b20b134a5" type="Picture">
<allowedCapturingMethods>Click2Sign</allowedCapturingMethods>
<StampImprintConfiguration>
<DisplayExtraInformation>1</DisplayExtraInformation>
<DisplayEmail>1</DisplayEmail>
<DisplayIp>1</DisplayIp>
<DisplayName>1</DisplayName>
<DisplaySignatureDate>1</DisplaySignatureDate>
<FontFamily>Times New Roman</FontFamily>
<FontSize>11</FontSize>
</StampImprintConfiguration>
</sigType>
</AllowedSignatureTypes>
</sig>
</signatureTemplate>
<resourceUris>
<signatureImagesUri>https://demo.xyzmo.com//Resource/SignatureImages/?link=1VcbZC4rhfQ0vfJ~XelpnshMFFPCcKU6sOGw6EeLE1KvNaOBF1j8A1PC7mUq21moG</signatureImagesUri>
<delegationUri>https://demo.xyzmo.com//Resource/Delegate</delegationUri>
</resourceUris>
<AuditingToolsConfiguration WriteAuditTrail="0">
<NotificationConfiguration />
</AuditingToolsConfiguration>
<LoggingMetaInformation>
<envelopeId>e841898d-9bba-48c7-b3c5-4e057a77089a</envelopeId>
<envelopeRecipientId>4c1a2900-5b4b-49b2-906a-f50f5daeea18</envelopeRecipientId>
</LoggingMetaInformation>
</workstepConfiguration>
<recipients>
<recipient>
<eMail>##EMAIL##</eMail>
<emailBodyExtra></emailBodyExtra>
<firstName>Charly</firstName>
<lastName>Xyzmo</lastName>
<languageCode>en</languageCode>
<disableEmail>false</disableEmail>
<skipExternalDataValidation>false</skipExternalDataValidation>
<addAndroidAppLink>false</addAndroidAppLink>
<addIosAppLink>false</addIosAppLink>
<addWindowsAppLink>false</addWindowsAppLink>
<allowDelegation>true</allowDelegation>
<authentications />
</recipient>
</recipients>
</step>
<step>
<emailBodyExtra></emailBodyExtra>
<orderIndex>2</orderIndex>
<recipientType>Cc</recipientType>
<useDefaultAgreements>false</useDefaultAgreements>
<recipients>
<recipient>
<eMail>##EMAIL##</eMail>
<emailBodyExtra></emailBodyExtra>
<firstName>Charly</firstName>
<lastName>Xyzmo</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>
<attachSignedDocumentsToEnvelopeLog>false</attachSignedDocumentsToEnvelopeLog>
</envelope> |
...
- Name of the envelope (name)
- E-Mail Subject
- E-Mail Body: the message for the signers email (see Email Templating for more details and the available tags).
- Reminders and expiration
- enableReminders: if set to false, no reminders will be sent at all
- firstReminderDayAmount: an active recipient will retrieve a 1st notification after the defined amount of days. Values: 1 to (daysUntilExpire – 1)
- recurrentReminderDayAmount: an active recipient will retrieve a recurring notification after the first notification every configured days. Values: 1 to (daysUntilExpire – 1)
- beforeExpirationReminderDayAmount:an active recipient will retrieve a notification on the configured days before expiration. Values: positive integer
- daysUntilExpire: If the envelope isn’t finished or rejected within the defined amount of days, the envelope will expire. Values: 1 to _global.xml ‘maxEnvelopeValidityInDays’ setting (default: 28)
- Callback URL is fired when the envelope is finished (this means successfully finished & signed or by a recipient rejected). So you can notify your integrating system and get the information which envelope is finished (placeholder for envelope id is ##EnvelopeId##). If you want to listen to events within the workflow use the workstep-callbacks.
Attention: if the callback URL doesn’t return a HTTP 200 the envelope goes into an error state is will not be finished! eSAW tries to call the URL until it gets a HTTP 200 or reaches the limit of callback-attempts (30). - The meta data element allows you to store additional, non-eSAW-data (e.g. for archiving) directly in the envelope. You can retrieve this information via
getEnvelopeByIdcall. An example of metaData is to store data for the archiving system in the envelope. The callback-integrating solution then can download the files (PDF & Audit-Trail) and store them directly in the archive. - DisplayedEmailSender Configuration: If the displayedEmailSender is empty only eSignAnywhere is used. If the field is not empty, this text will be used before ” via eSignAnywhere”. Without displayedEmailSender the organization default setting is used. On-Premise or private SaaS allows to modify “via eSignAnywhere” text.
- attachSignedDocumentsToEnvelopeLog allows to add the final & signed document to the audit trail. Per default this feature is disabled. Note: this requires eSAW 3.4+
...
There are many ways how to make a workstep configuration. The following list shows some options:
- Developer mode (Visit the guide)
- Workstep designer
- Create your own configuration
- GetAdHocWorkstepConfiguration
- Place advanced tags
...
For more information please have a look at the developer mode guide.
Workstep Designer
| Info | ||
|---|---|---|
| ||
The workstep designer is a tool for developers only. It is usually not available on production environments, but can be used on our demo environment and on-premise staging environments. |
With the workstep designer you can add fields, authentications, viewer preferences, general policies and more. Following steps guide you through the process of using the workstep designer:
...
You can also watch the following video which shows the process from the beginning.
| Multimedia | ||||||
|---|---|---|---|---|---|---|
|
Create your own configuration
...
Another way to prepare the workstep is to use signature field placeholder (‘sig’) or advanced tags in the document. For signature field placeholders you need to get the AdHocWorkstepConfiguration via API (GetAdHocWorkstepConfiguration_v1) and for advanced tags you have first to perform a prepare call (PrepareSendEnvelopeSteps_v1). An alternative is to use the Workstep Designer. The workstep designer can help you creating a workstep xml and you can directly try it in the SignAnyWhere Viewer (the eSignAnyWhere default signing client).
...
Input Validation for Form Fields 
In the workstep configuration you can define (since version 3.1) a form field valdiation for text fields.
...