The SubmitWithFileRetrieval operation is used to launch an instance of a Template where a document has been created prior to the submission and is accessible via a URL. Any values passed as pre-fill information for the document will also be applied and be made visible to any signers of the document. The workflow and email designs attached to a template will be used, along with any dynamically populated information intended to guide the flow of the document.
The SubmitWithFileRetrieval operation may be executed using either the W3C standard Message Transmission Optimization Mechanism (MTOM) protocol or not. Using MTOM is not critical to the structure body of the communication, as opposed to the SubmitWithFile operation, as no document is passed in the SubmitWithFileRetrieval operation; however, the MTOM protocol environment is provided as a consistent parallel option to the options available in the SubmitWithFile method calls.
Note: AssureSign is configured to support documents that are a maximum of 2,000 pages in length (documents being parsed for Dynamic JotBlock text tags must be 250 pages in length or less). If an attempt is made to submit a document that exceeds this configured maximum, AssureSign will return an appropriate error message. See Defining JotBlocks Through Embedded Text Tags for information on attributes that may be set to increase the 250 page limit on a given document when only a subset of pages need be parsed for Dynamic JotBlocks.
The SubmitWithFileRetrieval operation requires knowledge of the following:
- the Template ID of the Template to use
- the AssureSign account ContextIdentifier (this is exposed in the AssureSign administrative application account settings and serves to provide some security to the transaction). The ContextIdentifier is in the form of a global unique identifier (GUID).
- the UserName of the AssureSign user that will be the owner of the document within AssureSign
- the defined parameters that are required to be filled in on the Template. Note that the count and content of these will vary depending on how you have set up your document template. For example, if your data supports passing the first and last name for a signatory, and your document template differentiates these as distinct data fields, then you will pass the values as distinct fields (named according to your own naming convention that you specified on the template); if your data only provides signatory names as full un-parsed values, then you may tailor the document template to receive data in a single parameter. The parameter names provided here must either match the user-defined parameter names provided when the parameters were created for the template or a pre-defined system parameter name (ex. “Signatory 1 Email Address”).
- It is also possible to pass parameters into AssureSign that are not defined in the template and do not map to any JotBlocks or workflow elements (signatory name or email, etc). These parameters can be passed into AssureSign in the same way that template parameters are passed in, and AssureSign will encrypt and store them as usual. While AssureSign will not make use of these “unbound” parameters, they will be available to be referenced as custom merge fields in DocumentTRAK designs to facilitate passing data through AssureSign.
- the publicly accessible URL of the document (including FTP and SFTP locations)
- any credentials required to access the document.
Alternatively, if the same username and password will be used for all requests, this default credential can be stored under the AssureSign settings area of the administration tab.
An optional password may be passed as an attribute within the Metadata element. If a password is specified, then access to the signed document will require knowledge of the password. If this document is being added to an envelope, a password should not be specified here as the completed document will be protected by the password set for the envelope. Signatory passwords protect a signing session; the document password passed in the metadata protects the completed document. Other important attributes in the Metadata are:
- the UserName of the AssureSign user that will be the owner of the document
- the name of the document (assigned by you for your purposes)
- an optional ExpirationDate, which is the date the document will expire. If not specified, the expiration date will be set based on the default expiration period for the account. If this document is being added to an envelope, an expiration date should not be specified here as the document will expire based on the expiration date set for the envelope.
- an optional OrderNumber, which is designed to provide you a way to store your unique order number or key to identify the document
- an optional Culture indicator used to specify the ISO-code for the culture (language) to use for displaying the document. If not specified or if language customization has not been enabled on your account, the template or account default will be used. Currently supported cultures are: en-US (English - US), es-US (Spanish - US), fr-CA (French - Canada).
- An optional SignatureDeviceSupportEnabled indicator used to specify whether or not support will be enabled for signing written JotBlocks using an external signing device. If not specified or if signing device support has not been enabled at the account level, the template or account default will be used. It is recommended that this be left off unless it is explicitly known that an external signing device will be used to sign the document.
- An optional EnvelopeId indicator used to specify the unique identifier of the envelope the document should be added to. If specified, the document signing process will not be started immediately as it will only be triggered after the envelope is closed.
An optional TermsAndConditions element may also be passed within the Metadata element. In order to use this element, your AssureSign account must be configured to allow customization of the standard terms and conditions; this setting may only be modified by your AssureSign account representative. This element may contain an AdditionalComplianceStatement child element, an AdditionalAgreementStatement child element and anAdditionalExtendedDisclosures.
Information passed in the AdditionalComplianceStatement element will be appended to any default system or account terms that have been set that appear at the bottom of the signing splash page, and will replace any terms saved on the template. Information passed in the AdditionalAgreementStatement will be appended to any default system or account agreement terms, and will replace any agreement terms saved on the template; this information appears within a box requiring signatory action and the combined statement is followed by an “I Agree” check box. Information passed in the AdditionalExtendedDisclosures will be appended to the account extended disclosures box (this scrollable box is not displayed unless your account is configured to allow customization of the standard terms and conditions and some text has been specified to populate this area).
These elements should not be used merely for passing messages or additional information to the signer. Any information you pass here will be recorded as having been agreed to by the signatory. The standard non-customized AssureSign agreement statement starts with “By checking the box below, I agree that …”; therefore, additional phrases you may add to address specific legal requirements of a jurisdiction or type of document in the agreement section should conform to this first person statement or not interfere with the clarity of the overall statement.
Sample XML
<?xml version="1.0" encoding="utf-8"?>
<SubmitWithFileRetrieval xmlns="https://www.assuresign.net/Services/DocumentNOW/Submit">
<Documents>
<FileRetrievalDocument ContextIdentifier="06C4A84A-693C-46CB-8DF2-40A8215AA056">
<Metadata UserName="georgeuser@company.com" DocumentName="John Doe Contract 2-15-2007" OrderNumber="7xe-123478" ExpirationDate="2007-04-13" Password="" Culture="en-US" SignatureDeviceSupportEnabled="false" EnvelopeId="EBB73445-AB39-CD1F-8AF5-BC06AB44E93A">
<TermsAndConditions>
<AdditionalComplianceStatement>
This information will be displayed at the bottom of the page and is being added for a specific jurisdiction by my code.
</AdditionalComplianceStatement>
<AdditionalAgreementStatement>
I acknowledge that all terms and conditions of this sale have been explained to me.
</AdditionalAgreementStatement>
<AdditionalExtendedDisclosures>
Longer extended disclosures are appended to in this section.
</AdditionalExtendedDisclosures>
</TermsAndConditions>
</Metadata>
<Template Id="DCB79445-4D39-DD11-8735-00065B8CE99B">
<Parameters>
<Parameter Name="Signatory 1 First Name" Value="John" />
<Parameter Name="Signatory 1 Last Name" Value="Doe" />
<Parameter Name="Signatory 1 Email Address" Value="john.doe@assuresign.com" />
<Parameter Name="Signatory 1 Password" Value="jdoe1234" />
</Parameters>
</Template>
<UnderlyingFileMetadata FileType="PDF" RequiresAuthentication="true" RetrievalMethod="BasicHttp" Url="http://yoursite/pdftest.pdf">
<Credential Username="jdoe" Password="" Domain=""/>
</UnderlyingFileMetaData>
</FileRetrievalDocument>
</Documents>
</SubmitWithFileRetrieval >The SOAP Action header is
https://www.assuresign.net/Services/DocumentNOW/Submit/ISubmitService/SubmitWithFileRetrievalThe Parameter elements are either the parameters you created to fill JotBlocks , or parameters that fill workflow items , such as signer information.
Using the SubmitWithFileRetrieval requires the including of an UnderlyingFileMetadata element which contains information needed to access the document remotely. Typically, “BasicHttp” will be specified as the retrieval method if the URL is accessed via http, https or ftp. If the file is to be retrieved via sftp, the retrieval method should be “Sftp”. An additional RetrievalMethod customized for Salesforce.com clients may be passed: “SalesforceApi”; please contact your AssureSign account representative for information on the integration possibilities available from within Salesforce.com.
The FileType attribute of the UnderlyingFile element should be one of:
- DOC
- DOCX
- RTF
- HTML
- HTM
- ODT
- TIFF
- TIF
Information will be returned that should be stored to allow future operations on the newly created document. In particular, the Document ID and AuthToken will be required to request any further operations on an active document. The Document ID and AuthToken returned are in the form of a global unique identifier (GUID). A GUID is a 128 bit value returned as a 36 character string including embedded dashes; there are a variety of ways to store these values depending on your environment, and subsequent calls requiring these values will accept them in a number of supported formats. Sample XML returned by the SubmitWithFileRetrieval operation is presented here:
<?xml version="1.0" encoding="utf-8"?>
<SubmitWithFileRetrievalResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/Submit">
<SubmitWithFileRetrievalResult>
<DocumentResult Id="2CE11EF1-8938-DD11-8735-00065B8CE99B" AuthToken="8CC9A84B-693C-46CC-4342-40A8215AD76A">
<Metadata UserName="georgeuser@company.com" DocumentName="John Doe Contract 2-15-2007" OrderNumber="7xe-123478" ExpirationDate="2007-04-13" Culture="en-US" SignatureDeviceSupportEnabled="false" EnvelopeId="EBB73445-AB39-CD1F-8AF5-BC06AB44E93A" />
</DocumentResult>
</SubmitWithFileRetrievalResult>
</SubmitWithFileRetrievalResponse>The DocumentResult should be checked for the presence of an Exceptions element, which may contain multiple DocumentException items.
Dynamic JotBlocks
Refer to the documentation on Defining JotBlocks Through Embedded Text Tags or Defining JotBlocks in XML for information on how to dynamically create or modify JotBlocks. When the document being submitted contained dynamic JotBlocks, the FileDocument element of the XML – which contains the ContextIdentifier attribute – must be modified to contain a ParseDocument attribute with value "true"; else, if this value is false or missing the document will not be checked for the existing of text tags.
