This case leads you through the process of the API call to prepare an envelope. Generally this call helps you to prepare all steps and the whole configuration for an envelope you want to send later.
The Story
A car seller is in the final step of selling the car to a customer. He/She creates the contract and adds all the features, that the car will later include, in the document. In order not to overwrite the signature field with text, the seller has created a dynamic field so that the signature field is dynamically placed on the page.
Use Case Description
In a car sales, it is likely that with additional features, which should be installed in the new car, the signature field in the contract is not always on the same position (page 1) but on the second or third. Therefore, it makes sense to place dynamic placeholders. Exactly this case will be described here. The next figure illustrates this case:
This function should be used in combination with the advanced tags in documents. For detailed information about the advanced document tags please also have a look at the advanced document tag guide.
Integration
The following steps (including the optional use of the advanced document tag) are necessary for the API call:
- prepare a document with advanced document tags
- upload the document
- prepare the envelope
- send the envelope
Please also see the developer mode for this tutorial here: Visit the developer mode.
Prepare a document with advanced document tags
For more information please have a look at the advanced document tag guide. For this case you can use the following document which includes one text field and one checkbox:
Download the document here.
Upload the document
Make sure you upload a document which contains advanced document tags to see the differences in preparing the envelope.
Preparing the envelope
For this call you need the File Id which you got from the upload file call, an adhoc workstep configuration and the steps descriptor.
The next configurations show you sample workstep configuration.
{ "SspFileIds": [ "##FILE-ID##" ], "AdHocWorkstepConfiguration": { "WorkstepLabel": "string", "SmallTextZoomFactorPercent": 0, "WorkstepTimeToLiveInMinutes": 0, "FinishAction": { "ClientActions": [ { "RemoveDocumentFromRecentDocumentList": true, "CallClientActionOnlyAfterSuccessfulSync": true, "ClientName": "string", "CloseApp": true, "Action": "string" } ] }, "NoSequenceEnforced": true, "SigTemplate": { "Size": { "Height": 0, "Width": 0 }, "AllowedSignatureTypes": [ ] }, "ParseFormFields": { "MapRequiredFieldsToRequiredTask": true, "FormsGrouping": "PerPage", "ReturnSimplifiedConfig": true, "AddKeepExistingValueFlag": true, "ParseFormField": true }, "AdhocPolicies": { "AllowModificationsAfterSignature": true }, "ViewerPreferences": { "ShowPageNavigationBar": true, "ShowThumbnails": true, "SkipFinishConfirmDialog": true, "SkipDocumentDialog": true, "ShowImagesInFullWidth": true, "DisableGeolocation": true, "ShowDocumentDownloadDialogAfterAutomaticFinish": true, "AttachmentsMaxFileSize": 0, "SkipPreviewImageOnDisposableCertificate": true, "LoadCustomJs": true, "AllowCustomButtons": true, "GuidingBehavior": "GuideOnlyRequiredTasks", "FormFieldsGuidingBehavior": "AllowSubmitAlways", "ShowVersionNumber": true, "EnableWarningPopupOnLeave": true, "WarningPopupDisplayAfter": "FillOrSignField", "FinishWorkstepOnOpen": true, "AutoFinishAfterRequiredTasksDone": true, "GuidingBehaviorOnFinishedTask": "NoMove", "SkipThankYouDialog": true, "NativeAppsUrlScheme": "string", "DocumentViewingMode": "EndlessPaperAllDocuments", "ThumbnailMode": "ShowAllPages", "ShowTopBar": true, "DisplayRejectButtonInTopBar": true, "MultipleSignatureTypesAndBatchSigningSettings": { "IsUseBatchSigningCheckedByDefault": true, "IsRememberSignatureTypeCheckedByDefault": true, "IsRememberBatchSigningDecisionCheckedByDefault": true, "SkipMultipleSignatureTypesAndBatchSigningDialogIfBatchSigningPossible": true }, "VisibleAreaOptions": { "AllowedDomain": "string", "Enabled": true }, "ShowStartGuidingHint": true, "ShowStatusBar": true, "ShowZoomButtons": true, "ShowNoGeolocationWarning": true, "AutoStartGuiding": true, "ShowPageGap": true, "ShowPageNavigationButtons": true, "ShowFinishPossibleHint": true, "SkipRejectConfirmDialog": true, "BatchSigningType": "Basic", "BatchSigningDisableNextButtonUntilDialogScrolledToBottom": true }, "SignatureConfigurations": [ { "SpcId": "string", "PdfSignatureProperties": { "PdfAConformant": true, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": true, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude", "SignatureTimestampData": { "Uri": "string", "Username": "string", "Password": "string", "SignatureHashAlgorithm": "Sha1", "AuthenticationCertifiateDescriptor": { "Identifier": "string", "Type": "string" } }, "EnableEutlVerification": true, "EnableValidateSigningCertificateName": true, "SigningCertificateNameRegex": "string" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha1", "SigningCertificateDescriptor": { "Identifier": "string", "Type": "Sha1Thumbprint", "Csp": "Default" } }, "CertificateFilter": { "KeyUsages": [ "string" ], "ThumbPrints": [ "string" ], "RootThumbPrints": [ "string" ] } } ], "SigStringParsingConfiguration": { "SigStringsForParsings": [ { "StartPattern": "string", "EndPattern": "string", "ClearSigString": true, "SearchEntireWordOnly": true } ] }, "GeneralPolicies": { "AllowSaveDocument": true, "AllowSaveAuditTrail": true, "AllowRotatingPages": true, "AllowAppendFileToWorkstep": true, "AllowAppendTaskToWorkstep": true, "AllowEmailDocument": true, "AllowPrintDocument": true, "AllowFinishWorkstep": true, "AllowRejectWorkstep": true, "AllowRejectWorkstepDelegation": true, "AllowUndoLastAction": true, "AllowColorizePdfForms": true, "AllowAdhocPdfAttachments": true, "AllowAdhocSignatures": true, "AllowAdhocStampings": true, "AllowAdhocFreeHandAnnotations": true, "AllowAdhocTypewriterAnnotations": true, "AllowAdhocPictureAnnotations": true, "AllowAdhocPdfPageAppending": true, "AllowReloadOfFinishedWorkstep": true }, "FinalizeActions": { "FinalizeActionList": [ ] }, "TransactionCodeConfigurations": [ { "Id": "string", "HashAlgorithmIdentifier": "Sha1", "Texts": [ { "Language": "string", "Value": "string" } ] } ] }, "PrepareSendEnvelopeStepsDescriptor": { "ClearFieldMarkupString": true } }
The next lines of code show you how to configure the steps descriptor:
"PrepareSendEnvelopeStepsDescriptor": { "ClearFieldMarkupString": true }
For the tag “clearFieldMarkupString” you can choose between the values “true” and “false” in REST and “0” and “1” in SOAP. If you define for example “false” the field markup string will not be cleared. If you choose “true” the field markup string will be cleared.
After successful configuration you get as response a workstep configuration with the form fields at the end. Those form fields will be added to the document. You can find a sample response in the next collapse:
{ "AdHocWorkstepConfigResult": { "WorkstepLabel": "string", "SmallTextZoomFactorPercent": 0, "FinishAction": { "ServerActions": [], "ClientActions": [ { "RemoveDocumentFromRecentDocumentList": true, "CallClientActionOnlyAfterSuccessfulSync": true, "ClientName": "string", "CloseApp": true, "Action": "string" } ] }, "TransactionCodeConfigurations": [ { "Id": "string", "HashAlgorithmIdentifier": "Sha1", "Texts": [ { "Language": "string", "Value": "string" } ] }, { "Id": "smsAuthTransactionCodeId", "HashAlgorithmIdentifier": "Sha256", "Texts": [ ] } ], "SignatureConfigurations": [ { "SpcId": "string", "PdfSignatureProperties": { "PdfAConformant": true, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": true, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude", "SignatureTimestampData": { "Uri": "string", "Username": "string", "Password": "string", "SignatureHashAlgorithm": "Sha1", "AuthenticationCertifiateDescriptor": { "Identifier": "string", "Type": "string" } }, "EnableEutlVerification": true, "EnableValidateSigningCertificateName": true, "SigningCertificateNameRegex": "string" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha1", "SigningCertificateDescriptor": { "Identifier": "string", "Type": "Sha1Thumbprint", "Csp": "Default" } }, "CertificateFilter": { "KeyUsages": [ "string" ], "ThumbPrints": [ "string" ], "RootThumbPrints": [ "string" ] } } ], "ViewerPreferences": { "ShowPageNavigationBar": true, "ShowThumbnails": true, "SkipFinishConfirmDialog": true, "SkipDocumentDialog": true, "ShowImagesInFullWidth": true, "DisableGeolocation": true, "ShowDocumentDownloadDialogAfterAutomaticFinish": true, "AttachmentsMaxFileSize": 0, "SkipPreviewImageOnDisposableCertificate": true, "LoadCustomJs": true, "AllowCustomButtons": true, "GuidingBehavior": "GuideOnlyRequiredTasks", "FormFieldsGuidingBehavior": "AllowSubmitAlways", "ShowVersionNumber": true, "EnableWarningPopupOnLeave": true, "WarningPopupDisplayAfter": "FillOrSignField", "FinishWorkstepOnOpen": true, "AutoFinishAfterRequiredTasksDone": true, "GuidingBehaviorOnFinishedTask": "NoMove", "SkipThankYouDialog": true, "NativeAppsUrlScheme": "string", "DocumentViewingMode": "EndlessPaperAllDocuments", "ThumbnailMode": "ShowAllPages", "ShowTopBar": true, "DisplayRejectButtonInTopBar": true, "MultipleSignatureTypesAndBatchSigningSettings": { "IsUseBatchSigningCheckedByDefault": true, "IsRememberSignatureTypeCheckedByDefault": true, "IsRememberBatchSigningDecisionCheckedByDefault": true, "SkipMultipleSignatureTypesAndBatchSigningDialogIfBatchSigningPossible": true }, "VisibleAreaOptions": { "AllowedDomain": "string", "Enabled": true }, "ShowStartGuidingHint": true, "ShowStatusBar": true, "ShowZoomButtons": true, "ShowNoGeolocationWarning": true, "AutoStartGuiding": true, "ShowPageNavigationButtons": true, "ShowFinishPossibleHint": true, "SkipRejectConfirmDialog": true, "BatchSigningType": "Basic", "BatchSigningDisableNextButtonUntilDialogScrolledToBottom": true }, "Policy": { "GeneralPolicies": { "AllowSaveDocument": true, "AllowSaveAuditTrail": true, "AllowRotatingPages": true, "AllowAppendFileToWorkstep": true, "AllowAppendTaskToWorkstep": true, "AllowEmailDocument": true, "AllowPrintDocument": true, "AllowFinishWorkstep": true, "AllowRejectWorkstep": true, "AllowRejectWorkstepDelegation": true, "AllowUndoLastAction": true, "AllowColorizePdfForms": true, "AllowAdhocPdfAttachments": true, "AllowAdhocSignatures": true, "AllowAdhocStampings": true, "AllowAdhocFreeHandAnnotations": true, "AllowAdhocTypewriterAnnotations": true, "AllowAdhocPictureAnnotations": true, "AllowAdhocPdfPageAppending": true, "AllowReloadOfFinishedWorkstep": true }, "WorkstepTasks": { "PictureAnnotationMinResolution": 0, "PictureAnnotationMaxResolution": 0, "PictureAnnotationColorDepth": "Color16M", "SequenceMode": "NoSequenceEnforced", "PositionUnits": "PdfUnits", "ReferenceCorner": "Lower_Left", "Tasks": [] } } }, "Steps": [ { "OrderIndex": 1, "Recipients": [ { "Email": "placeholder1@placeholder1.com", "FirstName": "placeholder1", "LastName": "placeholder1", "LanguageCode": "en", "DisableEmail": false, "AddAndroidAppLink": false, "AddIosAppLink": false, "AddWindowsAppLink": false, "AllowDelegation": true, "SkipExternalDataValidation": false, "AuthenticationMethods": [] } ], "RecipientType": "Signer", "WorkstepConfiguration": { "WorkstepLabel": "string", "SmallTextZoomFactorPercent": 0, "FinishAction": { "ServerActions": [], "ClientActions": [ { "RemoveDocumentFromRecentDocumentList": true, "CallClientActionOnlyAfterSuccessfulSync": true, "ClientName": "string", "CloseApp": true, "Action": "string" } ] }, "TransactionCodeConfigurations": [ { "Id": "string", "HashAlgorithmIdentifier": "Sha1", "Texts": [ { "Language": "string", "Value": "string" } ] }, { "Id": "smsAuthTransactionCodeId", "HashAlgorithmIdentifier": "Sha256", "Texts": [ ] } ], "SignatureConfigurations": [ { "SpcId": "string", "PdfSignatureProperties": { "PdfAConformant": true, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": true, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude", "SignatureTimestampData": { "Uri": "string", "Username": "string", "Password": "string", "SignatureHashAlgorithm": "Sha1", "AuthenticationCertifiateDescriptor": { "Identifier": "string", "Type": "string" } }, "EnableEutlVerification": true, "EnableValidateSigningCertificateName": true, "SigningCertificateNameRegex": "string" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha1", "SigningCertificateDescriptor": { "Identifier": "string", "Type": "Sha1Thumbprint", "Csp": "Default" } }, "CertificateFilter": { "KeyUsages": [ "string" ], "ThumbPrints": [ "string" ], "RootThumbPrints": [ "string" ] } } ], "ViewerPreferences": { "ShowPageNavigationBar": true, "ShowThumbnails": true, "SkipFinishConfirmDialog": true, "SkipDocumentDialog": true, "ShowImagesInFullWidth": true, "DisableGeolocation": true, "ShowDocumentDownloadDialogAfterAutomaticFinish": true, "AttachmentsMaxFileSize": 0, "SkipPreviewImageOnDisposableCertificate": true, "LoadCustomJs": true, "AllowCustomButtons": true, "GuidingBehavior": "GuideOnlyRequiredTasks", "FormFieldsGuidingBehavior": "AllowSubmitAlways", "ShowVersionNumber": true, "EnableWarningPopupOnLeave": true, "WarningPopupDisplayAfter": "FillOrSignField", "FinishWorkstepOnOpen": true, "AutoFinishAfterRequiredTasksDone": true, "GuidingBehaviorOnFinishedTask": "NoMove", "SkipThankYouDialog": true, "NativeAppsUrlScheme": "string", "DocumentViewingMode": "EndlessPaperAllDocuments", "ThumbnailMode": "ShowAllPages", "ShowTopBar": true, "DisplayRejectButtonInTopBar": true, "MultipleSignatureTypesAndBatchSigningSettings": { "IsUseBatchSigningCheckedByDefault": true, "IsRememberSignatureTypeCheckedByDefault": true, "IsRememberBatchSigningDecisionCheckedByDefault": true, "SkipMultipleSignatureTypesAndBatchSigningDialogIfBatchSigningPossible": true }, "VisibleAreaOptions": { "AllowedDomain": "string", "Enabled": true }, "ShowStartGuidingHint": true, "ShowStatusBar": true, "ShowZoomButtons": true, "ShowNoGeolocationWarning": true, "AutoStartGuiding": true, "ShowPageNavigationButtons": true, "ShowFinishPossibleHint": true, "SkipRejectConfirmDialog": true, "BatchSigningType": "Basic", "BatchSigningDisableNextButtonUntilDialogScrolledToBottom": true }, "Policy": { "GeneralPolicies": { "AllowSaveDocument": true, "AllowSaveAuditTrail": true, "AllowRotatingPages": true, "AllowAppendFileToWorkstep": true, "AllowAppendTaskToWorkstep": true, "AllowEmailDocument": true, "AllowPrintDocument": true, "AllowFinishWorkstep": true, "AllowRejectWorkstep": true, "AllowRejectWorkstepDelegation": true, "AllowUndoLastAction": true, "AllowColorizePdfForms": true, "AllowAdhocPdfAttachments": true, "AllowAdhocSignatures": true, "AllowAdhocStampings": true, "AllowAdhocFreeHandAnnotations": true, "AllowAdhocTypewriterAnnotations": true, "AllowAdhocPictureAnnotations": true, "AllowAdhocPdfPageAppending": true, "AllowReloadOfFinishedWorkstep": true }, "WorkstepTasks": { "PictureAnnotationMinResolution": 0, "PictureAnnotationMaxResolution": 0, "PictureAnnotationColorDepth": "Color16M", "SequenceMode": "NoSequenceEnforced", "PositionUnits": "PdfUnits", "ReferenceCorner": "Lower_Left", "Tasks": [ { "Forms": [ { "Id": "myText1", "PositionPage": 1, "DocRefNumber": 1, "Position": { "PositionX": 72.0, "PositionY": 563.0 }, "Size": { "Height": 65.15, "Width": 200.0 }, "DiscriminatorType": "TextBox" }, { "IsRequired": true, "RequiredEvalPolicy": "IsChecked", "Id": "chk1", "PositionPage": 1, "DocRefNumber": 1, "Position": { "PositionX": 72.0, "PositionY": 440.0 }, "Size": { "Height": 25.0, "Width": 25.0 }, "DiscriminatorType": "CheckBox" } ], "IsRequired": true, "Id": "c9919432-ccd0-46a1-a715-9568faa2d57a", "DisplayName": "", "DocRefNumber": 1, "DiscriminatorType": "FormGroup" } ] } } }, "DocumentOptions": [], "UseDefaultAgreements": false } ], "AddFormFields": { "Forms": { "1": [ { "Value": "Place for signer1", "MaxLength": 100, "IsMultiline": false, "IsPassword": false, "IsFileSelect": false, "IsScrollAllowed": false, "IsComb": false, "TextColor": "255, 0, 0", "FontSize": 12.0, "FontName": "Arial", "Bold": false, "Italic": false, "TextAlign": "Center", "Name": "myText1", "ReadOnly": false, "Required": true, "X": 72.0, "Y": 563.477001953125, "Width": 200.0, "Height": 65.149999999999991, "Page": 1, "DiscriminatorType": "AddTextBoxFormFieldDescriptor" }, { "IsChecked": true, "ExportValue": "", "Name": "chk1", "ReadOnly": false, "Required": true, "X": 72.0, "Y": 439.802001953125, "Width": 25.0, "Height": 25.0, "Page": 1, "DiscriminatorType": "AddCheckBoxFormFieldDescriptor" } ] } } }
Sending the envelope
You can now add the workstep configuration which you got from the prepare call and send the document to recipients.