Page tree
Skip to end of metadata
Go to start of metadata

Troubleshooting the Agiloft Contract Assistant for Word

Error messages and their solutions are included in tables specific to each section, and compiled in a table at the bottom of the page.

The Word app is only compatible with versions of Microsoft Word 2013 and onward. Running any versions previous to 2013 results in an error. For more information, visit the Microsoft page on Installing Office Updates.

Pre-Installation

Consult this section before you install the app, or if you have some problems during installation.

Pre-Installation Notes

  • 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.
  • If you intend to use the app 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.

Basic KB

This section assures that you have some basic settings set up properly in your KB, as well as to ensure that your version and structure of Agiloft is compatible with the app.

  • 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.
  • If you've made changes to clauses or key terms in the body of the contract document and then sync, multiple blank Attachment records (usually eight) may be unintentionally created instead of a single record that represents the new version of the contract document. If you observe this, follow the steps below to prevent it from happening further:

    1. Navigate to Setup > Rules.
    2. Edit the rule called "Edit: Create new revision document (web, API)."
    3. Navigate to the Conditions tab, and de-select the API checkbox under the Apply Rule section.
    4. Click Finish
  • 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 and search 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. 

  • 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 app in Microsoft Word. 
Error MessageSolution
No metadata_type_table configuredDownload 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. 

Tables

This section assures that you have the basic KB structure necessary to configure and use the app.

  • Before you can configure the app, ensure that your system contains certain tables and fields. These tables are:
    • Contracts
    • Attachments
    • Clause Library
    • Contract Clauses
    • Clause Types
    • Contract Types

If you intend to use the app 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 for Word article for in-depth information about these tables.

Installation

Consult this section for troubleshooting issues that may occur during installation.

Connected Experiences

You may need to turn on connected experiences in order to to view the AppSource store, or to view the app if it has been installed for you. To turn on connected experiences:

    1. Open Microsoft Word and click Options.
    2. Click Trust Center and then Trust Center Settings.
    3. On the left-hand side of the Trust Center window, click Privacy Options and then Privacy Settings.
    4. Make sure that connected experiences is turned on.
    5. Restart Word.
      Optional connected experiences

Shared Folder

When installing the app, you may find that the Shared Folder tab doesn't appear in the shared folder in the Microsoft Word add-in manager. There are several reasons for this:

  • When you try to click 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. To fix this issue:
    1. 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.
    2. Right-click C:/AgiloftWordAddIn and select Properties.
    3. Navigate to the Sharing tab and copy the entire string under Network Path.
    4. Open Microsoft Word.
    5. Navigate to File > Options.
    6. On the left-hand side, select Trust Center.
    7. Click the Trust Center Settings... button.
    8. On the left-hand side of the new window, select Trusted Add-in Catalogs.
    9. Paste the Network Path string from step 3 into the Catalog Url field and click Add Catalog.
    10. 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 MessageSolution
Cannot connect to catalogAdd 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.

Post-Installation

Consult this section if you find issues with the app after you've installed it.

Logging In

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 app 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.

    SSO Login URL example
  • If you get an error message when logging in with OAuth, you'll receive an error message similar to the one below. 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.
    Login with OAUTH error message
Error MessageSolution
EWWrongDataException: Session was not createdIf 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.

Missing Icon

If you don't see the an icon in your ribbon after your manifest file has been updated, there are several things that could be the problem:

  • 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 app 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.
    O365 User
  • You may be using a manifest file with outdated information.
  • You may have only downloaded the app to the web app or locally; installing the app in a web app or on your local app does not always mean that they have been installed universally.
    Web vs Local


Configuration Wizard

This section contains information about how to solve errors that generally occur because of issues with the configuration wizard. To access the configuration wizard, go to Setup > Integrations and click Configure under Word Add-in.

  • If you receive the error message "An error occurred when trying to retrieve the add-in configuration from Agiloft servers: Exception has occurred: null," check the Word app configuration wizard. Make sure that every drop-down has a value selected; none should show "Choose One." If a drop-down list doesn't include any options besides "Choose One," you may need to hit the Upgrade button under Setup > Integrations > Word Add-in. If the Upgrade button isn't available, simply open the Word add-in configuration wizard and save it. This should also solve the problem.
Error MessageSolution
An error occurred when trying to retrieve the add-in configuration from Agiloft servers: Exception has occurred: nullGo 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 URLIf 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 configuredIf 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.

Add-in Error

Error MessageSolution
We can't load this add-in because we couldn't connect to the catalogVerify your network settings and IT security policies surrounding connection to sources like the Microsoft store's catalog.


Addin Diagnostic Log Table

The Addin Diagnostic Log table is a System table that allows you to track your Word app usage in Agiloft. This table is useful because it gives you a visual track record for the behavior of the app 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 app. 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:

  1. Log in to the app.
  2. Click the menu icon on the top right-hand corner and select Settings.
    Enable Diagnostic Logging
  3. Toggle Enable Diagnostic Logging to Yes to create an Addin Diagnostics Log record. Take note of the new Addin Diagnostic Log record's ID.
  4. Repeat whatever behavior led the problem. Ideally, these steps should be written down somewhere so they can be easily shared and reproduced.
  5. After the behavior has been repeated, copy the log text from the Settings page and attach it to a Support ticket. If the app 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.
    Diagnostic Logging Enabled

Usage

This section covers some system edits you may need to make if the app is not working as intended.

  • If multiple blank Attachment records are 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 app, 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 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. 
    Missing link error message
Error MessageSolution
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. 

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.

  • 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 configuration wizard.
  • 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 denied 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 MessageSolution
No metadata_type_table configuredDownload 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. 
Cannot connect to catalogAdd 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.
EWWrongDataException: Session was not createdIf 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.
An error occurred when trying to retrieve the add-in configuration from Agiloft servers: Exception has occurred: nullGo 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 URLIf 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 configuredIf 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 catalogVerify your network settings and IT security policies surrounding connection to sources like the Microsoft store's catalog.
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.