Scenario:
My application dynamically generates a contract (PDF) on-the-fly through the use of some base language and replacement variables from user data. That pdf is then sent to the DocuSign REST API with the list of recipients/signers/tabs which handles delivery of the agreement to the various parties.
Issue:
At times during the negotiation process for the contract, users may need to make edits to the agreement. My application has a correction interface where they're able to regenerate the original PDF and then have an action that allows them to update the existing envelope.
To perform these corrections, I'm currently using the following API Calls for a single correction:
getEnvelope to retrieve the current status and make sure the envelope hasn't been voided, completed, etc.
deleteEnvelopeDocuments to remove all existing documents.
updateDocuments to send the base64 encoded document to the envelope.
updateEnvelope to send the recipients back to the envelope because they're deleted as a result to #2.
These 4 API calls feel like a mistake to me because if any one of them fails for whatever reason, the entire process fails. In addition, the processing time for the back-and-forth is also a consideration even though I could delegate that to a queue'd background process.
My Question (I know, finally)
Is there a better way to do what I'm trying to do? Perhaps I can skip #1 and just catch an exception thrown by DocuSign when attempting to update a completed / voided envelope. What I'm really interested in knowing is if I can consolidate #2-4 into a single call somehow. The API doesn't feel super clear on corrections and also doesn't send any notifications when an envelope is updated via the API.
I think this can be done with two API calls instead of four.
You can make a PUT call to replace a document
PUT .../envelopes/<envID>/documents/1
This API replaces an existing document, there's no need to do 2+3 separately.
This would eliminate the need to do #4 as well, because the tabs (not recipients as you stated) are not going to be removed if you don't delete the document but simply update it.
Related
I'm performing a DocuSign integration with a FileMaker solution to send signature requests via email, and receive a copy of the signed document once completed. I'm using the Java SDK to email signature request, as well as a Javalin app process to listen for the completed signature event, as well as more Java to pull the document back into FileMaker.
When the completed document is sent to my listener and pulled in, the document lacks a signature and tab field. It essentially looks just like the pdf document before being sent.
I have a feeling there's a variable I can tweak in some object to allow the signature to appear after being signed. I've played with all the usual suspects (e.g., eventNotification.setIncludeDocumentFields("true")), but nothing seems to do the trick. Any hints?
Aside from looking through the code for every object I'm instantiating and trying different variations, it's hard to pinpoint the exact source of failure in this. Thanks for any leads!
Sounds like you're receiving notifications by either including the eventNotification object in your Envelopes::create call or are using Connect at the account level. Either way, that's great, that's exactly right.
You can request notifications at many different points along the processing route of the envelope. To receive signed documents, you'll want the notification when the envelope is completed. At that point all signer recipients have signed.
To receive the notification when the envelope is complete, either adjust your Envelope Send parameters (the eventNotification value) or the settings for Connect (via the Admin tool), whichever one you're using.
We have a service integration with docusign. The envelope is created, in Draft mode, with API key A. Key A is already live in production.
We have a custom script that applies a template to the already created envelope and populates some mail notifications (custom) using API key B. Key B is a non-live key.
Each invocation, omitting the call for retrieving the base URL, the custom script (Key B) makes four calls for a particular envelope:
Apply template : POST
Get recipients : GET
Update recipients : PUT
Delete recipients : DELETE
At the end of this operation the updated envelope would still be in Draft mode.
Now, we make around 7 - 8 invocations of the custom script, each time for a different envelope, which gives us around 28 API calls and then try a key review. But every time it fails.
We're pretty sure that we are not crossing the hourly API call limit. Key B is not used elsewhere as well. Also, there're no repetitive GET requests to the same envelope endpoint.
The calls are made using standard java libraries. No SDK.
Is the sequence of calls made not a valid one?
Is there something we're missing here? We're sure that the key being used in script and the key we're trying to promote are the same.
Any help is appreciated.
In general, specific questions about the DocuSign Go-Live process should go to go-live#docusign.com. There is more information about the process here - https://developers.docusign.com/esign-rest-api/guides/go-live
Few questions about PowerForms
What is the real advantage of using PowerForms? In which case(s) it is most useful?
In Docusign Classic View >> PowerForms, there is an option to download Form Data as XML and CSV. Can we download this data using APIs?
For this question, I referred this thread "Can We get a report for the values filled in radio button in DocuSign Envelope".
PowerForms are an easy way of referencing a DocuSign Template through the API without writing any code. They are intended for less technical end-users who want to quickly access a Template through either email delivery or through a direct link (URL) but don't know / want to code it up. Instead they manually initiate such requests through a created PowerForm.
With regards to the form data question- yes, you can programmatically retrieve the form data through the API. You need to keep in mind that DocuSign tabs (aka fields) are always with respect to recipients and not the document itself.
Therefore, you can make the Get Tab Information For Recipient API call (REST version linked).
While working on a DocuSign embedded signing process (which has worked in the past), I noticed that after signing the document the 'event' parameter was missing from the 'returnUrl' I was being sent back to.
The returnUrl looks like:
http://www.example.com/index.php?param1=value1 ... ¶m10=value10
The parameters were being passed on returning from signing, but no event=signing_complete parameter was being added. I tried removing the parameters, and suddenly the event parameter returned.
After further experimentation, I discovered that the returnUrl parameter has a 500 character limit. Anything more is truncated. This will also truncate the event parameter from the end of the returnUrl.
This does not seem to documented in the DocuSign REST API documentation (https://www.docusign.com/p/RESTAPIGuide/Content/REST%20API%20References/Post%20Recipient%20View.htm).
So, is this a feature or a bug? Other than using session or database storage, is there a recommended workaround for the 500-character limit?
There might be some limits to the URL that is being passed in by the web servers themselves. I have not seen a lot of people hit this limit because probably most of the time folks do not put that much information into a return URL.
If you are coming from software that has session state you can use the following technique:
1) add the information you were previously sending via URL to a dictionary or a collection object and save it in the session on the server. Follow the best security practices for that one so that this information can't be easily accessed (there is a ton of material on how to do this properly and it's probably beyond this answer)
2) in the url instead of all the keys and values just provide the key to your collection.
3) upon return from DocuSign look up the object and retrieve the passed in information.
If there is no state in your software you can try using other properties of the envelope to put the additional information such as envelope custom fields. You can populate those on create and you can retrieve the information back when the control comes back to your software. Here is the article about custom fields: https://www.docusign.com/p/RESTAPIGuide/RESTAPIGuide.htm#REST API References/Get Envelope Custom Field Information.htm
I want to make sure I am on the right track as I have been having some problems getting started with the API. I am looking to maintain a list of product application PDFs as templates on docusign. When a customer comes to our site and wants a particular product they need to fill out an application form. All the data would be collected on our site. I would then want to:
Create an envolope with the customer (and potentially other parties) that need to sign the document
Fill in the form fields from data collected on our site
Send the envelope out for signature and monitor the progress.
So in doing this I am trying to build this up a piece at a time and first task is to make sure that I can provide form data to docusign. I create a template with the docusign web user interface and all of the form fields seem to be preserved. However when I try and retrieve the template with API
https://demo.docusign.net/restapi/v2/accounts/xxxx/templates/yyyy
I see a very short response with an envelopeTemplateDefinition showing the correct name for the template but no documents object and no custom fields object. I have also tried this by creating an envelope with the document (in draft) but with similar results.
My apologies in advance for this newbie question.
I've repro'd the issue you describe -- i.e., the Response I get from a GET Template request contains only very limited information and is thereby not consistent with the expected Response as documented on pages 194-196 of the DocuSign REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf). Not sure if this is a bug with the GET Template operation or with the Documentation -- someone at DocuSign will need to confirm (#Ergin).
In light of this limitation with the GET Template operation, you can alternatively retrieve the recipient information (including tabs) and document information about a Template by using the GET Envelope Recipients and GET Envelope Documents operations -- just specify the TEMPLATE Id in place of the Envelope Id, as shown here:
GET https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/{templateId}/documents
GET https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/{templateId}/recipients?include_tabs=true