Callback Model (Legacy QFE 5.4)

The Callback E-Sign Integration is for customers who want to use Quik! Forms directly with DocuSign without having to play a part in calling the DocuSign APIs to kick off the signing process. This methodology was specifically designed for customers using SalesForce.com and similar systems where it is difficult or impossible to intercept a POST from the form in order to call the DocuSign APIs.
While this method will start the e-signing process, customers will still need to call the DocuSign APIs for other functions (e.g. to check for status, to download the final signed document, etc.). The assumption in this model is that the customer has an existing account with DocuSign and sets up an OAuthToken (see next section on setting up the OAuthToken) with Quik! to call the API on behalf of the customer. An OAuthToken can be established via web service or manually by request.
This integration method is mostly be used by retail or individual customers, or enterprise-level customers who need a streamlined method to start the envelope process (e.g. SalesForce users).

Process Flow

The above graphic shows the basic architecture of how a callback transaction works.

How To Use the Callback Method

You must set up the following components to use the Callback method:

OAuthToken – Set up a token by request or via web service call (use ApplicationID = 3): https://websvcs.quikforms.com/Docusign/ESignWSVersion/5400/OAuthToken.asmx
1. Use ApplicationID = 3 (Quik! Forms Engine application ID)
2. Set the SignEnvironmentID (see values below) and set up an OAuthToken for each environment you're actively using. For help with which environment you use, see: https://www.docusign.com/results?qu=post%20api%20certification
  1. 1 for DocuSign production accounts on NA1 (www.docusign.net)
  2. 2 for DocuSign DEMO accounts (demo.docusign.net)
  3. 3 for DocuSign production accounts on NA2 (na2.docusign.net)
  4. 4 for DocuSign production accounts in Europe on EU1 (eu1.docusign.net)
  5. 5 for DocuSign Preview accounts (preview.docusign.net)
Set up a URL on your application or server to receive the DocuSign EnvelopeID
In the Quik! Forms Engine assign your Callback URL to the SignCallBackURL property.
OPTIONAL: Call the Quik! web service to retrieve the DocuSign EnvelopeID using the QFVUNID (unique form transaction ID)

Callback Web Service URL:

https://websvcs.quikforms.com/Docusign/ESignWSVersion/5400/ESignWithOAuthToken.asmx

Detailed Method Steps

Here are the basic setup steps for this method:

Use the following settings in the Quik! Forms Engine:
1. HTMLShowButtonSign set to TRUE
2. SignSubmitCombined set to TRUE to make the e-sign SEND button event first invoke the Submit event and Submit URL before starting the signature process. The Submit validation for required fields will also be triggered but a failed validation will not stop the signature process using the default Submit Javascript.
3. SignCallBackURL is a customer-defined URL for the Quik! Form to post the EnvelopeID to so customer's system knows the transaction is complete (i.e. Step 6 in the graphic in this parent page).

NOTE: If the SignCallBackURL is set then the SignURL value, even if set by you, will automatically be set by the Quik! Forms Engine to this URL: https://websvcs.quikforms.com/DocuSign/ESignWSVersion/5400/GetDocuSignEnvelopeID.aspx

1. Set the SignEnvironmentID and set up an OAuthToken for each environment you're actively using.
  1. 1 for DocuSign production accounts on NA1 (www.docusign.net)
  2. 2 for DocuSign DEMO accounts (demo.docusign.net)
  3. 3 for DocuSign production accounts on NA2 (na2.docusign.net)
  4. 4 for DocuSign production accounts in Europe on EU1 (eu1.docusign.net)
  5. 5 for DocuSign Preview accounts (preview.docusign.net)
2. In step 6, the customer's SignCallBackURL will receive the EnvelopeID and then respond to the form in JSON format with any status message to display or an event to invoke (e.g. redirect the user to a new window, update the form with data, display a message, etc.)
3. Alternatively the customer can set the SignSendJavascript property to override the default javascript associated to the e-sign SEND button in order to use the customer's own javascript.
The user clicks the "Sign" button, which captures the envelope data needed for signing.
1. The Sign button event displays the Quik! Form's e-sign popup screen.
2. User enters relevant envelope data and clicks the SEND button.
3. The SEND event posts the form data directly to Quik! (https://websvcs.quikforms.com/DocuSign/ESignWSVersion/5400/GetDocuSignEnvelopeID.aspx)
Quik! starts an envelope with DocuSign
1. The customer must have previously set up an OAuthToken with Quik! and DocuSign (only once per CustomerID!) using the OAuthToken web service (https://websvcs.quikforms.com/Docusign/ESignWSVersion/5400/OAuthToken.asmx)
2. Quik! uses the form's QFVUNID to lookup the Customer's OAuthToken stored by Quik! and then calls the DocuSign REST API to start the envelope
DocuSign responds with the EnvelopeID
1. The EnvelopeID is stored with the QFVUNID in the Quik! system for later retrieval by the customer via web service as a backup method for retrieving EnvelopeIDs.
Quik! responds to user's Quik! Form (HTML window) with the EnvelopeID in JSON format.
The user's Quik! Form posts the EnvelopeID to the Customer's SignCallBackURL in JSON format along with any status message returned by the signing process
1. The HTML form's SEND event does a callback to the SignCallBackURL with the EnvelopeID.
2. The customer's SignCallBackURL receives the EnvelopeID and should then respond in JSON format to the user's form with a status message, a javascript command to run to initiate the next action or redirects the user to a new page.
Customer independently downloads the envelope and documents from DocuSign
The customer will be able to access/sign the form by logging into their DocuSign account.

Setting Up OAuth Tokens

In order for users to sign, the Quik! Master Account must be setup with an OAuth Token for the user/customer's DocuSign account (partners will need to set up OAuth Tokens for each of their customer accounts). You’ll need to set up the OAuth Token using our web service (API Ref Guide): https://efficienttech.atlassian.net/wiki/pages/viewpage.action?pageId=34144315

Partners

Partners who offer Quik! to multiple customers will need to address how each of their customers will set up OAuth tokens on their Quik! accounts. The ideal solution is for the partner to build a user interface that asks the customer to enter their DocuSign credentials which you pass to our CreateOAuth2Token web service to establish the token. Quik! does not store the customer credentials, just the token which never expires. This enables customers to change their DocuSign password without affecting their integration with Quik! and you don’t have to manage their credentials, per se. In your user interface you need to ask the user to identify their DocuSign environment (NA1, NA2, Demo, etc.). The most reliable way to determine the DocuSign environment is for the user to login to their DocuSign account and to look at the DocuSign URL after they log in – if the URL begins with “www” then NA1, if “NA2” then NA2, etc. Most DocuSign users are on NA2.

For an example of how Quik! has built a similar user experience, please see this page (you’ll be prompted to log in – then go to the ESign Setup page): https://qcc.quikforms.com/QFLM/ESignSetup.aspx

Callback JSON Format

When you build your web page to receive the EnvelopeID you'll need to respond to the form in JSON format. The format is as follows:
"{"StatusCode":"0","StatusMessage":"Quik request to CallBack URL successful."}"
The StatusCode of 0 tells the form that the event was successful, any other code is a failure. The status message can be anything you want to display to the user.

Hosted Callback Endpoint

In certain cases you may want to kick off DocuSign without doing your own integration with DocuSign (i.e. to check the status of an envelope or to download signed documents). If you don't need to do anything with the DocuSign EnvelopeID that the Callback method returns then you may want to use our hosted endpoint for the callback method. Our hosted URL will simply return a message that the DocuSign envelope has been started. Use this URL at your discretion.

Hosted Callback Endpoint https://websvcs.quikforms.com/Docusign/CallbackEndPoint/CallBack.aspx