About Retrieve 3. Installing DocuSign Retrieve 4. Logging on to DocuSign 6

Transcription

1 Quick Start Guide DocuSign Retrieve 3.3 May 2018 Rev A Overview DocuSign Retrieve is a windows-based tool that "retrieves" envelopes, documents, and data from DocuSign for use in external systems. Retrieve runs on your system and can be run as one-time request or on a schedule. When run, Retrieve contacts DocuSign, and retrieves envelopes, documents, and information for those envelopes based on filters you set. Note: With v3.2, the DocuSign Fetch application was renamed DocuSign Retrieve. This guide provides information about: Installing Retrieve Creating, loading, deleting, and setting default Retrieve settings Using the Retrieve command line The DocuSign Retrieve application and Retrieve settings can be set up with the assistance of DocuSign Professional Services. Contact your Account Manager for more information about working with DocuSign Professional Services and Retrieve. About Retrieve 3 Installing DocuSign Retrieve 4 Logging on to DocuSign 6

2 Quick Start Guide Creating Retrieve Settings 10 Default Retrieve Settings 17 Loading Retrieve Settings 18 Deleting Retrieve Settings 18 Retrieve Command Line Information 19 For More Information or Assistance 21

3 3 About Retrieve Retrieve is a DocuSign product that allows you to download envelope information from DocuSign by creating Retrieve settings. Retrieve settings are "bookmarks" where you save search information. When creating Retrieve settings, you can select the date range and the envelope statuses to search, along with how and where to save the search results. You can save Retrieve settings for later use and use them to build a command line for scheduled tasks. You can configure the Retrieve output to meet your needs. You can have the output saved as a ZIP file, as separate PDF files or as a single PDF file. You can also specify where to save the output files. Many customers save files to some convenient location, and then have their back end system pick up the files from that location on a regular schedule. Additionally, if you want the data (such as envelope ID, date signed, custom information you added to the documents, etc.), then you can have Retrieve create and save an Index file (a CSV file) with this data. For example, you can have a schedule set to run Retrieve once per day to retrieve all of the completed, signed PDFs, for any envelope completed in the last 24 hours, and create an Index file with the values for the 20 custom fields you placed in those documents. DocuSign Retrieve was previously known as DocuSign Fetch.

4 4 Installing DocuSign Retrieve This topic describes how to install DocuSign Retrieve, including system requirements and other prerequisites. System Requirements DocuSign Retrieve supports the following Windows server, desktop, or laptop systems. The application may function on other configurations not listed here, but only the following systems are supported: Operating Systems Windows 7, SP2 Windows 8.1, Windows 10 Server Environments WinServer 2012 R2.NET.NET required Before installing Retrieve v3.3, you must uninstall any previously installed version. When you install v3.3, it recognizes and uses any previously saved configurations and settings.

5 5 Internet Communications - Security Considerations Retrieve securely connects to DocuSign's API servers via HTTPS. These servers reside at multiple public addresses hosted under "docusign.net". Example addresses include: na2.docusign.net, eu.docusign.net, and demo.docusign.net. Retrieve relies on its underlying.net framework for negotiating TLS/SSL versions and proxy configuration as described below. Contact your IT operations group before attempting to install Retrieve. DocuSign Professional Services can help answer any questions your IT operations group might have. TLS/SSL The.NET framework attempts a connection to a host using the highest level of TLS available. Should that fail, attempts are made to successively lower levels of TLS and SSL. Should all fail, Retrieve discontinues connection attempts. Proxy Server The.NET framework uses the proxy as configured and used with Microsoft Internet Explorer. You can override this behavior using.net configuration files. For further information, see Microsoft Developer Network <defaultproxy> Network Settings function.

6 6 To install Retrieve Once you have signed up to use Retrieve, DocuSign provides you with the DocuSign Retrieve zip file. To install Retrieve: 1. Uninstall any previously installed version. 2. Extract the files from the zip file. There are two files in the zip file: Release Notes DocuSignRetrieve.3.3Install.msi 3. Run DocuSignRetrieve.3.3Install.msi to start the installation. The setup uses an installation wizard to gather information and install Retrieve on your system. 4. Follow the wizard instructions to complete the installation. Logging on to DocuSign Note: Starting with v3.3, Retrieve uses Account Login for authentication.

7 7 When you open DocuSign Retrieve, the main window is shown. The Retrieve main window is used to configure Retrieve settings, which determine the envelope information that is searched for and downloaded, save Retrieve settings, select Retrieve settings, and to run the Retrieve process manually.

8 8 You must be logged on to a DocuSign account within a particular environment, such as Production or Demo, to take actions in the Retrieve main window. To log on to an account 1. In the Login Info tab, select the Environment to retrieve the envelope information from, and click Login. This will open a new window with the DocuSign Account Login interface.

9 9 Note: For advanced users only - If the selected environment is Other, enter the host server location in the Account Server Host field. 2. After you log in, the DocuSign environment you are logged on to is shown in the upper left of the Retrieve main window.

10 10 3. Retrieve can only retrieve information from one corporate account at a time. If you have multiple accounts associated with the login credentials, use the account dropdown list (adjacent to the Make Default button) to select the account from which information is retrieved. Creating Retrieve Settings Retrieve settings are "bookmarks" where you save search information (such as environment, passwords, and filters). You can then reuse a saved search repeatedly, without having to create a new setting each time. Define an Index output file As an optional part of a Retrieve setting, you can define an Index output file. The Index file data can include common information, such as a recipient's name or envelope ID, along with envelope custom fields and custom tags that are specific to each customer's use case. You can specify which data are included in the Index file in the Output Columns tab. This file is a CSV file that can be used to import data about envelopes and documents into your system. Follow the steps below to create a new Retrieve setting for your system.

11 11 To create a Retrieve setting 1. From Retrieve, log on to a DocuSign environment. 2. Select the account to use from the drop-down menu: Note: Retrieve can only retrieve information from one corporate account at a time. If you have multiple accounts, use the drop-down list (adjacent to the button) to select the account you want to check.

12 12 3. Set the output format and location information for retrieved files: a. Click the Output tab. b. Location. Type or select the location of where to save the files. You can browse to the location by clicking the folder icon. This folder can be on your workstation or on a server. c. File Save Format. Select the format for the saved file. The file can be saved as a zipped file, as one merged PDF, or as separate PDFs, with or without the Certificate of Completion. Or you can choose to save just the Index file with your document data output. d. File Name Format. Select how the saved files are named. The can be by envelope subject, envelope ID, or using one or more custom fields. If you select to use custom fields for naming the files, type the custom field name and click Add Custom Field. Remove custom fields by clicking on the field name and clicking Remove Custom Field.

13 13 4. Set the date range for the query. a. Click the Date Range tab. b. Type the Start Date Time and End Date Time for the setting. The default value for the end date is the current date. The default value for the start date is one week ago. All times are in Greenwich Mean Time (GMT). Important: DocuSign recommends you limit the extent of your date range. Large date range requests can take a long time to complete and result in very large files, and you should avoid using them if possible. 5. Set the envelope filter information. The filter process also allows you to limit the information retrieved. For example, if you only want to retrieve information for envelopes sent and completed by all

14 14 signers, you would select to include only envelopes Sent out to at least one signers that have changed status to Completed or Signed by all the signers. a. Click the Envelope Filters tab. b. Select the changed from envelope statuses (the check boxes on the left). Then select the changed to envelope status (the radio buttons on the right). You can select any number of changed from statuses, but only one changed to status. 6. (Optional) Set the Index output file information. The Index file is a CSV file containing the data from your envelopes that you specify in the Output Columns tab.

15 15 a. Click the Output Columns tab. b. Select a property in the Index Options column and use the green right arrow button to move it to the Index Fields column. To remove a property, select it in the Index Fields column and use the red left arrow button to move it to the Index Options column. Note: The information in the Index output file writes in the order shown in the Index Fields column (from top to bottom). Some of the options are explained here: Document - Date Signed. If you include the Date Signed field in your documents, then that data will write to the Index file.

16 16 Document - Title. If you include the Title field in your documents, then that data will write to the Index file. Document - Company. If you include the Company field in your documents, then that data will write to the Index file. Envelope Custom Field. Enter the envelope custom field name in the Custom Field Name field. Then then use the green right arrow to move the option to the Index Fields column. Envelope Custom Fields are set up in the DocuSign web application in the account Preferences. These entries are case sensitive. Document Custom Fields Enter the field's Label value (Data Label in the New DocuSign Experience) in the Custom Field Name field. Then use the green right arrow to move the option to the Index Fields column. Custom Tags are set up in the DocuSign web application in the account Preferences. These entries are case sensitive and must match exactly the Label entry. c. (Optional) Select Include Headers to include envelope headers in the Index output file. d. (Optional) Select Skip Missing to create CSV rows in the Index file only for envelopes with information in all of the selected index fields. If this option is not selected, a CSV row is created for all envelopes that meet your envelope filter criteria, even if an envelope does not have information for all selected index fields. In that case, the column for an index field that does not have information is left blank. 7. Test and save the setting information. a. To test a setting or run a setting, click the Test tab and then click Start Processing to download the envelopes that meet the criteria of the setting.

17 17 A Processing complete dialog box displays when the processing is completed. The dialog box shows the number of envelopes and documents processed by the setting. Click OK to close the dialog box. b. To save a Retrieve setting, click Save Settings. Type a Name for the setting and click Save. The setting is added to the Retrieve settings list in the upper portion of the Retrieve main window: Default Retrieve Settings A default Retrieve setting is the setting that is automatically loaded when a user logs on to Retrieve. You can only have one default setting at a time, but you can change this setting at any time. The default setting has a star adjacent to its name. You can make a Retrieve setting the default setting by selecting it in the upper portion of the Retrieve main window and clicking Make Default.

18 18 Loading Retrieve Settings You can load any previously saved Retrieve setting. Loading a setting allows you to use it to process your envelopes. To load an existing Retrieve setting 1. Log on to a DocuSign environment and if necessary, select the account to use. 2. Select the Retrieve setting you want to load in the upper portion of the Retrieve main window. 3. Click Load Settings. The selected Retrieve setting is loaded for use. You can run the setting, by clicking the Test tab and then clicking Start Processing to download the envelopes that meet the criteria of the setting. Deleting Retrieve Settings You can delete previously saved Retrieve settings. You cannot delete your default settings. To delete default settings, first select a new default setting. To delete a Retrieve setting 1. From Retrieve, log on to a DocuSign environment and select the account to use. 2. Select the Retrieve setting you want to delete in the upper portion of the Retrieve main window. 3. Click Delete Settings. 4. Click Yes to delete the setting.

19 19 Retrieve Command Line Information With the Retrieve Console Script Builder, you can display a script with the command line parameters associated with a selected Retrieve setting. You can copy the command line information to use it to schedule a task that runs the Retrieve process, which automatically runs Retrieve to download envelopes. Note: Retrieve v3.x supports command line scripts created in Fetch v1. Fetch v2 did not support command line information. (Fetch was the previous name for this application.) To schedule a task using the script for a Retrieve setting 1. In the Retrieve main window, log in, and create a new setting or load an existing Retrieve setting. 2. In the Retrieve main window menu, click Tools and select Console Script Builder. The Script Builder dialog box appears. The upper section of the dialog box shows the different command line parameter definitions and the lower section shows the command line information for the selected Retrieve setting.

20 20 Note: The username and password arguments are deprecated in v3.3. You no longer need to provide this information as Retrieve automatically manages it for you.

21 21 Note: The Script Builder converts the date range for the Retrieve setting into the span parameter, which sets the number of days for the search. For the Retrieve setting shown above, the system searches for envelopes that meet the filter criteria for the past month days (-31). a. Copy the command line information in the lower section of the dialog box and then close the dialog box. b. (Optional) Click Open Command Prompt to open a command prompt in a separate window and paste the command line information there to run the command. 3. Open the Windows Task Scheduler and create a new task. Name the new task and set the Triggers for the task. For the Actions, select Start a Program and paste the command line into the program/script field. Save the new task. 4. Close the Windows Task Scheduler. Your automatic download is set up. For More Information or Assistance For more information or assistance, visit DocuSign Support, the DocuSign Community, docusign.com, or contact DocuSign Support.