AssureSign: SubmitWithFile

Code Sample in C#

The SubmitWithFile operation is used to launch an instance of a Template where a document is sent in the communication. 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 SubmitWithFile operation may be executed using either the W3C standard Message Transmission Optimization Mechanism (MTOM) or by converting the document to a Base64 encoded string and including it in the document. Using MTOM, the document is passed in its original raw binary form using XML-binary Optimized Packaging (XOP). Non-MTOM enabled clients may use the process of encoding the document contents and including the data as an additional element in the XML.

MTOM SubmitWithFile operations are sent to

• /Services/DocumentNOW/v2/DocumentNOW.svc/Submit/mtom

Non MTOM SubmitWithFile operations are sent to 

• /Services/DocumentNOW/v2/DocumentNOW.svc/Submit/text

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 SubmitWithFile 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.

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

Sample condensed XML using the non-MTOM method is presented here:

<?xml version="1.0" encoding="utf-8"?>
<SubmitWithFile xmlns="https://www.assuresign.net/Services/DocumentNOW/Submit"> 
    <Documents> 
        <FileDocument 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> 
            <UnderlyingFile FileType="PDF"> 
                <Data> 
                [file contents here]
                </Data> 
            </UnderlyingFile> 
        </FileDocument> 
    </Documents> 
</ SubmitWithFile>

The SOAP Action header is

https://www.assuresign.net/Services/DocumentNOW/Submit/ISubmitService/SubmitWithFile

The Parameter elements are either the parameters you created to fill JotBlocks , or parameters that fill workflow items , such as signer information.

Different than the Submit operation whereby no document is passed, using the SubmitWithFile requires the including of an UnderlyingFile element which references, within the xop:Include element, the data passed as an attachment within the SOAP message. A more detailed example could be provided, however an explanation of MTOM at a detailed level is beyond the intended scope of this document. Please refer to W3C documentation and your client environment documentation for a better understanding on how this may be implemented from within your unique network environment.

The FileType attribute of the UnderlyingFile element should be one of:

• PDF
• DOC
• DOCX
• RTF
• HTML
• HTM
• ODT
• TIFF
• TIF

Using either the MTOM or encoded text method, 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 SubmitWithFile operation is presented here:

<?xml version="1.0" encoding="utf-8"?> 
<SubmitWithFileResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/Submit"> 
    <SubmitWithFileResult> 
        <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> 
    </SubmitWithFileResult> 
</ SubmitWithFileResponse>

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.