Signing Workflow

​

Overview

​

Workflow States

​

DRAFT

• Document is being configured
• Recipients are being added
• Fields are being positioned on the document
• No emails have been sent
• Document can be freely edited or deleted

​

PENDING

• Document has been distributed to recipients
• One or more recipients have not yet completed their actions
• Recipients can view and sign the document
• Sender can track recipient activity
• Document cannot be edited (only canceled)

​

COMPLETED

• All recipients have completed their required actions
• Document is sealed with a signing certificate
• Completed PDF is generated and distributed
• Audit log is finalized
• Document becomes read-only

​

REJECTED

• Signing process is terminated
• Remaining recipients cannot sign
• Rejection reason is recorded
• Document becomes read-only

​

Signing Modes

​

Parallel Signing

DocumentSigningOrder.PARALLEL

• All recipients receive the document at the same time
• Recipients can complete actions in any order
• Fastest completion time
• Ideal for simple approval workflows
• No dependencies between signers

• Team agreements where order doesn’t matter
• Multi-party contracts with equal standing
• Acknowledgment forms
• Internal approvals

​

Sequential Signing

DocumentSigningOrder.SEQUENTIAL

• Recipients are assigned a signingOrder number (0, 1, 2, etc.)
• Only the current recipient in sequence can access the document
• Next recipient is notified only after previous completes
• Enforces hierarchical approval chains
• Supports “dictate next signer” feature

• Hierarchical approvals (employee → manager → executive)
• Chain of custody requirements
• Progressive disclosure workflows
• Compliance scenarios requiring ordered sign-off

documentMeta: {
  signingOrder: DocumentSigningOrder.SEQUENTIAL
}

recipients: [
  { email: '[email protected]', signingOrder: 0 },
  { email: '[email protected]', signingOrder: 1 },
  { email: '[email protected]', signingOrder: 2 }
]

documentMeta: {
  allowDictateNextSigner: true
}

​

Workflow Events

​

Document Level

• DOCUMENT_CREATED - Document is created in DRAFT state
• DOCUMENT_SENT - Document transitions from DRAFT to PENDING
• DOCUMENT_COMPLETED - All recipients have completed actions
• DOCUMENT_REJECTED - Any recipient rejects the document
• DOCUMENT_CANCELLED - Sender cancels the document

​

Recipient Level

• EMAIL_SENT - Invitation email sent to recipient
• DOCUMENT_OPENED - Recipient views the document
• DOCUMENT_FIELD_INSERTED - Recipient completes a field
• DOCUMENT_RECIPIENT_COMPLETED - Recipient completes all required fields
• DOCUMENT_RECIPIENT_REJECTED - Recipient rejects with reason
• RECIPIENT_EXPIRED - Recipient’s signing deadline passes

​

Workflow Logic

​

Sending a Document

1. Validation Phase
   • Check all recipients have valid emails
   • Verify all recipients have required fields assigned
   • Validate field configurations (required fields, validation rules)
   • Ensure at least one recipient exists
2. Status Update
   • Document status changes to PENDING
   • Recipient sendStatus changes to SENT
3. Notification Phase
   • In parallel mode: All recipients receive emails immediately
   • In sequential mode: Only the first recipient (signingOrder: 0) receives email
4. Audit Trail
   • DOCUMENT_SENT event logged
   • EMAIL_SENT events logged for each notified recipient

​

Completing a Signature

1. Field Validation
   • All required fields must be completed
   • Field values must pass validation rules
   • Authentication requirements must be met
2. Recipient Update
   • signingStatus changes from NOT_SIGNED to SIGNED
   • signedAt timestamp is recorded
   • Field data is inserted into the PDF
3. Next Steps Logic
   IF sequential signing AND more recipients:
     Notify next recipient in sequence
   ENDIF
   
   IF all recipients completed:
     Transition document to COMPLETED
     Generate sealed PDF with certificate
     Send completion notifications
   ENDIF
   
4. Audit Trail
   • DOCUMENT_FIELD_INSERTED events for each field
   • DOCUMENT_RECIPIENT_COMPLETED event
   • DOCUMENT_SIGNED webhook triggered

​

Document Completion

1. Status Update
   • Document status changes to COMPLETED
   • completedAt timestamp is set
2. PDF Sealing
   • All field data inserted into PDF
   • Signing certificate generated and appended
   • Audit log generated and appended (if enabled)
   • Final PDF is cryptographically signed
3. Distribution
   • Completed PDF sent to all recipients
   • Completion notification emails sent
   • Webhooks triggered
4. Archival
   • Document becomes read-only
   • QR token generated for certificate verification

​

Error Handling

​

Common Workflow Errors

if (envelope.recipients.length === 0) {
  throw new AppError(AppErrorCode.NOT_FOUND, {
    message: 'Document has no recipients'
  });
}

const recipientsWithMissingFields = getRecipientsWithMissingFields({
  recipients,
  fields
});

if (recipientsWithMissingFields.length > 0) {
  throw new AppError(AppErrorCode.INVALID_REQUEST, {
    message: 'Some recipients are missing required fields'
  });
}

const invalidRecipients = recipients.filter(
  recipient => !isRecipientEmailValidForSending(recipient.email)
);

if (!getIsRecipientTurn({ envelope, recipient })) {
  throw new AppError(AppErrorCode.UNAUTHORIZED, {
    message: 'It is not your turn to sign this document'
  });
}

​

Best Practices

​

Choosing Signing Mode

• Use parallel for simple, time-sensitive documents
• Use sequential for hierarchical approvals or compliance requirements
• Consider recipient timezones when using sequential signing

​

Workflow Optimization

• Set expiration dates to prevent indefinite pending states
• Use reminders for overdue recipients
• Enable authentication for sensitive documents
• Configure webhooks to integrate with your systems

​

Error Prevention

• Validate recipient emails before sending
• Ensure all recipients have at least one field assigned
• Test sequential ordering before production use
• Set reasonable expiration periods

​

Integration Points

​

Webhooks

{
  "event": "DOCUMENT_COMPLETED",
  "data": {
    "documentId": "doc_123",
    "status": "COMPLETED",
    "completedAt": "2024-03-15T10:30:00Z"
  }
}

​

API Endpoints

• POST /api/v1/documents/:id/send - Send a document
• POST /api/v1/documents/:id/complete - Complete recipient action
• GET /api/v1/documents/:id - Check document status
• POST /api/v1/documents/:id/cancel - Cancel pending document