Module docusign.monitor
ballerinax/docusign.monitor Ballerina library
Overview
Docusign is an agreement management platform for preparing, signing, acting on and managing agreements. Docusign Monitor provides security and compliance teams with visibility into account activity by exposing the events that occur in an organization as a continuous data set.
The Docusign Monitor connector lets Ballerina applications read the organization event stream and page through it with a cursor. It supports version 3.0 of the Docusign Monitor API.
Key features
- Read the real-time event stream of a Docusign organization
- Page through events with a cursor and control the page size
- Inspect event details such as the action, result, user, IP address, device and location
Setup guide
To use the Docusign Monitor connector, you need a Docusign organization with Docusign Monitor enabled and an app that is authorized to call the Monitor API using OAuth 2.0.
Step 1: Create an integration key
- Sign in to the Docusign Developer Console and open your apps and keys page.
- Create an app and note down its Integration Key, which is the client ID.
- Add a secret key to the app and note it down, which is the client secret.
- Add the redirect URI that your application uses.
Step 2: Obtain a refresh token
- Direct the user to the Docusign authorization endpoint, replacing
CLIENT_IDandREDIRECT_URI. Useaccount-d.docusign.cominstead ofaccount.docusign.comfor the demo environment.
https://account.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation%20extended&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
- After the user grants consent, Docusign redirects to your redirect URI with an authorization code.
- Exchange the authorization code for tokens.
curl -X POST https://account.docusign.com/oauth/token \ -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \ -d "grant_type=authorization_code&code=AUTHORIZATION_CODE"
This returns both an access_token and a refresh_token. If your application authenticates with the JWT grant instead, pass the resulting access token as a bearer token.
Step 3: Find your organization ID
- Open the Docusign Admin console of your organization.
- Copy the Organization ID shown in the organization details. It identifies the organization whose events you read.
Quickstart
To use the Docusign Monitor connector in your Ballerina application, update the .bal file as follows:
Step 1: Import the module
Import the docusign.monitor module.
import ballerinax/docusign.monitor;
Step 2: Instantiate a new connector
- Create a
Config.tomlfile and configure the values obtained in the steps above:
clientId = "<Client ID>" clientSecret = "<Client Secret>" refreshToken = "<Refresh Token>" organizationId = "<Organization ID>"
- Create a
monitor:ConnectionConfigwith the OAuth 2.0 refresh token grant credentials and initialize the connector with it.
configurable string clientId = ?; configurable string clientSecret = ?; configurable string refreshToken = ?; configurable string organizationId = ?; final monitor:Client monitorClient = check new ({ auth: { clientId, clientSecret, refreshToken } });
Step 3: Invoke the connector operation
Now, utilize the available connector operations.
Read a page of the organization event stream
public function main() returns error? { monitor:StreamResponse _ = check monitorClient->getStream(organizationId); }
Step 4: Run the Ballerina application
bal run
Examples
The Docusign Monitor connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
-
User activity audit - Page through the organization event stream, collect the events of one user and count them by action.
-
Event location summary - Page through the organization event stream and summarize events and distinct IP addresses by country.