---
title: "Troubleshooting the Outlook app"
canonical: "https://help.agiloft.com/space/HELP/43715994/Troubleshooting+the+Outlook+app"
format: markdown
---
<span style="color: #333333">If you encounter issues installing, accessing, or using the Agiloft Contract Assistant for Word, use this page to troubleshoot. </span>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 information before you install the app.

#### Hosting

You cannot use versions of the app that use Release 23 or beyond if the Outlook server is hosted on premise; the app only works if the email server is hosted on O365. If you are not hosted on O365, you can only access the Release 22 version.

The recommended server configurations is the Exchange Mail server on O365 and Agiloft on an Agiloft-maintained server.

#### Inbound Email

For the best experience with the app, you should have [inbound email](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43719542) set up for your KB.

# Installation

<span style="color: #333333">Consult this section for troubleshooting issues that may occur during installation.</span>

#### > Macro (anchor)

Can't view Add-in store or app

<span style="color: #333333">Check to see if connected experiences are turned on if:</span>

- <span style="color: #333333">You can't view the Office Add-in store</span>
- <span style="color: #333333">You can't view the app in Outlook</span>

<span style="color: #333333">To turn on connected experiences:</span>

1. Open Microsoft Outlook 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 Outlook.

#### <span style="color: #333333">Privacy service turned off</span>

<span style="color: #333333">If you receive the error message in the table below the first time you launch Word after adding the app, check to see if connected experiences are turned on. To do so, follow the steps in </span><span style="color: #333333">[Can't view Add-in store or app](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715994/Troubleshooting+the+Outlook+app#TroubleshootingtheOutlookapp-1)</span><span style="color: #333333">.</span>

| **Error Message** | **Solution** |
| --- | --- |
| `The service required to use this feature is turned off. Check your privacy settings. ` | Open Microsoft Outlook > Options > Trust Center > Trust Center Settings > Privacy Options > Privacy Settings > Turn On optional connected experiences. |

# Post-Installation

This section addresses issues that may occur when using the app after installation.

#### Not receiving email messages

If you are not receiving email messages, always make sure to check your spam folder first. You may have to reconfigure your email rules or other settings to receive these messages.

#### 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:

1. Navigate to **Setup > System > Manage Web Services > Groups Allowed for REST.**
2. Check the list to see if your Group is selected. If it is not selected, select it.
3. Click Finish.

| **Error Message** | **Solution** |
| --- | --- |
| `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. |

## Inbound Email

Check these sections for issues that revolve around inbound email. You should use a different inbound email for every KB. 

#### Disabled inbound email or emails not appearing

After setting up inbound email, make sure it is enabled. To do so:

1. Navigate to **Setup > Email and SMS**.
2. Click **Configure Inbound Email**.
3. Open the Inbound Email record, and navigate to the Account tab.
4. Under Activity, make sure that the account is not disabled.

#### CC field blank or not updated properly

If you click Add this Contract as a Recipient and the CC field is blank or is not properly updated with the correct email address, it's likely the system does not recognize the email address that was entered as the inbound email account. This is likely because the account was entered incorrectly, but also could be because the account has been deleted or configured improperly.

In this case, the system automatically assigns the inbound email account to the out-of-the-box "Anonymous" user. A blank field occurs if the Anonymous user has been deleted, or does not have the proper permissions.

To solve this issue, follow these steps:

1. Go to **Setup** **> Email and SMS.**
2. Under Inbound Email Accounts, click **Configure Inbound Email**.
3. Open the Inbound Email record, and navigate to the Access tab.
4. Under "On record update if the sender is not recognized," make sure to click the radio button next to "Update the record from this user account."
5. Make sure that there is a value in the look-up field underneath "Update the record from this user account." This value should be a user that has update permissions, such as admin; this is the same location where the anonymous user would be listed if it was not deleted.
6. Save the record.

#### Custom headers removed 

When a mailbox is created at the Exchange mail server and used as an inbound email address, custom headers about the record ID and table are added to the email when the Add this Contract as a Recipient button is pressed. This button also puts the inbound email address in the CC field. When messages sent using the Outlook app arrive in the inbound email inbox, the headers are still present. However, when Agiloft processes those emails, the server may remove the headers. 

These custom headers are:

- x-agiloft-record-id
- x-agiloft-table-id

To authorize these custom headers, you can follow either of these sets of steps. To do so, you must have access to the inbound email inbox. 

#### Option 1 (Standard)

1. Log in to the inbound email account, and open Outlook.
2. Install the Outlook app for this account.
3. Connect to your KB, using an admin-level login and password.
4. Create a new message and add a contract record as a recipient. Ensure that the inbound email address is added to the CC field.
5. Copy the email address in the CC field and add it to the To field. This email address should remain present in the CC field.
6. Enter some arbitrary text in the Subject and Body fields of the email, then click Send.

This results in the email being routed correctly to the record you selected in step 4 above, and authorizes the custom headers listed above for all users sending emails through the Outlook app for the particular organization.

#### Option 2 (EOL via EWS)

To complete these steps, you must have the role of admin.

1. Log in to the inbound email account, and open Outlook.
2. Install the Outlook app for this account.
3. Connect to your KB, using an admin-level login and password.
4. Select a table running in CC-mode and wait for it to load.
5. Navigate to the Tools tab.
6. In the Admin tools tab, press the Let's fix it button.

These steps should authorize Agiloft’s custom headers.

#### Inbound Email doesn't attach an email

If an email fails to attach while CC-ing, you may have to change a global variable in your system. To do so:

1. Go to **Setup > System > Manage Global Variables**.
2. Navigate to the Variables with Default Values tab.
3. Locate the variable with the name `process_email_when_record_locked_by_user`<span style="color: #222c31">. </span>
4. <span style="color: #222c31">Click the Edit icon.</span>
5. <span style="color: #222c31">Change the Global Variable Value to 0.</span>
6. <span style="color: #222c31">Click Finish.</span>

#### Inbound Email on EOL via IMAP

If you prefer to configure your Inbound Email in Agiloft to receive messages from Exchange Online via IMAP, then the administrator must run the following PowerShell command. This will prevent EOL from removing custom mail headers.  
 `Set-TransportConfig –HeaderPromotionModeSetting MustCreate`   
  
This command forces each new custom email header (x-agiloft-id) to be stored in Microsoft Exchange named properties. If you use a high nvolume of unique header names in your practice, this can lead to Exchange named property exhaustion.

# On-Premise Metadata Transmissions

<span style="color: #001028">Fixed an issue where environments using Office.js API 1.5 could fail to translate certain metadata to Agiloft, as the InternetHeaders feature is unavailable, which prevented metadata transmission for record linking. Users could receive the following issues as a result:</span>

- A "Download Failed" error appears in the UI after attaching a document.
- The file is saved with a generic API name like EWRetrieve instead of the original document name.
- When attempting to save the document, we get a message saying "An unexpected error has occurred. or "You don't have appropriate permission to perform this operation."
- The document link appears as a direct hotlink in the browser window while trying to open/save.
- The document appears as a linked file in Outlook, not an embedded attachment

<span style="color: #001028">As a workaround to prevent these issues, relevant metadata (such as record ID, table ID, and rule ID) is now embedded in the email body as a hidden HTML element. This ensures consistent metadata handling across both Cloud (Office.js 1.8+) and on-premise (Office.js 1.5) environments.</span>

# Error Message Glossary

<span style="color: #333333">This section compiles the error message and solution tables.</span>

| **Error Message** | **Solution** |
| --- | --- |
| `The service required to use this feature is turned off. Check your privacy settings. ` | Open Microsoft Outlook > Options > Trust Center > Trust Center Settings > Privacy Options > Privacy Settings > Turn On optional connected experiences. |
| `EWWrongDataException: Session could not be created` | <span style="color: #333333">If you get this error message when logging in, check your REST group permissions with the information mentioned in the Logging In section. </span> |
| `Download Failed` | <span style="color: #333333">If using on-premise hosting, this likely has something to do with the Office.js API. Consult with your Agiloft representative about implementing the workaround.</span> |
| `An unexpected error has occurred.` | <span style="color: #333333">If using on-premise hosting, this likely has something to do with the Office.js API. Consult with your Agiloft representative about implementing the workaround.</span> |
| `You don't have appropriate permission to perform this operation.` | <span style="color: #333333">If using on-premise hosting, this likely has something to do with the Office.js API. Consult with your Agiloft representative about implementing the workaround.</span> |

> Macro (hide-if)
> 
> #### Related articles
> 
> > Macro (contentbylabel)