Importing and Exporting Annotations in a Database

Using export and import functionality provided by PSPDFKit for Web, you can save any changes made to annotations in a file, save that file in a database of your choice, and then import it when you open the document again to restore the changes. The benefit of this approach is that you don’t need to transfer the whole modified document over the network to save it in your database. Rather, you only send the annotations, which saves bandwidth.

Note that if you use the Web Server-Backed operational mode, all of this is transparently handled for you. Any changes made to the annotations are saved to the Document Engine backend, and all the annotations are loaded back when you open the document again. The whole file is never transferred from the server to the client.

If you choose to use the Standalone operational mode, you can use either Instant JSON or XFDF as the export format.

Export and Import Instant JSON from the Database

To export all annotation changes to Instant JSON, you first need to make sure they’re saved. One option is to use the PSPDFKit.Instance.save method to wait for all the changes to be saved and only then export Instant JSON:

await instance.save();
const instantJSON = await instance.exportInstantJSON();
// This saves the Instant JSON to your server, which in turn stores it in a database.
await fetch("https://your-server.example.com/instant-json", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(instantJSON)
});

Alternatively, you can use the annotations.didSave event to export the Instant JSON to the database as soon as any annotation changes are made:

instance.addEventListener("annotations.didSave", async () => {
  const instantJSON = await instance.exportInstantJSON();
  // This saves the Instant JSON to your server, which in turn stores it in a database.
  await fetch("https://your-server.example.com/instant-json", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(instantJSON)
  });
});

To import the annotations saved as Instant JSON when opening the document, pass the Instant JSON object in the configuration to the PSPDFKit.load:

// This loads the Instant JSON from your server, which retrieves it from the database.
const response = await fetch("https://your-server.example.com/instant-json");
const instantJSON = await response.json();
PSPDFKit.load({
  // required options..
  instantJSON: instantJSON
});

ℹ️ Note: The instantJSON option is only supported by PSPDFKit for Web Standalone.

The benefit of using Instant JSON over the XFDF format is that Instant JSON represents the changes made to annotations, whereas XFDF is a complete snapshot of all the annotations in a document. For documents that originally contained a lot of annotations, Instant JSON might greatly reduce the required bandwidth.

Export and Import XFDF from the Database

To export all annotations to XFDF, make sure any changes made are saved first. One option is to use the PSPDFKit.Instance.save method to wait for all the changes to be saved, and only then export XFDF:

await instance.save();
const xfdf = await instance.exportXFDF();
// This saves the XFDF payload to your server, which in turn stores it in a database.
await fetch("https://your-server.example.com/xfdf", {
  method: "POST",
  body: xfdf
});

Alternatively, you can use the annotations.didSave event to export the XFDF to the database as soon as any annotation changes are made:

instance.addEventListener("annotations.didSave", async () => {
  const xfdf = await instance.exportXFDF();
  // This saves the XFDF payload to your server, which in turn stores it in a database.
  await fetch("https://your-server.example.com/xfdf", {
    method: "POST",
    body: xfdf
  });
});

To import the annotations saved as XFDF when opening the document, pass the XFDF payload in the configuration to the PSPDFKit.load:

// This loads the XFDF payload from your server, which retrieves it from the database.
const response = await fetch("https://your-server.example.com/instant-json");
const xfdf = await response.text();
PSPDFKit.load({
  // required options..
  XFDF: xfdf
});

ℹ️ Note: The XFDF option is only supported by PSPDFKit for Web Standalone.