Unclear webhook eventNotification documentation - docusignapi

There are several conflicts in the docs about the eventNotification object in the envelopeDefinition type.
First
https://developers.docusign.com/docs/esign-rest-api/reference/Envelopes/Envelopes/create/#eventNotification
Shows the following
{
eventNotification:eventNotification{
eventData:connectEventData{
format:String,
version:String,
includeData:Array
}
}
}
while
https://apiexplorer.docusign.com/#/esign/restapi?categories=Envelopes&tags=Envelopes&operations=create
shows
{
eventNotification:eventNotification{
connectEventData:undeclared_type{
format:String,
version:String
}
}
}
It is unclear which of these is correct.
Secondly
https://developers.docusign.com/docs/platform/webhooks/connect/architecture
Very heavily implies that a valid version and format would be v2.1 and JSON, however after many combinations I'm only ever able to get XML back. I was unable to find any place in the docs that list out the allowed versions and formats.
Lastly
https://developers.docusign.com/docs/platform/webhooks/connect/configuration
Is not what is shown at
https://admindemo.docusign.com/connect/edit-custom?accountId=\
The questions that arose because of this are:
Is there some doc that I just missed in my exploration? If not then an answer to the following would be greatly appreciated.
What are valid format, version and includeData values?
Is the name of the object containing those fields eventData or connectEventData?
Does the webhook support any format other than XML?

To get json formatted connect messages from eventNotifications defined in the envelope create call, I'd refer to this blog for some great detail - https://www.docusign.com/blog/developers/connect-webhooks-json-notifications.
It will look something like:
"eventNotification": {
"url": "https://yourwebhookurl",
"loggingEnabled": "true",
"requireAcknowledgment": "true",
"eventData": {
"version": "restv2.1",
"format": "json",
"includeData": ["tabs"]
},
"envelopeEvents": [
{"envelopeEventStatusCode": "Completed",
"includeDocuments": "false"}
]}
Keep in mind, SIM is not available for json at this time, so make sure your account is set for aggregate messaging.

After contacting support I got the following answer:
Connect publishing in JSON format is planned and near release, but due
to some performance issues that needed to be addressed, the rollout
has been delayed. Unfortunately, this means that some of our
documentation is a bit ahead of schedule.
The notification format is as follows:
"eventNotification": {
"url": "https://example/EventNotifications",
"loggingEnabled": "true",
"requireAcknowledgment": "false",
"envelopeEvents": [{
"envelopeEventStatusCode": "sent",
"includeDocuments": "false"
},
{"envelopeEventStatusCode": "delivered"},
{"envelopeEventStatusCode": "completed"},
{"envelopeEventStatusCode": "declined"},
{"envelopeEventStatusCode": "voided"}
]
}

Related

How does DocuSign specify the message format for Envelope Connect?

We're exploring using Envelope Connect to receive status updates for our envelopes we create through the DocuSign API.
We'd like the messages to come to us in JSON format, but it seems that no matter what we provide, the messages arrive in XML format.
An example of an eventNotification we're including with our envelopes is below:
{
"envelopeEvents": [
{
"envelopeEventStatusCode": "Completed",
"includeDocuments": false
},
{
"envelopeEventStatusCode": "Declined",
"includeDocuments": false
},
{
"envelopeEventStatusCode": "Voided",
"includeDocuments": false
}
],
"eventData": {
"format": "json",
"includeData": [
"custom_fields"
],
"version": "restv2.1"
},
"loggingEnabled": true,
"recipientEvents": [
{
"includeDocuments": false,
"recipientEventStatusCode": "Completed"
}
],
"requireAcknowledgment": true,
"url": "https://webhook.site/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
The DocuSign Developer API Reference says to use the "events" property of the eventNotification object when using the JSON SIM event model, but when we use this instead of envelopeEvents or recipientEvents, we don't receive any status updates.
I followed the message format in this youtube video, which shows the message coming back as JSON, but when I do the same, we get XML.
https://www.youtube.com/watch?v=bcTaBKf_c50
The Connect logs in the DocuSign Admin center confirm this:
Connect log
Could there be some configuration in our account that is preventing the message format from being JSON?
We do have some account level Connect configurations, could these be interfering?
Yes, you have to do this in the "Settings" page (DocuSign Admin) and go to the Connect section and configure account-wide connect configuration.
There, you can select which format you want used like this:
By selecting REST v2.1, you will get JSON instead of XML.
DocuSign Support was able to identify the issue.
Our API calls were going through /v2/ of the REST API:
https://demo.docusign.net/restapi/v2/
But JSON status updates are only sent with v2.1.
https://demo.docusign.net/restapi/v2.1/

Microsoft Graph Search 400 error when searching

I'm getting a 400 error when trying to do a search both through the Graph Explorer and through my own code. Both worked a few weeks ago but have stopped working recently. Another developer has been able to replicate it in their Tenancy, but Microsoft will not provide me support as we are not a Premier Customer.
If I run this query:
https://graph.microsoft.com/v1.0/drives{drive_id}/root/
it succeeds and returns information about the drive.
Following the documentation at https://learn.microsoft.com/en-us/graph/api/driveitem-search?view=graph-rest-1.0&tabs=http a search can be used via
https://graph.microsoft.com/v1.0/drives/{drive-id}/root/search(q='foobar')
But this returns a 400 error with "One of the provided arguments is not acceptable."
However, if I search for items in our entire Tenancy via the group search it succeeds so it doesn't appear to be a permissions error, but is not a viable solution as I need to search a particular drive.
please confirm whether you are still facing the issue. I was not able to reproduce the same from my side.
I ran this query:
https://graph.microsoft.com/v1.0/me/drives/drive-id/root/Search(q='Practices Checker')
And was able to get the desired result as below:
{
"#odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)",
"value": [
{
"#odata.type": "#microsoft.graph.driveItem",
"createdDateTime": "2020-12-09T11:55:47Z",
"id": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"lastModifiedDateTime": "2020-11-03T06:51:27Z",
"name": "Practices Checker",
"webUrl": "https://microsoftapc-my.sharepoint.com/personal/ribera_xxxxxxxx_com/Documents/Documents/Practices%20Checker",
"size": 0,
"createdBy": {
"user": {
"email": "ribera#xxxxxxxxxx.com",
"displayName": "Rinki Bera"
}
},
"lastModifiedBy": {
"user": {
"email": "ribera#xxxxxxxxxx.com",
"displayName": "Rinki Bera"
}
},
...
]
}
Thank you.

Q: Create and Send envelope with template with REST API

I am trying to add the new witness functionality to my API call. Heres the json that I am sending now:
POST https://demo.docusign.net/restapi/v2/accounts/[my id]/envelopes
{
"emailSubject":"test",
"status":"sent",
"templateId":"[Valid template id]",
"templateRoles":[
{
"roleName":"sign1",
"email":"valid#email.com",
"name":"John",
"recipientId":"1",
"routingOrder":"1",
"tabs":{}
},
{
"roleName":"Witness for sign1",
"witnessFor":"sign1",
"witnessForGuid":"1",
"recipientId":"2",
"routingOrder":"2",
"recipientType":"witness"
}
]
}
I have configured the template in DocuSign and verified the functionality by sending an envelope via the DocuSign website. However, the envelopes created from my API call does not trigger the witness functionality. I am not sure what I am missing, and I really appreciate any help/feedbacks.
Cheers
Here is a successful Envelopes::create call that includes the witness recipient type:
"recipients": {
"witnesses": [
{
"name": "Witness Name",
"email": "witness#example.com",
"recipientId": "2",
"witnessFor": "1"
}
],
"signers": [
{
"email": "someone#example.com",
"name": "Signer name",
"recipientId": "1",
"clientUserId": "1000",
"tabs": {
"signHereTabs": [
{
"anchorString": "/sig1/",
"anchorXOffset": "20",
"anchorUnits": "pixels"
}
]
}
}
]
},
Suggested changes in your templateRoles attributes:
(Not tested)
I'm assuming that you have a witness role set in the template.
If you don't, then I think you'll need to add the additional witness recipient to the envelope via composite templates.
You can also try your idea of including "recipientType":"witness"
At the API level, the witness is a distinct recipient for the envelope. It could also the case that the DocuSign web tool creates a hidden recipient (and recipient role) for the witness. To determine if this is the case, use API logging to see what the DocuSign web tool is actually doing.
"templateRoles":[
{
"roleName":"sign1",
"email":"valid#email.com",
"name":"John",
"recipientId":"1",
"routingOrder":"1",
"tabs":{}
},
{
"roleName":"Witness for sign1",
"witnessFor":"1",
OMIT THIS: "witnessForGuid":"1",
"recipientId":"2",
OMIT THIS: "routingOrder":"2",
OMIT THIS: "recipientType":"witness"
}
]
Note
Older developer sandbox accounts don't include the witness feature. If you receive the error message of not having the witness feature, contact go-live --at-- docusign.com to have the feature added to your developer account.
Turns out to be a bug in DocuSign, I had to split the creation step into 2.
1st POST /envelopes:
{
"emailSubject":"Template Action Test",
"status":"created",
"templateId":"866fcb03-1342-4678-9dc3-107772c59e89",
"templateRoles":[
{"roleName":"sign1","email":"email#test.com","name":"JK","tabs":{}}
]
}
2nd PUT /envelopes/envelope-id:
{
"status":"sent"
}

How to retrieve Work Item linked to specific commit - Azure Devops REST API

I need to be able to retrieve the linked work item of any given specific commit. I'm currently using the following api call
GET https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/commits/{commitId}?api-version=5.0
with the following response
{
"parents": [],
"treeId": "7fa1a3523ffef51c525ea476bffff7d648b8cb3d",
"push": {
"pushedBy": {
"id": "8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
"displayName": "Chuck Reinhart",
"uniqueName": "fabrikamfiber3#hotmail.com",
"url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
"imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
},
"pushId": 1,
"date": "2014-01-29T23:33:15.2434002Z"
},
"commitId": "be67f8871a4d2c75f13a51c1d3c30ac0d74d4ef4",
"author": {
"name": "Chuck Reinhart",
"email": "fabrikamfiber3#hotmail.com",
"date": "2014-01-29T23:32:09Z"
},
"committer": {
"name": "Chuck Reinhart",
"email": "fabrikamfiber3#hotmail.com",
"date": "2014-01-29T23:32:09Z"
},
"comment": "First cut\n",
"url": "https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/be67f8871a4d2c75f13a51c1d3c30ac0d74d4ef4",
"remoteUrl": "https://dev.azure.com/fabrikam/_git/Fabrikam-Fiber-Git/commit/be67f8871a4d2c75f13a51c1d3c30ac0d74d4ef4",
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/be67f8871a4d2c75f13a51c1d3c30ac0d74d4ef4"
},
"repository": {
"href": "https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249"
},
"changes": {
"href": "https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/be67f8871a4d2c75f13a51c1d3c30ac0d74d4ef4/changes"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_git/Fabrikam-Fiber-Git/commit/be67f8871a4d2c75f13a51c1d3c30ac0d74d4ef4"
},
"tree": {
"href": "https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/trees/7fa1a3523ffef51c525ea476bffff7d648b8cb3d"
}
}
}
from https://learn.microsoft.com/en-us/rest/api/azure/devops/git/commits/get?view=azure-devops-rest-5.0 and am missing a way to see what work item its linked to or if it is linked at all. Does anyone know of a way to get this information? Thanks
You could use the Get Commits API, docs here. The base request looks like:
GET https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/commits?api-version=5.0
You could then add the following parameters:
fromCommitId - string - If provided, a lower bound for filtering commits alphabetically
toCommitId - string - If provided, an upper bound for filtering commits alphabetically
includeWorkItems - boolean - Whether to include linked work items
So that your final query would look something like, with your toCommitId and fromCommitId parameters being your commit id that you are after (the documentation doesn't specificy whether these are inclusive or exclusive so your might have to tweak this slightly):
GET https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/commits?includeWorkItems=true&.toCommitId={searchCriteria.toCommitId}&fromCommitId={searchCriteria.fromCommitId}&api-version=5.0
The result should contain a workItems property inside each commit object of the response as per this documentation.
Note:
Parameters that use the searchCriteria prefix in their name can be specified without it as query parameters, e.g. searchCriteria.$top -> $top
There is also:
ids - array - If provided, specifies the exact commit ids of the commits to fetch. May not be combined with other parameters.
Which could allow you to forgo passing in the to and from commit ids but the docs state that it May not be combined with other parameters - even though the example request does combine it with other parameters. I haven't tried this myself so please do comment when you find out whether you go with from-to id or just ids.
OPs action
The OP ended up using the following request as they didn't mind all commits being returned:
GET https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/commits?includeWorkItems=true&api-version=5.0

DocuSign - Document Download

I'm trying to use DocuSign via Rest API and ran into a question. After a user signed document and is redirected to the URL that is specified on RecipientView (/accounts/{accountId}/envelopes/{envelopeId}/views/recipient), Considering both best and worst case scenarios, how long should we wait before we download the signed document?
I'm asking this question because we saw some issues with SigniX in the past where, after SigniX returning the control to redirectUrl, the signed document was not available to download. Even though this happened very little number of times which might be <1% of all requests, Every single document is $$ and cannot afford to lose it.
If answer to my question is Yes, Please provide a C# example on using webhook.
Thanks.
You can setup DocuSign WebHook aka Connect notifications at your account level or envelope level and automatically receive the Documents when an envelope is completed.
Here is a sample CreateEnvelope request to setup configuration for the connect notifications per envelope level. Look at eventNotification property. All you have to do is host a listener to which DocuSign can send messages.
{
"emailSubject": "Testing connect notification",
"status": "sent",
"eventNotification": {
"url": "<Add your listener URL here>",
"loggingEnabled": "true",
"requireAcknowledgment": "true",
"envelopeEvents": [
{
"envelopeEventStatusCode": "Completed"
}
],
"includeDocuments": "true"
},
"recipients": {
"signers": [
{
"name": "john smith",
"email": "johnsmith#acme.com",
"recipientId": "1",
"routingOrder": "1"
}
]
},
"documents": [
{
"documentId": "1",
"name": "Contract",
"fileExtension": "contract",
"documentBase64": "DQoNCg0KDQogICAgICAgICBEdW1teSBDb250cmFjdA=="
}
]
}
Here are some useful links which help you to setup your connect listener
WebHook c# recipe
More Api Recipes
Blog Posts
Webhooks: Don’t Poll Us, We’ll Call You!
Adding Connect Webhooks to your Application
Securing Your Connect Webhook Listener

Resources