> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Office Add-Ins

> Configure and centrally deploy VARIOS AI add-ins for Microsoft Word and Outlook.

Use this page to configure the VARIOS AI add-ins for Microsoft Word and Outlook. You generate the corresponding manifests and then deploy them centrally through Microsoft 365, in an on-premises environment, or manually for individual users.

<Tip>
  Open **Admin Menu** > **Settings** > **Microsoft Office Add-In**.
</Tip>

The VARIOS AI Office Add-In is an Office web add-in. Office loads its task pane from your VARIOS AI instance. You distribute only the manifest generated by VARIOS AI.

## Prerequisites

* Access to **Settings** in VARIOS AI
* For a preconfigured connection: an API key with access to the required assistants and models
* Access to your VARIOS AI instance over HTTPS from every Office client
* For centralized deployment through Microsoft 365: permission to manage integrated apps in the Microsoft 365 admin center
* For on-premises deployment of **Word**: a network share and Office on Windows
* For on-premises deployment of **Outlook**: Exchange Server on-premises and Exchange administration permissions

<Warning>
  If you select an API key, the manifest contains that key. Treat the file as confidential and distribute it only through trusted channels. Where possible, use separate API keys for each application, target group, or rollout.
</Warning>

<Warning>
  Connectors with **Human-in-the-Loop** enabled are currently not supported by the add-in. The add-in cannot display the approval prompt, so the intended manual approval does not take place there. Therefore, only make assistants available to the add-in whose connectors are configured without Human-in-the-Loop.
</Warning>

## Set the add-in icon

The icon appears on the Office ribbon and in add-in management. All Office Add-Ins use the same icon.

<Steps>
  <Step title="Upload the add-in icon">
    Drag an image file into the upload area or select **Upload**.
  </Step>

  <Step title="Review the icon preview">
    Check the preview of the automatically generated 16 × 16, 32 × 32, and 80 × 80 pixel sizes.
  </Step>

  <Step title="Redeploy the manifests">
    Regenerate all affected manifests and deploy them again.
  </Step>
</Steps>

Use a square image that remains clear at the smallest size. VARIOS AI automatically creates the required PNG files. Select **Reset to the VARIOS AI Standard logo** to restore the bundled icons.

<Warning>
  Changing the icon does not automatically update deployed add-ins. After redeployment, it can take up to 72 hours for all Office applications to display the new icon, depending on the Microsoft 365 tenant and Office cache.
</Warning>

## Generate manifests

VARIOS AI generates a separate manifest for Word and Outlook. Excel appears as **Coming soon** on the page and cannot yet be configured.

<Steps>
  <Step title="Select an API key">
    On the **Word** or **Outlook** card, select the required **API Key**. Select **Without API Key** to generate a manifest without preconfigured authentication.
  </Step>

  <Step title="Generate the manifest">
    Select **Generate manifest**. VARIOS AI downloads `ManifestWord.xml` or `ManifestOutlook.xml`, respectively.
  </Step>
</Steps>

Select **Generate all manifest files** to download the Word and Outlook manifests in sequence. Select the required API key on both cards first.

The API key selected in the manifest controls which assistants and models are available in the Add-in. If the API key enables more than one assistant or more than one model, the Add-in displays a picker so users can switch the assistant or model. If only one assistant or one model is assigned to the API key, no picker is shown and the Add-in automatically uses that single assignment.

| Status            | Meaning                                                               |
| ----------------- | --------------------------------------------------------------------- |
| **Not generated** | No manifest has been generated for this application.                  |
| **Up to date**    | The API key and icons match the last generated manifest.              |
| **Regenerate**    | The selected API key or icons have changed since the last generation. |
| **Coming soon**   | The add-in cannot yet be configured or generated.                     |

<Info>
  The add-in ID for an application remains the same when you regenerate its manifest. VARIOS AI increments the manifest version so Microsoft 365 can process the file as an update to the existing add-in.
</Info>

## Deploy add-ins

Choose the deployment method that suits your environment.

<Tabs>
  <Tab title="Microsoft 365">
    Recommended for organizations that use Microsoft 365. Repeat these steps for Word and Outlook with the corresponding manifest:

    <Warning>
      Central deployment of the **Outlook** add-in requires mailboxes in Exchange Online. It does not support mailboxes on a local Exchange Server. Use the **On-premises** method for these users. This restriction does not apply to the **Word** add-in.
    </Warning>

    <Steps>
      <Step title="Open the Microsoft 365 admin center">
        Open the [Microsoft 365 admin center](https://admin.microsoft.com).
      </Step>

      <Step title="Open Integrated apps">
        Go to **Settings** > **Integrated apps**.
      </Step>

      <Step title="Select the Office add-in">
        Select **Upload custom apps**, then select **Office Add-in**.
      </Step>

      <Step title="Upload the manifest">
        Upload the manifest generated by VARIOS AI.
      </Step>

      <Step title="Validate the manifest">
        Review and confirm the manifest validation.
      </Step>

      <Step title="Assign the add-in">
        Assign the add-in to the entire organization, specific users, or groups.
      </Step>

      <Step title="Complete the deployment">
        Complete the wizard.
      </Step>
    </Steps>

    After deployment, VARIOS AI is available from the ribbon in Word. In supported Outlook clients, the add-in is available when reading and composing messages.

    <Warning>
      Group assignments include only direct members of the selected group. Users who are members only through a **nested group** do not receive the add-in. Assign such groups separately.
    </Warning>

    It can take up to 24 hours for the add-in to appear for every user after deployment. If it is not immediately visible, restart Office and check the assignment in the admin center.
  </Tab>

  <Tab title="On-premises">
    Use this option for environments without Microsoft 365. Word and Outlook require **different** deployment methods: Word uses an add-in catalog on a network share, while Outlook uses Exchange Server on-premises.

    <Info>
      With an on-premises deployment, Office still loads the task pane from your VARIOS AI instance over HTTPS. The network share distributes only the manifest file.
    </Info>

    ### Deploy Word through a network share

    <Warning>
      An add-in catalog on a network share is supported only by Office on Windows. For Word on the web and Word for Mac, use centralized deployment through Microsoft 365 or manual installation.
    </Warning>

    <Steps>
      <Step title="Set up the network share">
        Create a folder on a file server and share it. Open the folder's **Properties**, switch to the **Sharing** tab, and grant all target users at least read permission. Note the complete UNC path, for example `\\fileserver\OfficeAddins`.
      </Step>

      <Step title="Add the manifest">
        Copy the `ManifestWord.xml` file generated by VARIOS AI to the shared folder.
      </Step>

      <Step title="Trust the catalog through Group Policy">
        Open Group Policy Management and go to **User Configuration** > **Administrative Templates** > **Microsoft Office 2016** > **Security Settings** > **Trust Center** > **Trusted Catalogs**. Enable one of the **Location of a trusted catalog** policies and enter the UNC path of the share. This user policy requires the Office Administrative Templates (ADMX) in the central store.
      </Step>

      <Step title="Insert the add-in in Word">
        After restarting Word, users select **Home** > **Add-ins**, followed by **Advanced**. In the **Office Add-ins** dialog, they open the **Shared Folder** tab and select **VARIOS AI**.
      </Step>
    </Steps>

    <Info>
      To test the catalog without Group Policy or a script, a user can add the share directly: go to **File** > **Options** > **Trust Center** > **Trust Center Settings** > **Trusted Add-in Catalogs**, enter the UNC path, select **Add catalog**, enable **Show in Menu**, and restart Word.
    </Info>

    ### Deploy Outlook through Exchange on-premises

    Exchange manages Outlook add-ins; they are not distributed through the network share. Use a remote PowerShell session to your Exchange Server.

    <Steps>
      <Step title="Install the add-in for the organization">
        Install the manifest with `New-App` as an organization add-in:

        ```powershell theme={null}
        New-App -OrganizationApp `
          -FileData ([System.IO.File]::ReadAllBytes("C:\Temp\ManifestOutlook.xml")) `
          -DefaultStateForUser Enabled
        ```
      </Step>

      <Step title="Define the target users">
        If required, restrict deployment to specific users by adding `-ProvidedTo SpecificUsers` and `-UserList`. Without these parameters, the add-in is available to all mailboxes.
      </Step>

      <Step title="Verify the installation">
        List the installed add-ins with `Get-App` and, if necessary, enable the add-in with `Set-App -Enabled $true`.
      </Step>

      <Step title="Open the add-in in Outlook">
        After restarting Outlook, **VARIOS AI** is available when reading and composing messages.
      </Step>
    </Steps>

    <Info>
      If users should be allowed to install add-ins themselves, their Exchange mailboxes require the **My Custom Apps** role. This role is not required for an administrator-only deployment.
    </Info>
  </Tab>

  <Tab title="Manual">
    Use this option for testing, pilot users, and individual workstations. Each user installs the manifest in their own account.

    <Warning>
      Install manifest files only from trusted sources. Your organization's policy may disable manual installation.
    </Warning>

    ### Install Word manually

    <Steps>
      <Step title="Open Word on the web">
        Open a document in Word on the web.
      </Step>

      <Step title="Open add-in management">
        Select **Home** > **Add-ins** > **More Add-ins**, then switch to **My Add-ins**.
      </Step>

      <Step title="Upload the manifest">
        Select **Upload My Add-in** and upload `ManifestWord.xml`.
      </Step>

      <Step title="Open the add-in">
        Open **VARIOS AI** from the ribbon.
      </Step>
    </Steps>

    <Info>
      After installation in Word on the web, the add-in also appears in supported Word desktop clients if the user is signed in with the same account.
    </Info>

    ### Install Outlook manually

    <Steps>
      <Step title="Open add-in management">
        Open Outlook on the web or new Outlook and open add-in management, for example at [https://aka.ms/olksideload](https://aka.ms/olksideload).
      </Step>

      <Step title="Add a custom add-in">
        Switch to **My Add-ins** and, under **Custom Add-ins**, select **Add from file**.
      </Step>

      <Step title="Upload the manifest">
        Upload `ManifestOutlook.xml` and confirm the notice.
      </Step>

      <Step title="Open the add-in">
        Open a message or compose a new message, then start **VARIOS AI**.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Verify the rollout

<Steps>
  <Step title="Sign in with a test account">
    Sign in to Word or Outlook with a test account to which the add-in has been deployed.
  </Step>

  <Step title="Restart the add-in">
    Restart the Office application and open the VARIOS AI add-in.
  </Step>

  <Step title="Verify the add-in functions">
    Verify that the intended assistants and models are available and that the Add-in processes a request. If the API key enables multiple assistants or models, also verify that the picker appears and the selection can be changed. With only one assignment, no picker should appear.
  </Step>
</Steps>

## Update a manifest

Update the manifest whenever you change the icon or selected API key. First generate a new manifest for the affected application in VARIOS AI, then distribute it using the same method as the original deployment.

<Tabs>
  <Tab title="Microsoft 365">
    <Steps>
      <Step title="Open the integrated app">
        Open the existing integrated app in the Microsoft 365 admin center.
      </Step>

      <Step title="Replace the manifest">
        Replace its manifest and save the change.
      </Step>

      <Step title="Test the update">
        Check the assignments and test the add-in with a test account.
      </Step>
    </Steps>

    <Warning>
      If Microsoft rejects the manifest, you may have uploaded a file that was already deployed. Regenerate the manifest in VARIOS AI to increment its version, then upload the newly generated file.
    </Warning>

    Updates do not reach clients immediately. Allow up to 24 hours, or up to 72 hours for add-in files that are already cached. If an individual client still loads the old version afterwards, [clear the Office add-in cache](#clear-the-office-add-in-cache) on that device.
  </Tab>

  <Tab title="On-premises">
    <Steps>
      <Step title="Word: Replace the manifest on the share">
        Overwrite `ManifestWord.xml` in the shared folder. Users receive the new version after they restart Word and add the add-in again from **Shared Folder**. The share and trusted catalog configuration remain unchanged.
      </Step>

      <Step title="Outlook: Reinstall the add-in">
        Remove the existing add-in, then install the new manifest:

        ```powershell theme={null}
        Remove-App -Identity <AppId> -OrganizationApp
        New-App -OrganizationApp `
          -FileData ([System.IO.File]::ReadAllBytes("C:\Temp\ManifestOutlook.xml")) `
          -DefaultStateForUser Enabled
        ```

        Use `Get-App -OrganizationApp` to find the required `AppId`.
      </Step>

      <Step title="Test the update">
        Restart Word or Outlook and test the add-in with a test account.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual">
    <Steps>
      <Step title="Remove the existing add-in">
        Remove the add-in from **My Add-ins** in add-in management.
      </Step>

      <Step title="Install the new manifest">
        Upload the newly generated manifest as you did during the initial installation.
      </Step>

      <Step title="Test the update">
        Restart the Office application and verify the add-in.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Operations and security

* Use separate API keys for each application, target group, or rollout.
* Set cost limits appropriate to the use case.
* Record which API key is used in each manifest.
* Rotate or remove API keys when a manifest is no longer required.
* Check the status on the manifest cards after changes and update affected deployments.
* For on-premises deployment, restrict write access to the network share because Office clients trust every manifest stored there.

## Troubleshooting

| Problem                                               | Possible cause                                                                                  | Solution                                                                                                                               |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| The add-in does not appear                            | The assignment is not yet active.                                                               | Restart Office, check the assignment, and allow time for distribution.                                                                 |
| The add-in opens a blank window                       | The task pane URL is unavailable or embedding is blocked.                                       | Check HTTPS access and the security headers of the VARIOS AI instance.                                                                 |
| The **Shared Folder** tab is missing in Word          | The catalog is not configured as trusted or Office has not been restarted.                      | Check the Group Policy or registry key, close all Office applications, and restart Word.                                               |
| The shared folder is unavailable on macOS or the web  | Network share add-in catalogs are supported only by Office on Windows.                          | Use centralized deployment through Microsoft 365 or manual installation.                                                               |
| The add-in is missing in Outlook after `New-App`      | The add-in is disabled or was not assigned to the correct target users.                         | Check with `Get-App -OrganizationApp` and enable it with `Set-App -Enabled $true`.                                                     |
| A request returns error 401                           | The API key is invalid or has been rotated.                                                     | Select a valid API key, then regenerate and deploy the manifest.                                                                       |
| A request returns error 403                           | The API key lacks access or a limit applies.                                                    | Check the API key configuration, license, and cost limit.                                                                              |
| A connector does not behave as expected in the add-in | **Human-in-the-Loop** is enabled for the connector. The add-in currently does not support this. | Disable **Human-in-the-Loop** for the connector, or make an assistant without such connectors available to the add-in.                 |
| The new icon does not appear                          | The manifest was not updated or Office is using a cached version.                               | Regenerate and deploy the manifest, restart Office, and allow up to 72 hours if necessary.                                             |
| An old version is loaded                              | Office is using an old manifest or cached add-in files.                                         | Restart Office, check the deployed manifest version, and [clear the Office add-in cache](#clear-the-office-add-in-cache) if necessary. |

### Clear the Office add-in cache

Office caches the manifest, icons, and add-in files locally. If a client still loads the old version after an update, clear the cache on the affected device. Perform the steps per workstation and in the user account of the affected user.

<Warning>
  Always clear the cache completely. Never delete individual manifest files from the cache — doing so prevents all Office Add-Ins from loading.
</Warning>

<Tip>
  If only the task pane files changed, reloading is often enough: select anywhere in the add-in's task pane and press **Ctrl + F5**.
</Tip>

<Tabs>
  <Tab title="Windows: Word, Excel, PowerPoint">
    <Steps>
      <Step title="Close Office completely">
        Close Word and all other Office applications. Check Task Manager for `WINWORD.EXE`, `EXCEL.EXE`, `POWERPNT.EXE`, or `OfficeClickToRun` still running.
      </Step>

      <Step title="Open the cache folder">
        Open File Explorer and paste this path into the address bar:

        ```
        %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\
        ```
      </Step>

      <Step title="Delete the contents">
        Delete the entire contents of this folder, including all subfolders. You can keep the `Wef` folder itself.
      </Step>

      <Step title="Delete the additional cache">
        If it exists, also delete the contents of this folder:

        ```
        %USERPROFILE%\AppData\Local\Packages\Microsoft.Win32WebViewHost_cw5n1h2txyewy\AC\#!123\INetCache\
        ```
      </Step>

      <Step title="Restart Office">
        Restart Word. The add-in reloads its manifest and files.
      </Step>
    </Steps>

    <Info>
      From Office 2108 onwards, Office can clear the cache itself: go to **File** > **Options** > **Trust Center** > **Trust Center Settings** > **Trusted Add-in Catalogs**, select **Next time Office starts, clear all previously-started web add-ins cache**, and restart Word. This option applies to Word, Excel, and PowerPoint only, not to Outlook.
    </Info>
  </Tab>

  <Tab title="Windows: classic Outlook">
    Classic Outlook uses the same `Wef` folder as Word.

    <Steps>
      <Step title="Remove the add-in the regular way">
        First remove the add-in through the usual route — via **My add-ins** for manual installation, or through the Microsoft 365 admin center or `Remove-App` for centralized deployment. This often makes any further step unnecessary.
      </Step>

      <Step title="Close Office completely">
        Close Outlook and all other Office applications. Check Task Manager for `OUTLOOK.EXE`, other Office processes, or `OfficeClickToRun` still running.
      </Step>

      <Step title="Clear the cache folder">
        Delete the contents of `%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\`, including all subfolders, as described for Word.
      </Step>

      <Step title="Restart Outlook">
        Restart Outlook and redeploy the add-in if necessary.
      </Step>
    </Steps>

    <Info>
      The `%USERPROFILE%\AppData\Local\Microsoft\Outlook\HubAppFileCache` folder only needs to be cleared for add-ins that use the unified manifest (JSON). VARIOS AI distributes XML manifests, so this step is not required here.
    </Info>
  </Tab>

  <Tab title="Windows: new Outlook">
    New Outlook on Windows does not use a `Wef` folder. Its cache is cleared through the developer tools of the embedded Edge component.

    <Steps>
      <Step title="Close Outlook">
        Close new Outlook.
      </Step>

      <Step title="Start Outlook with developer tools">
        From a command line, run `olk.exe --devtools`. Outlook starts together with the Microsoft Edge DevTools.
      </Step>

      <Step title="Clear the browser cache">
        In the DevTools, open the **Network** tab, right-click anywhere in the requests table, and select **Clear browser cache**.
      </Step>

      <Step title="Restart Outlook">
        Start Outlook again without any parameters.
      </Step>
    </Steps>
  </Tab>

  <Tab title="macOS">
    In Word for Mac, clear the web cache from within the add-in: open the task pane, select the menu at the top of the task pane (personality menu), and choose **Clear Web Cache**. This menu is not available in Outlook for Mac.

    If that does not help, or if the issue affects Outlook, delete the contents of these folders. Replace `{host}` with the Office application, for example `Word`. In Finder, you must show hidden files to see them.

    ```
    ~/Library/Containers/com.Microsoft.OsfWebHost/Data/
    ~/Library/Containers/com.microsoft.{host}/Data/Documents/wef
    ```

    If the `com.Microsoft.OsfWebHost` folder does not exist, delete the contents of these folders instead, where present:

    ```
    ~/Library/Containers/com.microsoft.{host}/Data/Library/Caches/
    ~/Library/Containers/com.microsoft.{host}/Data/Library/Application Support/Microsoft/Office/16.0/Wef/
    ~/Library/Containers/com.microsoft.Office365ServiceV2/Data/Caches/com.microsoft.Office365ServiceV2/
    ~/Library/Containers/com.microsoft.Office365ServiceV2/Data/Library/Caches/com.microsoft.Office365ServiceV2/
    ```

    Then restart the Office application. Deleting the `wef` folder also removes manually installed add-ins from the application.
  </Tab>

  <Tab title="Web and mobile">
    Word on the web and Outlook on the web do not use a `Wef` folder but the browser cache. Clear the browser cache and reload the page with **Ctrl + F5** or **Cmd + Shift + R**. Alternatively, test the add-in in a private window.

    <Info>
      On iOS, the web cache can only be cleared by reloading the add-in: close the document or email and open it again. If that does not help, reinstall the Office app.
    </Info>
  </Tab>
</Tabs>

<Tip>
  On Windows and macOS, you can alternatively clear the cache with the Microsoft tool `npx office-addin-cache clear`. This requires Node.js on the device.
</Tip>

## Further Microsoft documentation

* [Centrally deploy Office Add-Ins](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-deployment-of-add-ins)
* [Create an add-in catalog on a network share](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/create-a-network-shared-folder-catalog-for-task-pane-and-content-add-ins)
* [Manage trust options for Office Add-ins](https://learn.microsoft.com/en-us/office/dev/add-ins/publish/manage-trust-options)
* [`New-App` for Exchange PowerShell](https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/new-app)
* [Publish Office Add-Ins](https://learn.microsoft.com/en-us/office/dev/add-ins/publish/publish)
* [Clear the Office Add-In cache](https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache)

## Example prompts for assistants

The system prompt of the authorized assistant determines how the add-in processes selected content and formats responses for Word or Outlook. Use the following templates as a starting point and add only the sections for tools that are actually available.

<CardGroup cols={2}>
  <Card title="System prompt for Word" icon="file-word" href="/en/monthly/admin/settings/office-addins/prompt-word">
    Recommended base prompt with optional sections for the assistant in the Word Add-In.
  </Card>

  <Card title="System prompt for Outlook" icon="envelope" href="/en/monthly/admin/settings/office-addins/prompt-outlook">
    Recommended base prompt for read and compose modes in the Outlook Add-In.
  </Card>
</CardGroup>