Skip to content

Commit 00e543c

Browse files
karissarjacobsenkarissarjacobsen
authored
Merge pull request #38 from docusign/readme-updates
update readme
2 parents 85488bc + 3636e6f commit 00e543c

File tree

2 files changed

+186
-93
lines changed

2 files changed

+186
-93
lines changed

‎DocuSign.Workspaces/DocuSign.Workspaces/appsettings-example.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
}
66
},
77
"AllowedHosts": "*",
8+
"ClientAppUrl": "{ClientAppUrl}",
89
"DocuSign": {
910
"IntegrationKey": "{IntegrationKey}",
1011
"SecretKey": "{SecretKey}",

‎README.md‎

Lines changed: 185 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,185 @@
1-
# Workspaces Sample Application: React
2-
3-
## Introduction
4-
5-
The Workspaces Sample App provides ISV developers with a practical example of how to build a quality in-product integration. This is a Single Page Application (SPA) leveraging the Docusign C# eSignature SDK. The SPA is created using React.js and .Net Web API. You can find a live instance at [https://Workspaces.sampleapps.docusign.com/](https://Workspaces.sampleapps.docusign.com/).
6-
7-
The Workspaces Sample App demonstrates the following:
8-
9-
1. **Authentication** with Docusign via [JWT Grant](https://developers.docusign.com/platform/auth/jwt/) or [ACG](https://developers.docusign.com/platform/auth/authcode/).
10-
2. **Send an Employment Contract:**
11-
This use case presents a scenario wherein the ISV’s app enables an employee to send an employment contract to a new hire.
12-
Key elements:
13-
- Composite templates
14-
- Envelope-level Connect notifications
15-
- Electronic or digital signature options (SBS)
16-
- Embedded sending
17-
- Remote signing via email notification
18-
3. **T&Cs Contract:**
19-
This use case presents a scenario in which a sales employee is sending a standard Terms and Conditions document along with a Contract document to an external buyer.
20-
Key elements:
21-
- Composite templates
22-
- Envelope-level Connect notifications
23-
- Prepopulated field data
24-
- Recipient Authentication with Access Code
25-
4. **Update Customer Profile Self-service:**
26-
This use case presents a scenario in which an online customer portal provides a means for customers to update their profiles. The app requires password authentication. As an added level of security, the embedded signing session will require that the signer pass an IDV check.
27-
Key elements:
28-
- Composite templates
29-
- Envelope-level Connect notifications
30-
- Embedded signing with login data mapped to security elements
31-
- IDV or SMS/Phone authentication
32-
5. **Custom Quote:**
33-
This use case presents a scenario in which a sales employee is sending a generated custom quote to a prospective buyer.
34-
Key elements:
35-
- Composite templates with anchor tabs
36-
- Envelope-level Connect notifications
37-
- Remote signing via SMS delivery
38-
39-
## Prerequisites
40-
41-
- Create a Docusign [Developer Account](https://go.docusign.com/o/sandbox/).
42-
- Create an application on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page.
43-
- Add redirect URIs:
44-
- `{ PROTOCOL }://{ DOMAIN }`
45-
- `{ PROTOCOL }://{ DOMAIN }/admin`
46-
- `{ PROTOCOL }://{ DOMAIN }/api/consentcallback`
47-
- Press "ADD SECRET KEY" and save the generated key (it will be used later in "Settings configuration" section to configure {SecretKey})
48-
- Press "GENERATE RSA" and save the generated key pairs (it will be used later in "Settings configuration" section to configure "private.key")
49-
- Installed and configured [Node.js](https://nodejs.org/en/download)
50-
- Installed and configured [Docker](https://www.docker.com/)
51-
- Installed and configured [.Net 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
52-
53-
### Settings configuration
54-
55-
Create a copy of the file appsettings-example.json, save the copy as appsettings.json, and fill in the data:
56-
57-
- {IntegrationKey} - integration key of the application created in section "Create an application on the Apps and Keys page" above (GUID)
58-
- {SecretKey} - the application secret code that was generated in "Prerequisites" section
59-
- Save generate private RSA key (section "Prerequisites") to the file \sample-app-Workspaces-csharp\Docusign.MyWorkspaces\DocuSign.MyWorkspaces\private.key
60-
- {RedirectBaseUrl} - internal redirection URL that is used during the obtaining consent and embedded signing process
61-
- {EventNotificationBaseUrl} - public base URL of the application that is used by Docusign Events webhook
62-
- "TestAccountConnectionSettings" section:
63-
- {AuthBasePath} - base authentication URL that is used during loging with a test account
64-
- {BaseUri} - base API url that is used to call the API endpoints in case using the test account
65-
- {UserId} - ID of the test user
66-
- {AccontId} - ID of the account that is connected to the test user
67-
- "CustomerProfile" section:
68-
- {Login} - hardcoded login that is used as a part of Use Case 3
69-
- {Password} - hardcoded password that is used as a part of Use Case 3:
70-
71-
## Local installation instructions (without Docker)
72-
73-
1. Clone the git repository to your local machine
74-
1. Make the Settings configuration described above
75-
1. Open a terminal and navigate to \sample-app-Workspaces-csharp\DocuSign.MyWorkspaces\DocuSign.MyWorkspaces\ClientApp folder
76-
1. Install required client application packages running the following command in the terminal:
77-
```
78-
npm install
79-
```
80-
1. Start the client application running the following command in the terminal:
81-
```
82-
npm start
83-
```
84-
1. Open a new terminal and navigate to \sample-app-Workspaces-csharp\DocuSign.MyWorkspaces
85-
1. Build the .Net solution:
86-
```
87-
dotnet build --configuration Debug
88-
```
89-
1. Start the .NET application:
90-
```
91-
dotnet run --project .\DocuSign.MyWorkspaces\DocuSign.MyWorkspaces.csproj --configuration Debug
92-
```
93-
1. Open a browser to [localhost:5001](https://localhost:5001) (if the page is not openned automatically).
1+
2+
3+
# **Workspaces Sample Application: C\# / React**
4+
5+
## **Overview**
6+
7+
The Workspaces Sample App is a Single Page Application (SPA) built with **React.js** (frontend) and **.NET 8.0 Web API** (backend). It demonstrates practical examples of building Workspaces as an in-product integration using the **Docusign C\# eSignature SDK**.
8+
9+
A live instance of the application is available at: https://workspaces.sampleapps.docusign.com/
10+
11+
---
12+
13+
## **Features**
14+
15+
This application demonstrates the following Docusign use cases:
16+
17+
1. **Authentication** — Authorization Code Grant (ACG)
18+
2. **Dynamically create transactional spaces** — Workspace creation, Workspace envelope creation, document upload request
19+
3. **Persistent workspaces** — Workspace lookup, envelope creation, document upload
20+
21+
---
22+
23+
## **Prerequisites**
24+
25+
Before building or running the application, ensure the following are installed and configured:
26+
27+
| Requirement | Notes |
28+
| ----- | ----- |
29+
| [Node.js](https://nodejs.org/en/download) | Required to build the React frontend |
30+
| [.NET 8.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) | Required to build and run the backend API |
31+
| [Docker](https://www.docker.com/) | Required only for containerized deployment |
32+
| Docusign Developer Account | [Sign up here](https://go.docusign.com/o/sandbox/) |
33+
34+
### **Docusign app setup**
35+
36+
1. Log in to your Docusign Developer Account and navigate to the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page.
37+
2. Create a new application and note down the **Integration Key**.
38+
3. Add the following **Redirect URIs** for your app:
39+
* `{PROTOCOL}://{DOMAIN}`
40+
* `{PROTOCOL}://{DOMAIN}/admin`
41+
* `{PROTOCOL}://{DOMAIN}/api/consentcallback`
42+
4. Click **ADD SECRET KEY** and save the generated key — this is your `{SecretKey}`.
43+
5. Click **GENERATE RSA** and save both the public and private key — the private key will be stored as `private.key`.
44+
45+
---
46+
47+
## **Configuration**
48+
49+
### **1\. Create `appsettings.json`**
50+
51+
Copy the example config file and fill in your values:
52+
53+
```shell
54+
cp DocuSign.Workspaces/DocuSign.Workspaces/appsettings-example.json DocuSign.Workspaces/DocuSign.Workspaces/appsettings.json
55+
```
56+
57+
Edit `appsettings.json` and replace the following placeholders:
58+
59+
| Placeholder | Description |
60+
| ----- | ----- |
61+
| `{ClientAppUrl}` | URL of the React frontend (e.g. http://localhost:3000) |
62+
| `{IntegrationKey}` | The Integration Key (GUID) from your Docusign app |
63+
| `{SecretKey}` | The secret key generated in the Docusign Apps and Keys page |
64+
| `{SecretKeyProd}` | Secret key for the production Docusign app — not required for local development |
65+
| `{RedirectBaseUrl}` | Internal redirection URL used for consent and embedded signing (e.g. http://localhost:3000) |
66+
| `{EventNotificationBaseUrl}` | Public base URL used by the Docusign Events webhook (e.g. http://localhost:5000) |
67+
| `{AuthBasePath}` | Base authentication URL (e.g. https://account-d.docusign.com) |
68+
| `{BaseUri}` | Base API URL for test account API calls (e.g. https://demo.docusign.net) |
69+
| `{UserId}` | ID of the test user |
70+
| `{AccountId}` | ID of the account connected to the test user |
71+
| `{Login}` | Hardcoded login used in Use Case 3 (Customer Profile) |
72+
| `{Password}` | Hardcoded password used in Use Case 3 (Customer Profile) |
73+
74+
### **2\. Add the RSA Private Key**
75+
76+
Save the RSA private key generated during Docusign app setup to:
77+
78+
```
79+
sample-app-workspaces-csharp/DocuSign.Workspaces/DocuSign.Workspaces/private.key
80+
```
81+
82+
---
83+
84+
## **Local Installation (Without Docker)**
85+
86+
Follow these steps to run the application locally:
87+
88+
### **Step 1 — Clone the Repository**
89+
90+
```shell
91+
git clone https://github.com/docusign/sample-app-workspaces-csharp.git
92+
cd sample-app-workspaces-csharp
93+
```
94+
95+
### **Step 2 — Configure the Application**
96+
97+
Complete the **Configuration** steps above before proceeding.
98+
99+
### **Step 3 — Install Frontend Dependencies**
100+
101+
Navigate to the React client app folder and install Node packages:
102+
103+
```shell
104+
cd DocuSign.Workspaces/DocuSign.Workspaces/ClientApp/
105+
npm install
106+
```
107+
108+
### **Step 4 — Start the Frontend**
109+
110+
```shell
111+
npm start
112+
```
113+
114+
Leave this terminal running. The React dev server will start on its default port.
115+
116+
### **Step 5 — Build the .NET Backend**
117+
118+
Open a **new terminal** and navigate to the solution root:
119+
120+
```shell
121+
cd DocuSign.Workspaces
122+
dotnet build --configuration Debug
123+
```
124+
125+
### **Step 6 — Run the .NET Backend**
126+
127+
```shell
128+
dotnet run --project ./DocuSign.Workspaces/DocuSign.Workspaces.csproj --configuration Debug
129+
```
130+
131+
### **Step 7 — Open the App**
132+
133+
Open a browser and go to:
134+
135+
```
136+
https://localhost:3000
137+
```
138+
139+
---
140+
141+
## **Project Structure**
142+
143+
```
144+
sample-app-workspaces-csharp/
145+
├── .github/workflows/ # CI/CD workflows
146+
├── DocuSign.Workspaces/ # Solution directory
147+
│ ├── DocuSign.Workspaces/ # Main project directory
148+
│ │ ├── ClientApp/ # React.js frontend (SPA)
149+
│ │ ├── appsettings-example.json
150+
│ │ ├── appsettings.json # Your local config (not committed)
151+
│ │ └── private.key # Your RSA private key (not committed)
152+
│ └── DocuSign.Workspaces.sln
153+
├── .gitignore
154+
├── LICENSE
155+
├── README.md
156+
└── package-lock.json
157+
```
158+
159+
---
160+
161+
## **Technology Stack**
162+
163+
| Layer | Technology |
164+
| ----- | ----- |
165+
| Frontend | React.js, SCSS |
166+
| Backend | .NET 8.0 Web API, C\# |
167+
| Auth | Docusign JWT Grant / ACG |
168+
| SDK | Docusign C\# eSignature SDK |
169+
| Containerization | Docker |
170+
171+
---
172+
173+
## **Additional Resources**
174+
175+
* [Docusign Developer Center](https://developers.docusign.com/)
176+
* [JWT Grant Authentication](https://developers.docusign.com/platform/auth/jwt/)
177+
* [Authorization Code Grant](https://developers.docusign.com/platform/auth/authcode/)
178+
* [eSignature REST API Reference](https://developers.docusign.com/docs/esign-rest-api/)
179+
180+
---
181+
182+
## **License**
183+
184+
This project is licensed under the [MIT License](LICENSE).
185+

0 commit comments

Comments
 (0)