Retrieve – Managing downloaded filesNOTE: Much of this article expands on concepts initially covered in the Retrieve Quick Start Guide. If you have not already read this guide, we recommend doing so first. You can find the latest copy of the Retrieve Quick Start Guide.
To understand how Retrieve handles downloads, we first need to understand the options available for file formats.
The Output tab within Retrieve allows you to choose where files are downloaded to, what format they’re downloaded in, and what naming structure is used for the files.
Retrieve offers four file formats, with or without a certificate (for a total of 8 formats). All download options will also include a .CSV (Comma-Separated-Value) file with a summary of what was downloaded. Selections made under the Output Columns tab control what information included in the CSV file.
- Save as one Zip – This saves the documents within each envelope as a .zip file. The .zip file uses the naming convention selected by the File Name Format. The documents inside that zip keep the same names they had when they were sent.
- Save documents as one merged PDF – This creates one PDF file for each envelope. If an envelope had multiple documents in it, we merge them together as one large PDF. The file name will be determined by the File Name Format selection. Choosing the With Certificate option here will add the Certificate of Completion to the end of the PDF.
- Save documents as separate PDFs – This behaves in the same manner as the Save as one Zip option. However, the folders created are not zipped. As above, the folder will use the File Name Format rules, and the files inside the folder will retain their original names from when they were sent for signature.
- No PDFs – This downloads only the .CSV summary file, and not the envelopes themselves.
Viewing the Results
When you open the folder that you chose to download the results to, it will contain all of the results that matched the criteria set under the Date Range and Envelope Filters tabs. If you selected the “Skip if Missing” box under Output Columns, then envelopes lacking one or more of the pieces of information in your Index Fields area will not be downloaded. In the previous screenshot, we selected the format of “Separate PDFs with Certificate”, and “Use Envelope ID”. Here are the results:
Since “Use Envelope ID” was selected as the File Name Format, each folder is the Envelope ID of one of the downloaded envelopes. Inside that folder, we see a PDF for each document, and a separate “Summary” PDF (the Certificate of Completion).
Frequently Asked Questions
Q: I selected the wrong format or output columns. When I choose the correct settings, nothing downloads!
A: Retrieve is set up to not re-download the same envelopes multiple times, unless the status of the envelope has changed from the last time it was downloaded. This is done because each DocuSign account has a limited number of API calls it can make each hour, and Retrieve uses DocuSign’s API to pull data. If you go over the API call limit, you end up having to wait until the top of the next hour to pull more information.
Retrieve keeps track of what you’ve already downloaded by creating a hidden file on your computer. Knowing this, there are a couple of ways to pull the same information that you’ve already pulled previously:
- Change the location you save your results to. The hidden file is saved in the same folder that the results of a search are saved to. Save your search to a different folder, and a new hidden folder is created there to track what’s been downloaded to that folder.
- Delete the folder that you saved your previous results to, and re-create it. The end result looks the same to Retrieve as the first option. Simply deleting the contents of the folder won’t be enough, since you can’t delete hidden files unless you can see them, or you delete the folder they reside in (see #3 below). If you delete the folder completely, that takes the hidden file with it. Create a new folder with the same name, and your next search that saves to this folder will have no history filtered out.
- Configure your computer to show hidden files, and you’ll be able to interact with the hidden file in question. For directions on how to show hidden files in Windows, see the following Microsoft Support article:
WARNING: Microsoft uses hidden files and folders to protect portions of Windows from accidentally being moved or deleted. While DocuSign can confirm that modifying the .downloaded folder created by Retrieve won’t harm your computer, we cannot speak for any other hidden files or folders. Please use caution when interacting with any files or folders that are normally hidden.
Once revealed, the icon for a hidden file or folder will appear fainter than other icons.For Retrieve, the name of the folder in question is .downloaded.Once you can see the folder, you can delete just that folder.This will remove Retrieve’s records of what’s already been downloaded, giving you a fresh start for your next search.
Q: The results from my Retrieve search didn’t contain a specific envelope I was expecting.
- Using the process in option #3 above, you can also edit the contents of the .downloaded folder. Inside that folder, Retrieve creates a .txt file for each envelope (using the Envelope ID as the name). You can delete individual .txt files from the .downloaded folder to allow specific envelopes to download again, while leaving others alone to prevent them from re-downloading.
A: There are a few different reasons this could happen. Here is a checklist of some of the most common causes:
Q: How do I tell if I have the latest version of Retrieve?
- It was already downloaded in a previous search saved to the same folder. This is addressed by the previous question, and can be easily tested by changing the output folder to a new one that you haven’t used with Retrieve before.
- The Date Range didn’t include the correct date. As covered in the Retrieve Quick Start Guide, Retrieve dates and times are GMT, rather than your local time. Be sure to account for this time difference on the Date Range page. Also note that GMT doesn’t change when Daylight Savings time changes. If you live in a place where Daylight Savings Time is used, your GMT offset will be different depending on whether the desired date range was during Daylight Savings Time or not. For example, if you want to find envelopes that were Completed on August 20th, 2017 (Eastern Time), you would set your Date Range to be “8/20/2017 4:00:00 AM” to “8/21/2017 4:00:00 AM”. Since August 20th is during Daylight Savings Time for the United States, the GMT-offset is -4. This means that the Eastern US is 4 hours behind GMT. So, Midnight Eastern time is 4 AM GMT. Thus, Midnight-to-Midnight Eastern Daylight Time would be 4 AM to 4 AM GMT.
- The Envelope Filters were set in a way that excludes the envelope. The Envelope Filters and the Date Range work together. Since an envelope can have vastly different dates associated with it, Retrieve handles this by searching for envelopes where the event chosen in the Envelope Filters tab occurred within the times selected under the Date Range tab. The left column is the status the envelope was in before the change, and the right column is the status the envelope entered. For most standard searches, you would leave all of the options in the left column unchecked, and only select the status in the right column that the envelope reached. Using the example above of all envelopes Completed on August 20th, 2017, you would leave the left column blank, and select “Completed or Signed by all signers” in the right column. This means that Retrieve will pull all envelopes that reached the Completed state, within the times set under the Date Range tab, no matter what state they were in before they became Completed.
- The “Skip If Missing” box was checked under Output Columns. As mentioned under “Viewing the Results” above, checking this box means that any envelopes that don’t contain one or more of the fields under the Index Fields area will be excluded from the results Retrieve pulls. It is advised that you only use the “Skip If Missing” box if you have a well-established workflow that uses a template, and you are only trying to pull data for that specific workflow.
- The envelope in question was not sent from the account you logged in to. Retrieve is only able to pull data for envelopes that were sent by a user on the DocuSign account it is connected to. If you manage multiple DocuSign accounts and the envelope was sent from one of those accounts, you will need to connect Retrieve to that account before it can pull the envelope. If the envelope in question was sent by a different organization, Retrieve will not be able to pull that envelope, even if a member of your account was a signer on that envelope.
A: Use link at the top of this article to the Retrieve Quick Start Guide to find out what the latest version of Retrieve is. Any time DocuSign releases a new version of Retrieve, we will update the version number of the Quick Start Guide, and we update the guide itself to reflect any changes to the program.
The version number of Retrieve is included in the program’s file name by default, and is also displayed in the upper-left corner of the program’s window. You can also find the version number by going to Help > About in the program itself.
Q: How do I get the latest version of Retrieve?
A: Each iteration of Retrieve is built as a stand-alone product, and does not automatically update. If you find that you do not have the latest version of Retrieve, you will need to contact your DocuSign Account Manager to request the download link for the latest version. Once your Account Manager verifies that your company’s contract includes Retrieve, they can send you the link to the current version of Retrieve.
Q: I believe I have encountered a bug with Retrieve. What do I do?
A: We first recommend that you make sure you are using the latest version of Retrieve. Fixes for any bugs reported in earlier versions of Retrieve would be included in the latest release. So, if you are not using the latest version, we may have already fixed the issue you’re seeing!
If you’ve updated to the latest version (or confirmed that you’re already using the latest version), then we recommend that you contact DocuSign Support for assistance. Our Support team can help investigate the behavior, and will file a report with our engineers if we confirm that there is an issue with the program.
If the issue is with a specific Envelope, be sure to have the Envelope ID handy, as Support will need that to investigate. Contact Support