From b67f26cc21c65062dd0db9fbf81342ea7b42204b Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Tue, 7 Oct 2025 21:31:38 +0200
Subject: [PATCH] refactor(PDFBurner): enhance annotation ID handling and
 validation

- Added parsing of annotation `id` into `envelopeId`, `receiverId`, `index`, and `internalType`.
- Added validation for `id` format, ensuring it has exactly 4 parts and numeric checks for relevant fields.
- Throws `BurnAnnotationException` if `id` is null, empty, or incorrectly formatted.
- Maintains existing functionality for adding image, ink, and widget annotations.
---
 .../Jobs/FinalizeDocument/PDFBurner.vb        | 101 +++++++++++++-----
 1 file changed, 72 insertions(+), 29 deletions(-)

diff --git a/EnvelopeGenerator.CommonServices/Jobs/FinalizeDocument/PDFBurner.vb b/EnvelopeGenerator.CommonServices/Jobs/FinalizeDocument/PDFBurner.vb
index f5f3cc6d..83155e46 100644
--- a/EnvelopeGenerator.CommonServices/Jobs/FinalizeDocument/PDFBurner.vb
+++ b/EnvelopeGenerator.CommonServices/Jobs/FinalizeDocument/PDFBurner.vb
@@ -76,35 +76,35 @@ Namespace Jobs.FinalizeDocument
             Dim isSeal = True   'First element is signature seal
 
             Dim formFieldIndex = 0
-                For Each oAnnotation In oAnnotationData.annotations
-                    Logger.Debug("Adding AnnotationID: " + oAnnotation.id)
-
-                    Select Case oAnnotation.type
-                        Case ANNOTATION_TYPE_IMAGE
-
-                            If (isSeal) Then
-                                oAnnotation.bbox.Item(1) = yPosOfSigAnnot
-                            End If
-
-                            AddImageAnnotation(oAnnotation, oAnnotationData.attachments)
-                            Exit Select
-
-                        Case ANNOTATION_TYPE_INK
-                            AddInkAnnotation(oAnnotation)
-                            Exit Select
-
-                        Case ANNOTATION_TYPE_WIDGET
-                            'Add form field values
-                            Dim formFieldValue = oAnnotationData.formFieldValues.FirstOrDefault(Function(fv) fv.name = oAnnotation.id)
-                            If formFieldValue IsNot Nothing AndAlso Not _pdfBurnerParams.IgnoredLabels.Contains(formFieldValue.value) Then
-                                AddFormFieldValue(oAnnotation, formFieldValue, formFieldIndex)
-                                formFieldIndex += 1
-                            End If
-                            Exit Select
-                    End Select
-
-                    isSeal = False
-                Next
+            For Each oAnnotation In oAnnotationData.annotations
+                Logger.Debug("Adding AnnotationID: " + oAnnotation.id)
+
+                Select Case oAnnotation.type
+                    Case ANNOTATION_TYPE_IMAGE
+
+                        If (isSeal) Then
+                            oAnnotation.bbox.Item(1) = yPosOfSigAnnot
+                        End If
+
+                        AddImageAnnotation(oAnnotation, oAnnotationData.attachments)
+                        Exit Select
+
+                    Case ANNOTATION_TYPE_INK
+                        AddInkAnnotation(oAnnotation)
+                        Exit Select
+
+                    Case ANNOTATION_TYPE_WIDGET
+                        'Add form field values
+                        Dim formFieldValue = oAnnotationData.formFieldValues.FirstOrDefault(Function(fv) fv.name = oAnnotation.id)
+                        If formFieldValue IsNot Nothing AndAlso Not _pdfBurnerParams.IgnoredLabels.Contains(formFieldValue.value) Then
+                            AddFormFieldValue(oAnnotation, formFieldValue, formFieldIndex)
+                            formFieldIndex += 1
+                        End If
+                        Exit Select
+                End Select
+
+                isSeal = False
+            Next
         End Sub
 
         Private Function AddImageAnnotation(pAnnotation As Annotation, pAttachments As Dictionary(Of String, Attachment)) As Void
@@ -193,7 +193,50 @@ Namespace Jobs.FinalizeDocument
         End Class
 
         Friend Class Annotation
+
+            Private _id As Integer
+
+            Public envelopeId As Integer
+
+            Public receiverId As Integer
+
+            Public index As Integer
+
+            Public internalType As String
+
             Public Property id As String
+                Get
+                    Return _id
+                End Get
+                Set(value As String)
+                    _id = value
+
+                    If String.IsNullOrWhiteSpace(id) Then
+                        Throw New BurnAnnotationException("The identifier of annotation is null or empty.")
+                    End If
+
+                    Dim parts As String() = value.Split("-"c)
+
+                    If (parts.Length <> 4) Then
+                        Throw New BurnAnnotationException($"The identifier of annotation has more or less than 4 sub-part. Id: {_id}")
+                    End If
+
+                    If Not Integer.TryParse(parts(0), envelopeId) Then
+                        Throw New BurnAnnotationException($"The envelope ID of annotation is not integer. Id: {_id}")
+                    End If
+
+                    If Not Integer.TryParse(parts(1), receiverId) Then
+                        Throw New BurnAnnotationException($"The receiver ID of annotation is not integer. Id: {_id}")
+                    End If
+
+                    If Not Integer.TryParse(parts(2), index) Then
+                        Throw New BurnAnnotationException($"The index of annotation is not integer. Id: {_id}")
+                    End If
+
+                    internalType = parts(3)
+                End Set
+            End Property
+
             Public Property bbox As List(Of Double)
             Public Property type As String
             Public Property isSignature As Boolean