DocuSign Java API - voiding/cancelling an envelope

Question

We've been trying to implement a "reset" for an envelope our server code created via the DocuSign Java SDK. I tried many approaches, however, it also appears the current state of the envelope will also change what needs to be done. For instance, if the document has just been sent out and no one has signed yet, 2) Someone has already signed, but not all signers 3) one of the signers declines signing.

In my committed approach I set the status to "void" and set a reason. I thought that worked, but sometimes it moves the envelope to the delete folder, sometimes not, but when in delete folder the envelope can still be signed (don't want) I even tried the approach of Envelope move from inbox to delete and that throws errors for me.

Here is the current code.

private void deleteFromDocuSign(String envelopeId) {
    ApiClient apiClient = getApiClient()

    FoldersApi foldersApi = new FoldersApi(apiClient)
    FoldersResponse response = foldersApi.callList(accountId)

    String inboxFolderId = null
    String deleteFolderId = null
    for (Folder folder : response.getFolders()) {
        if (folder.getName() == "Inbox") {
            inboxFolderId = folder.getFolderId()
        } else if (folder.getName() == "Deleted Items") {
            deleteFolderId = folder.getFolderId()
        }
    }
    if (inboxFolderId != null && deleteFolderId != null) {
        FoldersRequest folderRequest = new FoldersRequest()
        folderRequest.setFromFolderId(inboxFolderId)
        folderRequest.addEnvelopeIdsItem(envelopeId)
        //FoldersResponse movedResponse = foldersApi.moveEnvelopes(accountId, deleteFolderId, folderRequest)
        //log.info(movedResponse.toString())
        EnvelopesApi envelopesApi = new EnvelopesApi(apiClient)
        EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition()
        envelopeDefinition.setStatus("voided")
        envelopeDefinition.setVoidedReason("Resetting Envelope through App")
        envelopeDefinition.setDocuments(new ArrayList<Document>())
        EnvelopeDocumentsResult result = envelopesApi.deleteDocuments(accountId, envelopeId, envelopeDefinition)
        log.info(result.toString())
        //EnvelopeUpdateSummary summary = envelopesApi.update(accountId, envelopeId, envelope)
        //log.info(summary.toString())
    } else {
        throw new PanoramException("Couldn't find folders")
    }

}

Answer 1

Here is the solution we came up with to correctly void/delete/purge an envelope. The key here is finding out the current status of the envelope as that determines what you are able to do.

private void deleteFromDocuSign(String envelopeId) {
    Envelope envelope = getEnvelope(envelopeId)
    String status = envelope.getStatus()
    if ([CREATED, SENT, DELIVERED].contains(status)) {
        moveEnvelopeToRecyclebin(envelopeId)
    } else if ([COMPLETED, SIGNED].contains(status)) {
        log.info("DocuSign document is completed or signed already")
        throw new Exception("DocuSign document is signed/completed cannot reset.")
    } else if ([VOIDED, DELETED, DECLINED].contains(status)) {
        log.info("Docusign already has it set to be removed.")
    }
}

So then if it is possible to remove. Created, Sent or Delivered (In our code I made static final String for the Docusign value)

private static final String COMPLETED = "completed"
private static final String CREATED = "created"
private static final String DECLINED = "declined"
private static final String DELETED = "deleted"
private static final String DELIVERED = "delivered"
private static final String SENT = "sent"
private static final String SIGNED = "signed"
private static final String VOIDED = "voided"

private static final String RECYCLE_BIN = "recyclebin"

And then the code that moves the envelope to the recycle bin

private void moveEnvelopeToRecyclebin(String envelopeId) {
    FoldersApi foldersApi = new FoldersApi(getApiClient())

    FoldersRequest folderRequest = new FoldersRequest();
    folderRequest.setEnvelopeIds(new ArrayList<String>());
    folderRequest.getEnvelopeIds().add(envelopeId);
    foldersApi.moveEnvelopes(accountId, RECYCLE_BIN, folderRequest);
}

Now the envelope is moved to the delete/recycle bin folder and cannot be signed anymore (it is voided)