This case guides you through the configuration of the workstep. Generally the following steps are necessary to test the workstep configuration:
- Upload a file
- Workstep configuration
- Send an envelope
For a basic guide of REST and the different API calls please also have a look at our Postman tutorial.
Upload a file
You can upload a file with the following URL:
https://demo.xyzmo.com/Api/v4.0/sspfile/uploadtemporary
The result of the API call is the SspFileId which we need for the sending call.
Workstep configuration
The workstep configuration is the core of the envelope. Within the workstep configuration you can define following settings:
- Viewer preferences
- Policy
- Sender and receiver information
- Workstep tasks
- Authentication
- PdfForms
Empty workstep configuration
Lets start with an empty workstep first and then fill it step by step with the settings above. In the next collapse you can find an empty workstep (change ##EMAIL## to the email-address you want to send the envelope):
Configuration
{
"SspFileIds": [
"##FileId##"
],
"SendEnvelopeDescription": {
"Name": "test",
"EmailSubject": "Please sign the enclosed envelope",
"EmailBody": "Dear #RecipientFirstName# #RecipientLastName#\n\n#PersonalMessage#\n\nPlease sign the envelope #EnvelopeName#\n\nEnvelope will expire at #ExpirationDate#",
"DisplayedEmailSender": "",
"EnableReminders": true,
"FirstReminderDayAmount": 5,
"RecurrentReminderDayAmount": 3,
"BeforeExpirationDayAmount": 3,
"DaysUntilExpire": 28,
"CallbackUrl": "",
"StatusUpdateCallbackUrl": "",
"Steps": [
{
"OrderIndex": 1,
"Recipients": [
{
"Email": "##EMAIL##",
"FirstName": "##NAME##",
"LastName": "##NAME##",
"LanguageCode": "en",
"EmailBodyExtra": "",
"DisableEmail": false,
"AddAndroidAppLink": false,
"AddIosAppLink": false,
"AddWindowsAppLink": false,
"AllowDelegation": true,
"SkipExternalDataValidation": false,
"AuthenticationMethods": []
}
],
"EmailBodyExtra": "",
"RecipientType": "Signer",
"WorkstepConfiguration": {
"WorkstepLabel": "test",
"SmallTextZoomFactorPercent": 100,
"FinishAction": {
"ServerActions": [],
"ClientActions": []
},
"TransactionCodePushPluginData": [],
"TransactionCodeConfigurations": [
{
}
],
"SignatureConfigurations": [],
"ViewerPreferences": {
"FinishWorkstepOnOpen": false,
"VisibleAreaOptions": {
"AllowedDomain": "*",
"Enabled": false
}
},
"Policy": {
"WorkstepTasks": {
"PictureAnnotationMinResolution": 0,
"PictureAnnotationMaxResolution": 0,
"PictureAnnotationColorDepth": "Color16M",
"SequenceMode": "NoSequenceEnforced",
"PositionUnits": "PdfUnits",
"ReferenceCorner": "Lower_Left",
"Tasks": []
}
}
},
"DocumentOptions": [
{
"DocumentReference": "1",
"IsHidden": false
}
],
"UseDefaultAgreements": true
},
{
"OrderIndex": 2,
"Recipients": [
{
"Email": "##EMAIL##",
"FirstName": "##NAME##",
"LastName": "##NAME##",
"LanguageCode": "en",
"EmailBodyExtra": "",
"DisableEmail": false,
"AddAndroidAppLink": false,
"AddIosAppLink": false,
"AddWindowsAppLink": false,
"AllowDelegation": false,
"SkipExternalDataValidation": false,
"AuthenticationMethods": []
}
],
"EmailBodyExtra": "",
"RecipientType": "Cc",
"DocumentOptions": [],
"UseDefaultAgreements": false
}
],
"AddFormFields": {
"Forms": {}
},
"OverrideFormFieldValues": {
"Forms": {}
},
"AttachSignedDocumentsToEnvelopeLog": false
}
}
The next screenshot shows the document after sending the workstep configuration:
With this empty workstep configuration we can now add the settings which are mentioned above. First, lets start with the policies.
Policy
You can place the general policies directly below the following row:
Within this brace you can add the following policies:
"GeneralPolicies": {
"AllowSaveDocument": false,
"AllowSaveAuditTrail": false,
"AllowRotatingPages": false,
"AllowEmailDocument": false,
"AllowPrintDocument": false,
"AllowFinishWorkstep": false,
"AllowRejectWorkstep": false,
"AllowRejectWorkstepDelegation": false,
"AllowUndoLastAction": false,
"AllowAdhocPdfAttachments": false,
"AllowAdhocSignatures": false,
"AllowAdhocStampings": false,
"AllowAdhocFreeHandAnnotations": false,
"AllowAdhocTypewriterAnnotations": false,
"AllowAdhocPictureAnnotations": false,
"AllowAdhocPdfPageAppending": false
},
In this case all policies are disabled. The table will show you the differences on the document if you enable all policies and if you disable all policies:
| Policies disabled | Policies enabled |
|---|
|  |
As you can see on the right screenshot the recipient of the envelope can now print the document as well as reject the envelope and more.
Sender information:
"SenderInformation": {
"UserInformation": {
"FirstName": "Manuel",
"LastName": "Gierlinger",
"EMail": "##EMAIL##"
}
},
Receiver information:
"ReceiverInformation": {
"UserInformation": {
"FirstName": "manuel",
"LastName": "gierlinger",
"EMail": "##EMAIL##"
}
},
The next section shows you where you can place the sender and receiver information.
"EmailBodyExtra": "",
"RecipientType": "Signer",
"WorkstepConfiguration": {
"WorkstepLabel": "test",
"SmallTextZoomFactorPercent": 100,
"FinishAction": {
"ServerActions": [],
"ClientActions": []
},
"ReceiverInformation": {
"UserInformation": {
"FirstName": "manuel",
"LastName": "gierlinger",
"EMail": "##EMAIL##"
},
"TransactionCodePushPluginData": []
},
"SenderInformation": {
"UserInformation": {
"FirstName": "Manuel",
"LastName": "Gierlinger",
"EMail": "##EMAIL##"
}
},
Workstep tasks
In this section you can define the signature fields. In the next collapses you can find some examples of the signature fields configuration.
Click2Sign
"WorkstepTasks": {
"PictureAnnotationMinResolution": 0,
"PictureAnnotationMaxResolution": 0,
"PictureAnnotationColorDepth": "Color16M",
"SequenceMode": "NoSequenceEnforced",
"PositionUnits": "PdfUnits",
"ReferenceCorner": "Lower_Left",
"Tasks": [
{
"PositionPage": 1,
"Position": {
"PositionX": 69.0,
"PositionY": 529.92
},
"Size": {
"Height": 80.0,
"Width": 190.0
},
"AdditionalParameters": [
{
"Key": "enabled",
"Value": "1"
},
{
"Key": "positioning",
"Value": "onPage"
},
{
"Key": "req",
"Value": "1"
},
{
"Key": "fd",
"Value": ""
},
{
"Key": "fd_dateformat",
"Value": "dd-MM-yyyy HH:mm:ss"
},
{
"Key": "fd_timezone",
"Value": "datetimeutc"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Click2Sign",
"StampImprintConfiguration": {
"DisplayExtraInformation": true,
"DisplayEmail": true,
"DisplayIp": true,
"DisplayName": true,
"DisplaySignatureDate": true,
"FontFamily": "Times New Roman",
"FontSize": 11.0
},
"Id": "d63ec0d5-a2ca-46d9-9c73-7bd8d91aa4ea",
"DiscriminatorType": "SigTypeClick2Sign",
"Preferred": true
}
],
"UseTimestamp": false,
"IsRequired": true,
"Id": "1#XyzmoDuplicateIdSeperator#Signature_94816166-6b59-1cc1-de9b-285633162aef",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
}
]
}
}
},
Type2Sign
"WorkstepTasks": {
"PictureAnnotationMinResolution": 0,
"PictureAnnotationMaxResolution": 0,
"PictureAnnotationColorDepth": "Color16M",
"SequenceMode": "NoSequenceEnforced",
"PositionUnits": "PdfUnits",
"ReferenceCorner": "Lower_Left",
"Tasks": [
{
"PositionPage": 1,
"Position": {
"PositionX": 69.0,
"PositionY": 529.92
},
"Size": {
"Height": 80.0,
"Width": 190.0
},
"AdditionalParameters": [
{
"Key": "enabled",
"Value": "1"
},
{
"Key": "positioning",
"Value": "onPage"
},
{
"Key": "req",
"Value": "1"
},
{
"Key": "fd",
"Value": ""
},
{
"Key": "fd_dateformat",
"Value": "dd-MM-yyyy HH:mm:ss"
},
{
"Key": "fd_timezone",
"Value": "datetimeutc"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Type2Sign",
"StampImprintConfiguration": {
"DisplayExtraInformation": true,
"DisplayEmail": true,
"DisplayIp": true,
"DisplayName": true,
"DisplaySignatureDate": true,
"FontFamily": "Times New Roman",
"FontSize": 11.0
},
"Id": "d63ec0d5-a2ca-46d9-9c73-7bd8d91aa4ea",
"DiscriminatorType": "SigTypeType2Sign",
"Preferred": true
}
],
"UseTimestamp": false,
"IsRequired": true,
"Id": "1#XyzmoDuplicateIdSeperator#Signature_94816166-6b59-1cc1-de9b-285633162aef",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
}
]
}
}
},
Draw2Sign
"WorkstepTasks": {
"PictureAnnotationMinResolution": 0,
"PictureAnnotationMaxResolution": 0,
"PictureAnnotationColorDepth": "Color16M",
"SequenceMode": "NoSequenceEnforced",
"PositionUnits": "PdfUnits",
"ReferenceCorner": "Lower_Left",
"Tasks": [
{
"PositionPage": 1,
"Position": {
"PositionX": 69.0,
"PositionY": 529.92
},
"Size": {
"Height": 80.0,
"Width": 190.0
},
"AdditionalParameters": [
{
"Key": "enabled",
"Value": "1"
},
{
"Key": "positioning",
"Value": "onPage"
},
{
"Key": "req",
"Value": "1"
},
{
"Key": "fd",
"Value": ""
},
{
"Key": "fd_dateformat",
"Value": "dd-MM-yyyy HH:mm:ss"
},
{
"Key": "fd_timezone",
"Value": "datetimeutc"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Draw2Sign",
"StampImprintConfiguration": {
"DisplayExtraInformation": true,
"DisplayEmail": true,
"DisplayIp": true,
"DisplayName": true,
"DisplaySignatureDate": true,
"FontFamily": "Times New Roman",
"FontSize": 11.0
},
"Id": "d63ec0d5-a2ca-46d9-9c73-7bd8d91aa4ea",
"DiscriminatorType": "SigTypeDraw2Sign",
"Preferred": true
}
],
"UseTimestamp": false,
"IsRequired": true,
"Id": "1#XyzmoDuplicateIdSeperator#Signature_94816166-6b59-1cc1-de9b-285633162aef",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
}
]
}
}
},
Biometric
"WorkstepTasks": {
"PictureAnnotationMinResolution": 0,
"PictureAnnotationMaxResolution": 0,
"PictureAnnotationColorDepth": "Color16M",
"SequenceMode": "NoSequenceEnforced",
"PositionUnits": "PdfUnits",
"ReferenceCorner": "Lower_Left",
"Tasks": [
{
"PositionPage": 1,
"Position": {
"PositionX": 67.0,
"PositionY": 521.92
},
"Size": {
"Height": 80.0,
"Width": 190.0
},
"AdditionalParameters": [
{
"Key": "enabled",
"Value": "1"
},
{
"Key": "positioning",
"Value": "intersectsWithField"
},
{
"Key": "req",
"Value": "1"
},
{
"Key": "fd",
"Value": ""
},
{
"Key": "fd_dateformat",
"Value": "dd-MM-yyyy HH:mm:ss"
},
{
"Key": "fd_timezone",
"Value": "datetimeutc"
}
],
"AllowedSignatureTypes": [
{
"IsBio": false,
"AllowSkipBiometricVerification": false,
"AllowBiometricStoringOnly": false,
"SignedResponseWithoutBioData": false,
"Id": "6fa90b47-847f-47b1-b73a-9c3802aa077d",
"DiscriminatorType": "SigTypeBiometricSignature",
"Preferred": true
}
],
"UseTimestamp": false,
"IsRequired": true,
"Id": "1#XyzmoDuplicateIdSeperator#Signature_532f40e1-0583-8285-fc50-c2a76dc2fa44",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
}
]
}
}
},
For the biometric signature you have to define the "positioning" property, as a key-value pair with key "positioning", in the AdditionalParameters array:
| Enum value | equivalent text option in designer | Description |
|---|
| intersectsWithField | intersects with field | The signature has to start within the signature field, but the signer is allowed to leave the boundaries of the box while signing |
| withinField | within field | The signature must be completely within the boundaries of the signature field |
| onPage | on page | The signature can start anywhere on the page, even without intersecting with the signature field |
Authentication
You can add different authentications for the recipient to ensure that only the one who has the code/phone number can open the envelope. Following list shows the different authentications:
In the next two sections you can find the configuration for the Pin-authentication and for the SMS-authentication:
Place the authentication within the recipient in the authentication methods.
PIN:
{
"Method": "Pin",
"Parameter": "1234"
}
SMS:
{
"Method": "Sms",
"Parameter": "+0123456789"
}
The next lines of code show you where you have to place the authentication. (In this case we used a pin authentication)
"Steps": [
{
"OrderIndex": 1,
"Recipients": [
{
"Email": "##EMAIL##",
"FirstName": "##NAME##",
"LastName": "##NAME##",
"LanguageCode": "en",
"EmailBodyExtra": "",
"DisableEmail": false,
"AddAndroidAppLink": false,
"AddIosAppLink": false,
"AddWindowsAppLink": false,
"AllowDelegation": false,
"SkipExternalDataValidation": false,
"AuthenticationMethods": [
{
"Method": "Pin",
"Parameter": "1234"
}
]
}
],
The following list shows you all different form fields which can be placed on the document:
- Textfield
- Radiobutton
- Checkbox
- Listbox
- Combobox
To add the form fields we have to add them within the WorkstepTasks and within the AddFormFields.
The next collapse show you how to configure the workstep tasks for all form fields:
Textfield
"Forms": [
{
"Id": "TextBox_3daf9a88-bf45-70af-99d0-c077bcb48245",
"PositionPage": 1,
"DocRefNumber": 1,
"Position": {
"PositionX": 77.0,
"PositionY": 590.0
},
"Size": {
"Height": 20.0,
"Width": 124.0
},
"DiscriminatorType": "TextBox"
}
],
"IsRequired": false,
"Id": "f390ebd3-4b9c-4554-ab61-4d1234bad681",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "FormGroup"
},
RadioButton
{
"RadioButtonGroupId": "RadioButton_942fca6a-5e0e-7694-b858-b5ded711ed0b",
"Id": "0",
"PositionPage": 1,
"DocRefNumber": 1,
"Position": {
"PositionX": 77.0,
"PositionY": 553.0
},
"Size": {
"Height": 20.0,
"Width": 20.0
},
"DiscriminatorType": "RadioButton"
},
Checkbox
{
"IsRequired": false,
"RequiredEvalPolicy": "None",
"Id": "CheckBox_41371eaf-6e1a-0d9a-58a9-0705fd8d08d1",
"PositionPage": 1,
"DocRefNumber": 1,
"Position": {
"PositionX": 77.0,
"PositionY": 520.0
},
"Size": {
"Height": 20.0,
"Width": 20.0
},
"DiscriminatorType": "CheckBox"
},
Listbox
{
"Items": [],
"Id": "ListBox_d51c4e55-2497-8ab4-f2c8-6f60ac6a2cfd",
"PositionPage": 1,
"DocRefNumber": 1,
"Position": {
"PositionX": 79.0,
"PositionY": 475.0
},
"Size": {
"Height": 30.0,
"Width": 150.0
},
"DiscriminatorType": "ListBox"
},
Combobox
{
"IsRequired": false,
"Items": [],
"Id": "ComboBox_67a8d39f-3a49-65e0-0d5d-88ac97b387ea",
"PositionPage": 1,
"DocRefNumber": 1,
"Position": {
"PositionX": 79.0,
"PositionY": 424.0
},
"Size": {
"Height": 30.0,
"Width": 150.0
},
"DiscriminatorType": "ComboBox"
}
After this configuration we have to add the form fields within the following section:
"AddFormFields": {
"Forms": {##Fields##}
},
In the next collapses you can find the configuration for all form fields.
Add this line within the “Forms” section:
Then you can place the form fields within this tag.
Textfield
{
"Value": "",
"MaxLength": -1,
"IsMultiline": false,
"IsPassword": false,
"IsComb": false,
"TextColor": "0, 0, 0",
"FontSize": 11.0,
"FontName": "Times New Roman",
"Bold": false,
"Italic": false,
"TextAlign": "Left",
"Name": "TextBox_3daf9a88-bf45-70af-99d0-c077bcb48245",
"ReadOnly": false,
"Required": false,
"X": 77.0,
"Y": 590.92,
"Width": 124.0,
"Height": 20.0,
"Page": 1,
"DiscriminatorType": "AddTextBoxFormFieldDescriptor"
},
RadioButton
{
"ExportValue": "1b6c204b-0642-5566-f526-a725e16737a5",
"IsChecked": false,
"Name": "RadioButton_18d57bcd-6a82-ebde-a2ab-c4557a720bfe",
"ReadOnly": false,
"Required": false,
"X": 77.0,
"Y": 550.92,
"Width": 20.0,
"Height": 20.0,
"Page": 1,
"DiscriminatorType": "AddRadioButtonFormFieldDescriptor"
},
Checkbox
{
"IsChecked": true,
"Name": "CheckBox_e5ba8ea4-8c39-324f-0170-a83dd3fb3aeb",
"ReadOnly": false,
"Required": false,
"X": 79.0,
"Y": 516.92,
"Width": 20.0,
"Height": 20.0,
"Page": 1,
"DiscriminatorType": "AddCheckBoxFormFieldDescriptor"
}
Listbox
{
"Items": [],
"TextColor": "",
"FontSize": 11.0,
"FontName": "Times New Roman",
"Bold": false,
"Italic": false,
"TextAlign": "Left",
"Name": "ListBox_e4076d02-c636-0138-fe54-03d19fe10a7d",
"ReadOnly": false,
"Required": false,
"X": 79.0,
"Y": 468.92,
"Width": 150.0,
"Height": 30.0,
"Page": 1,
"DiscriminatorType": "AddListBoxFormFieldDescriptor"
},
Combobox
{
"Value": "",
"Items": [],
"TextColor": "",
"FontSize": 11.0,
"FontName": "Times New Roman",
"Bold": false,
"Italic": false,
"TextAlign": "Left",
"Name": "ComboBox_6936c368-b465-6355-0367-bdfe042c8ec7",
"ReadOnly": false,
"Required": false,
"X": 79.0,
"Y": 418.92,
"Width": 150.0,
"Height": 30.0,
"Page": 1,
"DiscriminatorType": "AddComboBoxFormFieldDescriptor"
},
Sending envelope
After you have added all form fields and signatures you can send the envelope to recipients. Therefor, add the file Id and the workstep configuration to the REST call basicURL/envelope/send and send the envelope to the recipients.
