The Envelope XML
SOAP API is deprecated
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.
See Api Reference - Introduction REST for the REST API reference which should be considered as the successor of the SOAP API.
Repeating here also how SOAP discontinuation was published in the release notes:
We declared SOAP as deprecated and therefore SOAP will not be included in versions after 21.76 (already postponed by one year, initially the 20.76 was announced). Latest release including SOAP API for eSAW will be 21.76, released in spring 2022 and with the software maintenance on 21.76 until spring 2024.
Therefore, we recommend REST technology for integration. Please see also the migration guide.
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.
Envelope Structure
The envelope contains all information necessary 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.
The following table shows the different icons for the document status with explanation:
Hello World Tutorial – Envelope XML
Requires Rework
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:
<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>
Let’s have a look at the Hello World Tutorial envelope XML. You can download the XML here.
<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>
Envelope Section
The Envelope Section contains the configuration of the envelope.
The example configures the following settings:
- 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
getEnvelopeById
call. 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+
Following collapse contains an example of an envelope section.
<name>eSignAnyWhere Tutorial</name> <eMailSubject>Hello World</eMailSubject> <eMailBody>Dear #RecipientFirstName#! Please sign this document.</eMailBody> <enableReminders>True</enableReminders> <firstReminderDayAmount>1</firstReminderDayAmount> <recurrentReminderDayAmount>1</recurrentReminderDayAmount> <beforeExpirationReminderDayAmount>1</beforeExpirationReminderDayAmount> <daysUntilExpire>2</daysUntilExpire> <!-- callback to your backend system on a completed envelope <callbackUrl>http://172.16.17.78:57550/default.aspx?EnvelopeId=##EnvelopeId##&myParamForMe=1234</callbackUrl> --> <callbackUrl /> <metaData>Your meta data</metaData> <displayedEmailSender></displayedEmailSender> <attachSignedDocumentsToEnvelopeLog>1</attachSignedDocumentsToEnvelopeLog>
Step(s) Section
The step(s) section is defining the workflow. You can define steps (with the order-index) and its recipients (at least one recipient, parallel recipients are supported).
<steps> <step> <!-- Step x in Workflow: Information about recipient(s) and Workstep Configuration --> <workstepConfiguration /> </step> <step> <!-- next step in workflow --> <workstepConfiguration /> </step> </steps>
Recipient Configuration within a Step
Example of a simple step (one recipient as signer with empty workstep configuration; see section about workstep configuration for more details):
<step> <emailBodyExtra /> <orderIndex>1</orderIndex> <recipientType>Signer</recipientType> <recipients> <recipient> <languageCode>en-us</languageCode> <eMail>first.signer@email.com</eMail> <firstName>First</firstName> <lastName>Signer</lastName> <allowDelegation>True</allowDelegation> <!-- No notification will be sent if set to True use this in case you want to integrate this step into a portal or handle this step with another product (Kiosk, iOS/Android/Windows Phone App --> <disableEmail>False</disableEmail> <!-- optional authentication methods for this recipient --> </recipient> </recipients> <workstepConfiguration /> </step>
The following parts are configured in this example:
- emailBodyExtra
- Order index in workflow
- Recipient Type (Signer, CC, Acknowledge)
- Recipient Data (Language, E-Mail, Firstname, Lastname, Delegation, Authentication)
- Workstep configuration to define the signing task
Authentication
There are different authentications available. In this section the PIN and the SMS authentication are explained:
<authentications> <authentication> <method>Pin</method> <parameter>4812</parameter> </authentication> <authentication> <method>SMS</method> <parameter>+43664123456789</parameter> </authentication> </authentications>
You can copy paste the authentication within the recipient tag. Following lines of code shows the place for the authentication:
<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> <authentication> <method>Sms</method> <parameter>+43664123456789</parameter> </authentication> <authentication> <method>Pin</method> <parameter>1234</parameter> </authentication> </authentications> </recipient> </recipients>
To configure a OAuth2/SAML Authentication you can additionally use checks (eSAW 2.6+) to force a specific user to authenticate.
<authentications> <authentication> <!-- CustomAuthenticationProvider will be mapped to GenericOAuthProvider --> <method>CustomAuthenticationProvider</method> <parameter>nameofprovider</parameter> <checks> <check compareOperation="equals" fieldId="userprofile" value="a232656-6656-5665"></check> </checks> </authentication> <authentication> <method>CustomOAuthProvider</method> <parameter>nameofprovider</parameter> <checks> <check compareOperation="equals" fieldId="useremail" value="jordan@xyzmo.com"></check> <check compareOperation="equals" fieldId="userprofile" value="a232336-6656-5665"></check> </checks> </authentication> </authentications>
Hide Specific Documents
To configure the visibility of documents you first have to upload at least two documents. Therefor, upload two documents with the API call UploadTemporarySspFile_v1 to get two document Ids. After this API call you have to add the document Ids to the API call SendEnvelope_v1:
<esig:sspFileIds> <esig:string>First document</esig:string> <esig:string>Second document</esig:string> </esig:sspFileIds>
After adding the documents you can now configure the visibility of the documents.
API Configuration is done via envelope/steps/step/documentOption; Sample:
<envelope> ... <steps> <step> <emailBodyExtra> </emailBodyExtra> <orderIndex>1</orderIndex> <documentOptions> <documentOption docRef="1"> <isHidden>1</isHidden> </documentOption> <documentOption docRef="2"> <isHidden>1</isHidden> </documentOption> </documentOptions> <useDefaultAgreements>true</useDefaultAgreements> <recipientType>Signer</recipientType> <workstepConfiguration>...</workstepConfiguration> <recipients> <recipient> <eMail>next@recipient.domain</eMail> ... </recipient> </recipients> </step> </steps> </envelope>
This feature is not available in all subscriptions.
Disposable Certificate Additional Information
If you want to use the disposable certificate you have to add additional information for the recipient:
<recipient> ... <disposableCertificateAdditionalInformation> <countryResidence>IT</countryResidence> <phoneMobile>+39XXXXXXXXXX</phoneMobile> <documentType>CI</documentType> <documentIssuedBy>Comune di XXXXXXXXX</documentIssuedBy> <documentIssuedOn>20XX-XX-01T00:00:00Z</documentIssuedOn> <documentExpiryDate>20XX-XX-30T00:00:00Z</documentExpiryDate> <serialNumber>XXXXXXXXXXXXXXXX</serialNumber> <identificationType>FOREIGN_TAX_CODE</identificationType> <identificationCountry>IT</identificationCountry> <documentNumber>XXXXXXXXXXXXX</documentNumber> </disposableCertificateAdditionalInformation> <recipient>
Workstep Configuration
The workstep configuration is the most tricky part for an integration.
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
Developer mode
To allow you to generate these, sometimes quite complex configuration, we created the Developer Mode. The Developer Mode allows you to use eSignAnyWhere as a “configuration builder”. This means you create your desired workflow with the eSignAnyWhere User Interface (upload document, define recipients, define signature and form fields, etc.) and download its configuration. So eSAW is generating the configuration for your via UI created workflow. Therefor, you do not have to know each step in the configuration and how it is build. Example: If you want to configure a signature field on your document you can first add it on a document in the SAW Viewer and then download the configuration and add the signature in your workstep configuration.
For more information please have a look at the developer mode guide.
Workstep Designer
Availability of Workstep Designer
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:
- Open the workstep designer
- Select SignAnyWhere
- Start designing
- Create your workstep and finish it with the button “Save configuration”
Following Screenshots show you these steps:
Figure | Description |
---|---|
|
Figure | Description |
---|---|
|
You can also watch the following video which shows the process from the beginning.
Create your own configuration
You can also start with an empty workstep configuration and add those elements which you want. The next lines of code shows an example of an empty workstep configuration.
<WorkstepConfiguration> <pdfForms isEditingAllowed="1"> <pdfFormsGroup id="formFilling1"> </pdfFormsGroup> </pdfForms> <signatureTemplate></signatureTemplate> <signaturePluginConfiguration /> <FinishAction /> <Policy version="1.0.0.2"> <GeneralPolicies /> <WorkstepTasks></WorkstepTasks> </Policy> </WorkstepConfiguration>
Signature
First you have to add the signature field in the signature template. You can copy paste the following code and replace the ##Placeholder## with the following signature configurations in the following section:
<signatureTemplate>##Placeholder##</signatureTemplate>
The following collapses shows examples of signature configurations (Click2Sign, Draw2Sign, Type2Sign and biometric signature):
After you have added the signature field to the workstep configuration you have to add a new task for the signature field and you have to add the signature plugin information.
Note: The Id for the signature field must be the same as in the workstep task.
Following code shows an example for a workstep task. You can replace the workstep task from the empty workstep configuration by the following one:
<WorkstepTasks SequenceMode="SequenceOnlyRequiredTasks" originalSequenceMode="SequenceOnlyRequiredTasks"> <Task enabled="1" completed="0" required="1" id="93cce567-ae5c-4e98-ac99-9f56ac034250" displayName="SignField 1" DocRefNumber="1" type="SignField" internalAllConcernedDocRefNumbersList="1" allRequiredFieldsFilledOnWorkstepCreation="0" /> </WorkstepTasks>
GetAdHocWorkstepConfiguration
Another way to get the workstep configuration is to upload a file and call the GetAdHocWorkstepConfiguration_v1. For this API call you need the document Id which you got from the UploadTemporarySspFile_v1 and a AdHocWorkstepConfiguration. You can find an AdHocWorkstepConfiguration in the next collapse.
Then you receive an empty configuration based on the uploaded PDF. You can now add additional signature fields or change some behaviors
Place advanced tags
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 a form field valdiation for text fields.
<textBox id="Text1"> ... <minLength>5</minLength> <placeholders> <placeholder language="*">example.mail@xyzmo.com</placeholder> <placeholder language="de">beispiel.mail@xyzmo.com</placeholder> </placeholders> <tooltips> <tooltip language="*">Please enter your phone number in the format +{countryCode}{phoneNumber}</tooltip> <tooltip language="de">Bitte geben Sie hier Ihre Telefonnummer in dem Format +{Ländercode}{Telefonnummer} ein</tooltip> </tooltips> <inputValidation> <type>Number/Decimal/Currency/Phone/Email/Date/Time/Custom</type> <format>dd-MM-yyyy / \d*(\.|,)?\d?</format> <range from="-128" to="127" /> </inputValidation> </textBox>
In the next collapse you can find a workstep configuration with one recipient and a textfield for the input validation:
The following options are availabe:
- Date
- Format is required; Value: any .NET format
- Range is optional and must match with given format
<inputValidation> <type>date</type> <format>dd. MMMM yyyy</format> <range from="13. Mai 2018" to="18. December 2019" /> </inputValidation>
- Email
- no format or range
<inputValidation> <type>email<type> </inputValidation>
- Number
- Format is required
- decimalPlaces required; between 0..10
- decimalSeparator (if decimalPlaces > 0): comma, point or apostrophe
- thousandsSeparator (must be different to decimalSeparator): comma, point, apostrophe, blank
- symbol (optional): any text, e.g. for currency
- symbolLocation (required if symbol is set): start, startWithBlank, end, endWithBlank
- Range: allowed (optional): must match with given format
- Format is required
<inputValidation> <type>number</type> <format decimalPlaces="2" decimalSeparator="comma" thousandsSeparator="point" symbol="€" symbolLocation="endWithBlank" /> <range from="-300,00 €" to="5.000,00 €" /> </inputValidation>
True (within the range) | False (outside the range) |
- Phone
- Format: required; International, InternationalLeadingZeros, InternationLeadingPlus
<inputValidation> <type>phone</type> <format type="international" /> </inputValidation>
- Time
- Format: required; any .NET time format
- Range: allowed (optional), must match with given format
<inputValidation> <type>time</type> <format>HH:mm</format> <range from="12:00" to="18:00" /> </inputValidation>