Retrieving a document’s filename using Microsoft’s powerful, yet sometimes nuanced, Word.JS API unearths a critical insight into the API’s asynchronous design: the danger of relying on seemingly ‘live’ synchronous values that are actually stale. This seemingly straightforward request often hides surprising complexities that our teams at Revelry are adept at navigating efficiently.
The Word.JS API is relatively new compared to the more mature APIs Microsoft has put out, such as those for VB and C#. The documentation provides this description: “…provides strongly-typed objects that you can use to access objects and metadata in a Word document” – https://learn.microsoft.com/en-us/office/dev/add-ins/reference/overview/word-add-ins-reference-overview
Let me explain a few quirks of the Word.JS API to provide context for what follows and why it matters. It relies heavily on asynchronous callbacks to load and sync data. That looks something like this:
async function doSomethingWithTheWordAPI() {
await Word.run(async (context) => {
/* In this code block, I might make changes to the document or it's properties. Then I would call context.sync which reconciles the changes I'm making with the actual document.
*/
await context.sync();
});
}
Whenever a developer wants to interact with a Word document using Word.JS API, it’s going to happen in a code block like this. Whether it’s inserting text or searching paragraphs, or anything else, you need a Word.run block. There is an exception, however. Some meta information can be derived about the document outside of a block, as long as your office context is initialized. If it is, you can access some information via Office.context.document. If we look at the documentation for Document, we can see that there is a properties key. If we look at the documentation for that, we see a property called title, described as: ”Specifies the title of the document.”
Naively, you might think that you can get this property, and use that as the filename. However, the title property on the document properties is not the filename you see at the top of your window when working in Word. It’s actually a meta value you have to supply to the document in the properties window. Here it is for Mac:
That’s no big deal. I misunderstood what the title property represented. I can adjust my approach. Looking at the Office.context.document object in my code editor reveals another property that might be useful: url.
interface Document {
// ... other props
/**
* Gets the URL of the document that the Office application currently
has open. Returns null if the URL is unavailable.
*/
url: string;
// ... rest of the props
}What’s confusing about this is that it is not the Word Document object, but instead the Office Document Object. They’re both document objects, but one is specific to Word and accessed in that Word.run code block I mentioned before. The other is used in the common api that’s used by Word, Excel, Outlook, etc and that’s the one that lives on the Office.context. Office.context.document.url will give a file path to where the document is on your computer, and as long as I get the last part of that file path, that should work, right? Well…yes and no. It’s easy to get crossed up because of the way this works. My function for getting the file name looked like this:
function loadFileName(): string {
return Office.context.document.url?.split("/").pop() || "document.docx";
}My thought process was, if Office.context.document.url is null, we give it the default filename of document.docx for my purposes. This wouldn’t name the file, but it would provide a filename where I need it. That way the app would still allow the upload even if the file didn’t have a name yet.
When I went to test this though, I always got my fallback value. I made sure the document was saved and had a file name, but no luck. I thought I had fixed it at one point because I finally got the url I was expecting, but whenever anyone else used it they got the fallback (except in one particular case when they were using sharepoint, and to confuse things, there was another bug reported where the Office.context.document.url from sharepoint wouldn’t update when the filename updated). Fun!
It turns out that the reason for all of this odd behavior was the way I was getting the url value. Office.context.document.url is static when retrieved this way. When starting with a fresh document, the url would be an empty string, hence hitting my fallback case. When I opened a file which had already been saved, the url would be the correct filename. If I changed the filename from contract-1 to contract-2, the office.context.document.url wouldn’t update.
The proper way to get the most up to date values from the office context is to use the Office.context.document.getFilePropertiesAsync method:
async function loadFileName(): Promise<string> {
try {
const result = await new Promise<Office.AsyncResult<Office.FileProperties>>((resolve) => {
Office.context.document.getFilePropertiesAsync(resolve);
});
if (result.status === Office.AsyncResultStatus.Succeeded && result.value.url) {
const docUrl = result.value.url;
const urlParts = docUrl.split(/[/\\]/); // Handle both forward and back slashes
const maybeFileName = urlParts.pop();
if (maybeFileName && maybeFileName.length > 0) {
return decodeURIComponent(maybeFileName);
}
}
// Fallback to timestamp-based name
return `document-${Date.now()}.docx`;
} catch (error) {
console.warn("Error getting filename:", error);
return `document-${Date.now()}.docx`;
}
}Loading the values this way ensures they are up to date every time. My advice when using the Word.JS API is to remember you’re dealing with 2 APIs (Word and Office) and to be wary of synchronous operations and properties, because they may be giving you stale values. The API is designed to be asynchronous. Remember that or you’ll sync too much time into debugging it.