Annotations added via Office Word JS api are not showing up when you reopen the document.

[SachinTekchandaniCrowe]

I have created an Word add-in that allows user to add a text with annotation in the current document. There is also a click handler defined to handle annotation click event. When the text with annotation is added they appear and work fine (like the clicks are triggered). But when you save the document (either manually or using context.document.save) and reopen it, you just see the text that was added and not the annotation.

Your Environment

• Platform [PC desktop, Mac, iOS, Office on the web]: PC Desktop
• Host [Excel, Word, PowerPoint, etc.]: Word
• Office version number: version 2409 (Build 18025.20214)
• Operating System: Windows 11 Enterprise
• Browser (if using Office on the web): NA

Expected behavior

Annotations must be saved within the document and when the document is opened, annotations be displayed. When add-in is loaded, the click event on annotations should call the click event handler defined in the add-in.

Current behavior

Annotations are not displayed. I also checked the document.xml (after saving the docx as zip file and extracting it) and there is no references to the annotations that were added.

Steps to reproduce

1. Create add-in and add text with annotation using Paragraph.insertAnnotations method.
2. Save the document (either manually or through code using context.document.save method)
3. Close the document.
4. Open the same document and you will notice the text that was added in step 1 but not the annotation.

Link to live example(s)

None

Provide additional details

None

Context

We are trying to build a citation viewer functionality using add-in. When citation (annotation in word api terms) is clicked, we will load the pdf in side panel.

Useful logs

None
Thank you for taking the time to report an issue. Our triage team will respond to you in less than 72 hours. Normally, response time is <10 hours Monday through Friday. We do not triage on weekends.

[guoms1]

Hi, @SachinTekchandaniCrowe

Thank you for sharing the details of the issue you encountered. We have carefully reviewed your report and attempted to reproduce the problem in our environment based on the provided information. Unfortunately, we were unable to replicate the behavior you described.

To help us investigate this further and identify the root cause, we kindly request a minimal code snippet that demonstrates the issue. This will greatly assist us in reproducing the problem under similar conditions.

We appreciate your understanding and look forward to resolving this matter for you.

Best regards,

[SachinTekchandaniCrowe]

Hi, @SachinTekchandaniCrowe

Thank you for sharing the details of the issue you encountered. We have carefully reviewed your report and attempted to reproduce the problem in our environment based on the provided information. Unfortunately, we were unable to replicate the behavior you described.

To help us investigate this further and identify the root cause, we kindly request a minimal code snippet that demonstrates the issue. This will greatly assist us in reproducing the problem under similar conditions.

We appreciate your understanding and look forward to resolving this matter for you.

Best regards,

Hi. Sorry for the delayed response.

Below is the code snippet

I have created this function that adds a text in the document with annotation and saves the document (you could also save the document manually).

async function insertAnnotation() {
  // Adds annotations to the selected paragraph.
  await Word.run(async (context) => {
    
    const selection = context.document.getSelection();
    const options1= {
      brandingTextResourceId: "PG.TabLabel",
      subtitleResourceId: "PG.HelpCommand.TipTitle",
      titleResourceId: "PG.Title",
      suggestions: ["Generated by office add-in"]
    };
    
    try 
    {
      
      let citationRange = selection.insertText("Annotation Text", Word.InsertLocation.after);
      citationRange.load("text, paragraphs");
      citationRange.font.color = "red";            
      await context.sync();   
      
      let annotation1 = {
        colorScheme: Word.CritiqueColorScheme.red,
        start: citationRange.paragraphs.items[0].text.length - citationRange.text.length,
        length: citationRange.text.length,
        popupOptions: options1
      };
      const annotationSet = {
        critiques: [annotation1]
      };
       
      let annotation = citationRange.paragraphs.items[0].insertAnnotations(annotationSet);
      await context.sync();        
      
	  //Save the document
	  context.document.save();
    } 
    catch (error) {
        console.error("Error inserting annotations:", error);
    }
    
  });
}

When the document is reopened, I run below function to attach onclick event handler

export async function onLoad() {
  Word.run(async (context) => {
    context.document.onAnnotationClicked.add(annotationClickHandler);    
    await context.sync();   
  });  
}

async function annotationClickHandler(args) {  
  await Word.run(async (context) => {
    const annId = args.id;
    console.log("Annotation clicked : " + annId);    
  });
}

What is happening is when the document is reopened, text on which annotation was added doesn't appear as annotation i.e. underline style is missing from the text and also when you click on the text onclickhandler doesn't get triggerred.

Note: During the session when the annotation was added and when you click it, the corresponding event handler was getting called.

[guoms1]

Hi, @SachinTekchandaniCrowe

Confirmed with the expert that this is the expected behavior.

Annotations are not persisted becaused they are only meant to provide visual indications, they are not part of the document.

Thanks,
Neo GUO