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.
Related
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.
I've been working on an integration that sends an envelope to 2 signers. I am trying to test and program for the case of 1 of the signers having a bad email address. I would need to:
Be notified of this (webhook?)
Update the email address for the signer
Update the email address in the custom fields as that's printed on the agreement
Resend the envelope
When I enable the delivery failure notification in Connect (this is set up at the account level, for now), I don't see where the failure is noted in the webhook response or for which signer the error is happening.
I've found multiple links via Google talking about "correct and resend" but I haven't been able to get anything definitive in terms of what steps need to be taken or a (PHP) code example. I've also found "resend" in the API reference but still no code examples.
I also haven't seen any code examples (PHP) of how I would update a signer's email address and how that would work via the API.
It'd also be good to know how to update custom field data for both signers so the email address in the contract is updated (it's listed separately as part of the custom form data).
And finally, how would I resend the envelope?
Thank you for your thoughts.
Per DocuSign support (customersupport#docusign.com):
Be notified of this (webhook?)
I have updated your account settings and now you should be able to see AutoResponded in your webhook messages when email invalid or unreachable.
(my comments: so it sounds like you have to ask to be able to see this stuff, it's not part of their standard webhook responses)
Update the email address for the signer
I also haven't seen any code examples of how I would update a signer and how that would work.
Unfortunately we don't have an example for recipient update but the logic is to get list of all recipients, pick the one need to be updated, and update.
You can use below to retrieve all recipients per envelope
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/list/
GET /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
Extract the one you need to update edit email and update using the below
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/update/
PUT /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
You can also see example code in C# how to do this in this thread https://github.com/docusign/docusign-csharp-client/issues/307
Update the email address in the custom fields as that's printed on the agreement
There is bug case created ( above link ) regarding this. At the moment you can not update signer custom fields case EC-2944.
Resend the envelope
You can resend the envelope during recipient update
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/update/
PUT /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
My commentary:
Since custom fields can't be updated, this whole use-case goes out the window. We can't have contracts with incorrect data on it, so my client will have to do these corrections by hand. Kind of a bummer.
I've been working with a docusign integration into our own application for a while, and recently I've started encountering a new error that I've never experienced before. I create a docusign envelope using Docusign's own interface, add my recipients, set up the signing fields, and then click send.
An email goes out to the users with a link for them to sign the document, as expected. But simultaneously, there is another email that says the following:
[My User] has corrected [My Document].
As a result, you no longer have access.
I click on the link for signing the document, and it results in the following:
In theory, this makes sense. If an envelope is edited or corrected, then the previous links are no longer valid. However, the envelope is never being corrected. It is created and sent in a single action. There isn't even time for a correction to be made. I'm the only person with access to the account, so no one else can be making corrections to the envelope. Additionally, this only seems to occur for certain recipients. Some recipients are fine, and this correction thing doesn't occur. For others, it happens and breaks the entire chain.
What could be causing Docusign to do this? I'm working with a developer account if that makes any difference. The only recent change that was made to my configuration is the addition of Connect with HMAC signatures to verify the validity of docusign responses back to my application. Even so, most of the time things seem to work exactly as intended and expected.
I am implementing a listener for Docusign event notifications. For each new event Docusign sends a new xml serialized DosuSignEnvelopeInformation object. My question is, does that object include only new changed statuses or if for example one of the recipients status has not changed it will still be included. Also, since a change to one of the recipients status does not necessarily change the envelope status, will the notification always include the envelope status ?
I'd recommend taking a look at the XSD: https://www.docusign.net/api/3.0/schema/dsx.xsd
The type sent by connect is DocuSignEnvelopeInformation, which consists of EnvelopeStatus and DocumentPDF objects, both of which have their schema defined in this XSD. In short the connect XML is a snapshot of the envelope at the time the notification is sent to you - the snapshot will include all recipient information.
In the sandbox environment you can enable a test DS Connect configuration with logging enabled to see what types of messages you will be receiving.
Absolutely correct and keep in mind that to save space in the demo environment we don't include the PDF byte stream in the log as it has no logic, meaning it's just a bunch of bytes. If you want to see it you can use webhook.com (free) or some other tool like that.
The Connect Service and the related "eventNotification" node in the API are event-driven. They don't publish events, but rather, the complete current status of the envelope, which includes envelope status, recipient status for all recipients, and more. The service always publishes the current status, so two "near" events might trigger one coalesced status publication, or two close publications. However, the last publication will include the latest changes. If you get a "republished" status (such as due to failed acknowledgement or directly triggered), it again is the current status, not the "old" status at the time of the original publication.
I want to know if this is possible: I would like to have a custom text field on an envelope that I set and if the envelope fails for some reason, like there are missing tabs or email address is bad, I want to be able to look at the exception and see the custom field that I set. Would this info be in the raw data? It is as important to us to know which envelopes failed as to know why they failed. I saved the custom field in a database before sending out the envelope. When it fails, I can look up that custom field and discover which envelope didn't make it and to take some action, like correcting and resending.
If the envelope is created incorrectly (i.e: specifying a conditional parent tab which does not exist, syntax error, etc), then you will know at the time you attempt to create the envelope w/the API. The reason will be included in an error code the API returns
If an envelope was sent to an email address which does not exist/bounces, that information can be discovered using the DS API to see a recipient/envelope status of 'autoresponded', or if you are using DS Connect you can receive a push notification.
Is there additional rationale why you want to use a custom field? Per the above, I do not believe it is necessary or applicable.
With the RestSharp api, I was able to get the Request body. The Request body has a collection of Parameters, and one of those items is the RequestBody.