I have successfully implemented a system that creates documents to be signed via a template using the .NET API, and then has a DocuSign Connect listener that gets called upon the envelope being signed (right now only have Connect reporting on envelope signatures and declines). I have the option set to "Include Documents" on my DocuSign Connect settings. When I create the envelope for signature programmatically with one signer it all works - my Connect listener gets called, the /DocuSignEnvelopeInformation/DocumentPDF/PDFBytes element has Base64 data in it, and I have successfully decoded that and stored it in our doc management system. Cool. Demos well, management loves it.
However, I have noticed at least two scenarios where the /DocuSignEnvelopeInformation/DocumentPDF section isn't being returned at all:
When there are multiple signers.
When the envelope is created manually, even if it uses the same template.
I can still use the Connect response to get the /DocuSignEnvelopeInformation/EnvelopeStatus/DocumentStatuses and extract the document IDs from the DocumentStatus child elements, and then go retrieve those programmatically using the .NET API. But I am wondering why the PDF bytes aren't being consistently returned all the time? Is the above expected behavior? Am I missing something?
I would prefer to save "round trips" and just have Connect deliver all the signed PDFs to me when it calls (and yes, I have read the Recommendations for Receiving Documents section of the DocuSign Connect Guide and understand the trade-offs. Just wondering if I need to code around this issue, or what I am missing?
Hmmm. Envelopes don't get "signed," they get "sent" and "completed." See the envelopeEvents vs the recipientEvents lists in the Connect::Create call.
Currently, there is an existing issue which is that the connect daemon can miss an event if it is quickly superseded by another event. This might be what is happening when you have multiple signers for an envelope. The safest thing to do is to subscribe to all events and then ignore the notifications that are not of interest to you.
The terminal event of an envelope being "completed" will always be sent if you've subscribed to it.
Also, to make your app more bulletproof, I suggest subscribing to the Connect events via the API call (link is above) rather than depending on the human to setup up the subscription correctly. Since an account can easily have more than one connect subscription, you can track which one is your app's by using a specific name for the subscription.
Added
Just now, I created a Connect subscription for just the Envelope Completed event, for all users in my account on demo.docusign.net. As the subscription (listener) url, I used a free account from requestb.in
Using the web user interface (not the API), I created an envelope with two signers. After I completed the envelope, the requestb.in received the notification, it included:
<DocumentPDFs>
<DocumentPDF>
<Name>House architectural overview.pdf</Name>
<PDFBytes>....
as expected. So I'm unable to reproduce your problem. I suggest that you use requestb.in to double-check exactly what is being sent in the notification messages.
Related
In my returnUrl handler, I am using list documents.
In the returned array, how can I figure out if the document has been signed or not?
Thanks!
Your return url handler will be called with a query parameter event as discussed in Inbar's answer.
But you should not use the query parameter for making business decisions since a bad guy could easily call your return url and simply tack on an event=signing_complete query parameter--spoofing your application.
Instead, when your application needs to know if the envelope has been signed or not, it has two categories of options:
Ask DocuSign
Your app can call the Envelopes::get method to determine the current status of the envelope. Other API methods can also be used for this functionality.
Design your app such that you do not call DocuSign about a particular envelope more often than once every 15 minutes since such behavior is considered polling and is not allowed.
Webhook: DocuSign will call your app
You can set up a webhook with DocuSign so that the eSignature platform will call your application when the envelope is complete (signed by all the signers, etc).
Use the DocuSign webhook HMAC feature to guarantee that the notification message came from DocuSign (was not spoofed) and that it was not altered in transmission.
By using AWS or equivalent, you can easily receive the notification messages behind the firewall, with no firewall changes. And AWS will not charge you for the first million notification messages per month. See the connect-* repos on github.com/docusign
Dashboards
If your app wants to present a dashboard to a business decision maker about the status of your envelopes, then relying on the event query parameter is fine. But before your app does anything that costs real money, eg initiate goods or services to be provided to a customer, make sure that the envelope has been signed by using one of the two techniques above.
The URL you get back from DocuSign has an event parameter and looks like this:
http://www.acme.com?event=signing_complete
signing_complete means it was signed.
https://developers.docusign.com/esign-rest-api/guides/features/embedding has the full list of other events in the "Determining Recipient Action" section of the article.
We are doing an integration with DocuSign where users can submit documents stored in our system to DocuSign to get the documents signed. We have the DocuSign Connect feature working in our demo account. We can process messages from DocuSign successfully.
We were concerned that getting users to add a Connect Configuration themselves may be too challenging for some and it will be error-prone.
I see now in the documentation that it is possible to automatically get DocuSign to push notifications by passing the information in the EventNotification attribute when we call createEnvelope. Is this an acceptable way to get push notifications from DocuSign? Will this cause issues with getting the integration certified?
Is there any other way to get Connect configured easily in customer accounts?
This is an old question, but I wanted, for the record to have answers, since it's important to anyone who may be reading this.
We see now in the documentation that it is possible to automatically
get DocuSign to push notifications by passing the information in the
EventNotification attribute when we call createEnvelope. Is this an
acceptable way to get push notifications from DocuSign?
Yes, it is. It's a very good way in fact, to reduce polling and make your app better. We highly recommend that you use EvenNotification and sign-up for events going through a webhook to your app such that you can handle them in your code only when they occur, instead of polling DocuSign APIs repeatedly.
Will this cause issues with getting the integration certified?
The opposite is true. If you use polling you may have issues being certified. Using connect events with a webhook is one way to avoid the need for excessive polling which could cause issues with the certification.
Is there any other way to get Connect configured easily in customer
accounts?
You can configure connect like you suggested using EventNotification at the envelope level. This approach works well for ISVs since you don't need your customers to have admin access to their accounts.
The other option is account-level connect configuration, which does require admin level access and there are some other limitations. This approach adds the connect webhook for all envelopes in the account. So it may or may not be better, depending on your scenario.
I create a pdf on our system and then pass that to docusign for the user to sign. I want to automatically download and save the signed envelopes in our system. Is there a way for docusign to send a post request after the document is signed?
Right now, I randomly (every other hour) connect to docusign and check if the envelope is signed using the docusign api, but this is really not optimal. There are a lot of users who view the pdf in docusign and decide they don't want to sign the document.
The "DocuSign Connect" feature is designed to do exactly that -- send a POST to an endpoint you specify, in real-time, as specified Envelope events occur. Basically it works like this: you build a "listener" app (i.e., a web page that will receive POSTs from Connect), you configure Connect (within your DocuSign account (Preferences >> Connect) to specify the endpoint of your "listener" and select which Envelope events you want your listener to receive notifications for, etc., and once that Connect configuration is enabled, DocuSign will send a POST to your listener endpoint whenever the specified Envelope event(s) occur.
The DocuSign Connect Service Guide (https://10226ec94e53f4ca538f-0035e62ac0d194a46695a3b225d72cc8.ssl.cf2.rackcdn.com/connect-guide.pdf) describes Connect and how to configure/use it -- I'd suggest that you start by reviewing the guide, and post any additional questions here on SO if you run into any issues implementing Connect.
Currently I am using CONNECT API configured with my system.
Whenever DocuSign Envelope moves to Completed status, a POST request is generated to my system which contains:
DocuSign Envelope information
DocuSign PDF bytes ( Seperate PDF documents )
DocuSign certificate
I selected the option [X] Include Documents in Connect API and I am able to receive the PDF bytes.
Currently I am using PDFTK to merge all the documents into one.
But is there a way using Connect API to get all the Documents merged together as a one Single PDF document ?
Parallely while reading through the DocuSign REST API guide I came across /envelope/id?merge=true which would give me the required single PDF. But while digging deeper I came to know there is a concept called Integrator Key for each implementation, which would require a DocuSign Certification.
Inorder to just get a merged document instead of seperate PDF documents should I go through this certification process or is there a simple way to do the same ?
If Certification is Mandatory then what kind of certification would this fall in, because I have no front end application for signing process and I am just consuming the customer generated documents.
Using DocuSign Connect does not require an IntegratorKey or that you go through the DocuSign API Certification process. The Certification Process (https://www.docusign.com/developer-center/go-live/certification) and Integrator Key exist to ensure that DocuSign customers who utilize either the REST API or the SOAP API are not doing anything that could be harmful to the overall DocuSign service -- this is not relevant to DocuSign Connect, since Connect is merely pushing data to your listener when Envelope events occur (i.e., you're not explicitly polling DocuSign for changes, as you might with either the REST API or SOAP API).
I don't believe it's possible to configure Connect such that documents are sent merged together as one file; they're always going to be sent as separate files in the Connect message. It would be feasible to, during your processing of the Connect XML message, make a REST API call to DocuSign to request the Envelope's documents in a single file -- however, doing so would require that you use an Integrator Key, and that you go through the DocuSign API Certification process -- probably not worth the time, expense, and trouble, if there's another way for you to merge the files yourself.
In our DocuSign Demo environment, we noticed that when several envelopes were voided, we did not receive the corresponding connect events. We checked the connect logs and the envelope ID's are not listed. We checked the envelopes in DocuSign and verified that the envelopes were properly voided. We sent a couple more through and recieved the events successfully.
Has anyone else experienced this issue and if so, were you able to correct it?
I'd suggest you verify the following Connect settings via the DocuSign UI (Preferences >> Connect >> [Connect_Configuration_Name]).
Ensure that Allow Envelope Publish is selected:
Ensure that Envelope Voided is selected, and also that All Users Integrated is selected (assuming you want Connect to send notifications for all envelope void events, i.e., for all Envelope Senders)
Provided that the Connect configuration settings are specified as described above (and logs are enabled via the Enable Log checkbox), you should at least see the Envelope Id in the Connect Log file anytime an envelope is Voided (even if some connectivity issue prevented the message from actually reaching your listener). Also, keep in mind that the Log file only preserves the 100 most recent log file entries -- so if there have been more than 100 messages sent since the Envelope Void that you're looking for in the Connect log, it's expected that you wouldn't see that Envelope Id in the log file.
Working with enterprise support, we determined that our missing connect event problem was caused by using the 'Send on Behalf Of' feature. We were listing the authenticating user in the 'Select Users to Integrate', and needed to list the send on behalf of user.
Also, Require Acknowledgement is NOT mentioned here and can and generally does play into debugging connect issues.
Related article:
Docusign Connect retry frequency when require acknowledgement enabled