.. _client-manifest:

================
Add-in manifest
================

``site/manifest.xml`` is the file that Outlook reads to learn where the
task pane is hosted, what icons to show, and which permissions the
add-in requires. Everything else in the bundle (JS, HTML, icons) is
static content that is simply served over HTTPS - only the manifest
needs per-customer editing.

The host placeholder
====================

The released manifest ships with a sentinel hostname
``https://TOA_HOST_PLACEHOLDER/`` in every absolute URL it declares.
That single string is rewritten to the customer's real HTTPS origin by
the ``apply-host`` helper included in the bundle:

.. code-block:: console

   # POSIX
   $ chmod +x apply-host.sh
   $ ./apply-host.sh https://addin.customer.cz/

   # Windows
   PS> .\apply-host.ps1 -HostUrl https://addin.customer.cz/

The script is idempotent-hostile on purpose: if the placeholder is no
longer present, it exits non-zero. This prevents accidentally running
it twice and leaving a half-substituted manifest. Re-extract the
original ZIP when you need to re-run.

The chosen hostname **must**:

* be reachable over HTTPS with a publicly trusted certificate - Outlook
  refuses self-signed certs outside the ``localhost`` dev flow;
* serve the ``site/`` contents at its root (``/taskpane.html``,
  ``/assets/...``);
* reverse-proxy ``/api/*`` to the TOA server (see
  :ref:`client-hosting`).

Values that change per release
==============================

These fields are updated automatically by the release build and should
**not** be hand-edited by operators:

``<Version>``
    Incremented on each release. Outlook uses this to detect new
    manifests and re-download the bundle.

``<bt:Image ...>``, ``<bt:Url id="Taskpane.Url">``
    Default values point at the host placeholder; the
    ``apply-host`` script rewrites them.

Values that are stable across releases
======================================

``<Id>``
    The manifest GUID. It is deliberately kept stable between releases:
    rotating it would force every user to re-install the add-in.
    Rotate only when the requested ``<Permissions>`` level changes, so
    that Outlook's TitleId-backed sideload cache registers the new
    capabilities.

``<Requirements><Set Name="Mailbox" MinVersion="1.15"/></Requirements>``
    Mailbox 1.15 is required so the add-in can read the full
    RFC 822 MIME of the current message via
    ``MessageRead.getAsFileAsync``. Hosts that do not meet this version
    refuse to install the add-in (clean failure instead of a
    silently-missing method).

``<Permissions>ReadWriteItem</Permissions>``
    The minimum needed for the current feature set. The add-in only
    reads the active message and writes roaming settings - it does not
    need ``ReadWriteMailbox``. Raising the permission level in the
    future requires also rotating ``<Id>``.