Search code examples
c#.netdocusignconnect

DocuSign Connect: Moving from XML (Legacy) to JSON

Using C# and .NET (Framework)

We have a Production system for processing DocuSign Connect notifications which has been running great for over 2 years. We are currently setup to use the XML (Legacy) payload. I've taken the Connect payload schema (linked here) and generated the hierarchy of C# classes that represents the payload.

We have a Listener (webhook) and a Processor to handle the notifications:

  • The Listener does some security checks and a minimal parse (for validation) of the payload before queuing the notification for processing.
  • The Processor dequeues the notification and deserializes the XML to the DocuSign classes in order to process it.

As we understand it, in May 2023 we will no longer be able to get Connection notifications in XML, but we will have to be able to handle a JSON payload. In looking at some sample JSON payload data (displayed when setting up a Connect configuration), I'm not seeing any structural similarities to the XML format, so I doubt I'd be able to do what I'm currently doing (or similar):

var serializer = new XmlSerializer(typeof(DocuSignEnvelopeInformation));
var buffer = Encoding.UTF8.GetBytes(request.Content.ReadAsStringAsync().Result);
using (var stream = new MemoryStream(buffer))
{
    var envelopeInfo = (DocuSignEnvelopeInformation)serializer.Deserialize(stream);
    return envelopeInfo;
}

Question -- Is there a similar schema for the JSON payload that I can use to generate C# classes like I did with the XML payload?

I'm trying to get a rough estimate on how much effort this conversion is going to take. Any suggestions are appreciated.

If you need more information, please let me know.

thanks, randy

UPDATE 01/05/2023: I was interested in seeing what JSON DocuSign would send me so I setup a simple Connect Configuration to use JSON, activated it, and then sent in a DocuSign request. I did not have any listener running, so I expected to see connect failures which was OK as I just wanted to see what DocuSign was sending. I completed signing the documents and then looked at the Connect Logs. There were 2 notifications: (1) was a JSON notification for the "recipient-sent" event and (2) was an XML notification for the envelope complete status. This XML notification is of the same type I'm getting currently and already know how to process. I'm surprised it wasn't a JSON equivalent of envelope complete. Would anyone know why I'm getting a mixture of JSON and XML? Correction: I created a simplified Listener which only does some security checks, saves the payload to disk, and always returns success. I am getting a JSON payload for "envelope-completed" event. It looks like the XML version is being sent to a DocuSign "in-house" listener.

UPDATE #2 01/05/2023: I did run across several references to a handy feature of Visual Studio where you can put the JSON into the copy/paste buffer and then in Visual Studio use Edit -> Paste Special -> Paste JSON as Classes. I haven't tried deserializing any live data into these classes as I know these classes aren't complete -- they only reflect the structure that exists in the data you use at the time. I can already see that it only generated a few of the tab classes (Sign Here, Date Signed, Text, and Checkbox) but it doesn't know about all the other possible tabs. And several properties were just defined as "object" since the JSON I used didn't contain values for them. That's why I was hoping for a definitive schema for the JSON DocuSign intends to use for Connect notifications.

Solution

  • I was able to get back to this and I'll post what seems to be working.

    I created a support ticket to DocuSign and the Support representative was helpful and passed along some information from the developers. There doesn't seem to be any "official" schemas for the JSON notification so I decided to work on my own.

    I gathered as many examples of JSON notifications as I could. DocuSign has some here. Plus, as mentioned above, I could gather more by sending out DocuSign requests for the documents we primarily use and saving the JSON notifications I got back as I went through the signing process.

    I then used the Visual Studio feature about generating C# classes from JSON input (also mentioned above). For each JSON notification I obtained, I generated the corresponding C# classes. After selecting one set as the most complete, I started merging each new set with the old (my favorite merge tool is Araxis Merge) when there were new classes, properties, enums, etc. to be added.

    -- WARNING: I've found there are some XML property values which don't exist in the JSON version, or at least I haven't found where they are. Example: the VoidReason string.

    I believe what I have will meet our requirements. My listener and processor have been updated (still in Development) to handle both XML and JSON notifications and there is still a lot of testing to do before I feel it's ready for Production.

    If there's anything I can answer on this process, please let me know.

    thanks, randy

    Update 02/20/2023: As I understand it, DocuSign will let you create more than 1 Connect Configuration and have more than 1 active. This means you can have your normal Production configuration sending notifications to your production system (in the legacy format) and a temporary Test configuration sending the same notifications (in the JSON format) to a separate test system. I'm probably going to try this before the decision to totally update the Production system.

    Update 07/13/2023: I was searching for something else DocuSign-related when I stumbled upon the Connect JSON schema in their GitHub account.

    https://github.com/docusign/OpenAPI-Specifications/blob/master/connect.schema-v2.json

    I did the "paste JSON to C# classes" trick in Visual Studio and it mostly generates the classes I've already discovered, but there are a few new ones I'll need to add to my production code. I hope they keep this link active and this schema updated. Please let me know if you have questions or need more info.