Troubleshooting the Agiloft Contract Assistant for Word
If you encounter issues installing, accessing, or using the Agiloft Contract Assistant for Word, use this page to troubleshoot.
Error messages and their solutions are included in tables specific to each section, and compiled in a table at the bottom of the page.
General Notes
Consult this section for general guidance about how to minimize issues when working with the app.
Office version compatibility
The Word app is only compatible with versions of Microsoft Word 2019 and onward. Running any versions previous to 2019 results in an error. For more information, visit the Microsoft page on Installing Office Updates.
Acceptable file types
It is strongly recommended to only use .docx
files. 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 app.
Key terms
Adding a Key Term to the Key Term table does not cause the AI model to extract that annotation from the Contract automatically. Models can only recognize additional terms after they have been trained to do so.
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.
Adding clause library global variables
Determine the date the KB was created. For any KB created prior to November 13, 2020, using the app with the Clause Library requires extra Global Variables. These enable the markup feature, and are necessary for the app to work correctly.
If your KB was created prior to November 13, 2020:
- Go to Setup > System > Manage Global Variables
- Check for the contract_table_selector_props variable.
- If it doesn't exist in your system, contact your Agiloft representative for assistance in creating and configuring the necessary Global Variables.
Installation
Consult this section for troubleshooting issues that may occur during installation.
Can't view Add-in store or app
Check to see if connected experiences are turned on if:
- You can't view the Office Add-in store
- You can't view the app in Word
To turn on connected experiences:
- Open Microsoft Word and click Options.
- Click Trust Center and then Trust Center Settings.
- On the left-hand side of the Trust Center window, click Privacy Options and then Privacy Settings.
- Make sure that connected experiences is turned on.
- Restart Word.
If installing the app with a manifest file, you may find that the Shared Folder tab doesn't appear in the shared folder in the Microsoft Word add-in manager. To fix this:
- Click Refresh. If the Shared Folder tab doesn't appear, continue to step 2.
- After clicking Refresh, you may 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.
- 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. - Right-click
C:/AgiloftWordAddIn
and 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.
- Once the new Trusted Catalog appears in the Trusted Catalog Table, make sure that the "Show in Menu checkbox" is checked for the new entry.
Error Message | Solution |
---|---|
Cannot connect to catalog | Add the shared folder's network path to the Trusted Catalogs Table in Microsoft Word's Trust Center Settings using the steps below. |
We can't load this add-in because we couldn't connect to the catalog | Verify your network settings and IT security policies surrounding connection to sources like the Microsoft store's catalog. |
Post-Installation and Usage
This section addresses issues that may occur when using the app.
Checking your Console Logs
Console logs are very useful when debugging or diagnosing errors. To get a copy of your console log:
- Open Microsoft Word.
- Log in to the Word app.
- Click the top right corner of the app to get an arrow to appear.
- Click the arrow and select Attach Debugger from the drop-down list.
- In the new window that appears, select the Console tab from right below the URL.
- To the right of the Filter box, check to make sure the levels value says All levels. If it says Default levels, simply click Default levels and select all the available options that appear in the drop-down list. It's likely you will only need to select Verbose, and then the value will automatically change to display All levels.
- Keep the window open, and navigate back to Microsoft Word.
- In the Word app, recreate the behavior that caused your issue.
- Copy every bit of text in the text window and paste it in a file, ideally a .txt file. This should be everything below the ribbon where All levels is.
- Save the document, and provide it when creating a ticket.
Add-in version
You can tell at a glance if your version of the app is outdated from the logo on the ribbon in Word.
If it shows the old logos, use the directions on Installing the Agiloft Contract Assistant for Word page to uninstall and then reinstall the app.
Old Logos |
---|
Extra or duplicate files in Attached File field
If you notice that your Attached File field contains unwanted extra or duplicate files, it's possible that the word_aca_use_referer_header
global variable doesn't contain the correct value. This global variable should be set to Yes using a Yes/No Choice field. If there are two possible options when selecting a Yes/No Choice field, choose the second instance.
Missing icon
If you don't see the an icon in your ribbon after your manifest file has been updated, try the following:
- Sign out and sign back in to O365.
- Make sure you used the correct manifest file.
- Ensure you have installed the app on the platform you intend to use it with. For example, installing the Agiloft app on the web version of Word with a manifest file doesn't mean you can launch the app from the Microsoft Word application.
Checkout to Edit causes error and loads HTML
You may experience that clicking Checkout to Edit in your KB doesn't open your document as expected. Instead, it opens a webpage showing only HTML code. Clearing cookies should fix this issue.
Problems logging in
If you are unable to log in to the app once it is configured and installed, ensure that the Group you are in has access to REST services. To check:
- Navigate to Setup > System > Manage Web Services > Groups Allowed for REST.
- Check the list to see if your Group is selected. If it is not selected, select it.
- Click Finish.
You may also receive a Network Error message when pressing any of the Login options. If so, check to make. sure the Server URL field or KB Name field on the Connect to a different KB page perfectly matches your KB Name and Server URL. Beware of additional spaces before or after your inputted text. For more information, visit Logging In of Using the Agiloft Contract Assistant for Word.
Error Message | Solution |
---|---|
Error! Unable to login to Agiloft via OAuth 2.0 Single Sign-On | If you have decided to use OAuth, and get an error message when logging in, OAuth is probably not configured yet for your system. To check this status or to get it set up, contact your Agiloft representative. |
EWWrongDataException: Session was not created | If you get this error message when logging in, check your REST group permissions with the information mentioned above. |
Network Error | Check to make sure your Server URL and KB Name field contain proper the values. Beware of hidden errors like trailing spaces, which can occur commonly during copy/paste. |
White screen when logging in
If a blank white screen pops up when you are trying to log in to the app in Word, clear your Office add-in cache.
Problems in the configuration wizard
For issues that stem from the configuration wizard, consult this section. To access the configuration wizard, go to Setup > Integrations and click Configure under Word Add-in.
Error Message | Solution |
---|---|
An error occurred when trying to retrieve the add-in configuration from Agiloft servers: Exception has occurred: null | Click the Upgrade button under Word Add-in. If the Upgrade button isn't available, simply open the add-in configuration wizard by clicking Configure and then save it. If this still doesn't solve it, go through the configuration wizard and ensure every field has a value selected (aside from the AI or Document Risk sections). |
An error occurred when trying to retrieve the add-in configuration from Agiloft servers: HTTP method POST is not supported by this URL | Install a new version of the app from the Office store. If you installed with a manifest file, your manifest file may no longer be compatible with your Agiloft release version. To solve this issue, download and install a new manifest file from the configuration wizard using the stable build with the highest number |
An error occurred during validation of the add-in configuration from Agiloft servers: no *example* table configured | If you receive this error message, you need to check the configuration wizard and select a table for the value given in the error message. This value, such as contract_type, would replace *example* in the error message example to the left. |
Accidental Attachment record generation
If multiple blank Attachment records are generated when you change the body of the contract document and then sync, you need to update the automation in your KB. Follow the steps below:
- Navigate to Setup > Rules.
- Edit the rule called "Edit: Create new revision document (web, API)."
- Navigate to the Conditions tab, and de-select the API checkbox under the Apply Rule section.
- Click Finish.
Missing Key Terms table
This error occurs when you try and log in to the app or use the app without a Key Terms table. It's likely you'll see am error message similar to the following.
Error Message | Solution |
---|---|
No metadata_type_table configured | Go to Setup > Integrations and click Upgrade under Word Add-in. If the issue persists, clear your Office add-in cache and install a new version of the app. |
You were logged out: Session expired
If you find yourself automatically logged out of the app, consider clearing your Office add-in cache. It's likely that you'll see an error message similar to the following. This may happen right when logging in to the app, or randomly during use. Either way, clearing your cache should fix the issue.
Error Message | Solution |
---|---|
|
Document Template Clauses not appearing correctly
If the Document Template Clauses in your contract document are not appearing correctly in the app, replace any instance of the Document Template Clause ID variable in a document template with the Clause ID variable instead.
Similarly, variables referring to Document Template Clauses should be replaced with variables referring to Clause Library records.
No column with name
If tags fail to sync to Agiloft, you may receive the following error message.
Error Message | Solution |
---|---|
No column with name "contract_clause_type_id.link" (or something similar) | 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. |
New Contract Clause records don't link to Contract
If you try to create a Contract Clause record with the Word app, such by inserting a new clause into the contract, you may encounter an error where the Contract Clause records do not link back to the Contract record. This is a rare occurrence, but is due to the app failing to update automatically in your system when a new version is added to the Microsoft Store.
To solve this issue, simply clear your Office add-in cache. However, if you downloaded using a manifest file initially, you will need to update the manifest file.
Library Clauses use different fonts and different formatting
If you find that your Library Clause records often use different fonts and formats, you may need to update to R25 to change the way Agiloft handles the HTML in the Clause Text field.
However, best practice is to use the same font and formatting for all your contracts, whenever possible.
Permissions
Consult this section if you suspect your issue may be tied to permissions in Agiloft, or if you're experiencing any of the behaviors listed in this section.
Annotations failing to sync
If you see error messages about annotations failing to sync after trying to sync to Agiloft, ensure that the user has the following permissions for all of the tables included in the configuration wizard:
- View Own
- View Others
- Create
Missing Clause Library features
If your Clause Library table is empty, or you don't have the Build clause library options on the main landing page or from the navigation menu, it's likely you do not have the proper permissions.
To interact with the clause library in the Word app, you require Create permissions. However, if you want users to be able to use the clause library in the Word app without granting them Create permissions, you can instead add those users to a group with Create permissions in the Clause Library table, but deny field level write/create permissions to any required fields in the Clause Library table, which out-of-the-box are the Clause Text and Clause Title fields.
Error Message Glossary
This section compiles the error message and solution tables.
Error Message | Solution |
---|---|
Cannot connect to catalog | Add the shared folder's network path to the Trusted Catalogs Table in Microsoft Word's Trust Center Settings using the steps in the Shared Folder section. |
Error! Unable to login to Agiloft via OAuth 2.0 Single Sign-On | If you get an error message when logging in with OAuth, you'll receive an error message. If this occurs, OAuth is probably not configured yet for your system. To check this status or to get it set up, contact your Agiloft representative. |
EWWrongDataException: Session was not created | If you get this error message when logging in, check your REST group permissions with the information mentioned in the Logging In section. |
An error occurred when trying to retrieve the add-in configuration from Agiloft servers: Exception has occurred: null | Go to Setup > Integrations and click the Upgrade button under Word Add-in. If the Upgrade button isn't available, simply open the add-in configuration wizard by clicking Configure and then save it. |
An error occurred when trying to retrieve the add-in configuration from Agiloft servers: HTTP method POST is not supported by this URL | If you're on an r23 server and receive this message, you may be using an r22 manifest file. To solve this issue, download and install a new manifest file in the configuration wizard using the r23-stable build. |
An error occurred during validation of the add-in configuration from Agiloft servers: no *example* table configured | If you receive this error message, you need to check the configuration wizard and select a table for the value given in the error message. This value, such as contract_type, would replace *example* in the error message example to the left. |
We can't load this add-in because we couldn't connect to the catalog | Verify your network settings and IT security policies surrounding connection to sources like the Microsoft store's catalog. |
No metadata_type_table configured | Go to Setup > Integrations and click Upgrade under Word Add-in. If the issue persists, 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 app in Microsoft Word. |
No column with name "contract_clause_type_id.link" (or something 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. |
| Clear your Office add-in cache |