The SmartDocs API
SmartDocs is a COM add-in that executes within the Microsoft® Word application window. The add-in is based on the IDTExtensibility2 interface developed for Office® applications that enables Office applications to load third-party software that runs in the application window and extends the Office application's features.
When SmartDocs is loaded, it exposes an Application Programming Interface (API) that can be leveraged by developers to programmatically perform certain SmartDocs actions – available to the user on the SmartDocs tab, dialog boxes, and custom task pane. For example, variables can be populated, snippets inserted, and documents published.
This capability makes it possible to:
- Streamline often used steps in a workflow through the use of macros running inside the Microsoft Word process. The user can invoke a macro that executes a preset series of actions that would otherwise need to be performed manually. For example, it may be necessary to make editing changes to a document once it's been published. A macro can handle the publishing, plus all repetitive editing required, and then save and/or print the result.
- Automate document production from an application running outside of the Microsoft Word process.
SmartDocs Help File
The SmartDocs API Help file SmartDocs_Automation_API_220.chm can be downloaded by going to our Support Center and selecting the Downloads page. The information is presented in a format familiar to .NET developers; syntax is presented in C#; there are some VBA code samples.
If you are not familiar with C#, do not let the fact that the syntax is in that language deter you. You will mainly be looking at it to see what parameters are used; all you need to know is that the datatype precedes the parameter (and method) name, rather than following it and the keyword "As".
The exposed API comprises ten classes. Three of these are for managing the API and are discussed briefly in this article:
- SmartDocsAutomationService
- SmartDocsAutomationResult
- SmartDocsAutomationDocument
The remaining seven represent SmartDocs functionality:
- SmartDocsAutomationConditionalContent
- SmartDocsAutomationConditionalTag
- SmartDocsAutomationReusableSnippet
- SmartDocsAutomationReusableSnippetContent
- SmartDocsAutomationReusableVariable
- SmartDocsAutomationSmartBuilder
- SmartDocsAutomationMacroResult
Under each class there is a list of methods and/or properties used to manipulate the feature associated with it.
Initiating Interaction with the API
The entry point into the API is provided by the class SmartDocsAutomationService. A variable for the class is declared with the datatype Object. The COM Add-in instance for SmartDocs is invoked and its Object.Automation property assigned to the AutomationService object.
'VBA
Dim AutomationService As Object
Set AutomationService = Application.COMAddIns(_
"ThirtySix.SmartDocs.AddIn").Object.Automation
NOTE: No COM type library (dll or tlb) is provided. On the one hand, this means that it's not necessary to set a reference in order to use the API; but it also means there is no IntelliSense available for working with it.
Of course, it is important to know whether communication with the API has been properly initialized. For this purpose, the class provides the Initialized property. If this returns false, there was a problem and a follow up attempt is made to force initialization using the Initialize method.
At this point, things become somewhat unfamiliar for the VBA developer. In order to get back information from the API about whether method execution was successful, it is necessary to assign the method to an AutomationResult object. Depending on the outcome of the method invocation, the AutomationResult object's properties return information on whether the method was successful, what the error code was (if any), and the message associated with it.
'VBA
Dim AutomationResult As Object
If Not AutomationService.Initialized Then
Set AutomationResult = AutomationService.Initialize
If Not AutomationResult.Success Then
MsgBox "Error occurred initializing SmartDocs automation service: " & _
vbCr & "Error code: " & AutomationResult.ErrorCode & vbCr & _
AutomationResult.Message
Exit Sub
End If
End If
If initialization was successful, then the next step is to pick up the document where the SmartDocs API needs to work. This is done with the method GetDocument, to which a Word.Document object is passed.
Again, for the VBA developer this involves additional, unfamiliar steps. As with initialization of the API, a variable of datatype Object is required to capture the result of the method GetDocument (it can be the same AutomationResult variable, or another one with a different name).
Only if the method is successful is a variable of datatype Object for the SmartDocs document (AutomationDocument) instantiated; it is assigned the AutomationResult.Object object returned by the method.
'VBA
Dim AutomationDocument as Object
Set AutomationResult = AutomationService.GetDocument(ActiveDocument)
If Not AutomationResult.Success Then
MsgBox "Error occurred getting SmartDocs automation document: " & AutomationResult.Message
Exit Sub
End If
Set AutomationDocument = AutomationResult.Object
NOTE: It's important to recognize that in this API the methods do not directly return the objects required for variable instantiation. Those objects are returned by the Object property of an object of the SmartDocsAutomationResult class. This pattern is followed throughout the SmartDocs API object model.
The code described here can be seen in full in the Help file topic SmartDocsAutomationService Class.
Access to working with SmartDocs functionality is through the AutomationDocument object. This object is the gateway to working with the API and is explained in more detail in the article titled VBA Macros and SmartDocs: Retrieving a SmartDocs Document.
Comments