HelloSign to DocuSign Migration Script

This Python script migrates signature requests from HelloSign (now Dropbox Sign) to DocuSign, preserving the original sender information by using HelloSign's "Sent By" field as the DocuSign Owner. It supports batch migration with tracking of migration status through a CSV file.

Features

• Complete Migration: Transfers documents, recipients, and metadata from HelloSign to DocuSign
• Owner Preservation: Uses HelloSign's "Sent By" field as DocuSign Owner
• Batch Processing: Migrate multiple signature requests at once
• Progress Tracking: CSV-based tracking of migration status
• Multi-User Support: Migrate documents for multiple users with different HelloSign and DocuSign accounts
• Error Handling: Comprehensive logging and error handling
• Flexible Configuration: Support for both demo and production environments

Prerequisites

1. HelloSign API Keys: Get API keys for each user from HelloSign API Dashboard
2. DocuSign Developer Account: Create an account at DocuSign Developer Center
3. DocuSign JWT Authentication: Set up JWT authentication for impersonation
4. DocuSign Account IDs: Account identifiers for all users
5. User Mapping File: CSV file mapping HelloSign users to DocuSign users

Installation

1. Clone or download this project

2. Install dependencies:

   pip install -r requirements.txt

3. Copy the environment configuration:

   cp .env.example .env

4. Edit .env file with your DocuSign configuration:

   # DocuSign API Configuration
   DOCUSIGN_BASE_PATH=https://demo.docusign.net/restapi
   DOCUSIGN_INTEGRATOR_KEY=your_docusign_integrator_key
   DOCUSIGN_PRIVATE_KEY_FILENAME=docusign_private_key.key
   DOCUSIGN_ACCOUNT_ID=your_docusign_account_id
   DOCUSIGN_REDIRECT_URI=your_redirect_uri

5. Create a User_Mapping.csv file with the following columns:

   User_Name,User_Email,HelloSign_User_API_Key,DocuSign_User_ID
   

Usage

Basic Usage

1. Set up your environment variables (using .env file)

2. Create User_Mapping.csv with the following format:

   User_Name,User_Email,HelloSign_User_API_Key,DocuSign_User_ID
   John Doe,john@example.com,abc123hellosign_key,1234
   Jane Smith,jane@example.com,xyz456hellosign_key,5678
   

3. Run the migration script:

   python main.py

   This will:

   • Generate the all_user_migrated_content.csv file with all signature requests
   • Process all pending migrations

Advanced Usage

Generate Migration CSV Only

To only generate the CSV file without performing migrations:

from main import HelloSignClient, MigrationService

# Initialize client with any valid HelloSign API key
hellosign_client = HelloSignClient(api_key)
migration_service = MigrationService(hellosign_client, None)

# Generate the migration CSV
migration_df = migration_service.generate_migration_csv()
print(f"Generated CSV with {len(migration_df)} signature requests")

Custom Migration Logic

from main import HelloSignClient, DocuSignClient, MigrationService, get_docusign_access_token

# Get DocuSign access token using JWT
docusign_token = get_docusign_access_token("user@example.com")

# Initialize clients
hellosign_client = HelloSignClient(api_key)
docusign_client = DocuSignClient(docusign_token, account_id, base_url)
migration_service = MigrationService(hellosign_client, docusign_client)

# Migrate single request for specific user
success = migration_service.migrate_signature_request("signature_request_id", "user@example.com")

# Migrate multiple requests for specific user
results = migration_service.migrate_multiple_requests(["id1", "id2"], "user@example.com")

API Configuration

HelloSign API

• Base URL: https://api.hellosign.com/v3
• Authentication: Basic Auth using API key
• Required Permissions: Read signature requests and download files

DocuSign API

• Demo Base URL: https://demo.docusign.net/restapi
• Production Base URL: https://na1.docusign.net/restapi (varies by region)
• Authentication: Bearer token (OAuth2)
• Required Permissions: Create and send envelopes

Migration Process

Two-Step Process

1. Generate Migration CSV:
   • Scans all users' HelloSign accounts
   • Creates CSV with all signature requests
   • Sets initial status to "Pending"
2. Process Migrations:
   • Reads CSV file for pending migrations
   • For each user, processes their pending migrations:
     • Authenticates with both HelloSign and DocuSign
     • Fetches and migrates each document
     • Updates CSV with status ("Done" or "Failed")
     • Provides detailed summary after completion

Per-Document Process

1. Fetch HelloSign Data: Retrieves signature request details and metadata
2. Download Documents: Downloads PDF files from HelloSign
3. Map Recipients: Converts HelloSign signers to DocuSign recipients
4. Create Envelope: Creates new DocuSign envelope with:
   • Original document content
   • Recipient information
   • Email subject and message
   • Custom field storing original sender email
5. Send Envelope: Automatically sends the envelope to recipients
6. Update Status: Records migration result in CSV file

Data Mapping

HelloSign to DocuSign Fields

HelloSign Field	DocuSign Field	Notes
requester_email_address	Custom Field: OriginalSender	Preserves original sender
title	Document Name	Document title
subject	Email Subject	Email subject line
message	Email Blurb	Email message body
signatures[].signer_email_address	Recipients Email	Signer email
signatures[].signer_name	Recipients Name	Signer name
signatures[].order	Routing Order	Signing order

Migration CSV Fields

Field	Description
User_Name	Name of the user from User_Mapping.csv
User_Email	Email of the user from User_Mapping.csv
signature_request_id	HelloSign signature request ID
Migrate_Status	Migration status (Pending, Done, Failed)
Timestamp	Last update timestamp

Error Handling

The script includes comprehensive error handling:

• API Errors: Logs HTTP errors with response details
• Missing Data: Handles missing or incomplete signature requests
• Network Issues: Retries and proper error reporting
• Validation: Checks for required fields before processing

Logging

All operations are logged with timestamps and severity levels:

• INFO: Normal operation progress
• WARNING: Non-critical issues
• ERROR: Failed operations with details

Security Considerations

1. Environment Variables: Store API keys in environment variables, not in code
2. Access Tokens: Use short-lived access tokens when possible
3. Network Security: Use HTTPS for all API calls
4. Data Handling: Documents are processed in memory and not stored locally

Limitations

1. Document Types: Currently supports PDF documents only
2. Signature Positioning: Places signature tabs at default positions
3. Custom Fields: Limited to basic text custom fields
4. Rate Limits: Subject to API rate limits of both services

Troubleshooting

Common Issues

1. Authentication Errors:

   • Verify HelloSign API keys in User_Mapping.csv
   • Check DocuSign JWT configuration
   • Ensure DocuSign users have proper permissions
   • Verify correct base URLs

2. Document Download Failures:

   • Check HelloSign signature request status
   • Verify file permissions
   • Ensure signature request IDs in the CSV are valid
   • Check user has access to the requested document

3. Envelope Creation Failures:

   • Validate recipient email addresses
   • Check DocuSign account limits
   • Verify document format

Debug Mode

Enable detailed logging by setting log level to DEBUG:

logging.basicConfig(level=logging.DEBUG)

Support

For issues related to:

• HelloSign API: HelloSign Support
• DocuSign API: DocuSign Developer Support
• This Script: Check the error logs and ensure all prerequisites are met

License

This project is provided as-is for educational and integration purposes. Please ensure compliance with both HelloSign and DocuSign terms of service when using their APIs.