Skip to navigation

How to get monitoring data

View as Markdown

This topic demonstrates how to get and display all of your organization’s monitoring data.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Prerequisites

Running the code in this how-to requires this data:

PrerequisiteDescription
Admin accessTo call the Docusign Monitor endpoint, you must impersonate a user with administrator access to your organization.
This means that you must have obtained your access token using JWT Grant and have requested the impersonation scope.
Note: The impersonated administrator may not be an admin of more than one organization. Admins of two or more organizations who call the Monitor API endpoint will receive responses with the 403 Forbidden error code.
Your organization must have access to Docusign MonitorYour organization must have access to Docusign Monitor to call the endpoint.
The Monitor API is available for developer (demo) accounts for testing and development, but for apps in the production environment, it is a separate SKU that requires Enterprise Pro. For more information about how to enable the Monitor API for your account, contact Docusign Support.

Step 1. Obtain your OAuth token

To make the API calls shown in this how-to, you need a valid OAuth access token.

Because Docusign Monitor requires that you impersonate a user with admin access to your organization, you must have obtained your access token using JWT Grant and have requested the impersonation scope. For details, see Docusign Monitor Authentication.

Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}"
'--header' "Accept: application/json"
'--header' "Content-Type: application/json")

Step 3. Get monitoring data

Make a GET request to the DataSet:getStream endpoint to get your monitoring data. Because your organization may have large amounts of data, you can use the limit query parameter to specify the maximum number of records each call will return (2,000 in the example shown here) and a cursor value to continue the query from where the previous one left off.

In this example, we return and display chunks of monitoring data, record the returned cursor value, and use that value to begin the next query until all data has been returned.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

if date -v -10d &>/dev/null; then
# Mac
cursorDate=$(date -v -1y '+%Y-%m-%d')
else
# Not a Mac
cursorDate=$(date --date='-1 year' '+%Y-%m-%d')
fi
complete=false
cursorValue="${cursorDate}T00:00:00Z"
iterations=0
while [ $complete == false ]; do
((iterations=iterations+1))
# Create a temporary file to store the response
response=$(mktemp /tmp/response-bs.XXXXXX)
Status=$(curl -w '%{http_code}' -i --request GET "https://api-d.docusign.com/v1/organizations/${ORGANIZATION_ID}/stream?cursor=${cursorValue}&limit=2000" \
"${Headers[@]}" \
--output ${response})
# If the Status code returned is greater than 201 (OK / Accepted), display an error message
# along with the API response
if [[ "$Status" -gt "201" ]] ; then
echo ""
echo "You do not have Monitor enabled for your account, follow https://developers.docusign.com/docs/monitor-api/how-to/enable-monitor/ to get it enabled."
echo ""
cat $response
exit 1
fi
# Display the data
echo ""
echo "Increment:"
echo $iterations
echo "Response:"
cat $response
echo ""
# Get the endCursor value from the response. This lets you resume
# getting records from the spot where this call left off
endCursorValue=$(sed -n 's/.*"endCursor":"\([^"]*\)".*/\1/p' $response)
echo "endCursorValue is:"
echo $endCursorValue
echo "cursorValue is:"
echo $cursorValue
echo ""
# If the endCursor from the response is the same as the one that you already have,
# it means that you have reached the end of the records
if [ "$endCursorValue" == "$cursorValue" ] ; then
echo 'After getting records, the cursor values are the same. This indicates that you have reached the end of your available records.'
complete=$((true))
else
echo 'Updating the cursor value of ' ${cursorValue} ' to the new value of ' ${endCursorValue}
cursorValue="${endCursorValue}"
sleep 5
fi

Expected response

If your API call is successful, you should see a JSON response similar to this.

The sample response shows only the results of the final three query loops; the first loops (and the body of the data returned) are omitted due to lack of space. You can see the structure of the returned JSON in Tracking data and handling alerts.

Sample response
<Responses for the first 3 loops are displayed here. Only the final loops are
displayed in this example response>
Increment:
3
Response:
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
Server: Kestrel
Strict-Transport-Security: max-age=5184000; includeSubDomains; preload
api-supported-versions: 2.0
X-DocuSign-TraceToken: a778d0c4-xxxx-xxxx-xxxx-c676ed038c22
X-DocuSign-Node: SE4DFE181
Date: Thu, 29 Oct 2020 20:29:13 GMT
Strict-Transport-Security: max-age=15768000
{"resultData":[{EVENT/ALERT DATA HERE}],"endCursor":"aa_637395998467230467_637395997844343970_195"}
endCursorValue is:
aa_637395998467230467_637395997844343970_195
cursorValue is:
aa_637395449927163968_637395449443454544_380
Updating the cursor value of aa_637395449927163968_637395449443454544_380 to the new value of aa_637395998467230467_637395997844343970_195
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 68 0 68 0 0 111 0 --:--:-- --:--:-- --:--:-- 111
Increment:
4
Response:
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
Server: Kestrel
Strict-Transport-Security: max-age=5184000; includeSubDomains; preload
api-supported-versions: 2.0
X-DocuSign-TraceToken: 081e2182-xxxx-xxxx-xxxx-2da9af39aaea
X-DocuSign-Node: DA3DFE177
Date: Thu, 29 Oct 2020 20:29:20 GMT
Strict-Transport-Security: max-age=15768000
{"resultData":[],"endCursor":"aa_637395998467230467_637395997844343970_0"}
endCursorValue is:
aa_637395998467230467_637395997844343970_0
cursorValue is:
aa_637395998467230467_637395997844343970_195
Updating the cursor value of aa_637395998467230467_637395997844343970_195 to the new value of aa_637395998467230467_637395997844343970_0
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 68 0 68 0 0 129 0 --:--:-- --:--:-- --:--:-- 129
Increment:
5
Response:
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
Server: Kestrel
Strict-Transport-Security: max-age=5184000; includeSubDomains; preload
api-supported-versions: 2.0
X-DocuSign-TraceToken: 90a45fef-xxxx-xxxx-xxxx-d24725ecf21b
X-DocuSign-Node: DA3DFE177
Date: Thu, 29 Oct 2020 20:29:26 GMT
Strict-Transport-Security: max-age=15768000
{"resultData":[],"endCursor":"aa_637395998467230467_637395997844343970_0"}
endCursorValue is:
aa_637395998467230467_637395997844343970_0
cursorValue is:
aa_637395998467230467_637395997844343970_0
After getting records, the cursor values are the same. This indicates that you have reached the end of your available records.
Done.

Next steps