The Workstep XML

Owned by Former user (Deleted)
Last updated: Nov 14, 2022 by Fabian Wenny
12 min read

This pages explains the workstep configuration XML (a recipients signature task) and its content. See the envelope XML page for details about the workflow configuration (envelope and recipients).

Basic Structure of the Workstep Configuration XML

Requires Rework

This chapter requires rework. The examples below explain the Workstep 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 workstep configuration defines a signature task for a recipient. In the envelope XML the workflow and the recipients are defined and in the workstep configuration a single signature task for a recipient.

The easiest way to start getting the configuration is to enable for your user the developer mode (eSignAnyWhere > Settings > User). Then you can download the envelope XML inclusive the workstepconfigurations of your in eSignAnyWhere designed workflows.

In contrast to the envelope XML, the workstep configuration XML is much more complicated, due the flexibilty of our platform. Therefore, understanding the workstep configuration and writing it manually enables a lot more use cases, then supported in the eSignAnyWhere UI. If you need help with the workstep configuration contact our support.

The Basic Structure of the XML

<workstepConfiguration>
  <WorkstepLabel>Label</WorkstepLabel>
  <SmallTextZoomFactorPercent>100</SmallTextZoomFactorPercent>
  <WorkstepTimeToLiveInMinutes>3600</WorkstepTimeToLiveInMinutes>
  <signatureTemplate />
  <pdfForms />
  <Policy />
  <FinishAction>
  <signaturePluginConfiguration>
</workstepConfiguration>

General Settings

Worksteplabel

The WorkstepLabel is the label for the workstep.

SmallTextZoomFactorPercent

Defines a image generation correction factor. If, for example, a document contains very small text, which might not be readable with the standard image resolution of the client, this factor can be used to tell the client to get a higher resolution.

WorkstepTimeToLiveInMinutes

Not relevant for eSignAnyWhere. This setting comes for the Namirial SIGNificant Server Platform, which is designed for signature tasks. eSignAnyWhere takes care about the time to live within the workflow and its definition.

Defines the time to live of the workstep. After this time to live is expired, the workstep will be deleted. ‘0’ sets the time to live to forever (in which case you will have to make sure to remove the workstep in the integration).

Hint: Up to Namirial SIGNificant Server Platform version 22.28, time to live was relative and actions on the workstep extended the expiration by the time to live value again, if not already set to forever.

Signature Templates

Definition of all the signature fields in the workstep. Signature fields can be added by:

  • defining the absolute position of the signature fields in the workstep configuration (as shown in the example below)
  • defining Adobe signature fields into the PDF document
  • defining signature strings (i.e. ‘sig’) into the PDF document
  • defining advanced tags into the PDF document
Example

This example contains a Click2Sign, Type2Sign and Draw2Sign signature field and one field with three allowed methods (Click2Sign, Draw2Sign, Type2Sign).

 <signatureTemplate>
          <version>1.2.0.2</version>
          <positionReferenceCorner>Lower_Left</positionReferenceCorner>
          <positionUnits>PdfUnits</positionUnits>
		  <!-- Click2Sign Signature field -->
          <sig id="1#XyzmoDuplicateIdSeperator#Signature_32e62575-f3dd-32ed-2032-f87311195683">
            <TaskDisplayName>Click2Sign</TaskDisplayName>
            <positionPage>1</positionPage>
            <DocRefNumber>1</DocRefNumber>
            <positionX>39</positionX>
            <positionY>710.92</positionY>
            <width>189</width>
            <height>80</height>
            <param name="completed">0</param>
            <param name="positioning">onPage</param>
            <param name="req">1</param>
            <param name="enabled">1</param>
            <param name="fd" />
            <param name="fd_dateformat">dd-MM-yyyy HH:mm:ss (zzz)</param>
            <param name="fd_timezone">datetimelocal</param>
            <AllowedSignatureTypes>
              <sigType id="6e049969-8be4-458d-89be-9792f0641b68" 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>
		  <!-- Draw2Sign Signature field -->
          <sig id="1#XyzmoDuplicateIdSeperator#Signature_f0984b1d-359b-7f3f-6a63-d334694cb1f0">
            <TaskDisplayName>Draw2Sign</TaskDisplayName>
            <positionPage>1</positionPage>
            <DocRefNumber>1</DocRefNumber>
            <positionX>39</positionX>
            <positionY>601.92</positionY>
            <width>189</width>
            <height>80</height>
            <param name="completed">0</param>
            <param name="positioning">onPage</param>
            <param name="req">1</param>
            <param name="enabled">1</param>
            <param name="fd" />
            <param name="fd_dateformat">dd-MM-yyyy HH:mm:ss (zzz)</param>
            <param name="fd_timezone">datetimelocal</param>
            <AllowedSignatureTypes>
              <sigType id="7bf17fc0-9ded-45d6-81a9-98042effd6fb" type="Picture">
                <allowedCapturingMethods>Draw2Sign</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>
		  <!-- Type2Sign Signature field -->
          <sig id="1#XyzmoDuplicateIdSeperator#Signature_e6728eb3-2da8-18b0-150b-283256d1c1f0">
            <TaskDisplayName>Type2Sign</TaskDisplayName>
            <positionPage>1</positionPage>
            <DocRefNumber>1</DocRefNumber>
            <positionX>39</positionX>
            <positionY>484.92</positionY>
            <width>189</width>
            <height>80</height>
            <param name="completed">0</param>
            <param name="positioning">onPage</param>
            <param name="req">1</param>
            <param name="enabled">1</param>
            <param name="fd" />
            <param name="fd_dateformat">dd-MM-yyyy HH:mm:ss (zzz)</param>
            <param name="fd_timezone">datetimelocal</param>
            <AllowedSignatureTypes>
              <sigType id="c66e77bb-2b15-4df2-b104-e2e8ebb52d03" type="Picture">
                <allowedCapturingMethods>Type2Sign</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>
		  <!-- Click2Sign, Type2Sign or Type2Sign Signature field -->
          <sig id="1#XyzmoDuplicateIdSeperator#Signature_aab56455-755f-4440-23c0-71552e8093d2">
            <TaskDisplayName>CDT2S</TaskDisplayName>
            <positionPage>1</positionPage>
            <DocRefNumber>1</DocRefNumber>
            <positionX>59</positionX>
            <positionY>348.92</positionY>
            <width>189</width>
            <height>80</height>
            <param name="completed">0</param>
            <param name="positioning">onPage</param>
            <param name="req">1</param>
            <param name="enabled">1</param>
            <param name="fd" />
            <param name="fd_dateformat">dd-MM-yyyy HH:mm:ss (zzz)</param>
            <param name="fd_timezone">datetimelocal</param>
            <AllowedSignatureTypes>
              <sigType id="727e5158-3f13-460f-993a-a658ca7aa025" 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>
              <sigType id="e33da45f-1afe-42ea-9b13-9bffa0ceb8a6" type="Picture">
                <allowedCapturingMethods>Draw2Sign</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>
              <sigType id="b944c09b-db37-4d2f-9e54-64a145135d9e" type="Picture">
                <allowedCapturingMethods>Type2Sign</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>
Definition

See the full workstep configuration for details and description.

Policies

General Policies

Defines general policies for the workstep (i.e. does the client is allowed to save the document, print, …). Some policies are for advanced integration, e.g. if you want to integrate with SIGNificant Client Apps.

<Policy>
<GeneralPolicies>
  <!--Is the client allowed to save the workstep document-->
  <AllowSaveDocument>0</AllowSaveDocument>
  <!--Is the client allowed to save the audittrail document-->
  <AllowSaveAuditTrail>0</AllowSaveAuditTrail>
  <!--Is the client allowed to rotate the pages of the document-->
  <AllowRotatingPages>1</AllowRotatingPages>
  <!--Is the client allowed to append a file to the workstep-->
  <AllowAppendFileToWorkstep>0</AllowAppendFileToWorkstep>
  <!--Is the client allowed to add append tasks to the workstep-->
  <AllowAppendTasksToWorkstep>0</AllowAppendTasksToWorkstep>
  <!--Is the client allowed to email the workstep document-->
  <AllowEmailDocument>0</AllowEmailDocument>
  <!--Is the client allowed to print the workstep document-->
  <AllowPrintDocument>0</AllowPrintDocument>
  <!--Is the client allowed to finish the workstep-->
  <AllowFinishWorkstep>1</AllowFinishWorkstep>
  <!--Is the client allowed to reject the workstep-->
  <AllowRejectWorkstep>0</AllowRejectWorkstep>
  <!--Is the client allowed to reject the workstep with reject type 'Delegation'-->
  <AllowRejectWorkstepDelegation>1</AllowRejectWorkstepDelegation>
  <!--Is the client allowed to undo actions-->
  <AllowUndoLastAction>0</AllowUndoLastAction>
  <!--Is the client allowed to colorize pdf forms-->
  <AllowColorizePdfForms>0</AllowColorizePdfForms>
  <!--Is the client allowed to add adhoc attachments-->
  <AllowAdhocPdfAttachments>0</AllowAdhocPdfAttachments>
  <!--Is the client allowed to add signatures which are not defined in the tasks-->
  <AllowAdhocSignatures>0</AllowAdhocSignatures>
  <!--Is the client allowed to add stampings which are not defined in the tasks-->
  <AllowAdhocStampings>0</AllowAdhocStampings>
  <!--Is the client allowed to add adhoc freehand annotations-->
  <AllowAdhocFreeHandAnnotations>0</AllowAdhocFreeHandAnnotations>
  <!--Is the client allowed to add adhoc typewriter annotations-->
  <AllowAdhocTypewriterAnnotations>0</AllowAdhocTypewriterAnnotations>
  <!--Is the client allowed to add adhoc picture annotations-->
  <AllowAdhocPictureAnnotations>1</AllowAdhocPictureAnnotations>
  <!--Is the client allowed to append adhoc documents-->
  <AllowAdhocPdfPageAppending>0</AllowAdhocPdfPageAppending>
</GeneralPolicies>
</Policy>
Workstep Tasks

Defines the tasks for the workstep, their sequence, if they are mandatory or optional, etc.

<Policy>
<WorkstepTasks SequenceMode="SequenceOnlyRequiredTasks">
  <Task id="d7bc173a-8b55-437c-92f6-d1c36eca47e9" type="FillFormsGroup" displayName="Fill in form fields of page 1" required="0"/>
  <Task id="c4ff144b-3d1d-4c0e-82d7-5d77a13774a9" type="FillFormsGroup" displayName="Fill in form fields of page 2" required="0"/>
  <Task id="3050fb49-ac84-4ca8-88ae-b076d061ade1" type="FillFormsGroup" displayName="Fill in form fields of page 4" required="0"/>
  <Task id="Signature" type="SignField" displayName="Sign signature field" required="0" completed="0" enabled="1"/>
  <Task id="Signature_2" type="SignField" displayName="Sign signature field" required="0" completed="0" enabled="1"/>
</WorkstepTasks>
</Policy>

See the full workstep configuration for details and description.

Finish Actions

Finish actions are executed, when the signature task is finished by the signer (includes also rejected). Please note that the server action is not available in eSignAnyWhere (it is required for the workflow management). The envelope callback or event-based callbacks were created as alternative. For advanced integration other clients can be configured too (e.g. WSI, SIGNificant Apps).

<FinishAction>
  <ClientAction CallClientActionOnlyAfterSuccessfulSync="1" RemoveDocumentFromRecentDocumentList="0" closeApp="0" clientName="SIGNificant SignAnywhere"/>
</FinishAction>