Установка на 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» должна быть видна.

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


Настройка файла манифеста

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

Манифест содержит метаданные надстройки, URL-адреса ресурсов, интерфейса. Excel использует этот файл для:

  • регистрации надстройки в системе;
  • загрузки интерфейса и ресурсов;
  • отображения элементов управления в ленте Excel.

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


Основные параметры для настройки

1. Идентификатор надстройки (Id)

Уникальный идентификатор надстройки в формате GUID. Этот идентификатор используется Excel для идентификации надстройки.

Расположение: Строка 6 . 
Текущее значение: 11111111-2222-3333-4444-777777777777.

Рекомендации:

  • Использовать уникальный GUID для каждой установки.
  • Генерировать новый GUID при создании новой версии надстройки.
  • Сохранять один и тот же GUID для обновлений существующей надстройки.

Как сгенерировать GUID

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

powershell -Command "[guid]::NewGuid()"

Для macOS/Linux использовать следующую команду:

uuidgen //встроенная утилита

или

python3 -c "import uuid; print(uuid.uuid4())"

Также можно сгенерировать GUID олайн: https://www.guidgenerator.com/.

2. Версия надстройки (Version)

Версия надстройки в формате Major.Minor.Build.Revision. При обновлении надстройки необходимо актуализировать номер версии.

Расположение: Строка 7. 
Текущее значение: 1.0.0.0.

Рекомендации:

  • Увеличивать номер версии при каждом обновлении.
  • Использовать семантическое версионирование (Major.Minor.Patch).

3. Имя поставщика (ProviderName)

Название компании или организации, предоставляющей надстройку. Отображается в информации о надстройке.

Расположение: Строка 8.
Текущее значение: Polymatica.

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

4. Отображаемое имя (DisplayName)

Название надстройки, которое отображается в Excel — в списке надстроек, на ленте и т. д.

Расположение: Строка 10.
Текущее значение: POLYMATICA.

Рекомендации:

  • Использовать короткое, понятное название. Максимальная длина — 32 символа.
  • Избегать специальных символов.

5. Описание (Description)

Краткое описание функциональности надстройки. Отображается в диалоговых окнах Excel при работе с надстройками.

Расположение: Строка 11.
Текущее значение: Подключение к Polymatica Analytics и загрузка данных в Excel.

Рекомендации:

  • Описать основное назначение надстройки.
  • Использовать понятный язык для конечных пользователей.
  • Соблюдать ограничение длины — 200 символов.

6. URL иконок (IconUrl, HighResolutionIconUrl)

URL-адреса иконок надстройки разных размеров. Используются для отображения в интерфейсе Excel.

Расположение: Строки 12-13.  
Текущие значения:

Требования:

  • Иконки должны быть доступны по HTTPS.
  • Рекомендуемые размеры:
    • Стандартная иконка — 80x80 пикселей.
    • Высокое разрешение — 128x128 пикселей.
  • Формат — PNG с прозрачностью.

Настройка:

  1. Заменить домен exceladdin.analytics.polymatica.ru на ваш домен.
  2. Убедиться, что файлы иконок доступны по указанным URL, проверив доступность URL из браузера.


7. URL поддержки (SupportUrl)

URL страницы поддержки или документации. Открывается при запросе помощи пользователем.

Расположение: Строка 14.
Текущее значение: https://wiki.polymatica.ru/display/PAServicesForDev59/PolyAPI.

Рекомендации:

  • Указать актуальную страницу документации или поддержки.
  • Убедиться, что страница доступна для всех пользователей.
  • Использовать HTTPS.

8. Домены приложения (AppDomains)

Список доменов, с которых надстройка может загружать ресурсы и выполнять запросы. Это критически важный параметр безопасности.

Расположение: Строки 18-20.  
Текущее значение: https://exceladdin.analytics.polymatica.ru.

Требования безопасности:

  • Указывать только доверенные домены.
  • Использовать HTTPS для всех доменов.
  • Не добавлять домены без необходимости.
  • Каждый домен должен быть указан в отдельном теге <AppDomain>.

Настройка:

  • Заменить exceladdin.analytics.polymatica.ru на ваш домен.
  • Если надстройка обращается к нескольким доменам (например, API и фронтенд), добавить все необходимые домены, как показано в примере:
     <AppDomains>
    <AppDomain>https://exceladdin.analytics.polymatica.ru</AppDomain>
    <AppDomain>https://api.analytics.polymatica.ru</AppDomain>
  </AppDomains>

Excel блокирует запросы к доменам, не указанным в этом списке.

9. Основной URL надстройки (SourceLocation)

URL главной страницы надстройки, которая загружается в панель задач Excel.

Расположение: Строка 22.
Текущее значение: https://exceladdin.analytics.polymatica.ru/index.html.

Требования:

  • Домен должен быть указан в AppDomains.
  • Необходимо использовать HTTPS.
  • Файл должен быть доступен и корректно отображаться в браузере.

Настройка:

  • Заменить домен exceladdin.analytics.polymatica.ru на ваш домен.
  • Убедиться, что файл index.html существует и доступен.
  • Проверить, что страница загружается без ошибок.

10. URL ресурсов (иконки в Resources)

URL-адреса всех графических ресурсов, используемых в интерфейсе надстройки (кнопки, меню, иконки).

Расположение: Строки 113-124.
Текущие значения:

Требования:

  • Все файлы должны быть доступны по HTTPS.
  • Рекомендуемые размеры: 16x16, 32x32, 80x80 пикселей.
  • Формат — PNG с прозрачностью.

Настройка:

  • Заменить все вхождения exceladdin.analytics.polymatica.ru на ваш домен.
  • Убедиться, что все файлы иконок существуют и доступны.
  • Проверить доступность каждого URL.

Список необходимых файлов:

  • poly_icon_16.png, poly_icon_32.png, poly_icon_80.png.
  • settings_icon_16.png, settings_icon_32.png, settings_icon_80.png.
  • log-out_icon_16.png, log-out_icon_32.png, log-out_icon_80.png.
  • brush-cleaning_icon_16.png, brush-cleaning_icon_32.png, brush-cleaning_icon_80.png.

11. URL страниц действий (Taskpane URLs)

URL-адреса страниц, которые открываются при выполнении различных действий (открытие надстройки, очистка кэша, выход).

Расположение: Строки 127-129.
Текущие значения:

Настройка:

  • Заменить домен exceladdin.analytics.polymatica.ru на ваш.
  • Убедиться, что приложение корректно обрабатывает параметры action=clearCache и action=logout.

Чек-лист настройки для администратора

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

Подготовка инфраструктуры

Необходимо выполнить следующее:

  • Определить домен для размещения надстройки (например, exceladdin.yourcompany.com).
  • Настроить HTTPS с валидным SSL-сертификатом.
  • Развернуть веб-приложение надстройки на указанном домене.
  • Убедиться, что все статические ресурсы (иконки) доступны по HTTPS.

Настройка файла PA.xml

Необходимо выполнить следующее:

  • Сгенерировать уникальный GUID для параметра Id.
  • Установить корректную версию в параметре Version.
  • Обновить имя поставщика в ProviderName (если необходимо).
  • Настроить отображаемое имя в DisplayName.
  • Обновить описание в Description (если необходимо).
  • Обновить все URL иконок (IconUrl, HighResolutionIconUrl).
  • Указать корректный URL поддержки в SupportUrl.
  • Добавить все необходимые домены в AppDomains.
  • Обновить основной URL в SourceLocation.
  • Обновить все URL ресурсов в секции <bt:Images>.
  • Обновить все URL страниц в секции <bt:Urls>.

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

Необходимо убедиться, что:

  • Основная страница (index.html) доступна и загружается без ошибок.
  • Все файлы иконок доступны по указанным URL.
  • Страницы с параметрами (?action=clearCache, ?action=logout) работают корректно.
  • Все домены в AppDomains доступны и используют HTTPS.

Проверка безопасности

Необходимо убедиться, что:

  • Все URL используют HTTPS (не HTTP).
  • SSL-сертификаты валидны и не истекли.
  • В AppDomains указаны только необходимые домены.
  • Домены в AppDomains соответствуют доменам, используемым в URL.

Тестирование

Необходимо проверить следующее:

  • Файл PA.xml валиден (проверка XML-синтаксиса).
  • Надстройка устанавливается в тестовой среде.
  • Надстройка отображается в ленте Excel.
  • Все функции надстройки работают корректно.
  • Иконки отображаются правильно.
  • Нет ошибок безопасности в консоли браузера.

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

При развертывании надстройки на новом домене exceladdin.example.com необходимо заменить следующие значения:

<!-- Строка 12-13: Иконки -->
<IconUrl DefaultValue="https://exceladdin.example.com/assets/poly_icon_80.png"/>
<HighResolutionIconUrl DefaultValue="https://exceladdin.example.com/assets/poly_icon_128.png"/>

<!-- Строка 19: Домен приложения -->
<AppDomain>https://exceladdin.example.com</AppDomain>

<!-- Строка 22: Основной URL -->
<SourceLocation DefaultValue="https://exceladdin.example.com/index.html" />

<!-- Строки 113-124: Все URL ресурсов -->
<bt:Image id="Icon.16x16" DefaultValue="https://exceladdin.example.com/assets/poly_icon_16.png"/>
<!-- ... и так далее для всех иконок ... -->

<!-- Строки 127-129: URL страниц -->
<bt:Url id="Taskpane.Url" DefaultValue="https://exceladdin.example.com/index.html"/>
<bt:Url id="Taskpane.ClearCacheUrl" DefaultValue="https://exceladdin.example.com/index.html?action=clearCache"/>
<bt:Url id="Taskpane.LogoutUrl" DefaultValue="https://exceladdin.example.com/index.html?action=logout"/>


Дополнительные параметры

Обычно изменение дополнительных параметров не требуется.

Разрешения (Permissions)

Уровень разрешений надстройки. Значение "ReadWriteDocument" позволяет читать и записывать данные в документ Excel.

Расположение: Строка 24.
Текущее значение: ReadWriteDocument.

Обычно параметр не требует изменения, если надстройка должна записывать данные в Excel.

Требования (Requirements)

Минимальные требования к версии API Office. Определяет минимальную версию Excel, необходимую для работы надстройки.

Расположение: Строки 25-29, 145-149.
Текущее значение: "RibbonApi" версии "1.1".

Обычно параметр не требует изменения, если не используются новые функции Office API.

Локаль по умолчанию (DefaultLocale)

Локаль по умолчанию для надстройки.

Расположение: Строка 9.
Текущее значение: en-US.

Можно изменить на "ru-RU" для русскоязычной локализации, но это потребует дополнительных настроек локализации строк.


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

Для 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, указанных в манифесте:

Для 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, указанных в манифесте:


Требования

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

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