Working with WordWaiter class with Microsoft Dynamics NAV
SinceDynamics NAV 2017 Cumulative Update 13 – and also in Dynamics NAV 2018 – the Office Integration experience has been enriched by a new interop assembly to handle non-modal calls to Microsoft Word and retrieve document close events.
The .NET Type added to Microsoft.Dynamics.Nav.Integration.Office DLL are the following:
Microsoft.Dynamics.Nav.Integration.Office.Word.WordDocumentWaiter
Microsoft.Dynamics.Nav.Integration.Office.Word.WordDocumentWaiter+DocumentCloseHandlerEventArgs
A typical example where this could be used is when there are multiple documents to be open at the same time that needs to be checked and/or reviewed (revision) by users. This task might be interrupted by e.g. a call or whatever other activities in between. If used modally or in any other context scenario, users would have been forced to close the document(s) to go back to client activity or run another client session in parallel.
The WordDocumentWaiter paradigm helps registering an open document for the close event and expose it to the client in order to take action consequently. Below a practical and simple proof of concept
- Create 2 NEW Word document files in e.g. C:\TEMP folder and call it like
– ALPHA.docx
– BETA.docx - Import the page object that we attached as content to this blog post. Save, compile, and run it.
- In the FileName field type the path of the first file (C:\TEMP\ALPHA.docx) and click Register File. The word document specified will open. NOTE: the page must not be closed.
- In the FileName field type the path of the first file (C:\TEMP\BETA.docx) and click Register File action. The word document specified will open. NOTE: the page must not be closed.
- Now you can go back to the client and perform whatever activity you like, such as searching for a customer, browsing the item list, etc.
- Go back to one of the 2 documents open (e.g. ALPHA.docx) and do some modifications to the document (this is not mandatory) and then save and close the document. The Test Word Close Events page will trigger the close event and report the following
- Back to the remaining document, BETA.DOCX, do some modifications to the document (this is not mandatory) and then save the document with a different name (save as) like. E.g. C:\TEMP\GAMMA.docx and close it. The Test Word Close Events page will trigger the close event and report the following
WORDWAITER USAGE CONSTRAINTS
- The DotNet data types that are used with Microsoft Word must be declared as GLOBAL variables in the page with [RUNONCLIENT]. Therefore, it is not possible to move or centralize their declaration within a codeunit.
- Class instance must also enable the events [WITHEVENTS].
- Any WordDocument variable declared in the local function scope will be disposed when the function return and the application cannot keep the function running as the client will be inaccessible while the action is running. In other words, the WordDocument(s) object in AL must be a local variable as it will be invalidated next time you register a document. Global cannot be used within a multiple document context.
- OriginalFileName member contains the name that was registered. Each COM Word Document do have an internal immutable DocID which you can link to a file name. WordWaiter uses a dictionary with the registered original file name values and DocID as the key. The event handler is designed to handle registered files only and will remove the keys when their associated files are closed.
NOTE: DocID is unique PER DOCUMENT. This means that if you make a COPY of a document, DocID is MAINTAINED hence if you have document ALPHA and copyofdocumentALPHA ,then these have the same DocID and using OriginalFileName might become difficult. This is a constraint that must be taken into consideration during development.
NAV2017.Test-Word-Close-Events
NAV2018.Test-Word-Close-Events
These postings are provided “AS IS” with no warranties and confer no rights. You assume all risk for your use.
Duilio Tacconi (dtacconi)
Microsoft Dynamics Italy
Microsoft Customer Service and Support (CSS) EMEA
Thanks to Niels-Henrik Sejthen (Server Backend team MDCC Lyngby)