Saving PDF annotations

Nutrient Web SDK allows making changes to documents in these two fundamental ways:

• Changes to the document records (including annotations, form field values, comments, or bookmarks). These changes can be saved without touching the original document.

• Changes to the document itself either via the Document Editor or when digitally signing the document. These require saving the whole document.

This article explains the annotation saving mechanism. Refer to the Save a Document guides to learn more about document saving itself.

The annotation saving mechanism depends on the operational mode being used.

Nutrient Web SDK with Document Engine

By default, changes to annotations are always synced to the server. This means you can always use the backend API to interact with annotations. This auto-save behavior can be configured by the instantiation configuration option, Configuration#autoSaveMode. Learn more about this option in our Auto-Save guide.

Before the change is sent to the server, we assign a stable ID (ULID). This ID is also used by the server, and it allows you to track updates that happen to the annotation before the server responds.

ℹ️ Note: Each change sent to the server requires a unique ID. If you need to reference the annotation ID before it’s created (for example, when creating form fields with their widgets), a suitable ULID can be generated via PSPDFKit#generateInstantId().

If you’d like to ensure a new annotation has been saved by the server, use Instance#ensureChangesSaved:

PSPDFKit.load(configuration).then(async (instance) => {
	const createdAnnotations = await instance.create(newAnnotation);
	const [savedAnnotation] = await instance.ensureChangesSaved(
		createdAnnotations,
	);
	console.log(savedAnnotation.id); // => '01BS964AM5Z01J9MKBK64F22BQ'
});

Before annotations are saved, annotations.willSave is emitted. When this event occurs, you can be sure we’ll commit changes to the underlying backend. As an example, this event can be used to display a loading indicator.

After the server responds to our changes, annotations.didSave is emitted. This event will always follow annotations.willSave.

Standalone Web SDK

In a Web SDK installation, annotations will be stored in memory until they’re exported. See the guide on exporting and importing XFDF, Instant JSON or using the Document Engine mode for more information.

Without Document Engine (i.e. standalone Web SDK), annotation persistence steps are the same. This means we still differentiate between saved and unsaved annotations, and the exported Instant JSON will only contain annotations that are saved. Configure the auto-save behavior by the instantiation configuration option, Configuration#autoSaveMode. Learn more about this option in our auto save guide.