141 lines
5.1 KiB
Markdown
141 lines
5.1 KiB
Markdown
# Adobe Sign → DocuSign Migrator
|
|
|
|
A Python toolkit for migrating library templates from Adobe Sign (Acrobat Sign) to DocuSign.
|
|
It downloads templates via the Adobe Sign API, converts them to DocuSign format, and uploads them via the DocuSign API.
|
|
|
|
---
|
|
|
|
## What it does
|
|
|
|
1. **Authenticates** with Adobe Sign via OAuth (one-time browser flow, tokens saved to `.env`)
|
|
2. **Downloads** templates — PDF, metadata, and form field definitions
|
|
3. **Converts** each template to a DocuSign `envelopeTemplate` JSON, mapping all field types, coordinates, and recipient roles
|
|
4. **Authenticates** with DocuSign via JWT grant (one-time browser consent, then fully automated)
|
|
5. **Uploads** the converted template to DocuSign via the REST API
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.10+
|
|
- An Adobe Sign OAuth app (EU2 shard) with scopes: `library_read:self library_write:self user_read:self`
|
|
- A DocuSign developer account with an integration key and RSA keypair
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
**1. Install Python dependencies:**
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
**2. Create a `.env` file** in the project root (never commit this):
|
|
```
|
|
# Adobe Sign
|
|
ADOBE_CLIENT_ID=your-adobe-client-id
|
|
ADOBE_CLIENT_SECRET=your-adobe-client-secret
|
|
|
|
# DocuSign
|
|
DOCUSIGN_CLIENT_ID=your-integration-key
|
|
DOCUSIGN_CLIENT_SECRET=your-client-secret
|
|
DOCUSIGN_USER_ID=your-docusign-user-guid
|
|
DOCUSIGN_ACCOUNT_ID=your-docusign-account-id
|
|
DOCUSIGN_PRIVATE_KEY_PATH=/path/to/private.key
|
|
DOCUSIGN_AUTH_SERVER=account-d.docusign.com
|
|
DOCUSIGN_BASE_URL=https://demo.docusign.net/restapi
|
|
DOCUSIGN_REDIRECT_URI=http://localhost:8080/callback
|
|
```
|
|
|
|
Use `account-d.docusign.com` and `https://demo.docusign.net/restapi` for sandbox.
|
|
For production replace with `account.docusign.com` and your account's base URL (e.g. `https://na3.docusign.net/restapi`).
|
|
|
|
**3. Authenticate with Adobe Sign** (one-time):
|
|
```bash
|
|
python3 src/adobe_auth.py
|
|
```
|
|
Opens a browser. After authorizing, paste the redirect URL back into the terminal.
|
|
Tokens are saved to `.env` and auto-refreshed on subsequent runs.
|
|
|
|
**4. Grant consent for DocuSign** (one-time per user):
|
|
```bash
|
|
python3 src/docusign_auth.py --consent
|
|
```
|
|
Opens a browser for the DocuSign OAuth consent screen. After approving, paste the
|
|
redirect URL back into the terminal. This grants the `impersonation` scope required
|
|
for JWT grant. After this runs once, all subsequent API calls use JWT automatically —
|
|
no further browser interaction needed.
|
|
|
|
---
|
|
|
|
## Running a migration
|
|
|
|
**List available templates in Adobe Sign:**
|
|
```bash
|
|
python3 src/download_templates.py list
|
|
```
|
|
|
|
**Download templates:**
|
|
```bash
|
|
python3 src/download_templates.py download # all templates
|
|
python3 src/download_templates.py download "Template Name" # one specific template
|
|
```
|
|
Downloads to `downloads/<template-name>__<id>/` — one folder per template containing
|
|
`metadata.json`, `form_fields.json`, `documents.json`, and the PDF.
|
|
|
|
**Convert a downloaded template to DocuSign format:**
|
|
```bash
|
|
python3 src/compose_docusign_template.py
|
|
```
|
|
Writes DocuSign template JSONs to `migration-output/<template-name>/docusign-template.json`.
|
|
|
|
**Upload to DocuSign:**
|
|
```bash
|
|
python3 src/upload_docusign_template.py --file migration-output/<name>/docusign-template.json
|
|
```
|
|
|
|
**Or run the full pipeline end-to-end:**
|
|
```bash
|
|
python3 src/migrate_template.py --list # show available templates
|
|
python3 src/migrate_template.py --template "Template Name" # download → convert → upload
|
|
python3 src/migrate_template.py --template "Template Name" --skip-upload # convert only
|
|
```
|
|
If multiple templates share the same name, the most recently modified one is used.
|
|
|
|
---
|
|
|
|
## Field type mapping
|
|
|
|
See [field-mapping.md](field-mapping.md) for the full Adobe Sign → DocuSign tab type table,
|
|
including edge cases and known gaps.
|
|
|
|
## Known API quirks and bugs
|
|
|
|
See [tests/PLATFORM-QUIRKS.md](tests/PLATFORM-QUIRKS.md) for documented platform bugs,
|
|
unexpected API behaviors, and the fixes applied.
|
|
|
|
---
|
|
|
|
## Project structure
|
|
|
|
```
|
|
src/
|
|
adobe_auth.py # One-time OAuth flow for Adobe Sign
|
|
adobe_api.py # Adobe Sign API client (auto token refresh)
|
|
download_templates.py # List and download templates from Adobe Sign
|
|
compose_docusign_template.py # Core conversion: Adobe Sign → DocuSign JSON
|
|
docusign_auth.py # DocuSign JWT auth + one-time consent flow
|
|
upload_docusign_template.py # Upload a template JSON to DocuSign REST API
|
|
migrate_template.py # End-to-end runner (download → convert → upload)
|
|
create_adobe_template.py # Utility: create a test template in Adobe Sign
|
|
generate_pdfs.py # Utility: generate sample PDFs for offline testing
|
|
|
|
downloads/ # Downloaded Adobe Sign templates (gitignored)
|
|
migration-output/ # Converted DocuSign template JSONs (gitignored)
|
|
sample-templates/ # JSON fixtures for offline testing (PDFs gitignored)
|
|
|
|
field-mapping.md # Field type mapping table + edge case log
|
|
tests/PLATFORM-QUIRKS.md # Known bugs and API quirks
|
|
requirements.txt # Python dependencies
|
|
```
|