DocuSign Director

The DocuSign Director module, introduced in FormFusion verison 3.8, allows you to send FormFusion output as a PDF to DocuSign. DocuSign provides visibility into which users have opened a document, and allows you to request their signature on the document, based on a template that you configure in DocuSign.

In FormFusion 3.9, you now have the following new features:

• You have the option of using OAuth for authentication, in addition to authenticating with a user name and password.
• You have the option of using a Sandbox environment.

In order to use this Director, you must have a current license for FormFusion and have an account with DocuSign. If you would like more information on the DocuSign Director, please contact your Evisions account representative.

Configuring the DocuSign Director

The DocuSign Director screen contains three main sections:

• The Execute this Director section is common to all directors. For information on the Execute this Director section, please see the FormDirector page.
• The DocuSign Authentication section displays the currently selected type of authentication: OAuth or Username/Password, and the account name, once the connection is working. Select the Configure button to change the authentication method and the settings used for it.
• The Details section is where you configure the output.

DocuSign Authentication Settings

The DocuSign Authentication section of the DocuSign Director screen provides options for configuring the authentication method. When configured properly, authentication allows FormFusion to access the DocuSign account.

Before you can configure the authentication settings, you must establish your DocuSign account and decide how you want FormFusion to provide credentials to DocuSign for authentication and authorization.

• Use OAuth whenever possible. It is the most secure option, and is recommended by DocuSign. FormFusion uses the Authorization Code Grant OAuth method.
  
  If your account is inactive for approximately a month, your OAuth authorization expires. You can manually re-authenticate, or allow FormFusion to refresh the authentication on a scheduled basis.
• Use the Username and Password method if the OAuth method of authorization cannot be implemented.

DocuSign Configuration for OAuth Authentication

When you select the Configure button, a DocuSign Configuration dialog displays. Select the OAuth authentication type.

For information on selecting an Environment, see Selecting an Environment (Sandbox or Production).

Obtain the Integration Key, Secret Key, and Port information from DocuSign after you add FormFusion as an approved app in your DocuSign account.

• To add FormFusion to DocuSign, in the DocuSign Admin area, go to API and Keys at the bottom of the left menu, then select Add App/Integration Key. Enter a name for the app (i.e., "FormFusion").

Be sure to obtain the following information for the app so that you can enter it on the FormFusion configuration screen.

• Integration key - After you add FormFusion as an App in DocuSign, the Integration Key is displayed. Click on the Integration Key, then use the Copy to Clipboard button to copy the entire key. Paste the key into the corresponding field in FormFusion.
  
  Note: Make sure you copy the app's Integration Key, not the API Account ID above it.
  
  Continue on the same DocuSign screen to obtain the Secret key and Port information.
  
  
• Secret key - The Secret key is a type of password used with OAuth authentication. In the Authentication section of the DocuSign screen, select the Authorization Code Grant option, then select the Add Secret Key button. Copy the secret key. (Note that all but the last few characters in the secret key will be obscured the next time the key is displayed in DocuSign, after you save your changes.)
• Refresh after - The number of days between automatic refresh attempts. If you don't run the FormFusion template regularly (more frequently than about once a month), FormFusion will attempt to refresh the authorization token during FormFusion mapplet startup.
• Port - The port used for communication between DocuSign and FormFusion. On the DocuSign Add App page, enter the Redirect URI, http://localhost:, immediately followed by an open port number. (For example, http://localhost:8081.) The port number entered on the FormFusion dialog must match the port number entered on the DocuSign account page for the Redirect URI (8081 in this example).

DocuSign Configuration for Username and Password Authentication

When you select the Configure button, a DocuSign Configuration dialog displays. Select the Username/Password authentication type.

For information on selecting an Environment, see Selecting an Environment (Sandbox or Production).

Select the Username/Password method of authentication, and then enter the username and password:

• Username - The email address associated with your DocuSign account.
• Password - The password associated with your DocuSign account.

Obtain the Integration Key from DocuSign after you add FormFusion as an approved app in your DocuSign account.

• To add FormFusion to DocuSign, in the DocuSign Admin area, go to API and Keys at the bottom of the left menu, then select Add App/Integration Key. Enter a name for the app (i.e., "FormFusion").

Be sure to obtain the following information for the app so that you can enter it on the FormFusion configuration screen.

• Integration key - After you add FormFusion as an App in DocuSign, the Integration Key is displayed. Copy and paste the entire key into the corresponding field in FormFusion. You do not need to change any other API configuration settings in DocuSign.
  
  Note: Make sure you copy the app's Integration Key, not the API Account ID above it.
  
  
• Account ID - The account number of your DocuSign account. Note: If your user has access to multiple accounts in DocuSign, this account must be set as the default, since FormFusion will only look at the default account.

Selecting an Environment (Sandbox or Production)

As you develop your FormFusion director for DocuSign, you may want to test your configuration in an environment separated from your production environment. You can use the Sandbox environment for this purpose.

The URLs for the production and sandbox environments are pre-populated for you.

• If you are using OAuth authentication, the URL is the OAuth URL.
• If you are using a username and password for authentication, the URL is the base URL.

You can enter a different URL, if you wish.

• A custom URL is always shown as the sandbox environment.
• If using a custom URL, the environment will default to the sandbox environment.
• If you switch between the sandbox and production environments, the manually-entered URL is no longer available and is replaced by the default sandbox URL.

If you previously added a DocuSign base URL registry key to the MAPS server, FormFusion will use the registry key under the following circumstances:

• A director is opened for the first time after upgrading from Form Fusion 3.8 to 3.9
• A new DocuSign Director is created

If the URL is populated from the registry key, the Enviroment dropdown will be set to Sandbox.

Details Section: Output Settings

Use the Details section of the screen to configure how the output is processed.

• Template - The name of the template as configured in DocuSign. The template should be created based on a sample output file from FormFusion. You can use the Test Print Template feature to generate this sample, and then upload it into DocuSign to design the template.
  
  The template you create should have an equal or lesser number of pages than the document coming over from FormFusion. If all of your signatures are on the same page, a 1-page template is ideal. You can remove unnecessary pages when editing the template in DocuSign. Using the "AutoPlace" function to base the signature location on text found in the template will tell DocuSign which page of the document should contain the signature.
  
  Once the template is created (and you have entered your DocuSign credentials into FormFusion), use the Refresh button to update the list of templates in FormFusion. You can then select the desired template from the dropdown.
  
  
• Role - The role associated with the DocuSign template. Under the Add Recipients section in DocuSign, enter the name of the role you are creating in the Role field. Then, choose the desired recipient type in the dropdown on the right. FormFusion supports the Needs to Sign type (default), and Needs to View. Other types are not supported.
  
  Leave the Name and Email fields blank. These fields will be populated by FormFusion when sending the document.
  
  If desired, you can create more than one role in the DocuSign template; however, you will be required to select a single role when configuring the FormDirector since FormFusion only supports one role (one signature) per document.
  
  Once the template and role(s) are created in DocuSign (and you have entered your DocuSign credentials in FormFusion), use the Refresh button in the FormDirector to update the list of roles in FormFusion. You can then select the desired role from the dropdown.
  
  
• To - Required. The recipient of the email. This can be an email address typed in manually, or a FormFusion variable.
• Subject - Optional. The subject line of the email that will be sent to recipients. The subject can be typed in manually or use a combination of manual text and FormFusion variables.
• Key - Optional. Defines a string that an imaging system will search for within the PDF output. This key definition should exactly match the key configured in imaging system. Please refer to your imaging system's documentation regarding configuration of the key. The key field can include variables from MapForm or CaptureForm, using a colon preceding the variable name. FormFusion will place the generated key in "invisible" white text on every page of the output.
• Filename - Optional. The name of the PDF file to be sent to the recipient. You may use a variable as part of the filename. The .pdf file extension is not required. If this field is left blank, the filename will default to doc.pdf.
• Break pages on - Optional. Specifies how the DocuSign Director parses the output file into individual files. A MapForm or CaptureForm variable should be entered, with a colon preceding the variable name. In the figure above, the PONumber variable was created in either MapForm or CaptureForm. The value used for this variable must be present on each page of the output file and positioned consistently from page to page. Each time the PONumber variable changes, a new PDF will be created.
• Binary format - The output format of the document. This is always set to PDF for DocuSign. Use the Options button to configure PDF details such as document information, encryption, and file compression.

Troubleshooting

• Ensure that the Name and Email field for the selected role are blank in DocuSign (the role will not be visible if these are filled out).
• Ensure that the selected role is set to either Needs to Sign or Needs to View (the role will not be visible if another action is chosen).
• Roles will not be visible until a template is selected in DocuSign.
• You must save your changes in DocuSign before FormFusion can see them.