Troubleshooting the Agiloft Contract Assistant for Word
Use the following resources to ensure that the configuration and installation of the Agiloft Contract Assistant for Microsoft Word are completed successfully. This resource, along with the hyperlinked pages throughout it, should include everything you need when setting up the ACA to work with a KB. Error messages and their solutions are included in tables specific to each section.
Consult this section before you install the ACA, or if you have some problems during installation.
- It is strongly recommended to only use the ACA for Word with
.docxfiles. Using any other type of file can result in but not be limited to tagged annotations no longer loading or issues with running Analyze Document. Handwritten contracts will not register with the ACA.
- Adding a Key Term to the Key Term table does not allow the AI model to extract that annotation from the Contract automatically. However, if you add a Key Term to the Key Term table, you can manually tag that Key Term in your contract and upload it to the Contract record if you create the proper field with a matching label in the Contract record.
This section assures that you have some basic settings in your KB turned on, as well as to ensure that your version and structure of Agiloft is compatible with the ACA.
- Determine the Agiloft release version of the KB. Depending on the version of Agiloft, you may need various updates in order to run the add-in correctly.
For any KB created prior to 11/13/2020, using the ACA with the Clause Library requires extra Global Variables. This is especially important for enabling the markup feature that occurs when annotations are updated in the body of the contract document.
- If you intend to use the ACA with Agiloft's native AI capabilities, ensure you have AI enabled in your system. You can check this by navigating to Setup > Integration. If you see Deploy or Enable under the AI section, your system has the correct license to use AI. For more information, visit Setting Up AI.
- If you receive the error message "
No metadata_type_table configured" it is likely that you have upgraded your KB software but have not updated the manifest file. To do so, simply download a new manifest file from your KB, remove the unused manifest files from your shared Folder, clear your Office add-in cache, and then move the newly downloaded file to your shared Folder. Then, add the new ACA in Microsoft Word.
|No metadata_type_table configured||Download a new manifest file from your KB, remove the unused manifest files from your Ssared Folder, clear your Office add-in cache, and then move the newly downloaded file to your shared Folder. Then, add the new ACA in Microsoft Word.|
This section assures that you have the basic KB structure necessary to configure and use the ACA.
- Before you can configure the ACA, ensure that your system contains certain tables and fields. These tables are:
- Clause Library
- Contract Clauses
- Clause Types
- Contract Types
If you intend to use the ACA with AI, there are a few additional system items you need, such as the AI Clause Types table. You can use the Preparing your KB section of the Configuring the Agiloft Contract Assistant - Word article for in-depth information about these tables.
Microsoft Word Trust Center Settings
When installing the ACA, you may find that the Shared Folder tab doesn't appear in the shared folder in the Microsoft Word add-in manager. When you try to click Refresh, you receive an error message that says "Cannot Connect to Catalog." To make manifests available in the shared folder in MS Word's add-in manager, the shared folder's network path must appear in the "Trusted Catalogs Table" in the Trust Center Settings. To fix this issue:
- In file explorer, navigate to the shared folder called
C:/AgiloftWordAddIn. This folder automatically added to your computer after the ShareFolder_byAdmin.bat script and the ConfigureWordAddin_byUser.bat script run during the Installation process.
C:/AgiloftWordAddInand select Properties.
- Navigate to the Sharing tab and copy the entire string under Network Path.
- Open Microsoft Word.
- Navigate to File > Options.
- On the left-hand side, select Trust Center.
- Click the Trust Center Settings... button.
- On the left-hand side of the new window, select Trusted Add-in Catalogs.
- Paste the Network Path string from step 3 into the Catalog Url field and click Add Catalog.
|Cannot connect to catalog||Add the shared folder's network path to the Trusted Catalogs Table in Microsoft Word's Trust Center Settings.|
Consult this section if you find issues with the ACA after you've installed it.
This section covers issues you may encounter when logging in. If you can't log in at all, it is likely a REST issue with your Group permissions, but if you can log in with a username and password, there is an issue with your SSO configuration.
- If you are unable to log in to the ACA once it is configured and installed:
- Ensure that the Group you are in has access to REST services. You can check by accessing the REST groups multichoice field by going to the Setup gear icon > System > Manage Web Services > Groups Allowed for REST. You can then check the list to see if your Group is selected. If it is not selected, select it and click Finish.
- If you get an error message when logging in with SSO, ensure that the SSO Login URL in the Add-in Configuration Wizard is filled in properly. This field should contain the URL copied from the setup page of your SSO configuration. When it is added into the SSO Login URL field, it should include everything, including the
https:and all the way to the end of the URL. For reference, check out the example below.
|EWWrongDataException: Session could not be created||If you get this error message when logging in, check your REST group permissions with the information mentioned above. If you can successfully login in with a username and password, but still get this error message when logging in with SSO, then it is your SSO configuration that requires attention.|
Manifest File Updates
If you don't see the new icon in your ribbon after your manifest file has been updated, you need to make sure you are logged in to O365. After the new manifest file has been uploaded, you need to connect with O365 in order to get the new version of the ACA onto your local instance of Microsoft Word. You can tell you are signed in by looking for your name at the very top of Microsoft Word.
Addin Diagnostic Log Table
The Addin Diagnostic Log table is a System table that allows you to track your Word ACA usage in Agiloft. This table is useful because it gives you a visual track record for the behavior of the ACA in the System Logs field of the Addin Diagnostic Log record. You can turn on this feature to help Agiloft representatives diagnose issues you may be having with your ACA. For example, if you want the Agiloft Engineering or Support team to help you with an issue that isn't already listed in this article, you should turn on diagnostics logging, reproduce the undesirable behavior, and then create a Support ticket or contact your Agiloft representative. This feature is especially helpful if your issue involves Microsoft Word crashing.
To complete this process:
- Log in to the ACA for Word.
- Click the menu icon on the top right-hand corner and select Settings.
- Toggle Enable Diagnostic Logging to Yes to create an Addin Diagnostics Log record. Take note of the new Addin Diagnostic Log record's ID.
- Repeat whatever behavior led the problem with the Word ACA. Ideally, these steps should be written down somewhere so they can be easily shared and reproduced.
- After the behavior has been repeated, copy the log text from the Settings page and attach it to a Support ticket. If the ACA for Word crashed and the Settings pane is no longer open, you can access the log text by checking the corresponding record in the Addin Diagnostic Log table. This table can be found under System.
This section covers some system edits you may need to make if the ACA is not working as intended.
- If you see multiple blank Attachment records get created in the KB instead of a single complete record when data is synced using the Sync to Agiloft button, you may need to edit a rule called "Edit: Create new revision document (web, API)."
- Navigate to the Setup gear icon > Rules.
- Edit the "Edit: Create new revision document (web, API)" rule.
- Navigate to the Conditions tab, and de-select the API checkbox under the Apply Rule section.
- Click Finish.
- If the Print Template Clauses in your contract document are not appearing correctly in the Word ACA, replace any instance of the Print Template Clause ID variable in a Print Template with the Clause ID variable instead. Similarly, variables referring to Print Template Clauses should be replaced with variables referring to Clause Library records.
If you see error messages about annotations failing to sync after trying to sync to Agiloft, ensure that the user has View Own, View Others, and Create permissions for all of the tables included in the Word ACA configuration wizard.
If you receive the error message
No column with name "contract_clause_type_id.link"or similar, you may need to reestablish the link between the Contract Clause table and the Clause Type table. To do so, create a new linked field set between the Contract Clause table and the Clause Type table.
A suggestion is to copy/export and then import the linked field set between the Contract Clause table and the Clause Type table from the standard system demo or another R22 template KB. The new linked field set must contain a column with the logical name
contract_clause_type_id, which maps the Clause Type’s ID field into the Contract Clause table. The error is likely caused from older KBs that used the Contract Clause Modifications table name.
|No column with name "contract_clause_type_id.link" in table||You may need to reestablish the link between the Contract Clause table and the Clause Type table. To do so, create a new linked field set between the Contract Clause table and the Clause Type table.|
The following troubleshooting techniques are less common, but are included in this article for comprehensive purposes. This section is not visible to clients.
|An error occurred when trying to check key term extraction result: Operation failed||This error appears when you try to analyze a document that is already associated with records in a different KB. This generally only occurs to internal Agiloft employees who use multiple KBs. To fix this issue, either ensure you are working with the correct KB, or, if you have accidentally associated a document with the wrong KB, simply delete the document's Contract and Attachment records in the incorrect KB.|