Веб-расширения

Раздел для разработчиков.

Веб-расширения — это сторонние программы (веб-модули) внутри приложения КОСКО BPM. Расширение состоит из JS-файла, CSS-файла и других ресурсов (например, шаблонов или изображений).

Типы расширений

• Модальные — открываются в отдельном слое поверх открытого раздела (например, каталога с записями). Могут занимать часть экрана или всю рабочую область приложения. При этом основной экран приложения остается в DOM-дереве. Пример — панель телефонии.

• Экранные — занимают всю рабочую область приложения, замещая в DOM-дереве открытый раздел приложения. Этот тип расширений поддерживается пока не полностью.

• Фоновые — работают в фоне и управляют DOM-деревом (встраивают элементы) в нужный момент.

Создание расширений

1. Выберите уникальное название

Каждое расширение имеет уникальный код-идентификатор. Код может состоять из латинских букв, цифр и знака дефис.

2. Напишите расширение

Исходный код минимального расширения приведен в нашем публичном репозитарии:\

https://bitbucket.org/snippets/isup/d4bMe/blank-modal-extension

3. Регистрация расширения

КОСКО BPM защищает расширения от тиражирования между системами в разных компаниях. Все расширения проходят через систему лицензирования. Подключение расширения к системе возможно только при наличии лицензии на это расширение в лицензии компании.

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

Подключение расширений

Подключать сторонние и собственные расширения можно только в серверной версии.

Файлы расширения необходимо разместить на внешнем веб-сервере или положить в рабочую папку на сервере КОСКО BPM (если у вас несколько серверов, то на каждый сервер): bpium_path/www/modules/my-extension/

Список подключенных расширений хранится в каталоге «Расширения» в отделе «Система». Для подключения расширения создайте новую запись в этом каталоге:

• Название — название расширения в главном меню приложения

• Код — уникальный код расширения (должен совпадать с зарегистрированным в лицензии)

• Иконка — класс иконки для отображения в меню

• JS URL — URL или путь к JavaScript файлу расширения (можно указать несколько, каждый с новой строки)

• CSS URL — URL или путь к CSS файлу расширения (можно указать несколько, каждый с новой строки)

Проверка подключения

После создания записи расширения и обновления страницы в браузере проверьте подключение:

1. Откройте консоль браузера (F12).

2. Перейдите на вкладку Network (Сеть).

3. Обновите страницу (F5).

4. Проверьте запросы к файлам расширения:

   • Должны быть видны запросы к JavaScript файлам (указанным в поле JS URL).

   • Должны быть видны запросы к CSS файлам (указанным в поле CSS URL).

   • Статус запросов должен быть 200 OK (успешная загрузка).

5. Проверьте ответ сервера на запрос /auth/company:

   • В ответе должно быть поле extensions с массивом расширений.

   • Ваше расширение должно присутствовать в массиве (если оно разрешено лицензией).

Если запросы к файлам отсутствуют или возвращают ошибки (404, 403 и т.д.), проверьте:

• Правильность путей в полях JS URL и CSS URL.

• Доступность файлов по указанным адресам.

• Права доступа к файлам на сервере.

• Наличие лицензии на расширение для компании.

Как обновить расширение?

Для обновления существующего расширения:

1. Откройте запись расширения в каталоге «Расширения».

2. Измените необходимые поля (название, иконка, URL файлов).

3. Сохраните изменения.

Примечание:

• Изменение кода расширения может повлиять на доступность расширения для компаний, так как проверка лицензии выполняется по коду.

• Изменение URL файлов применяется для всех компаний, имеющих доступ к расширению.

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

Как удалить расширение?

Удаление расширения — операция, которая влияет на функциональность компаний, использующих это расширение.

Внимание: Перед удалением расширения убедитесь, что:

• Расширение не используется критически важными компаниями.

• Удаление не нарушит работу системы.

Как удалить расширение:

1. Откройте запись расширения в каталоге «Расширения».

2. Нажмите кнопку удаления записи.

3. Подтвердите удаление.

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

Технические детали

Структура данных расширения

Расширение в системе представлено следующими данными:

• code — уникальный код расширения (используется для идентификации и проверки лицензии).

• title — название расширения (отображается в интерфейсе).

• icon — класс иконки для отображения в меню.

• js — массив URL JavaScript файлов (может быть многострочным текстом).

• css — массив URL CSS файлов (может быть многострочным текстом).

API для работы с расширениями

Система предоставляет API для получения расширений компании:

• Endpoint: /auth/company (при авторизации пользователя)

• Метод: GET

• Ответ: объект с полем extensions, содержащим массив доступных расширений:

Расширения автоматически фильтруются по лицензии компании перед отправкой в веб-клиент. Сервер не вернет расширения, на которые не получена лицензия для компании.

Порядок загрузки расширений

Расширения загружаются в следующем порядке:

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

2. Веб-клиент инициализирует загрузку расширений через метод loadExtensions()

3. Для каждого расширения загружаются CSS файлы (если указаны)

4. Затем загружаются JavaScript файлы (если указаны)

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

Почему расширение не загружается в веб-клиенте?

Если расширение не загружается в веб-клиенте, проверьте:

1. Регистрация расширения: убедитесь, что расширение зарегистрировано в системе лицензирования (см. раздел "Регистрация расширения")

2. Код расширения в лицензии: убедитесь, что код расширения добавлен в лицензию компании через сервер лицензирования разработчиков

3. Доступность файлов: проверьте, что файлы расширений доступны по указанным в полях JS URL и CSS URL адресам

4. Права доступа: убедитесь, что файлы расширений доступны для чтения веб-сервером

5. Кэш браузера: попробуйте очистить кэш браузера или выполнить жесткую перезагрузку страницы (Ctrl+Shift+R)

6. Консоль браузера: проверьте консоль браузера (F12) на наличие ошибок загрузки файлов

7. Сетевые запросы: проверьте вкладку Network в консоли браузера — должны быть запросы к файлам расширений со статусом 200 OK

Можно ли использовать внешние URL для расширений?

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

• Пример: https://cdn.example.com/extensions/my-extension.js

• Преимущества: не требуется хранить файлы на сервере КОСКО BPM.

• Ограничения: внешние ресурсы должны быть доступны по HTTPS и иметь правильные CORS заголовки.

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

Можно ли изменить код расширения после создания?

Технически можно изменить код расширения, однако это повлияет на доступность расширения:

• Проблема: если код расширения изменен, лицензии компаний, которые ссылаются на старый код, перестанут работать.

• Решение: перед изменением кода необходимо обновить все лицензии компаний, использующих это расширение, указав новый код.

• Рекомендация: лучше создать новое расширение с новым кодом, чем изменять существующее.

Как проверить, какие расширения доступны для компании?

Чтобы проверить доступные расширения для компании:

1. Войдите в систему от имени пользователя этой компании.

2. Откройте консоль браузера (F12).

3. Перейдите на вкладку Network (Сеть).

4. Обновите страницу (F5).

5. Найдите запрос к /auth/company и откройте его.

6. В ответе сервера проверьте поле extensions — там будет список доступных расширений для этой компании.

7. Также проверьте сетевые запросы — должны быть запросы к файлам расширений (JS и CSS файлы).

Примечание: В ответе /auth/company будут только расширения, разрешенные лицензией компании. Расширения без лицензии не будут отображаться в списке.

Можно ли временно отключить расширение для компании?

Да, можно временно отключить расширение для компании:

• Через каталог: удалите запись расширения из каталога «Расширения» (это отключит расширение для всех компаний).

• Через лицензию: обратитесь к технической поддержке КОСКО BPM для удаления кода расширения из лицензии компании (это отключит расширение только для конкретной компании).

Примечание: Удаление записи из каталога отключит расширение для всех компаний. Для отключения расширения только для одной компании необходимо обратиться к технической поддержке КОСКО BPM, так как изменения в лицензиях выполняются только через сервер лицензирования разработчиков.

Как обновить файлы расширения?

Для обновления файлов расширения:

1. Замените файлы расширения на сервере (если используются относительные пути).

2. Или обновите URL в поле JS URL или CSS URL (если используются внешние URL).

3. Сохраните изменения в записи расширения.

4. Пользователям может потребоваться очистить кэш браузера или выполнить жесткую перезагрузку страницы.

Совет: Используйте версионирование в URL файлов (например, /extensions/my-extension/v1.0.0/script.js) для контроля версий и обновлений расширений.

Как добавить расширение в лицензию компании?

ВАЖНО: Подключать сторонние и собственные расширения можно только в серверной версии КОСКО BPM.

Сервер лицензирования находится у разработчиков КОСКО BPM. Все проверки доступности расширений и добавление их в лицензии выполняются через сервер лицензирования платформы.

Для серверной версии процесс добавления расширения в лицензию компании:

1. Зарегистрируйте расширение в системе лицензирования (см. раздел "Регистрация расширения"):

• Напишите письмо на support@bpium.ru

• Укажите выбранный уникальный код расширения

• Укажите ваш регистрационный номер лицензии

1. Создайте расширение в каталоге (см. раздел "Как создать расширение?")

2. Разместите файлы расширения на сервере (см. раздел "Размещение файлов расширений")

3. Дождитесь подтверждения регистрации от технической поддержки Бипиум:

• Разработчики Бипиум добавят код расширения в лицензию компании через сервер лицензирования;

• Лицензия будет обновлена с правильной цифровой подписью на сервере лицензирования;

• Ваша система автоматически загрузит обновленную лицензию при следующем обращении к серверу лицензирования разработчиков.

Связи с другими каталогами

Каталог Расширения связан с другими системными каталогами:

• Компании — доступность расширений для компаний определяется через лицензию компании. Подробнее см. в документации по каталогу Компании

Поддержка

Версию Бипиум

Лицензию (серийный номер)

Описание проблемы или вопроса

Код расширения

Скриншоты