Файл манифеста

Файл PA.xml является манифестом надстройки Polymatica Analytics для Microsoft Excel. Этот файл содержит метаданные надстройки, URL-адреса ресурсов, интерфейса и определяет конфигурацию надстройки Polymatica Analytics.

Перед установкой надстройки нужно скачать файл PA.xml по адресу <адрес сервера, на котором развернута надстройка>/api/addin/manifest.

Настраивать файл манифеста вручную не требуется. 

URL-адрес фронтенда и версия манифеста подставляются в PA.xml автоматически при формировании файла на сервере. За это отвечают следующие настройки backend:

  • PUBLIC_FRONTEND_URL — публичный URL фронтенда надстройки, который попадает в элементы <SourceLocation>, <AppDomain> и ссылки на иконки в манифесте;
  • versions.json — версия манифеста (manifest_version) и минимально допустимая версия (min_supported_manifest_version).

Перед установкой убедитесь, что PUBLIC_FRONTEND_URL указывает на адрес фронтенда, доступный пользователям из их сети. Неверное значение приведет к тому, что надстройка установится, но не сможет загрузиться в Excel.

Подробнее о настройке переменных окружения backend см. в разделе «Конфигурация надстройки Excel».

В дальнейшем при обновлении версии надстройки файл манифеста на сервере будет обновляться автоматически. При этом пользователю может потребоваться обновление файла манифеста на ПК (см. раздел «Обновление» ниже).

Если вы разворачиваете несколько экземпляров надстройки на нескольких серверах, то для каждого сервера файл манифеста должен иметь уникальное поле <Id>.


Установка на Windows (через доверенные каталоги надстроек)

Создание сетевой папки (локально на Windows)

Если у вас нет централизованного файлового сервера, можно создать сетевую папку локально. Для этого нужно выполнить следующее:

1. Создать папку для надстроек, например «ExcelPA».

Для создания папки нужно перейти в директорию, в которой требуется создать папку, и нажать правой кнопкой мыши на пустой области в окне, а замем выбрать «Создать»  → «Папку».

Также папку можно создать через командную строку Windows, указав путь до создаваемой папки и ее название следующим образом:

cmd
mkdir C:\ExcelPA

2. Открыть общий доступ к созданной папке. Для этого:

  • Нажать правой кнопкой мыши на созданной папке «ExcelPA».
  • Выбрать «Свойства» → «Доступ» → «Расширенная настройка».


Расширенная настройка доступа к папке


  • Установить отметку на чекбоксе «Открыть общий доступ к этой папке».
  • Указать имя общего ресурса (например, «ExcelPA») в соответствующем поле.
  • Нажать на кнопку «Разрешения» и настроить права доступа, установив в столбце «Разрешить» отметки на чекбоксах:
    • для чтения нужно выбрать «Чтение»;
    • для администраторов нужно выбрать «Полный доступ».
  • Нажать «ОК» в окне «Разрешения для группы "ExcelPA"», а затем в окне «Расширенная настройка общего доступа».


Настройка разрешений

3. Получить сетевой путь к папке:

  • Открыть «Проводник».
  • Перейти в «Сеть» → [Имя компьютера].
  • Найти папку «ExcelPA».
  • Скопировать путь (например, \\COMPUTER-NAME\ExcelPA).

Альтернативные способы получения сетевого пути:

  • Узнать имя компьютера, нажав на Win+Pause или открыв «Свойства системы», и скопировать его в строку \\COMPUTER-NAME\ExcelPA вместо <COMPUTER-NAME>.
  • Узнать IP-адрес компьютера с помощью команды ipconfig и скопировать его в строку \\192.168.x.x\ExcelPA вместо <192.168.x.x>.

4. Поместить в папку файл манифеста:

  • Скопировать файл PA.xml в папку «ExcelPA».
  • Убедиться, что файл доступен для чтения всем пользователям.

5. Добавить полученный сетевой путь в Excel:

  • Использовать путь с именем компьютера \\COMPUTER-NAME\ExcelPA или с IP-адресом \\192.168.x.x\ExcelPA.
  • Следовать инструкциям из раздела «Настройка доверенного каталога».

Настройка доверенного каталога

1. Открыть Excel.
2. Перейти в «Файл» → «Параметры» → «Центр управления безопасностью» → «Параметры центра управления безопасностью».
3. Выбрать «Доверенные каталоги надстроек».
4. В поле для ввода URL-адреса каталога указать путь к сетевой папке, полученный на шаге 3 предыдущей инструкции.
5. Нажать на кнопку «Добавить каталог».


Добавление каталога


6. Установить отметку на чекбоксе «Показывать в меню».
7. Нажать «ОК».


Добавленный каталог отображается в списке


Рекомендации по настройке SharePoint (для корпоративных сред)

Для централизованного развертывания в корпоративной среде рекомендуется использовать SharePoint:

1. Создать библиотеку документов в SharePoint (например, «ExcelPA») и настроить права доступа. Все пользователи должны иметь права на чтение.

2. Загрузить в библиотеку файл манифеста PA.xml и убедиться, что файл доступен для чтения всем пользователям.

3. Скопировать URL библиотеки в формате https://your-company.sharepoint.com/sites/SiteName/LibraryName.

4. Добавить URL библиотеки в Excel в разделе «Доверенные каталоги надстроек» (аналогично шагу 4 инструкции «Настройка доверенного каталога»). Excel автоматически обнаружит файлы «.xml» в библиотеке.

Преимущества использования SharePoint:

  • централизованное управление надстройками,
  • версионирование файлов,
  • автоматическое обновление для всех пользователей при изменении файла,
  • контроль доступа через права SharePoint,
  • аудит использования.

Использование надстройки

После настройки доверенного каталога:

1. Открыть Excel.
2. Перейти в «Главная» → «Надстройки» → «Другие надстройки».
3. Открыть вкладку «Общая папка».
4. Найти и выбрать надстройку «Polymatica Analytics».
5. Нажать «Добавить».

Надстройка из доверенного каталога будет доступна всем пользователям, у которых настроен этот каталог, и будет автоматически обновляться при изменении файла в сетевой папке или библиотеке SharePoint.

Установка на macOS

Для macOS установка надстройки выполняется простым копированием файла манифеста в системную папку Excel.

1. Создать папку для надстроек:

bash
   mkdir -p ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/

2. Скопировать файл манифеста:

bash
   cp .../PA.xml ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/PA.xml

3. Проверить, что файл скопирован:

bash
   ls -la ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/PA.xml

4. Закрыть Excel, если он открыт.

5. Перезапустить Excel.


Проверка установки

Для Windows

После установки надстройки необходимо проверить следующее:

  • Надстройка доступна в ленте Excel через «Главная» → «Надстройки» → «Другие надстройки» → вкладка «Общая папка».
  • Надстройка называется «POLYMATICA».
  • Кнопка «Открыть Polymatica Analytics» должна быть видна.

Надстройка будет автоматически обновляться при изменении файла в сетевой папке.

Для macOS

После установки надстройки необходимо проверить следующее:

  • Надстройка доступна в ленте Excel через «Главная» → «Надстройки».
  • Надстройка называется «POLYMATICA».
  • Кнопка «Открыть Polymatica Analytics» должна быть видна.

Надстройка будет автоматически обновляться при изменении файла в сетевой папке.


Устранение проблем

Для Windows

Если надстройка не появляется, нужно выполнить следующее:

1. Проверить путь к файлу PA.xml и убедиться, что файл находится в настроенной сетевой папке или библиотеке SharePoint. Если файл отсутствует, выполнить установку заново.

2. Проверить права доступа к сетевой папке.

    Для SharePoint: убедиться, что библиотека доступна и файл загружен корректно.

3. Убедиться, что путь к каталогу правильно указан в настройках Excel.

    Можно попробовать использовать IP-адрес вместо имени компьютера в сетевом пути.

4. Проверить, что у файла PA.xml правильно настроены права доступа: чтение для всех пользователей.

5. Убедиться, что сетевое обнаружение включено в Windows.

6. Очистить кэш Microsoft Office, выполнив следующее:

  • Закрыть Excel.
  • Удалить содержимое %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\.
  • Переустановить надстройку.

7. Проверить доступность URL, указанных в манифесте:

  • Убедиться, что домен сервера, где развернута надстройка, доступен.
  • Проверить доступность иконок по URL.

8. Проверить содержимое манифеста:

  • Открыть PA.xml и проверить URL в <SourceLocation> и <AppDomain> — они должны указывать на доступный адрес фронтенда.
  • Если URL в манифесте неверные, проверить настройку PUBLIC_FRONTEND_URL на backend (см. раздел «Конфигурация надстройки Excel»).

URL фронтенда и версия манифеста подставляются в PA.xml автоматически при скачивании файла с /api/addin/manifest. Если адреса в файле неверные, нужно исправить PUBLIC_FRONTEND_URL на backend, скачать манифест заново и заменить установленный PA.xml.

Для macOS

1. Проверить наличие файла в нужной директории:

bash
     ls -la ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/PA.xml

    Если файл отсутствует, выполнить установку заново.

2. Проверить права доступа к файлу:

bash
     chmod 644 ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/PA.xml

3. Убедиться, что Excel был полностью закрыт перед копированием файла.

    Попробовать перезапустить Excel несколько раз.

4. Проверить версию Excel — требуется Excel 2016 или выше.

5. Проверить доступность URL, указанных в манифесте:

  • Убедиться, что домен сервера, где развернута надстройка, доступен.
  • Проверить доступность иконок по URL.

6. Проверить содержимое манифеста:

  • Открыть PA.xml и проверить URL в <SourceLocation> и <AppDomain> — они должны указывать на доступный адрес фронтенда.
  • Если URL в манифесте неверные, проверить настройку PUBLIC_FRONTEND_URL на backend (см. раздел «Конфигурация надстройки Excel»).

URL фронтенда и версия манифеста подставляются в PA.xml автоматически при скачивании файла с /api/addin/manifest. Если адреса в файле неверные, нужно исправить PUBLIC_FRONTEND_URL на backend, скачать манифест заново и заменить установленный PA.xml.


Требования

Для установки и использования надстройки необходимо следующее:

  • Microsoft Excel 2016 или новее (только версия Desktop).
  • Доступ к серверу Polymatica Analytics.
  • Учетные данные для входа в систему Polymatica Analytics.


Обновление

При обновлении версии надстройки пользователю может потребоваться обновление файла манифеста. Это происходит, если версия текущего файла манифеста становится меньше минимально допустимой. В таком случае при открытии надстройки отображается следующее сообщение:

Сообщение с кнопкой для скачивания актуального файла манифеста

Нужно нажать на кнопку «Скачать в браузере» и заменить загруженным актуальным манифестом ранее используемый. При этом устаревший манифест нужно обязательно удалить. После этого нужно перезапустить Excel и заново открыть надстройку. 

Excel кэширует манифест надстройки. После изменения файла пользователям может потребоваться перезапуск Excel или очистка кэша надстроек.


Логирование

Система логирует основные действия пользователя в формате [YYYY-MM-DD HH:MM:SS.mmm ±TZ:00][уровень][Компонент] Сообщение.

Пример: [2026-05-27 12:00:00.123 +03:00][ info][ Auth] User login: success, user=ivan

Компоненты: Auth, Export, API, UI, System.

Запись логов осуществляется в стандартные потоки вывода и отображается в системе сбора логов, которая должна быть дополнительно настроена.

Параметры конфигурации, связанные с логированием, см. в разделе «Конфигурация надстройки Excel».


Версия надстройки

Номер версии надстройки состоит их трех чисел, разделенных точками, x.y.z:

  • x увеличивается при внесении в надстройку изменений без сохранения обратной совместимости;
  • y увеличивается при добавлении в надстройку нового функционала с сохранением обратной совместимости;
  • z увеличивается при внесении в надстройку исправлений с сохранением обратной совместимости.

Номер версии манифеста состоит из четырех чисел, разделенных точками. Последнее число версии манифеста всегда равно нулю и не несет смысловой нагрузки, оно добавлено для соответствия требованиям к формату версии манифеста надстроек Excel.

Номера версии сервера надстройки и манифеста надстройки отображаются в интерфейсе при выборе опции «О программе» в меню «Настройки» (подробнее см. в Приложении В к руководству пользователя). 

  • Нет меток