Основные сведения

В разделе Настройки - Настройки почтовых шаблонов можно настроить внешний вид шаблонов писем, которые отправляются на email пользователей. Настройки получения уведомлений находятся в профиле пользователя.

В отправляемом шаблоне можно изменить не только текст. Его можно оформить средствами Jinja и HTML.

Все шаблоны разделены на 4 тематических вкладки:

• KCS, статьи и управление знаниями
• Системные уведомления
• Уведомления о заявках
• Уведомления CSAT

Полный перечень шаблонов вы найдёте в конце этой статьи.

Под названиями шаблонов указаны нюансы их применения:

Страница редактирования шаблона

Страница редактирования шаблона выглядит так:

Под заголовком находится пояснение о том, как работает шаблон.

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

Ещё ниже можно увидеть и/или изменить тему письма.

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

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

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

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

Настройки шаблонов

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

В меню можно так же применить эти настройки для всех текущих пользователей после их изменения, или же восстановить настройки к изначальным системным:

Список шаблонов

KCS, статьи и управление знаниями

• Назначена роль Проверяющего
  Письмо отправляется агентам, которым назначена роль Проверяющего.
• Роль Проверяющего снята
  Письмо отправляется агентам при снятии с них роли Проверяющего
• Статьи, ожидающие проверки
  Агентам, назначенным в качестве Опытных (contributor и publisher), регулярно отправляется электронное письмо с напоминанием о Непроверенных статьях со значительным повторным использованием (при достижении цели "Пороговое значение заявок, связанных с черновиком"), ожидающих рассмотрения и проверки.
• Статьи, ожидающие публикации
  Агентам, назначенным Редакторами, регулярно отправляется письмо с напоминанием о Проверенных статьях со значительным повторным использованием (при достижении цели "Пороговое значение заявок, связанных с черновиком"), ожидающих рассмотрения и публикации
• Получена оценка качества статьи
  Письмо отправляется всякий раз, когда вы получаете оценку качества статьи - для авторов статей, оцененных проверяющими.
• Получен комментарий проверяющего к оценке качества статьи
  Письмо отправляется каждый раз, когда проверяющий оставляет комментарий в оценке качества статьи
• Получен комментарий проверяемого к оценке качества статья
  Письмо отправляется каждый раз, когда оцениваемый оставляет комментарий и апелляцию в оценке качества статьи
• Получена оценка точности связности
  Письмо отправляется каждый раз, когда вы получаете оценку точности связности - для сотрудников, привязывавших статьи к заявкам.
• Получен комментарий проверяющего к оценке точности связанности
  Письмо отправляется каждый раз, когда проверяющий оставляет комментарий в оценке точности связности
• Новое достижение
  Письмо отправляется агентам, которые получают новое достижение KCS
• Статья отмечена на доработку
  Письмо отправляется вам всякий раз, когда статья, в которой вы указаны в качестве автора, помечается как требующая улучшения
• Статья исправлена
  Уведомление отправляется всем подписчикам на изменения статьи, когда убирается отметка о необходимости изменений
• Изменения в статье
  Письмо отправляется, когда в статье, на которую вы подписались, появляются изменения
• Мои заявки, где нет связи со статьей
  Уведомление высылается ежедневно и содержит информацию о заявках, в которых вы назначены ответственным и где отсутствуют связи со статьями KCS
• Все заявки, где требуются статьи KCS
  Уведомление планируется ежедневно для всех пользователей с ролью менеджера и содержит информацию обо всех заявках, к которым не привязаны статьи KCS
• Требуется оценка Точности Связанности
  Письмо рассылается сотрудникам с ролью Проверяющего на еженедельной основе, напоминая об оценках точности связанности, ожидающих рассмотрения
• Требуется оценка Качества Контента
  Письмо рассылается сотрудникам с ролью Проверяющего на еженедельной основе, напоминая об оценках Качества Контента, ожидающих рассмотрения
• Требуется оценка Качества Сервиса
  Письмо рассылается сотрудникам с ролью Проверяющего на еженедельной основе, напоминая об оценках Качества Сервиса, ожидающих рассмотрения
• Получена оценка качества сервиса
  Письмо отправляется каждый раз, когда вы получаете оценку качества сервиса
• Получен комментарий проверяющего к оценке качества сервиса
  Письмо отправляется каждый раз, когда проверяющий оставляет комментарий в оценке качества сервиса
• Получен комментарий проверяемого к оценке качества сервиса
  Письмо отправляется каждый раз, когда оцениваемый оставляет комментарий и апелляцию в оценке качества сервиса
• Этап внедрения KCS завершен
  Электронная почта отправляется администраторам после успешного завершения очередного этапа внедрения KCS

Системные уведомления

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

• Пользователь приглашен
  Письмо отправляется, когда пользователь получает приглашение в систему. Пользователю необходимо будет настроить свое имя и пароль, прежде чем он сможет войти в систему. Шаблон уведомления содержит инструкции по завершению настройки учетной записи пользователя.
• Учетная запись создана
  Письмо отправляется при создании учетной записи пользователя с заранее определенным паролем и именем. Шаблон уведомления содержит инструкции по входу в систему
• Запрошена регистрация
  Письмо отправляется пользователю, когда он начинает регистрацию в системе. Уведомление содержит ссылку с уникальным кодом и инструкцию по завершению регистрации.
• Запрошен сброс пароля
  Письмо отправляется пользователю, когда он запрашивает сброс пароля или пытается зарегистрироваться с адресом электронной почты, уже присутствующим в системе. В уведомлении содержится ссылка с уникальным кодом и инструкциями по сбросу пароля
• Код подтверждения доступа к почте
  Письмо отправляется пользователям, когда они добавляют или меняют адрес электронной почты, чтобы подтвердить владение этим почтовым адресом
• Заявка не создана
  Это письмо отправлено человеку, написавшему письмо в службу поддержки без какой-либо ссылки на существующую заявку, когда создание заявок по электронной почте отключено
• Запрос оценки CSAT
  Это письмо отправлено клиенту с просьбой заполнить опрос о полученных услугах
• Код подтверждения для 2FA
  Отправляется пользователю при подключении 2FA и прохождении верификации при входе
• Пересчет метрик завершен
  Отправляется администратору после завершения задачи по пересчёту данных для оптимизированных по скорости доступа метрик
• Отчет о массовом действии над статьями
  Уведомление приходит после завершения выполнения массового действия и содержит его детальные результаты
• Код подтверждения доступа к почте при регистрации через мессенджер
  Письмо отправляется пользователям, когда они указывают адрес электронной почты при регистрации через мессенджеры, чтобы подтвердить владение этим почтовым адресом
• Экспорт отчета завершен
  Отправляется пользователю, запросившему экспорт отчёта в файл
• Отчет о массовом действии над заявками
  Уведомление приходит после завершения выполнения массового действия и содержит его детальные результаты
• Отчет о массовом объединении
  Уведомление приходит после завершения выполнения массового объединения и содержит его детальные результаты
• Выгрузка заявки готова
  Уведомление содержит ссылку на скачивание готового файла выгрузки заявки
• Выгрузка фильтра готова
  Уведомление содержит ссылку на скачивание готового файла выгрузки фильтра

Уведомления о заявках

• Назначена новая заявка
  Письмо отправляется всякий раз, когда вы назначаетесь ответственным в заявке.
• Новая заявка создана и назначена мне
  Письмо отправляется сотрудникам при создании новой заявки, в которой вы назначаетесь ответственным или BCC.
• Любая новая заявка создана
  Письмо отправляется сотрудникам всякий раз, когда создается новая заявка
• Моя заявка создана
  Электронная почта отправляется вам, когда вы являетесь отправителем запроса или находитесь в CC в конкретной заявке
• Публичный ответ добавлен
  Письмо отправляется сотрудникам, назначенным ответственными или BCC, когда к заявке добавляется любой публичный ответ
• Добавлен мой публичный комментарий
  Письмо отправляется сотрудникам, назначенным ответственными или BCC, когда они добавляют публичный комментарий к заявке. В общем, отключите это уведомление, если не хотите получать уведомления о собственных комментариях.
• Добавлен внутренний комментарий
  Письмо отправляется сотрудникам, назначенным ответственными или BCC, когда к заявке добавляется какой-либо внутренний комментарий
• Добавлен мой внутренний комментарий
  Письмо отправляется сотрудникам, назначенным ответственными или BCC, когда они добавляют публичный комментарий к заявке. В общем, отключите это уведомление, если не хотите получать уведомления о собственных комментариях.
• Любой ответ добавлен в мою заявку
  Письмо отправляется всякий раз, когда кто-то отвечает на заявку, в которой вы являетесь отправителем запроса или в CC
• Мой ответ добавлен
  Письмо отправляется каждый раз, когда вы отвечаете на заявку, если вы являетесь отправителем запроса или в CC. В общем, отключите его, если не хотите получать уведомления о собственных ответах.
• Меня упомянули в заявке
  Письмо отправляется пользователю, когда другой пользователь упоминает его в комментарии к заявке
• Мою группу упомянули в заявке
  Письмо отправляется пользователю, когда другой пользователь упоминает его группу в комментарии к заявке
• Мое сообщение в чате
  Отправляется вам, когда вы добавляете сообщение в любом чате
• Сообщение от других участников чата
  Отправляется вам, когда кто-то ещё добавляет сообщение в чате, где вы участник
• Лог чата
  Вы получите всю переписку из чата, после того, как он завершится
• Заявка, назначенная на вас, решена
  Уведомление о смене статуса заявки на "Решена" для заявок, назначенных на вас. Отправляется если клиент сам сменил статус заявки.
• Заявка со статусом Ожидание переоткрылась
  Уведомление о смене статуса заявки с Ожидание на Открытая для заявок, назначенных на вас
• Связанная с заявкой задача сменила статус
  Уведомление отправляется, когда связанная с заявкой задача сменяет статус с Открыта на Закрыта

Уведомления CSAT

• Получена оценка от клиента
  Письмо отправляется, когда клиент заполняет опрос CSAT в заявке, в которой вы назначены ответственным
• Любая заявка оценена клиентом
  Электронная почта отправляется менеджерам и администраторам каждый раз, когда клиент заполняет опрос CSAT

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

Перейти в ваш профиль вы можете по нажатию на вашу аватарку в левом нижнем углу любой страницы Swarmica:

Аватар

Чтобы изменить аватар, нажмите на него. Откроется окно загрузки картинки. Вы можете также удалить существующую картинку:

Нажмите на поле выбора изображения, либо перетащите изображение из папки на ПК. Принимаются только форматы jpeg, png или gif.

Выбранную картинку можно уменьшить, а также выбрать фрагмент передвижением мыши.

После нажатия Сохранить аватарка закрепится в профиле.

Отмена отменит все изменения. Кнопка Удалить удалит существующую аватарку.

Профайл

Чтобы изменить имя, нажмите на иконку редактирования справа от него (1):

Внесите необходимые изменения и нажмите галочку для сохранения или крестик для отмены изменений.

Статус (2) - показывает является ли пользователь участником процесса автоназначения.

Выйти (3) - с её помощью можно разлогиниться из профиля.

Авторизация

В этом блоке можно включить/выключить двухфакторную аутентификацию (1) или сбросить пароль (2). Сбросить пароль отправляет на ваш email ссылку для смены пароля в Swarmica.

Способы коммуникации

В нем указаны все возможные пути связаться с пользователем. Тут могут быть указаны дополнительные email или мессенджеры.

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

1. Выбор языка интерфейса.
2. Выбор формата дат в системе.
   Абсолютный формат даты - это даты вида 20 фев. 2025, 22:11:24.
   Относительный формат - это даты вида несколько секунд назад, 2 минуты назад и т.п.
   Примеры отображения в списке заявок абсолютного формата (1) и относительного формата (2):
   
   
   
3. Настройка звука уведомлений в Колокольчике:
   - показывается вверху справа при наличии уведомлений
4. Настраивает режим редактора ответа в заявке, делая его свернутым или развернутым по умолчанию.
5. Настройка автоматического сворачивания длинных комментариев в заявке.
6. Выбор темы интерфейса. По умолчанию светлая тема выбрана.

Настройки подписи

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

Настройки email уведомлений

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

Подробнее про каждое из уведомлений.

Диагностика

Внизу страницы находятся опции для сброса настроек и для диагностирования проблем:

Очистить локальное хранилище - сбрасывает все выбранные предпочтения в настройки по умолчанию. Такие как прдпочтительный формат дат, тема, свернута или развернута статья в виджете, сколько выводить тикетов на странице и прочее.

Сбросить настройки экрана заявки - возвращает порядок блоков в заявке в изначальное состояние. Подробнее про настройку.

Возможности интеграции

К Swarmica можно подключить трекер задач для связывания задач с заявками. На данный момент доступны к подключению следующие трекеры:

• Yandex Tracker
• Jira
• Gitlab
• Youtrack

По запросу подключается:

• Kaiten

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

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

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

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

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

Когда задача будет закрыта, в заявку, связанную с этой задачей, добавится событие, а ответственному придёт уведомление на email.

Интеграция с трекерами

Для интеграции с вашим трекером перейдите в Настройки - Трекеры задач:

На открывшейся странице нажмите на название вашего трекера.

Подключение Gitlab

1. Трекер URL - адрес gitlab из адресной строки браузера.
2. Дополнительные поля - опциональные поля из трекера, которые должны содержаться в задаче для её передачи в Swarmica.
3. API Токен - создаётся в Gitlab в User Settings - Access tokens, обязательно отметить read_api!
4. Таймаут - временной промежуток в секундах, в течение которого Swarmica будет обращаться к трекеру при отсутствии моментального ответа. По умолчанию 30 секунд, менять этот параметр не рекомендуется, за исключением особых требований вашего девопса или сетевого администратора.
5. Активен - включите бегунок для активации интеграции.

Не забудьте сохранить настройки!

Блок Gitlab в заявке:

Подключение Jira

1. Тип авторизации: токен или базовый. Для базового типа требуется авторизация по имени пользователя и паролю, в отличие от авторизации по токену.
2. Пользователь - имя пользователя Jira, через которого будут осуществляться запросы. Не требуется для заполнения при типе авторизации по токену.
3. Трекер URL - адрес Jira из адресной строки браузера.
4. Дополнительные поля - опциональные поля из трекера, которые должны содержаться в задаче для её передачи в Swarmica.
5. Токен - для авторизации по токену его нужно создать в вашем аккаунте Jira в настройках безопасности. Для базового типа авторизации в это поле нужно вписать пароль пользователя, которого указали в п.2.
6. Таймаут - временной промежуток в секундах, в течение которого Swarmica будет обращаться к трекеру при отсутствии моментального ответа. По умолчанию 30 секунд, менять этот параметр не рекомендуется, за исключением особых требований вашего девопса или сетевого администратора.
7. Активен - включите бегунок для активации интеграции.

Не забудьте сохранить настройки!

Блок Jira в заявке:

Подключение Yandex Tracker

1. Сloud Organization ID - идентификатор организации, который можно найти в разделе Настройки > Организации, если используется платформа Yandex Cloud
2. Organization ID - в некоторых случаях используется вместо Сloud Organization ID, если используется платформа Яндекс 360 для бизнеса. В большинстве случаев поле остаётся пустым.
3. Трекер URL - обычно https://tracker.yandex.com
4. Дополнительные поля - опциональные поля из трекера, которые должны содержаться в задаче для её передачи в Swarmica.
5. Токен авторизации приложения. (См. инструкцию по получению токена)
6. Таймаут - временной промежуток в секундах, в течение которого Swarmica будет обращаться к трекеру при отсутствии моментального ответа. По умолчанию 30 секунд, менять этот параметр не рекомендуется, за исключением особых требований вашего девопса или сетевого администратора.
7. Активен - включите бегунок для активации интеграции.

Не забудьте сохранить настройки!

Блок Yandex в заявке:

Подключение Youtrack

1. Трекер URL - адрес Youtrack из адресной строки браузера.
2. Дополнительные поля - опциональные поля из трекера, которые должны содержаться в задаче для её передачи в Swarmica.
3. API Токен - инструкции как создать.
4. Таймаут - временной промежуток в секундах, в течение которого Swarmica будет обращаться к трекеру при отсутствии моментального ответа. По умолчанию 30 секунд, менять этот параметр не рекомендуется, за исключением особых требований вашего девопса или сетевого администратора.
5. Активен - включите бегунок для активации интеграции.

Не забудьте сохранить настройки!

Блок Youtrack в заявке:

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

• Заявки
• Чаты
• Статьи
• Пользователи
• Компании
• Лицензионные ключи
• Активы

Собственные фильтры располагаются вверху списка фильтров:

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

Кнопки и соответственно добавляют или удаляют фильтр из закладок:

Создание фильтра

Рассмотрим подробнее процесс создания фильтра. При нажатии на кнопку Создать откроется окно вида:

1. Название название фильтра, которое будет отображаться в списке.
2. Описание - краткая заметка к фильтру, чтобы его можно было отличить от остальных.
3. Выберите поля. Поля - это столбцы, которые будут видны в списке при применении вашего фильтра. Можно добавить как системные поля, так и кастомные.
4. Добавить условие - условия фильтрации, по которым будет формироваться список. Сначала выберите параметр, затем оператора, затем значение.
   Параметр - поле, которое вы будете фильтровать.
   Оператор - отношение параметра к значению (равно, не равно, больше, меньше). Оператор может иметь вид NULL - так мы указываем, что выбранное поле должно быть пустым.
   Значение - содержимое этого поля.
   
   Приведём пример. Мы хотим показать только заявк от определенного клиента. Выбираем поле Заявка от, затем оператор =, затем значение - имя пользователя (нужно будет начать вводить его имя). Вот что получается:
   
   
   После создания условия нажмите Добавить. Ошибочно созданное условие можно отменить.
   Условий может быть несколько, но для одного поля может быть только одно условие.
5. Сортировка - задайте сортировку нужных полей по умолчанию:
   
   
   Кнопка позволяет регулировать по возрастанию или убыванию сортировка, а удерживая можно менять порядок полей для сортировки, если их несколько.
6. После того, как фильтр будет настроен, нажмите в правом нижнем углу Сохранить. Для отмены создания фильтра нажмите в левом нижнем углу Отменить.

   Если кнопка Сохранить неактивна, проверьте, все ли обязательные параметры фильтра вы заполнили. Обязательные параметры: Название, Описание и Поля.

Описание полей в фильтре

В качестве колонок, в фильтре можно добавлять как системные поля, так и кастомные. Кастомные поля - те, что создаются администратором Свормики, подробнее про них в статье.

Системные же поля заложены в Свормике и не меняются. Рассмотрим их подробнее.

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

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

Так выглядит страница проверяющего точность связанности:

По нажатию на критерий открывается его описание:

Этими критериями можно управлять в разделе Настройки - Критерии точности связанности.

Для добавления нового критерия нажмите в правом верхнем углу.

Откроется окно добавления критерия:

Введите его название и описание и нажмите .

Для редактирования критерия нажмите справа от него в колонке "Редактировать".

Для удаления критерия нажмите справа от него в колонке "Удалить".

В разделе Настройки - Управление сотрудниками вы можете создать сотрудника, изменить настройки сотрудника, добавить или изменить сотруднику права, роль или навыки.

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

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

Создание сотрудника

Чтобы создать сотрудника, нажмите в правом верхнем углу раздела Настройки - Управление сотрудниками.

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

Ниже рассмотрим нюансы обоих вариантов.

Создать пользователя

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

1. Введите имя и фамилию пользователя.
2. Введите email пользователя.
3. Введите пароль. Пароль должен содержать не менее 8 символов, среди них должна быть минимум 1 прописная буква и 1 цифра.
4. Выберите роль сотрудника. Подробнее о ролях.
5. Нажмите для добавления пользователя в систему и перехода в его карточку для продолжения настроек.

Пригласить пользователя

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

С выбором этого способа создания сотрудника открывается такое окно:

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

Карточка сотрудника

В карточку сотрудника вы попадёте либо сразу после его создания, либо по нажатию на имя сотрудника в списке сотрудников в разделе Настройки - Управление сотрудниками. Карточка сотрудника выглядит так:

Карточка сотрудника состоит из нескольких блоков. Расскажем о них подробнее.

Свойства

1. Имя сотрудника.
2. Опции изменения пароля. Кнопка позволяет ввести новый пароль для сотрудника. Кнопка отправляет на email сотрудника письмо со ссылкой, по которой он сможет задать новый пароль.
3. 2FA аутентификация - показывает статус двухфакторной аутентификации, настроена ли она у сотрудника.
4. Роль сотрудника.
5. Робот - показывает, является ли пользователь ботом или другой системой.
6. Формат email - показывает какое форматирование использовать в почтовых уведомлениях для данного пользователя.
7. Статус - включение или отключение возможности автоназначения заявок на сотрудника, и настройки ограничения по количеству Новых+Открытых заявок.
8. Роль KCS влияет на возможности агентов при работе с базой знаний. Candidate / Кандидат - как правило новичок, на испытательном сроке. Может искать, создавать и связывать статьи с тикетами. Contributor / Опытный - может делать все то же, что и Кандидат, плюс проверять и исправлять статьи базы знаний. Publisher / Редактор - может публиковать и снимать с публикации статьи базы знаний.
9. Начал работать - период работы сотрудника с заявками, засчитывающийся в его статистику. Чтобы посмотреть точную дату или исправить информацию, нажмите на карандаш справа от срока работы.
   Чтобы вернуться назад, нажмите Отменить:
   
10. Вход в систему - показывает дату и время последней авторизации пользователя в Swarmica.
11. Уволить - перевести сотрудника в роль Заблокирован и проставить дату окончания работы:
    
12. Перевести сотрудника в роль Сотрудник и проставить дату окончания работы над заявками. Сотрудник сможет только читать заявки, не участвуя в них.
13. Не решает заявки - отметить пользователя, как не участвующего в процессе работы с заявками. Пользователь сможет только читать заявки, не участвуя в них, но его роль изменена не будет.
    После этого у него будет кнопка , нажав на которую можно будет активировать начало статистики работы с заявками.
14. Электронный адрес сотрудника, является его логином.

Проверяющий

Показывает, является ли пользователь проверяющим в процессе Контроля качества.

Группы

Показывает участником каких групп является пользователь. Группы используются для распределения обращений и разграничения статистики. Управлять группами можно в Настройках - Управление группами.

Навыки

В блоке Навыки сотруднику можно отметить его компетенцию в виде навыков для просмотра в карточке сотрудника или для настройки автоназначения заявок.

Сами навыки можно внести в систему в разделе Настройки - Управление навыками.

Способы коммуникации

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

Кастомные поля

В блоке Кастомные поля сотруднику можно добавить произвольную характеристику, атрибут или признак. Сами поля добавляются в разделе Настройки - Кастомные поля.

Назначенные заявки

В правой части страницы сотрудника находится список назначенных на него заявок - тех, в которых он является ответственным:

По умолчанию они отсортированы по дате обновления заявки и по статусу, начиная с Новая и Открытая, но есть сортировка по номеру заявки, по клиенту и по наличию/отсутствию удовлетворённости. Для сортировки нажмите на стрелку справа от названия интересующего столбца.

Зажмите CTRL или COMMAND, чтобы сортировать сразу по нескольким столбцам.

Статьи

На вкладке Статьи находится список статей, в которых сотрудник указан Автором:

Расшифруем некоторые колонки.

AQI (Article Quality Index) - индекс качества статьи.

FCR (First Call Resolution) - процент заявок, прикреплённых к статье и решённых в отчётном периоде одним первым ответом, без необходимости писать повторно, относительно общего количества решённых заявок.

Заявок (Месяц) - количество заявок, к которым была прикреплена статья за последний месяц до сегодняшнего дня включительно.

Заявок (Всего) - количество заявок, к которым была прикреплена статья.

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

Зажмите CTRL или COMMAND, чтобы сортировать сразу по нескольким столбцам.

AQI выборки, LAI выборки и QA выборки

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

Заявки пользователя

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

По умолчанию они отсортированы по дате обновления заявки, но есть сортировка по номеру заявки, по статусу, по приоритету и ответственному. Для сортировки нажмите на стрелку справа от названия интересующего столбца.

Зажмите CTRL или COMMAND, чтобы сортировать сразу по нескольким столбцам.

События

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

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

Фильтры сотрудников

Чтобы показать сотрудников, соответствующих определённым критериям, в разделе Настройки - Управление сотрудниками воспользуйтесь фильтрами:

1. Роль - Администратор, Агент, Менеджер, Сотрудник или Заблокирован.
2. Роль KCS - Кандидат, Опытный или Редактор.
3. Статус - включенная или отключенная возможность автоматического назначения заявок на сотрудника.
4. Качество контента - показывает сотрудников, которые являются проверяющими качества контента, или наоборот, отбрасывает их.
5. Точность связанности - показывает сотрудников, которые являются проверяющими точности связанности, или наоборот, отбрасывает их.
6. Качество сервиса - показывает сотрудников, которые являются проверяющими контроля сервиса, или наоборот, отбрасывает их.
7. Группа - показывает сотрудников выбранных групп.
8. 2FA включена - показывает сотрудников, у который включена двухфакторная аутентификация, или наоборот, отбрасывает их.

Список сотрудников

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

У каждого сотрудника в списке указано имя, email, роль, роль KCS, статус, а так же участие в проверке качества контента, точности связанности или качества сервиса:

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

, , - роли KCS.

- статус.

- сотрудник является проверяющим качество контента, точность связанности или контроля сервиса. Может присутствовать одно из трех назначений или ни одно из них.

В этой статье рассказывается о том, как автоматически распределять заявки на сотрудников и группы по заданным условиям. Эти настройки можно осуществить в разделе Настройки - Автоназначение заявок.

Здесь вы можете создать разные правила для назначения входящих заявок в разные группы. Правила создаются по принципу "Если (условие 1), то поместить в группу (группа) и назначить сотрудника, удовлетворяющего условию (условие 2). Создав несколько таких правил, можно настроить их порядок работы.

Правила в списке правил работают сверху вниз. Если первое правило не определило подходящего для новой заявки сотрудника, система применяет для заявки следующее правило, и так до тех пор, пока условие в каком-либо правиле не будет соблюдено.

При заведении заявки в системе, автоназначение срабатывает как триггер на событие создания завки.

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

Создание правила

Чтобы создать новое правило, нажмите в правом верхнем углу раздела. Откроется окно создания правила. Вот пример заполненного окна:

1. Введите Название - краткое и ёмкое название правила, отражающее суть его работы.
2. Добавьте условие выбора заявок кнопкой . Сначала выберите поле заявки, затем оператора, затем значение.
   Поле - поле на странице входящей заявки.
   Значение - содержимое этого поля.
   Оператор - отношение поля к значению (равно, не равно, больше, меньше). Оператор может иметь вид NULL - так мы указываем, что выбранное поле должно быть пустым.
   Приведём пример. Мы хотим применить правило только к заявкам с наивысшим приоритетом. Выбираем поле Приоритет, оператор =, значение Срочный. Вот что получается:
   
   Ещё пример: мы хотим создать правило назначения всех утренних заявок на группу утренней смены. Тогда условие будет выглядеть так:
   
3. Нажмите , чтобы добавить условие в правило. Для отмены некорректного условия нажмите . Для удаления ошибочно добавленного условия нажмите значок корзины справа от него.

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

4. Выберите группу, в которую нужно поместить заявку. Создать новую группу и добавить в неё сотрудников вы можете в разделе Настройки - Управление группами.

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

5. По умолчанию заявка будет назначаться на любого агента из выбранной группы, который сейчас Онлайн. Чтобы назначить заявку, в которой соблюдены указанные условия, на определённых агентов, нужно добавить условие для сотрудника. Атрибуты настраиваются в разделе Настройки - Кастомные поля.
   Нажмите в строке И назначить на пользователя, удовлетворяющего условиям .
   Поле - название дополнительного атрибута.
   Значение - значение атрибута.
   Оператор - отношение поля к значению (равно или не равно).
6. При необходимости настройте назначение по навыкам. Это дополнительная фильтрация подходящих сотрудников, навыки которых соответствуют навыкам в заявке полностью или частично. Навыки добавляются в заявку на странице заявки, а сотруднику - в его карточке.
7. Для сохранения правила нажмите в правом нижнем углу окна. Для закрытия окна добавления нового правила без сохранения нажмите .
8. Правило будет добавлено в список Доступные правила. Чтобы оно начало работать, перенесите его в список Действующие правила нажатием на + возле его названия:

Работа с действующими правилами

Когда приходит заявка, система пробует применить её к правилам поочерёдно, начиная с самого верхнего и останавливаясь на правиле, условие которого может быть соблюдено для этой заявки. Если не будет ни одного подходящего правила, заявка останется нераспределённой.

Чтобы изменить положение правила в списке, перетащите его, зацепив левой кнопкой мыши за 6 точек слева от правила:

Включение автоназначения на пользователе

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

Или администратор может выставить в Настройках - Управление сотрудниками:

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

При статусе Оффлайн заявки на агента назначаться не будут. Но могут остаться существующие нерешённые заявки.

Режим периодического перераспределения заявок балансировщиком

В нижней части страницы Автоназначение заявок доступна настройка периодического распределения заявок.

Когда опция включена, раз в заданное время система проверяет Новые и Открытые заявки, и если переназначает их по установленным правилам автоназначения, если:

1. Ответственный в заявке находится в статусе Оффлайн.
2. У заявки нет Ответственного.

Периодическое перераспределение заявок может работать в одном из двух режимов:

• По всем правилам - система перераспределяет заявки, используя все правила, даже если для этого нужно будет перенести заявку в другую группу.
• Внутри группы - система перераспределяет заявки только по правилам, подходящим для группы, в которой находится заявка.

Так же можно задать периодичность работы балансировщика в формате крон тасок. По-умолчанию, балансер работает каждые 30 минут.

Отключение автоназначения

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

Тогда все заявки, как новые, только что созданные, так и переоткрывшиеся в статусе Открытая, будут назначаться только по Индексу SLA.

Проверка качества контента является одним из этапов работы со статьями и осуществляется по определённым критериям. Изменить и добавить критерии качества контента можно в разделе Настройки - Критерии качества контента.

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

Критерии качества контента также называются критериями AQI (Article Quality Index) - индекса качества статей.

Критерии подразделяются на категории. Так выглядят критерии и категории во время оценки статьи проверяющим:

Так выглядит раздел Настройки - Критерии качества контента:

Раздел состоит из двух вкладок: Критерии AQI и Категории AQI.

Критерии AQI

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

Откроется окно добавления критерия. Вот пример заполненного окна:

Название критерия будет отображаться у проверяющего на странице проверки статьи.
Описание будет отображаться по клику на название.
Скриншот со страницы проверки статьи:

Вес - индекс значимости критерия. Из веса каждого критерия рассчитывается индекс качества контента в процентах. По умолчанию все существующие критерии имеют вес 1. Если у одного из критериев вес будет больше, его выполнение/невыполнение будет больше влиять на индекс качества, чем выполнение/невыполнение критериев, у которых вес меньше.

Категорию тоже нужно будет указать. Если в списке нет нужной вам категории, её можно будет добавить в разделе Настройки - Критерии качества контента, на вкладке Категории AQI.

Для редактирования критерия нажмите справа от него в колонке Редактировать.

Для удаления критерия нажмите справа от него в колонке Удалить.

Категории AQI

Список категорий критериев индекса качества контента располагается в разделе Настройки - Критерии качества контента, на вкладке Категории AQI.

У категории можно изменить название. После внесения изменений нажмите в конце строки. Для отмены изменений нажмите .

Для удаления категории нажмите в конце строки.

Для добавления новой категории введите её название в последней строке внизу списка и нажмите "Добавить":

В данной статье представлены рекомендации настроек установки Swarmica(~1000 пользователей всего и ~100-150 единовременно онлайн) на сервере с 16 CPU и 32Gb RAM.

Основная нагрузка в Swarmica ложится на сервисы: Postgres, Django и Celeryworker.

Postgres

Рекомендуемые настройки:

max_connections=500
shared_buffers=8GB
effective_cache_size=24GB
work_mem=16MB
maintenance_work_mem=512MB
random_page_cost=1.1
effective_io_concurrency=200
temp_buffers=32MB
track_activity_query_size=16384
wal_keep_size=512MB

Прямо влияют на производительность:

max_connections - Максимальное количество одновременных клиентских подключений к серверу.
shared_buffers - Основной буфер PostgreSQL для работы с таблицами и индексами. Рекомендуется устанавливать 20–25% от RAM сервера.
effective_cache_size - сколько суммарно кэша может быть доступно для данных — включая shared_buffers и кэш операционной системы. Рекомендуется устанавливать 70-75% от RAM сервера.
work_mem - Объём памяти для одной операции сортировки или хеш-таблицы внутри запроса.
maintenance_work_mem - Память для обслуживающих операций: VACUUM, CREATE INDEX, REINDEX, ALTER TABLE и т.п.
Большое значение ускоряет создание индексов и очистку.
random_page_cost - Оценка стоимости случайного чтения страницы относительно последовательного. Значение 1.1 обычно ставят на быстрых SSD/NVMe, чтобы планировщик не избегал index scans слишком агрессивно.

Опциональные:

effective_io_concurrency - Сколько одновременных дисковых I/O операций PostgreSQL может выполнять параллельно.
track_activity_query_size - Максимальная длина текста запроса, который сохраняется в pg_stat_activity.
temp_buffers - Локальные буферы для временных таблиц в рамках одной сессии. Память выделяется по мере необходимости, не сразу на всех.
wal_keep_size - Минимальный объём старых WAL-файлов, которые PostgreSQL будет держать в каталоге pg_wal. Полезно для репликации.

как применить

Чтобы применить данные настройки необходимо изменить команду старта сервиса postgres в docker-compose.yml файле:

...
 postgres:
    image: postgres:14.2-bullseye
    container_name: swarmica-postgres
    command: postgres -N 500 -c shared_buffers=8GB -c effective_cache_size=24GB -c work_mem=16MB -с maintenance_work_mem=512MB -с random_page_cost=1.1 -с effective_io_concurrency=200 -c temp_buffers=32MB -с track_activity_query_size=16384 -с wal_keep_size=512MB
    restart: always
...

и произвести рестарт Swarmica:

docker compose down && docker compose up -d

Django

Рекомендуемые настройки:

threads=4 
workers=16
max-requests=2000 
max-requests-jitter=100 
graceful-timeout=60

Прямо влияют на производительность:

threads - количество потоков на 1 worker'а. Рекомендуется 2-8 на 1 worker'а.
workers - количество worker'ов. Рекомендуется устанавливать 1 worker на 1 CPU unit.

Крайне не рекомендуется выставлять слишком высокие значения workers и threads, т.к. это может привести в обратному эффекту - снижению производительности.

Для эффективного использования памяти:

max-requests - максимальное кол-во запросов для одного воркера, после которых он рестартует
max-requests-jitter - погрешность для max-requests, чтобы все воркеры не рестартовали одновременно
graceful-timeout - (опционально) время, которое дается на завершение обработки запроса перед рестартом. По дефолту 30 сек

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

как применить:

Чтобы применить данные настройки необходимо изменить в файле .env строку GUNICORN_CMD_ARGS:

GUNICORN_CMD_ARGS="--threads=4 --workers=16 --max-requests=2000 --max-requests-jitter=100 --graceful-timeout=60"

и произвести рестарт Swarmica:

docker compose down && docker compose up -d

Celeryworker

Рекомендуемые настройки:

max-tasks-per-child=1000

Для эффективного использования памяти:

max-tasks-per-child - количество задач, после обработки которых процесс перезапускается. Необходимо для того, чтобы избежать утечки памяти.

как применить

Чтобы применить данные настройки необходимо изменить в файле .env строку CELERY_CMD_ARGS:

CELERY_CMD_ARGS="--max-tasks-per-child=1000"

и произвести рестарт Swarmica:

docker compose down && docker compose up -d

Симптомы

Как мне добавить проверки healthcheck и зависимости в docker-compose.yml, чтобы работоспособность контейнеров проверялась автоматически средствами Docker?

Решение

Для систем, установленных после 1 июля 2026 года эти проверки добавляются автоматически, в момент установки Swarmica.

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

1. Войдите на сервер Swarmica с правами root
2. Зайдите в папку установки Swarmica, обычно /root/swarmica/:

   cd /root/swarmica
   

3. Создайте резервную копию docker-compose.yml:

   cp docker-compose.yml{,.backup}
   

4. Отредактируйте сервис postgres, добавив healthcheck:

   healthcheck:
     test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
     interval: 10s
     timeout: 5s
     retries: 5
     start_period: 10s
   

   Таким образом, вся секция postgres будет выглядеть примерно так:

   postgres:
     image: postgres:14.2-bullseye
     restart: always
     container_name: swarmica-postgres
     shm_size: 1gb
     command: postgres -N 400 -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all -c track_activity_query_size=16384 -c wal_keep_size=512MB
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
       interval: 10s
       timeout: 5s
       retries: 5
       start_period: 10s
     volumes:
       - swarmica_postgres_data:/var/lib/postgresql/data:Z
       - swarmica_postgres_data_backups:/backups:z
       - ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf
     env_file:
       - .env
   

5. Отредактируйте сервис redis, добавив healthcheck:

   healthcheck:
     test: ["CMD", "redis-cli", "ping"]
     interval: 10s
     timeout: 5s
     retries: 5
     start_period: 5s
   

   Таким образом, вся секция должна выглядеть так:

   redis:
     image: redis:6-bullseye
     restart: always
     container_name: swarmica-redis
     command: redis-server --save 20 1 --loglevel warning --timeout 86400 --maxclients 100000
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 10s
       timeout: 5s
       retries: 5
       start_period: 5s
   

6. Отредактируйте секцию сервиса django, изменив разделы depends_on и добавив healthcheck вот так:

   django:
     ...rest of your config...
     depends_on:
       postgres:
         condition: service_healthy
       redis:
         condition: service_healthy
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; req = urllib.request.Request('http://127.0.0.1:5000/api/instance', headers={'Host': 'django'}); resp = urllib.request.urlopen(req, timeout=5); exit(0 if 200 <= resp.status < 400 else 1)"]
       interval: 15s
       timeout: 5s
       retries: 10
       start_period: 40s
     ...rest of your config...
   

7. Далее, в сервисах frontend, helpcenter, celeryworker, celerybeat, django-websocket, mcp, telegram, whatsapp_green, vk, max (в тех, которые есть у вас в docker-compose.yml - в зависимости от настроек системы, у вас могут быть не все из них) измените секцию depends_on вот так:

   depends_on:
     django:
       condition: service_healthy
   

8. Перезапустите сервисы:

   docker compose down && docker compose up -d
   

В данной статье описана поддержка управления активами CMDB через интеграцию Swarmica с Netbox. Интеграция реализована 2 скриптами:

• Скрипт, получающий объекты Netbox(Устройства, виртуальные машины и т.д.) и создающий/обновляющий активы в Swarmica. Этот скрипт запускается с заданной периодичностью.
• Скрипт, добавляющий комментарий в объект Netbox, когда соответствующий актив добавлен/удален в заявке в Swarmica.

Инструкция

1. Создайте скрипт в Swarmica - Настройки - Скрипты и загрузите в него этот скрипт

2. Создайте Событие по расписанию в Swarmica - Настройки и прикрепите к нему скрипт, созданный в п.1

3. Добавьте контекст с содержимым вида:

{
  "since": "<Дата начала>",
  "object_map": [
    {
      "fields": ["поле1", "поле2",...],
      "endpoint": "<API эндпойнт>",
      "display_name": {"en": "<Отображаемое название для en локали>", "ru": "<Отображаемое название для ru локали>"},
      "asset_type_name": "<Название>"
    },
    ...
  ],
  "netbox_host": "<NETBOX_HOST>",
  "netbox_token": "<NETBOX_TOKEN>",
  "verify_ssl": true|false
}

<Дата начала> - дата обновления объектов в Netbox. В Swarmica попадут и будут синхронизироваться только объекты, последнее обновление которых было после этой даты.
<NETBOX_HOST> - URL Netbox'а
<NETBOX_TOKEN> - API токен Netbox'а
"verify_ssl" - флаг о проверке SSL сертификата(по умолчанию true). Значение может быть true или false
"object_map" - маппинг объекта Netbox. В Swarmica попадут и будут синхронизироваться только объекты, удовлетворяющие указанному маппингу. В поле "fields" добавляются необходимые параметры, которые будут отображаться для актива в Swarmica.

Пример рабочего контекста:

{
  "since": "2020-01-01T00:00:00Z",
  "object_map": [
    {
      "fields": ["status", "primary_ip"],
      "endpoint": "dcim.devices",
      "display_name": {"en": "NetBox Device", "ru": "Устройство NetBox"},
      "asset_type_name": "Устройство"
    },
    {
      "fields": ["status", "primary_ip"],
      "endpoint": "virtualization.virtual-machines",
      "display_name": {"en": "NetBox VM", "ru": "Виртуальная машина NetBox"},
      "asset_type_name": "Виртуальная машина"
    }
  ],
  "netbox_host": "https://netbox.host.tld",
  "netbox_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "verify_ssl": true
}

в данном примере в Swarmica будут добавляться и синхронизироваться объекты полученные из эндпоинтов Netbox'а dcim.devices и virtualization.virtual-machines. Для каждого из объектов будут отображаться значения status и primary_ip.

Узнать endpoint объекта можно с помощью URL соответствующей страницы в панели Netbox. Например, необходимо добавить устройства. URL страницы https://netbox.host.tld/dcim/devices/. Тогда нужный endpoint - dcim.modules.

Для того, чтобы узнать название полей, откройте страницу любого устройства в Netbox в режиме API. Допустим если в обычном режиме страница устройства https://netbox.host.tld/dcim/devices/{device_id}, то в режиме API это будет https://netbox.host.tld/api/dcim/devices/{device_id}. На этой странице вы увидите данные об устройстве в JSON формате. И любой из параметров устройства можно использовать в маппинге полей.

Больше информации об объектах и их параметрах, получаемых с помощью API, можно найти в веб-интерфейсе вашей Netbox установки:
https://<NETBOX_HOST>/api/schema/swagger-ui/#/

4. Установите расписание. Например, 1 раз каждые 10 минут, т.е. */10 * * * * и установите статус Включен.

Выглядеть должно вот так:

5. Создайте Действие по событию в Swarmica - Настройки

6. Добавьте в него этот скрипт, установите Тип события Событие заявки и добавьте условие Тип события = Актив добавлен, Актив удалён

7. Добавьте контекст вида:

{
  "netbox_host": "<NETBOX_HOST>",
  "netbox_token": "<NETBOX_TOKEN>",
  "verify_ssl": true|false
}

и установите статус Включён

Выглядеть должно вот так:

В данной статье описана инструкция как добавить собственный CA сертификат в Swarmica.

Инструкция

1. Подключитесь к Swarmica серверу по SSH как root пользователь.

2. Создайте папку /root/swarmica/custom_certs:

mkdir /root/swarmica/custom_certs

3. Загрузите собственный CA сертификат в созданную папку. Если необходимо добавить несколько CA сертификатов их можно объединить в один. Например вот так:

cat CA-cert1.crt CA-cert2.crt > CAcert.crt

4. Создайте резервную копию файлов /root/swarmica/docker-compose.yml и /root/swarmica/.env:

cp /root/swarmica/docker-compose.yml{,.backup}
cp /root/swarmica/.env{,.backup}

5. Добавьте volume с CA сертификатом в /root/swarmica/docker-compose.yml в сервис django:

<...>
  django: &django
    image: reg.gl.swd.im/swarmica/backend:${SW_BACKEND_VERSION}
    depends_on:
      - postgres
      - redis
    volumes:
      - swarmica_ai_assistant:/swarmica/swarmica/ai_assistant/articles/:z
      - swarmica_runtime:/swarmica/swarmica/runtime_scripts/:z
      - swarmica_static:/swarmica/swarmica/static:z
      - swarmica_ugc:/swarmica/swarmica/attachments:z
      - swarmica_uploads:/swarmica/swarmica/uploads/:z
      - /root/swarmica/Articles/:/swarmica/swarmica/old_articles/:z
      - /root/swarmica/custom_certs/<CA-cert-name>.crt:/usr/local/share/ca-certificates/<CA-cert-name>.crt:ro  # <--- НУЖНАЯ СТРОКА
    env_file:
      - .env
<...>

где <CA-cert-name>.crt - это имя файла CA сертификата.

6. Добавьте следующие строки в файл /root/swarmica/.env:

REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
SSL_CERT_FILE=/usr/local/share/ca-certificates/<CA-cert-name>.crt

где <CA-cert-name>.crt - это имя файла CA сертификата.

7. Перезапустите Свормики:

docker compose down && docker compose up -d

Симптомы

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

Можем ли мы использовать отказоустойчивый кластер БД для Swarmica?

Можно ли настроить Swarmica в режиме active-active cluser?

Решение

Рекомендуемое решение

Наиболее оптимальным решением, с точки зрения стоимости обслуживания, влияния на производительность системы, а так же показателей восстановления RTO (Recovery Time Objective, целевое время восстановления работы) / RPO (Recovery Point Objective, максимальный допустимый объем потерянных данных) является размещение Swarmica внутри единой виртуальной машины, виртуальный диск которой расположен на сетевом хранилище с необходимыми настройками репликации и отказоустойчивости.

Таким образом, минимизируются накладные расходы на развертывание и обслуживание системы и обеспечиваются целевые показатели отказоустойчивости.

Вынос БД в отдельный сервер с репликацией

Для данной конфигурации нужны 2 сервера:

-Сервер Swarmica (Ubuntu 24)
-Сервер Postgresql-1 (Ubuntu 24)
-Сервер Postgresql-2 (Ubuntu 24)

Postgresql-1 выступает в роли Мастер сервера, а Postgresql-2 в роли реплики.

1. На сервере Swarmica установите Swarmica по инструкции

2. После установки создайте резервную копию БД как описано здесь

3. Остановите Swarmica:

cd /root/swarmica
docker compose down

4. Создайте резервную копию файла /root/swarmica/docker-compose.yml

cp /root/swarmica/docker-compose.yml{,.orig}

5. Закомментируйте спецификацию сервиса postgres и строки описывающие зависимость от сервиса postgres в файле /root/swarmica/docker-compose.yml:

volumes:
  swarmica_ai_assistant: {}
  swarmica_logs: {}
#  swarmica_postgres_data_backups: {}
#  swarmica_postgres_data: {}
  swarmica_runtime: {}
<...>
  django: &django
    image: reg.gl.swd.im/swarmica/backend:${SW_BACKEND_VERSION}
    depends_on:
#      - postgres
<...>
#  postgres:
#    image: postgres:14.2-bullseye
#    container_name: swarmica-postgres
#    shm_size: 1gb
#    command: postgres -N 200 -c work_mem=8MB -c temp_buffers=16MB -c shared_buffers=1GB -c track_activity_query_size=16384
#    restart: always
#    volumes:
#      - swarmica_postgres_data:/var/lib/postgresql/data:Z
#      - swarmica_postgres_data_backups:/backups:z
#    env_file:
#      - .env
<...>
  celeryworker:
    <<: *django
    depends_on:
#      - postgres
      - redis
<...>
  celerybeat:
    <<: *django
    restart: always
    depends_on:
#      - postgres
      - redis
<...>

6. В файле /root/swarmica/.env измените:

POSTGRES_HOST=postgres

на

POSTGRES_HOST=<IP_ADDRESS>

где <IP_ADDRESS> - IP адрес сервера Postgresql

и запустите Swarmica:

docker compose pull && docker compose up -d

7. На обоих Postgresql серверах установите postgresql-14:

sudo apt install curl ca-certificates -y
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
sudo apt update
sudo apt install postgresql-14 postgresql-contrib-14 -y

8. На обоих серверах авторизуйтесь как пользователь postgres и создайте пользователя и БД для Swarmica:

su - postgres
psql
CREATE USER swarmica_user WITH PASSWORD '<PASSWORD>';
CREATE DATABASE swarmica_app OWNER swarmica_user;
GRANT ALL PRIVILEGES ON DATABASE swarmica_app TO swarmica_user;
quit
exit

где <PASSWORD> - пароль БД из файла /root/swarmica/.env с сервера Swarmica.

9. На Postgresql-1 загрузите резервную копию БД из шага 2 и восстановите ее:

pg_restore --if-exists --clean -U swarmica_user -d swarmica_app <PATH-TO-BACKUP.sql> 

где <PATH-TO-BACKUP.sql> - путь до загруженной резервной копии БД.

10. На Postgresql-1 измените файл конфигурации /etc/postgresql/14/main/postgresql.conf, чтобы postgresql был доступен извне и добавьте конфигурацию Мастер сервера:

listen_addresses = '*'
wal_level = replica
max_wal_senders = 10
max_replication_slots = 5
hot_standby = on

11. Добавьте в файл /etc/postgresql/14/main/pg_hba.conf строку:

host    swarmica_app    swarmica_user    <IP>/<MASK>                 md5
host    replication     repuser          <REPLICA_IP>/<REPLICA_MASK> md5

где <IP> - IP адрес Swarmica сервера, <MASK> - маска подсети, <REPLICA_IP> - IP адрес сервера Postgresql-2 и <REPLICA_MASK> - его маска подсети.

12. Создайте пользователя для репликации:

sudo -u postgres psql -c "CREATE ROLE repuser REPLICATION LOGIN PASSWORD 'your_secure_password';"

13. Перезапустите postgresql на Postgresql-1:

systemctl restart postgresql@14-main

14. На Postgresql-2 остановите postgresql:

systemctl stop postgresql@14-main

15. Очистите папку с данными:

sudo rm -rf /var/lib/postgresql/14/main/*

16. Скопируйте данные с Postgresql-1:

sudo -u postgres pg_basebackup -h <IP_Мастера> -U repuser -D /var/lib/postgresql/14/main/ -P -R -v

17. Запустите posgresql на Postgresql-2:

systemctl start postgresql@14-main

Вынос БД в отдельный сервер + отказоустойчивость

Для данной конфигурации нужны 4 сервера:

-Сервер swarmica-master-1 (Ubuntu 24)
-Сервер swarmica-postgres-1 (Ubuntu 24)
-Сервер swarmica-postgres-2 (Ubuntu 24)
-Сервер swarmica-pgbouncer-1 (Ubuntu 24)

swarmica-master-1

Повторите шаги 1-6 этой секции, но на 6 шаге измените строки:

POSTGRES_HOST=postgres
POSTGRES_PORT=5432

на:

POSTGRES_HOST=<PGBOUNCER_IP>
POSTGRES_PORT=6432

где <PGBOUNCER_IP> - IP адрес сервера swarmica-pgbouncer-1

swarmica-pgbouncer-1

На данном сервере настраивается приложение pgbouncer + haproxy. Данная связка позволяет реализовать механизм failover, когда Мастер сервер базы данных станет недоступным.

1. Установите docker:

apt install docker.io docker-compose-v2

2. Создайте папку /root/swarmica-pgbouncer и перейдите в нее:

mkdir /root/swarmica-pgbouncer
cd /root/swarmica-pgbouncer

3. Создайте файл /root/swarmica-pgbouncer/docker-compose.yml со следующим содержимым:

version: "3.8"

services:
  haproxy:
    image: haproxy:2.9
    container_name: haproxy
    restart: always
    ports:
      - "5433:5433"
      - "8404:8404"
    volumes:
      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro

  pgbouncer:
    image: edoburu/pgbouncer
    container_name: pgbouncer
    restart: always
    ports:
      - "6432:6432"
    volumes:
      - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro
      - ./users/userlist.txt:/etc/pgbouncer/userlist.txt:ro

4. Создайте файл /root/swarmica-pgbouncer/haproxy.cfg со следующим содержимым:

global
  maxconn 10000

defaults
  mode tcp
  timeout connect 5s
  timeout client  1m
  timeout server  1m

# =========================
# Patroni API checks
# =========================
frontend pgsql_write
  bind *:5433
  default_backend pg_primary

backend pg_primary
  option httpchk GET /master
  http-check expect status 200

  server pg1 <swarmica-postgres-1_IP>:5432 check port 8008
  server pg2 <swarmica-postgres-2_IP>:5432 check port 8008

# =========================
# metrics
# =========================
listen stats
  bind *:8404
  stats enable
  stats uri /

где <swarmica-postgres-1_IP> IP адрес swarmica-postgres-1 и <swarmica-postgres-2_IP> - IP адрес swarmica-postgres-2.

5. Создайте файл /root/swarmica-pgbouncer/pgbouncer.ini со следующим содержимым:

[databases]
swarmica_app = host=<swarmica-pgbouncer-1_IP> port=5433 dbname=swarmica_app

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432

auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction

max_client_conn = 2000
default_pool_size = 50

ignore_startup_parameters = extra_float_digits

6. Создайте файл /root/swarmica-pgbouncer/users/userlist.txt со следующим содержимым:

"swarmica_user" "<DB_PASSWORD>"

где <DB_PASSWORD> - пароль БД из файла /root/swarmica/.env с сервера swarmica-master-1

7. Запустите приложение:

docker compose pull && docker compose up -d

swarmica-postgres-1 и swarmica-postgres-2

На этих серверах устанавливаются postgresql-14, etcd и patroni. Один из серверов выступает в роли Мастера, второй в роли Реплики. Связка etcd + patroni обеспечивает механизм failover. Если Мастер сервер вдруг станет недоступен, то patroni сделает Реплику Мастером, а старый Мастер станет Репликой, когда вернется в рабочее состояние.

1. Установите на обоих серверах postgresql-14 (п.7-11 этой секции)

2. На swarmica-postgres-1 установите пароль для пользователя postgres и создайте пользователя для репликации:

su - postgres
psql -c "ALTER ROLE postgres PASSWORD '<POSTGRES_PASSWORD>';"
psql -C "CREATE ROLE replication_user WITH REPLICATION LOGIN PASSWORD 'REPLICATION_PASSWORD';"
exit

3. На swarmica-postgres-1 восстановите резервную копию БД (п.12 этой секции). На swarmica-postgres-2 восстанавливать резервную копию не надо.

4. На обоих серверах остановите и выключите postgresql:

systemctl stop postgresql@14-main && systemctl disable postgresql@14-main

Это необходимо поскольку дальше управлять БД будет patroni.

5. На обоих серверах установите etcd:

apt install etcd-server etcd-client

6. Создайте файл /etc/systemd/system/etcd.service со следующим содержимым:

swarmica-postgres-1:

[Unit]
Description=etcd
After=network.target network-online.target
Wants=network-online.target

[Service]
Type=notify
User=etcd

ExecStart=/usr/bin/etcd \
  --name pg1 \
  --data-dir /var/lib/etcd \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://<swarmica-postgres-1_IP>:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://<swarmica-postgres-1_IP>:2380 \
  --initial-cluster pg1=http://<swarmica-postgres-1_IP>:2380,pg2=http://<swarmica-postgres-2_IP>:2380 \
  --initial-cluster-state new \
  --initial-cluster-token postgres-cluster

Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

swarmica-postgres-2:

[Unit]
Description=etcd
After=network.target network-online.target
Wants=network-online.target

[Service]
Type=notify
User=etcd

ExecStart=/usr/bin/etcd \
  --name pg2 \
  --data-dir /var/lib/etcd \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://<swarmica-postgres-2_IP>:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://<swarmica-postgres-2_IP>:2380 \
  --initial-cluster pg1=http://<swarmica-postgres-1_IP>:2380,pg2=http://<swarmica-postgres-2_IP>:2380 \
  --initial-cluster-state existing \
  --initial-cluster-token postgres-cluster

Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Замените <swarmica-postgres-1_IP> и <swarmica-postgres-2_IP> соответственно.

7. Запустите etcd сначала на swarmica-postgres-1, потом на swarmica-postgres-2:

systemctl daemon-reload
systemctl enable etcd --now

И проверьте, что кластер etcd запустился:

etcdctl member list

Пример ожидаемого вывода:

$ etcdctl member list
c9104917e339b5d, started, pg1, http://10.130.0.33:2380, http://10.130.0.33:2379, false
e8205d05fd4e969, started, pg2, http://10.130.0.27:2380, http://10.130.0.27:2379, false

8. Установите необходимые пакеты для patroni на обоих серверах:

apt install python3 python3-pip python3-dev pipx -y

9. Авторизуйтесь под пользователем postgres и установите patroni на обоих серверах:

su - postgres
pipx ensurepath
source ~/.bashrc
pipx install patroni[psycopg2-binary,etcd]
exit

10. Создайте файл /etc/systemd/system/patroni.service на обоих серверах с содержимым:

[Unit]
Description=High availability PostgreSQL cluster
After=syslog.target network.target etcd.service

[Service]
Type=simple
User=postgres
Group=postgres
ExecStart=/var/lib/postgresql/.local/bin/patroni /etc/patroni/patroni.yml
KillMode=process
TimeoutSec=30
Restart=no

[Install]
WantedBy=multi-user.target

11. Создайте файл конфигурации /etc/patroni/patroni.yml на обоих серверах.

swarmica-postgres-1:

scope: pg-cluster
namespace: /db/
name: pg1

restapi:
  listen: 0.0.0.0:8008
  connect_address: <swarmica-postgres-1_IP>:8008                             # здесь надо указать соответствующий IP

etcd3:
  hosts: ["<swarmica-postgres-1_IP>:2379", "<swarmica-postgres-2_IP>:2379"]  # здесь надо указать соответствующие IP

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10

    postgresql:
      use_pg_rewind: true
      use_slots: true
      parameters:
        wal_level: replica
        hot_standby: "on"
        max_wal_senders: 10
        max_replication_slots: 10
        wal_keep_size: 1GB

  initdb:
    - encoding: UTF8
    - data-checksums

  pg_hba:
    - host replication replication_user <NETWORK>/<MASK> md5    # здесь указываем нужные сеть и маску подсети
    - host all all 0.0.0.0/0 md5

postgresql:
  listen: 0.0.0.0:5432
  connect_address: <swarmica-postgres-1_IP>:5432                # здесь надо указать соответствующий IP 

  data_dir: /var/lib/postgresql/14/main

  bin_dir: /usr/lib/postgresql/14/bin

  authentication:
    replication:
      username: replication_user
      password: <REPLICATION_PASSWORD>
    superuser:
      username: postgres
      password: <POSTGRES_PASSWORD>

  pg_hba:
    - host replication replication_user <NETWORK>/<MASK> md5    # здесь указываем нужные сеть и маску подсети
    # Keep your other existing pg_hba lines below
    - host all all 0.0.0.0/0 md5

tags:
  nofailover: false
  noloadbalance: false
  clonefrom: false
  nosync: false

swarmica-postgres-2:

scope: pg-cluster
namespace: /db/
name: pg2

restapi:
  listen: 0.0.0.0:8008
  connect_address: <swarmica-postgres-2_IP>:8008                            # здесь надо указать соответствующий IP

etcd3:
  hosts: ["<swarmica-postgres-1_IP>:2379", "<swarmica-postgres-2_IP>:2379"] # здесь надо указать соответствующие IP

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10

    postgresql:
      use_pg_rewind: true
      use_slots: true
      parameters:
        wal_level: replica
        hot_standby: "on"
        max_wal_senders: 10
        max_replication_slots: 10
        wal_keep_size: 1GB

  initdb:
    - encoding: UTF8
    - data-checksums

  pg_hba:
    - host replication replication_user <NETWORK>/<MASK> md5       # здесь указываем нужные сеть и маску подсети
    - host all all 0.0.0.0/0 md5

postgresql:
  listen: 0.0.0.0:5432
  connect_address: <swarmica-postgres-2_IP>:5432                   # здесь надо указать соответствующий IP

  data_dir: /var/lib/postgresql/14/main

  bin_dir: /usr/lib/postgresql/14/bin

  authentication:
    replication:
      username: replication_user
      password: <REPLICATION_PASSWORD>
    superuser:
      username: postgres
      password: <POSTGRES_PASSWORD>

  pg_hba:
    - host replication replication_user <NETWORK>/<MASK> md5      # здесь указываем нужные сеть и маску подсети
    # Keep your other existing pg_hba lines below
    - host all all 0.0.0.0/0 md5

tags:
  nofailover: false
  noloadbalance: false
  clonefrom: false
  nosync: false

12. Запустите patroni сначала на swarmica-postgres-1 и через 5-10 секунд на swarmica-postgres-2:

systemctl daemon-reload
systemctl enable patroni --now

13. Проверьте работоспособность patroni:

sudo -u postgres -i patronictl -c /etc/patroni/patroni.yml list

Ожидаемый вывод команды:

+ Cluster: pg-cluster (7644156829524943409) -+----+-------------+-----+------------+-----+
| Member | Host        | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+--------+-------------+---------+-----------+----+-------------+-----+------------+-----+
| pg1    | 10.130.0.33 | Leader  | running   |  6 |             |     |            |     |
| pg2    | 10.130.0.27 | Replica | streaming |  6 |   0/F742FF0 |   0 |  0/F742FF0 |   0 |
+--------+-------------+---------+-----------+----+-------------+-----+------------+-----+

Active-active кластер Swarmica

Инструкция

Скрипты, используемые в этой инструкции берут данные о заявках (с комментариями и вложениями), клиентах, компаниях и сотрудниках из Omnidesk и импортируют эти данные в Swarmica.

0. Отключите почту: в Swarmica - Настройки - Настройки Swarmica переключите Email конфигурация на Файл.

1. Авторизуйтесь в Swarmica как Администратор.

2. Добавьте новый скрипт в Swarmica - Настройки - Скрипты

3. Загрузите скрипт prefetch_tickets.py и добавьте следующие Параметры веб-формы и нажмите Сохранить:

[
  {
    "name": "omnidesk_url",
    "type": "string",
    "required": true,
    "displayName": "Omnidesk URL"
  },
  {
    "name": "omnidesk_user",
    "type": "string",
    "required": true,
    "displayName": "API Пользователь Omnidesk"
  },
  {
    "name": "omnidesk_token",
    "type": "string",
    "required": true,
    "displayName": "API токен"
  },
  {
    "name": "omnidesk_delay",
    "type": "number",
    "required": true,
    "displayName": "Таймаут API запроса(10 с. по умолчанию)"
  },
  {
    "name": "date_from",
    "type": "date",
    "required": true,
    "displayName": "Дата с"
  },
  {
    "name": "date_to",
    "type": "date",
    "required": true,
    "displayName": "Дата по"
  }
]

Выглядеть это должно вот так:

здесь:

Omnidesk URL - URL панели Omnidesk. Например, https://domain.omnidesk.tld

API Пользователь Omnidesk - логин(email) администратора Omnidesk

API Токен - сгенерированный API токен

Задержка для API запроса(10 с. по умолчанию) - промежуток времени между API запросами(по умолчанию 10 сек.)

Дата с - дата создания заявок, с которой будет производится выборка

Дата по - дата создания заявок, до которой будет производится выборка

4. В панели администратора Omnidesk создайте API токен, заполните поля веб-формы и нажмите Отправить.

Как результат, в контейнере swarmica-django-1 будет создана директория /swarmica/swarmica/uploads/omnidesk_migration со следующей структурой:

└── omnidesk_migration
    ├── {case1_id}
    │   ├── {attachment1_id}.data
    │   ├── {attachment2_id}.data
    │   ├── attachments.json
    │   ├── comments.json
    │   └── ticket.json
    ├── {case2_id}
    │   ├── comments.json
    │   └── ticket.json    
    ├── companies.json
    ├── omnidesk_to_swarmica.log
    ├── staff.json
    └── users
        ├── {user_id}.json

5. Создайте резервную копию Swarmica по этой инструкции. Данный пункт можно пропустить, если миграция производится на чистую установку Swarmica.

6. Создайте скрипт в Swarmica - Настройки - Скрипты. Загрузите скрипт convert_import_omnidesk.py и добавьте следующие Параметры веб-формы и нажмите Сохранить:

[
  {
    "name": "omnidesk_data_path",
    "type": "string",
    "required": false,
    "displayName": "Путь к папке с данными (omnidesk_migration)"
  },
  {
    "name": "force_use_existing_users",
    "type": "boolean",
    "required": false,
    "displayName": "Принудительно привязывать пользователей при конфликте ext_id"
  },
  {
    "name": "force_use_existing_orgs",
    "type": "boolean",
    "required": false,
    "displayName": "Принудительно привязывать организации при конфликте ext_id"
  }
]

Выглядеть это должно вот так:

Поле Путь к папке с данными (omnidesk_migration) можно оставить пустым, если данные полученные в шаге 4 не перемещались.

7. Нажмите Отправить

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

8. Создайте скрипт в Swarmica - Настройки - Скрипты. Загрузите скрипт post_migration.py, добавьте следующие Параметры веб-формы и нажмите Сохранить:

[
  {
    "name": "omnidesk_data_path",
    "type": "string",
    "required": false,
    "displayName": "Путь к папке с данными (omnidesk_migration)"
  }
]

Выглядеть должно вот так:

9. Нажмите Отправить

В результате произойдет пост-обработка заявок в виде создания внутренних соответствующих тасок для статусов.

10. Включите почту в Swarmica - Настройки - Настройки Swarmica переключите Email конфигурация на SMTP.

Траблшутинг

Для прерывания и повторного запуска скрипта перезапустите celeryworker контейнер:

docker compose up -d --scale celeryworker=0; docker compose up -d

в логах можно отследить процесс и что пошло не так:

docker logs swarmica-celeryworker-1 2>&1 | grep "Omnidesk import:" > script.log

Симптомы

При настройке сервера получения при подключении email канала по IMAP, возникает Ошибка:

[SSL: UNSUPPORTED_PROTOCOL] unsupported protocol (_ssl.c:1017) и [SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1017)

Переменные IMAP_SSL_CUSTOM_CONTEXT=true и IMAP_SSL_CUSTOM_CIFERS=DEFAULT уже добавлены.

Почтовый сервер: MS Exchange

Решение

На почтовом сервере нужно либо разрешить коннект по логину для подключения без шифрования, либо использовать классические SSL/TLS и пробовать подключение по порту, где они настроены.

Альтернативно вместо простого IMAP подключения можно настроить SMTP трансфер.

Причина

Swarmica использует стандартную библиотеку для подключения по классическим TLS/SSL. Соответственно рекомендуется использовать либо стандартные типы подключения по этим протоколам, либо подключаться без шифрования. Все эти настройки находятся на стороне почтового сервера.

В Swarmica по умолчанию доступен только IMAP канал для почты.

В данной документации содержится инструкция по настройке SMTP канала для почты.

Инструкция

1. Подключитесь к серверу Swarmica по SSH под root пользователем

2. Перейдите в папку /root/swarmica:

cd ~/swarmica

3. Создайте резервную копию файлов docker-compose.yml и .env:

mkdir backup; cp -a .env docker-compose.yml ./backup

4. Добавьте следующую секцию postfix для соответствующего сервиса в docker-compose.yml:

  postfix:
    <<: *django
    restart: always
    depends_on:
      - postgres
      - redis
    volumes:
      - swarmica_logs:/swarmica/swarmica/logs:z
      - swarmica_ugc:/swarmica/swarmica/attachments/:z
    env_file:
      - .env
    ports:
      - "25:25"
    command: /start-postfix
    labels:
      - "traefik.enable=false"

5. Добавьте в .env файл SMTP настройки:

EMAIL_SERVER_HOSTNAME=<SWARMICA_HOSTNAME>
SMTP_SERVER=<SMTP_RELAY>
SMTP_PORT=<SMTP_RELAY_PORT>
SMTP_USERNAME=<SMTP_RELAY_USER>
SMTP_PASSWORD=<SMTP_RELAY_USER_PASSWORD>
SMTP_NETWORKS=<ALLOWED_NETWORKS_CIDR>
SMTP_USE_TLS=<YES|NO>

В качестве настроек SMTP здесь можно использовать те же, что и для уже настроенного SMTP Relay в Swarmica - Настройки - SMTP Relay

6. Добавьте фича-флаг __smtp_email_channel в файл .env по этой инструкции.

7. Перезапустите Swarmica:

docker compose down; docker compose up -d

8. Авторизуйтесь в Swarmica UI как Администратор.

9. Добавьте SMTP канал в Настройки - Каналы - Email - Создать - Перенаправление(SMTP):

10. В появившемся окне укажите Название канала, email получателя и email отправителя(например support@example.tld) и нажмите Сохранить:

11.На открывшейся странице настроек SMTP канал укажите Имя отправителя(например, swarmica support), включите канал, заполните Настройки сервера отправления или включите системный SMTP сервер(SMTP Relay) и нажмите Сохранить

Симптомы

Система остаётся открытой и залогиненной, даже после блокировки экрана в ОС на ПК сотрудника

Решение

1 - Добавить или изменить параметры в /root/swarmica/.env:

ACCESS_TOKEN_TTL_SECONDS=1800
REFRESH_TOKEN_TTL_SECONDS=3600
ROTATE_REFRESH_TOKENS=1

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

2 - Рестартануть сервисы:

docker compose down && docker compose up -d

Симптомы

После обновления до 5.9 пропал чекбокс с опцией Автоназначение в настройках сотрудника.

Решение

Использовать Статус:

Причина

Начиная с 5.9 опция Автоназначение была смигрированна в Статус.

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

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

Симптомы

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

Решение

Чтобы сменить логотип в уведомлениях, необходимо настроить вид писем в брендировании. Для этого нужно перейти в раздел Настройки - Управление брендами - Имя вашего бренда - Вид email — Шапка.

В этом разделе можно прописать HTML код и указать свою картинку, чтобы в письмах использовался корпоративный стиль.

Описание

Фича-флаги позволяют включать и выключать определенные функции системы в рамках лимитов установленной лиценизии.

Мехнизм подключения фичей следующий:

• Лицензия определяет, какие фичи можно включать
• Набор фича-флагов в /root/swarmica/.env в переменной FEATURES определяет, какие фичи на данном инстансе включены

В результате, применяется пересечение того, что разрешает лицензия и того, что записано в FEATURES:

• Если фича есть и в лицензии и в FEATURES, то фича будет включена
• Если фича есть только в лицензии, но нет в FEATURES - она будет выключена. А если прописать ее в FEATURES и перезагрузить приложение, тогда это сводится к предыдущему пункту, т.е. фича будет включена
• Если фича есть в FEATURES, но нет в лицензии, то она будет выключена. Чтобы она заработала, необходимо связаться с аккаунт-менеджером или поддержкой Swarmica и подтвердить подключение фичи на лицензии. После чего можно будет в разделе Настройки > Основные настройки > Лицензия Swarmica обновить данные ключа и фича будет включена.

Фича-флаги с префиксом __ не проверяются лицензией.

FEATURES=automations,automations_outgoing_emails,...

Фича-флаги

ВАЖНО! После редактирования .env файла обязательно нужно выполнить рестарт сервисов, чтобы применить нужные флаги:

docker compose down && docker compose up -d

Вопрос

Возможна ли конфигурация системы с выносом на отдельные инстансы сервисов postgresql, redis, backend-frontend?

Ответ

Такая конфигурация не рекомендуется.

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

Если в теории вынести сервер БД во внешний кластер на свой страх и риск, а приложение настроить на подключение к этому самому кластеру, то:

1. Такая схема штатно не тестируется - поэтому возможны какие-то неожиданные нюансы, которые будет сложно решать.
2. В случае сценария восстановления после сбоя есть риск (хоть и минимальный), что код приложения, который в контейнерах и версия базы будут отличаться. Особенно если отдельно восстановить данные на стороне БД, если там был сбой. А тогда сложно предсказать поведение приложения - сможет ли оно подняться и корректно прокатить все миграции или нет
3. В случае поломки, резервирование БД не решает проблему восстановления пользовательских данных , которые лежат в докер волюмах swarmica_ugc, swarmica_uploads, swarmica_runtime, swarmica_cron_d . В теории, конечно, можно примонтировать их как сетевые диски, но тогда будет задержка при чтении/записи этих файлов на latency сети, а это уже будет негативно сказываться на скорости работы веб-интерфейса

Симптомы

Есть ли возможность инициировать выход из учетной записи (логаут, logout) в виджете программно?

Есть ли API для выхода из учетной записи виджета?

Решение

Да, инициировать выход из учетной записи виджета можно программно, используя стандартное браузерное API window.postMessage на DOM объекте iframe:

const iframe = document.getElementById("swarmica_widget_iframe_id");
iframe.contentWindow.postMessage({ type: "LOGOUT_WIDGET" }, "*");

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

<!-- parent HTML --> 
<button id="logoutWidgetBtn">
  Logout widget
</button>

<!-- start embedded Swarmica widget script -->
<iframe src="..." id="swarmica_widget_iframe_id" style="position: fixed; right: 12px; bottom: 12px; width: 56px; height: 56px; overflow: hidden; "
  allowTransparency="true"
  frameborder="0"
  allowTransparency="true" frameborder="0"></iframe>
<!-- rest of embed code -->
<script>
  const iframe = document.getElementById("swarmica_widget_iframe_id")
  iframe.onload = () => {
    renderWidget("swarmica_widget_iframe_id")
  }
  document.getElementById("swarmica_widget_iframe_id").addEventListener("click", 
    () => {
            if (!iframe || !iframe.contentWindow) return;
            iframe.contentWindow.postMessage({ type: "LOGOUT_WIDGET" }, "*")
  });
</script>
<!-- end embedded Swarmica widget scripts -->

Симптомы

Контейнер Telegram находится в состоянии вечного рестарта. В логах нет никакой полезной информации, только сообщения о доступности PostgreSQL и о запуске Telegram-бота:

telegram-1  | PostgreSQL is available
telegram-1  | Starting the Telegram bot...

Решение

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

Если функционал Telegram-ботов не используется, контейнер можно остановить.

Причина

Контейнер Telegram находится в вечном рестарте из-за отсутствия в системе Telegram-ботов. Это сделано специально, чтобы при добавлении бота не требовалось перезапускать систему.

Симптомы

При попытке сменить роль пользователя в списке нет ролей Агент, Менеджер, Администратор.

Сообщение:

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

Решение

Докупить необходимое количество пользователей: sales@swarmica.com

Причина

Достигнут лимит пользователей на лицензии. Проверить можно в Настройках - Лиценция Swarmica. В лицензию считаются пользователи Агент, Менеджер, Администратор. Пользователей Сотрудников, у которых права только на чтение, можно создавать неограниченное количество.

Симптомы

Заходишь в хелпцентр и хочется праздника. Что делать?

Решение

Очень важно поддерживать праздничное настроение даже в мелочах, поэтому, давайте украсим нашу базу знаний!

1. Зайдем в Настройки > Основные настройки > Управление брендами и выберем ваш активный бренд
2. В раздел Стили для темы добавим такой контент в конец, после того, что там уже есть:

.xmas-snowflakes {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    pointer-events: none;
    z-index: 100;
}

.xmas-snowflake {
    position: absolute;
    top: -50px;
    color: #87CEEB;
    font-size: 1.5em;
    opacity: 0.8;
    text-shadow: 0 0 5px rgba(135, 206, 235, 0.5);
    animation-name: fall;
    animation-timing-function: linear;
    animation-iteration-count: infinite;
}

.xmas-snowflake:nth-child(1) { left: 10%; animation-duration: 8s; animation-delay: 0s; }
.xmas-snowflake:nth-child(2) { left: 20%; animation-duration: 10s; animation-delay: 1s; }
.xmas-snowflake:nth-child(3) { left: 30%; animation-duration: 12s; animation-delay: 2s; }
.xmas-snowflake:nth-child(4) { left: 40%; animation-duration: 9s; animation-delay: 3s; }
.xmas-snowflake:nth-child(5) { left: 50%; animation-duration: 11s; animation-delay: 4s; }
.xmas-snowflake:nth-child(6) { left: 60%; animation-duration: 8s; animation-delay: 5s; }
.xmas-snowflake:nth-child(7) { left: 70%; animation-duration: 10s; animation-delay: 6s; }
.xmas-snowflake:nth-child(8) { left: 80%; animation-duration: 12s; animation-delay: 7s; }
.xmas-snowflake:nth-child(9) { left: 90%; animation-duration: 9s; animation-delay: 8s; }
.xmas-snowflake:nth-child(10) { left: 15%; animation-duration: 11s; animation-delay: 9s; }
.xmas-snowflake:nth-child(11) { left: 25%; animation-duration: 8s; animation-delay: 10s; }
.xmas-snowflake:nth-child(12) { left: 35%; animation-duration: 10s; animation-delay: 11s; }
.xmas-snowflake:nth-child(13) { left: 45%; animation-duration: 12s; animation-delay: 12s; }
.xmas-snowflake:nth-child(14) { left: 55%; animation-duration: 9s; animation-delay: 13s; }
.xmas-snowflake:nth-child(15) { left: 65%; animation-duration: 11s; animation-delay: 14s; }

@keyframes fall {
    0% {
        transform: translateY(-100px) rotate(0deg);
        opacity: 0;
    }
    10% {
        opacity: 0.8;
    }
    90% {
        opacity: 0.8;
    }
    100% {
        transform: translateY(100vh) rotate(360deg);
        opacity: 0;
    }
}

.xmas-snowflake:nth-child(odd) {
    animation-name: fall-sway;
}

@keyframes fall-sway {
    0% {
        transform: translateY(-100px) translateX(0px) rotate(0deg);
        opacity: 0;
    }
    10% {
        opacity: 0.8;
    }
    50% {
        transform: translateX(50px);
    }
    90% {
        opacity: 0.8;
    }
    100% {
        transform: translateY(100vh) translateX(-50px) rotate(360deg);
        opacity: 0;
    }
}

.xmas-snowflake::before {
    content: "❄";
}

.xmas-snowflake:nth-child(3n)::before {
    content: "✦";
    font-size: 1.2em;
}

.xmas-snowflake:nth-child(5n)::before {
    content: "❅";
    font-size: 1.3em;
}


.xmas-garland {
    position: fixed;
    top: 60px;
    left: 0;
    width: 100%;
    height: 40px;
    z-index: 101;
    pointer-events: none;
}

.xmas-garland::before {
    content: '';
    position: absolute;
    top: 15px;
    left: 0;
    width: 100%;
    height: 2px;
    background: #333;
    box-shadow: 0 0 5px rgba(255, 255, 255, 0.2);
}

.xmas-light {
    position: absolute;
    top: 36px;
    width: 20px;
    height: 20px;
    border-radius: 50%;
    animation: blink 1.5s infinite alternate;
    box-shadow: 0 0 10px currentColor;
    transform: scale(1);
}

.xmas-light:nth-child(1) { left: 5%; animation-delay: 0s; background: #ff0000; color: #ff0000; } /* Red */
.xmas-light:nth-child(2) { left: 15%; animation-delay: 0.2s; background: #00ff00; color: #00ff00; } /* Green */
.xmas-light:nth-child(3) { left: 25%; animation-delay: 0.4s; background: #0000ff; color: #0000ff; } /* Blue */
.xmas-light:nth-child(4) { left: 35%; animation-delay: 0.6s; background: #ffff00; color: #ffff00; } /* Yellow */
.xmas-light:nth-child(5) { left: 45%; animation-delay: 0.8s; background: #ff00ff; color: #ff00ff; } /* Magenta */
.xmas-light:nth-child(6) { left: 55%; animation-delay: 1.0s; background: #00ffff; color: #00ffff; } /* Cyan */
.xmas-light:nth-child(7) { left: 65%; animation-delay: 1.2s; background: #ff8800; color: #ff8800; } /* Orange */
.xmas-light:nth-child(8) { left: 75%; animation-delay: 0.1s; background: #ff0088; color: #ff0088; } /* Pink */
.xmas-light:nth-child(9) { left: 85%; animation-delay: 0.3s; background: #88ff00; color: #88ff00; } /* Lime */
.xmas-light:nth-child(10) { left: 95%; animation-delay: 0.5s; background: #8800ff; color: #8800ff; } /* Purple */

.xmas-light::before {
    content: '';
    position: absolute;
    top: -4px;
    left: 50%;
    transform: translateX(-50%);
    width: 10px;
    height: 4px;
    background: #666;
    border-radius: 2px 2px 0 0;
}

.xmas-light::after {
    content: '';
    position: absolute;
    top: -15px;
    left: 50%;
    transform: translateX(-50%);
    width: 2px;
    height: 15px;
    background: #555;
}

@keyframes blink {
    0%, 100% {
        transform: scale(1);
        opacity: 0.8;
        box-shadow: 0 0 10px currentColor;
    }
    50% {
        transform: scale(1.2);
        opacity: 1;
        box-shadow: 0 0 20px currentColor, 0 0 30px currentColor;
    }
}

3. В раздел Стили публичного портала базы знаний > Шапка вставим перед имеющимся контентом:

<div class="xmas-garland">
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
    <div class="xmas-light"></div>
</div>

4. В раздел Стили публичного портала базы знаний > Подвал вставим после имеющегося контента:

<div class="xmas-snowflakes">
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
        <div class="xmas-snowflake"></div>
</div>

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

Симптомы

Как сменить хостнейм - доменное имя, по которому доступна Свормика?

Решение

Зайти по SSH на сервер с установленной Свормикой, и выполнить следующие команды:

make -f /root/swarmica/Makefile change-hostname HOSTNAME=my.new.hostname.tld
docker compose down && docker compose up -d

Симптомы

Необходимо настроить две и более витрины, которые будут находиться в разных географических точках и с разными доменными именами, которые будут ходить в один и тот же инстанс Swarmica. Как это сделать?

Решение

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

Подготовка Swarmica

1. В файле /root/swarmica/.env добавьте адреса балансировщиков в переменную DJANGO_ALLOWED_HOSTS:

DJANGO_ALLOWED_HOSTS=my.swarmica.tld,balancer1.swarmica.tld,balancer2.swarmica.tld

2. В файле /root/swarmica/docker-compose.yml везде, где используется директива Host, добавьте адреса балансировщиков, например, так:

services:

  frontend:
    image: reg.gl.swd.im/swarmica/frontend:${SW_FRONTEND_VERSION}
    depends_on:
      - django
    restart: always
    volumes:
      - ./robots.txt:/robots.txt:ro
      - swarmica_static:/admin_static:ro
      - swarmica_ugc:/attachments:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.nginx.entrypoints=web-secure"
      - "traefik.http.routers.nginx.rule=Host(`${SW_HOSTNAME}`) || Host(`balancer1.swarmica.tld`) || Host(`balancer2.swarmica.tld`)"
      - "traefik.http.routers.nginx.tls.certresolver=letsencrypt"
      - "traefik.http.routers.nginx.middlewares=secure-headers,compression"
      - "traefik.http.routers.nginx.priority=10"

Как правило, это необходимо сделать для сервисов frontend, django, django-websocket, helpcenter.

3. Перезагрузите сервисы:

sudo su -
cd /root/swarmica
docker compose down
docker compose up -d

Настройки балансировщиков (nginx)

1. Предварительно, установите и настройте nginx на каждом балансировщике

2. Получите SSL сертификаты для доменных имен и добавьте их в конфигурацию nginx

3. В директиве server сайта (виртуального хоста), который отвечает за обслуживание доменного имени балансировщика, замените секцию, отвечающую за location /, так, чтобы получилась такая конфигурация:

server {
        listen 80 default_server;
        listen [::]:80 default_server;

        listen 443 ssl;
        server_name balancer1.swarmica.tld;

        ssl_certificate /etc/nginx/ssl/balancer1.swarmica.tld.crt;
        ssl_certificate_key /etc/nginx/ssl/balancer1.swarmica.tld.key;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;

        root /var/www/html;

        index index.html index.htm index.nginx-debian.html;

        server_name _;

        location / {
                proxy_pass              https://my.swarmica.tld;
                proxy_set_header        Host    $host;
                proxy_set_header        X-Forwarded-For $remote_addr;
                add_header              X-Upstream      $upstream_addr;
        }
}

4. Перезагрузите nginx

invoke-rc.d nginx restart

5. Если необходимо использование различных брендов, то в балансировщики можно добавить указание бренда через заголовок:

proxy_set_header     X-Swarmica-Brand: UID

Симптомы

Можно ли настроить репликацию базы Swarmica для аналитики или резервного копирования?

Решение

Да, Swarmica использует Postgres в качестве СУБД, который поддерживает репликацию.

Чтобы включить репликацию, необходимо выполнить шаги на основном сервере и на реплике, описанные ниже.

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

1. Создайте файл /root/swarmica/pg_hba.conf со следующим содержимым (замените REPLICA_IP на IP адрес сервера реплики):

local   all             all                                     trust
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust
local   replication     all                                     trust
host    replication     all             127.0.0.1/32            trust
host    replication     all             ::1/128                 trust
host    replication     all             REPLICA_IP/32           scram-sha-256
host all all all scram-sha-256

2. Отредактируйте /root/swarmica/docker-compose.yml, добавив монтирование pg_hba.conf в раздел volumes и передав необходимые настройки сервера postgres через команды -c:

postgres:
  image: postgres:14.2-bullseye
  container_name: swarmica-postgres
  shm_size: 8gb
  command: postgres -N 300 -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all -c wal_keep_size=512MB -c work_mem=8MB -c temp_buffers=16MB -c shared_buffers=8GB -c track_activity_query_size=16384 -c max_wal_size=4GB -c checkpoint_timeout=10min
  restart: always
  volumes:
    - swarmica_postgres_data:/var/lib/postgresql/data:Z
    - swarmica_postgres_data_backups:/backups:z
    - ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf
  env_file:
    - .env
  ports:
    - "54321:5432"

3. Перезагрузите сервисы:

cd /root/swarmica
docker compose down
docker compose up -d

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

docker exec -it swarmica-postgres psql -U ... ...
CREATE USER replicator WITH REPLICATION ENCRYPTED PASSWORD 'replicator_insecure_password';
SELECT pg_create_physical_replication_slot('replication_slot');

Настройка реплики

Здесь приводится пример настройки реплики внутри Docker контейнера на другом физическом/виртуальном сервере, вы можете применять аналогичные настройки в любом варианте установки Postgres.

1. Установите docker.io и docker-compose-v2 пакеты:

apt-get update
apt-get install docker.io docker-compose-v2

2. Создайте папку для конфигурационных файлов:

mkdir replica
cd replica

3. Создайте .env файл с параметрами подключения Postgres:

# Master host connection configuration
POSTGRES_MASTER_HOST=my-swarmica-host.tld
POSTGRES_MASTER_PORT=54321
POSTGRES_MASTER_DB=swarmica_app
POSTGRES_MASTER_USER=replicator
POSTGRES_MASTER_PASSWORD=replicator_insecure_password

# Replica host configuration
POSTGRES_HOST=postgres
POSTGRES_USER=replicator
POSTGRES_PASS=repplicator_insecure_password
POSTGRES_PORT=5432

4. Создайте docker-compose.yml файл со следующим содержимым:

volumes:
  postgres_data: {}

services:
  postgres:
    image: postgres:14.2-bullseye
    restart: always
    container_name: swarmica-postgres
    shm_size: 1gb
    environment:
      PGPASSWORD: $POSTGRES_MASTER_PASSWORD
    command: |
      gosu postgres bash -c "
      if [ ! -s /var/lib/postgresql/data/postgresql.conf ]; then
        pg_basebackup -h $POSTGRES_MASTER_HOST -p $POSTGRES_MASTER_PORT -U $POSTGRES_MASTER_USER -D /var/lib/postgresql/data -R -v --slot=replication_slot;
      fi
      chmod 700 /var/lib/postgresql/data/
      postgres -N 1024 -c hot_standby=on
      "
    volumes:
      - postgres_data:/var/lib/postgresql/data:Z
    env_file:
      - .env

5. Скачайте образы и запустите сервис реплики:

docker compose pull
docker compose up -d

6. После этого репликация дожна начаться автоматически:

root@pg-replica:~/replica# docker logs -f swarmica-postgres
pg_basebackup: initiating base backup, waiting for checkpoint to complete
pg_basebackup: checkpoint completed
pg_basebackup: write-ahead log start point: 20/22000028 on timeline 1
pg_basebackup: starting background WAL receiver
pg_basebackup: write-ahead log end point: 20/22000B88
pg_basebackup: waiting for background process to finish streaming ...
pg_basebackup: syncing data to disk ...
pg_basebackup: renaming backup_manifest.tmp to backup_manifest
pg_basebackup: base backup completed
2025-12-11 12:54:07.181 UTC [1] LOG:  starting PostgreSQL 14.2 (Debian 14.2-1.pgdg110+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
2025-12-11 12:54:07.181 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
2025-12-11 12:54:07.181 UTC [1] LOG:  listening on IPv6 address "::", port 5432
2025-12-11 12:54:07.191 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
2025-12-11 12:54:07.201 UTC [14] LOG:  database system was interrupted; last known up at 2025-12-11 12:53:56 UTC
2025-12-11 12:54:07.461 UTC [14] LOG:  entering standby mode
2025-12-11 12:54:07.468 UTC [14] LOG:  redo starts at 20/22000028
2025-12-11 12:54:07.471 UTC [14] LOG:  consistent recovery state reached at 20/22000B88
2025-12-11 12:54:07.472 UTC [1] LOG:  database system is ready to accept read-only connections
2025-12-11 12:54:07.798 UTC [18] LOG:  started streaming WAL from primary at 20/23000000 on timeline 1

Интеграция внешней системы и быстрый логин

Пожалуйста, сначала прочитайте обзор логики интеграции описанной в статье.

Настройка системы (единоразово/по необходимости)

Настройка системы, как Swarmica, так и внешняя интегрируемая система (ваше приложение), настраиваются один раз (либо перенастраиваются при необходимости)

На стороне Swarmica:

1. На сервере:Необходимо настроить секретный ключ для шифра и максимально допустимое отклонение времени в timestamp и подключить провайдер авторизации code:Для этого нужно выставить переменные в /root/swarmica/.env:

root@swarmica# grep -i code .env
AUTH_PROVIDERS=email,code
OTP_CODE_KEY=E655633B-2FAB-4661-9637-DADBE53E9633
OTP_CODE_TIMESTAMP_DELTA=120

Параметр OTP_CODE_TIMESTAMP_DELTA - это срок жизни сгенерированной ссылки для авторизации пользователя в секундах. Для примера и тестов данный параметр выставлен в 120 секунд, для продакшена рекомендуется выставить его в несколько секунд (5-10).

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

Перезагрузить систему:

cd /root/swarmica
docker compose down
docker compose up -d

1. В приложении Swarmica (требуются права Администратора):Создать API ключ, который будет использоваться бэкендом интегрируемой системы в Настройки>API интеграцииВыглядеть он будет вот так:
   8932368e-cdc6-4be4-a31d-1cf0aa129b99

На стороне интегрируемой системы (биллинга или панели):

1. Подготовить код для работы с API Swarmica.

2. Записать в настраиваемые переменные:

- Код для шифра (то же, что указано в OTP_CODE_KEY выше): E655633B-2FAB-4661-9637-DADBE53E9633

- API ключ: 8932368e-cdc6-4be4-a31d-1cf0aa129b99

-Шаблон HTML кода вставки виджета с настройкой OTP https://support.swarmica.com/article/ru/599-vstraivaemyj-veb-vidzhet.html 

Пример кода виджета:

  <!-- start embedded Swarmica widget script -->
  <iframe src="https://helpdesk.ispmanager.tech/widgets/index.html?id=veNilW0QFQhTq2hg&locale=en&otpdata=URLENCODED_ДАННЫЕ_СМ_ДАЛЕЕ" id="veNilW0QFQhTq2hg" style="position: fixed; right: 12px; bottom: 12px; width: 56px; height: 56px; overflow: hidden; "
    allowTransparency="true"
    frameborder="0"
    allowTransparency="true" frameborder="0"></iframe>
  <script src="https://help.solar-start.ru/widgets/render.js"></script>
  <script>
    const iframe = document.getElementById("veNilW0QFQhTq2hg")
    iframe.onload = () => {
      renderWidget("veNilW0QFQhTq2hg")
    }
  </script>
  <!-- end embedded Swarmica widget scripts -->

Получение code для пользователя (при регистрации / авторизации пользователя в вашем приложении)

В случае, когда пользователь авторизуется в в вашем приложении, его бэкенд  должен проверять наличие code и если его нет, то выполнять запрос на получение code для пользователя:

https://support.yourdomain.tld/api/schema/doc/#post-/api/auth/otp/code/request

где support.yourdomain.tld - адрес вашей инсталляции Swarmica

Для удобства, в запросе можно передавать не только email искомого пользователя, но и другие поля - если такой учетной записи не будет, то Swarmica автоматически создаст пользователя и сразу выпишет ему код. Параметры объекта user идентичны вызову https://support,swarmica.com/api/schema/doc/#post-/api/users/ . Так же, см. ниже Параметры создания пользователя

ВАЖНО: Этот API запрос выполняется только от учетной записи с правами Администратор (то есть, нужен API токен, который был создан при настройке системы)

Пример такого вызова:

curl -X POST "https://support.yourdoamin.tld/api/auth/otp/code/request" \
 -H "accept: application/json"\
 -H "authorization: Token 8932368e-cdc6-4be4-a31d-1cf0aa129b99"\
 -H "content-type: application/json" \
 -d '{"user":{"name":"Joe Sudyin","email":"joedoe@swarmica.com","role":"CUSTOMER","ext_id":"fake_user_id","locale":"en","custom_fields":[{"uid":"OGRcFb1U8XFHM2r1","value":"freelancer"},{"uid":"IHZAwFQD3bBJSmAM","value":"+1234567890"}]}}' \

Ответ системы:

{
  "code": "c44f3108-76fd-4797-a61e-658aeda5876b",
  "user": {
    "uid": "6zndSQzdagK8WLfK",
    "name": "Max Sudyin",
    "email": "joedoe@swarmica.com",
    "date_joined": "2025-06-18T07:17:30.564278Z",
    "role": "CUSTOMER",
    "image_path": null,
    "signatures": null,
    "ext_id": "fake_user_id",
    "custom_fields": [],
    "schedule": null,
    "locale": "en",
    "tz_offset_minutes": 0,
    "timezone": "UTC",
    "organization": "s5cN_OBc_U5MXosr",
    "source": "api",
    "kcs_role": "CANDIDATE",
    "created_at": "2025-06-18T07:17:30.857456Z",
    "updated_at": "2025-06-18T07:17:30.857463Z",
    "groups": [],
    "is_system": false,
    "is_employee": false,
    "anonymous": false,
    "identities": [
      {
        "uid": "8ipu8ZpttthVGJIa",
        "user": "6zndSQzdagK8WLfK",
        "source": "EMAIL",
        "ext_id": "joedoe@swarmica.com",
        "ext_id_type": null,
        "data": null,
        "confirmed": true,
        "default": true
      }
    ],
    "merged_into": null,
    "last_login": null
  }
}

Полезно сохранить UID пользователя и необходимо сохранить code - первое нужно для того, чтобы впоследствии было проще сопоставлять учетные записи в других интеграциях, а code необходим для генерации данных otpdata для авторизации виджета.

Генерация параметра otpdata для авторизации виджета

Когда необходимо сделать ссылку для входа (например, при нажатии на ссылку “Мои заявки”), тогда бэкенд вашего приложения должен сделать следующее:

1. Сформировать JSON данные вида:{"email": "joedoe@swarmica.com", "code": "c44f3108-76fd-4797-a61e-658aeda5876b", "timestamp": int(time.time())}
2. Зашифровать их алгоритмом шифрования (см. далее) 
3. В коде инициализации виджета подставить в значение параметра otpdata в URLEncoded виде.Например, если функция encrypt вернула вот такие данные:

GPQi9F26yw/MaNUWvmSYrShqK+n9IdtcbUraB5/WfNNdjEJqZbWk1Qifn1BF3iV4phT0tt5GtH51Ks6DMCz6hZk4NxfNnHnfpCrM+P0y8BlTK2v6nGjN+KoP/1x1OptMN+at2ZNTlPn7nVrmxfMeJdu7pruLTDo62snxHQymWiPLKvhOdgCfFAKHyWWwmxIQ

То в ссылке нужно будет указать:

&otpdata=GPQi9F26yw%2FMaNUWvmSYrShqK%2Bn9IdtcbUraB5%2FWfNNdjEJqZbWk1Qifn1BF3iV4phT0tt5GtH51Ks6DMCz6hZk4NxfNnHnfpCrM%2BP0y8BlTK2v6nGjN%2BKoP%2F1x1OptMN%2Bat2ZNTlPn7nVrmxfMeJdu7pruLTDo62snxHQymWiPLKvhOdgCfFAKHyWWwmxIQ

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

Параметры создания пользователя

При создании пользователя через https://support,yourdomain.tld/api/schema/doc/#post-/api/auth/otp/code/request или напрямую через https://support.yourdomain.tld/api/schema/doc/#post-/api/users/ можно указывать следующие данные (ниже вариант примера):

{
  "user": {
    "name": "Joe Doe",
    "email": joedoe@swarmica.com",
    "role": "CUSTOMER",
    "ext_id": "fake_user_id",
    "locale": "en",
    "custom_fields": [
       {"uid": "OGRcFb1U8XFHM2r1", "value": "freelancer"},
       {"uid": "IHZAwFQD3bBJSmAM", "value": "+1234567890"}
    ]
  }
}

Обязательные поля:

name - имя пользователя, строка

email - email пользователя, который будет использоваться для его идентификации

role - роль в Swarmica, для клиентов это может быть CUSTOMER (имеет привилегии клиента, может работать только со своими заявками/чатами) или CUSTOMER_ADMIN (имеет привилегии клиента, но может работать не только со своими заявками/чатами, но и заявками/чатами других пользователей из своей Организации).

Необязательные поля:

ext_id -  строка, ID пользователя во внешней системе (например, в личном кабинете Solar, можно использовать для сопоставления учетных записей и поиска через API и интерфейс)

locale - язык интерфейса Swarmica для этого пользователя (ru или en)

custom_fields - массив значений для кастомных полей. Все кастомные поля пользователя можно посмотреть в API custom_fields с фильтром model = user

Значения кастомных полей:

Значения кастомных полей указываются в виде объекта:

{
  “uid”: “УИД КАСТОМНОГО ПОЛЯ”,
  “value”: “ЗНАЧЕНИЕ КАСТОМНОГО ПОЛЯ В ФОРМАТЕ ЕГО ТИПА”
}

Например, для поля Телефон (uid = “IHZAwFQD3bBJSmAM”) это текстовое значение.

А для поля Тип клиента (uid = “OGRcFb1U8XFHM2r1”) указывается ключ из словаря choices, соответствующий нужному параметру:

{
  "uid": "OGRcFb1U8XFHM2r1",
  "name": {
    "en": "User type",
    "ru": "Тип пользователя"
  },
  "field_type": "DROPDOWN",
  "applicable_to": [
    "user"
  ],
  "mandatory_for": [],
  "permissions": "INTERNAL",
  "default_value": null,
  "properties": {
    "choices": {
      "customer": {
        "en": "Customer",
        "ru": "Заказчик"
      },
      "freelancer": {
        "en": "Freelancer",
        "ru": "Фрилансер"
      }
    }
  }
}

Например, для значения Фрилансер/Freelancer нужно указать freelancer, а для Заказчик/Customer - customer.

Все значения и ключи настраиваются через графический интерфейс 

Симптомы

Периодически в интерфейсе возникает ошибка [object Object]

Во вкладке Network некоторые запросы завершаются ошибкой 500 Internal error has occurred

В логах контейнера postgres ошибка FATAL: sorry, too many clients already

Решение

Увеличить количество подключений для postgres

1. В конфигурационном файле docker-compose.yml в секции postgres отредактировать значение параметра N:

  postgres:
    image: postgres:14.2-bullseye
    container_name: swarmica-postgres
    shm_size: 4gb
    command: postgres -N 300 -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all -c wal_keep_size=512MB -c work_mem=8MB -c temp_buffers=16MB -c shared_buffers=4GB -c track_activity_query_size=16384
    restart: always
    volumes:
      - swarmica_postgres_data:/var/lib/postgresql/data:Z
      - swarmica_postgres_data_backups:/backups:z
      - ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf
    env_file:
      - .env
    ports:
      - "5432:5432"

2. Перезагрузите приложение docker compose down && docker compose up -d

Причина

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

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

Для этого необходимо подключить и настроить сервис helpcenter.

Если вы пользуетесь облачной SaaS версией, обратитесь к нам в поддержку, чтобы подключить этот сервис.

Если вы пользуетесь коробочным решением on-premise, то эта статья предоставит инструкции для самостоятельной настройки.

Стандартная установка (начиная с v5.2.0)

Если у вас стандартная конфигурация, в которой Swarmica обслуживает и HTTP и HTTPS соединения, то проделайте следующие шаги:

1 - Установите версию Swarmica v5.2.x или выше

2 - Установите следующие значения переменных в /root/swarmica/.env:

# Версия helpcenter, соответствует версии Swarmica, например для v5.2.0:
SW_HELPCENTER_VERSION=v5.2.0

# Адрес API для хелпцентра, должен совпадать с BASE_FRONTEND_URL, 
# Если BASE_FRONTEND_URL=https://my.swarmica.tld
NEXT_PUBLIC_HELPCENTER_SERVER_API_URL=https://my.swarmica.tld

3 - Добавьте конфигурацию контейнера helpcenter в docker-compose.yml:

  helpcenter:
    image: reg.gl.swd.im/swarmica/helpcenter:${SW_HELPCENTER_VERSION}
    restart: always
    depends_on:
      - django
    env_file:
      - .env
    volumes:
      - .env:/app/.env
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.helpcenter.loadbalancer.server.port=4000"
      - "traefik.http.routers.helpcenter-router.rule=Host(`${SW_HOSTNAME}`) && (PathPrefix(`/category`)||PathRegexp(`^/article/.*$`)||PathPrefix(`/_next`)||PathPrefix(`/help`)||Path(`/robots/sitemap.xml`))"
      - "traefik.http.routers.helpcenter-router.priority=11"
      - "traefik.http.routers.helpcenter-router.entrypoints=web-secure"
      - "traefik.http.routers.helpcenter-router.middlewares=secure-headers,compression"
      - "traefik.http.routers.helpcenter-router.service=helpcenter"
      - "traefik.http.routers.helpcenter-router.tls.certresolver=letsencrypt"

4 - Стяните образы и перезагрузите приложение:

docker compose pull
docker compose down
docker compose up -d

Установка за L7-балансировщиком (начиная с v5.3.0)

Если у вас Swarmica установлена за внешним балансировщиком, который терминирует HTTPS соединение, а Swarmica обслуживает только HTTP, то проделайте следующие шаги:

1 -Установите версию Swarmica v5.3.x или выше:

2 - Установите следующие значения переменных в /root/swarmica/.env:

# Версия helpcenter, соответствует версии Swarmica, например для v5.3.0:
SW_HELPCENTER_VERSION=v5.3.0

# Адрес API для хелпцентра должен быть установлен в http://django:5000
NEXT_PUBLIC_HELPCENTER_SERVER_API_URL=http://django:5000

# Адрес django должен быть добавлен в DJANGO_ALLOWED_HOSTS:
DJANGO_ALLOWED_HOSTS=django,my.swarmica.tld

# Должен быть включен флаг INSECURE_HTTP_SERVER=1
INSECURE_HTTP_SERVER=1

3 - Добавьте конфигурацию контейнера helpcenter в docker-compose.yml:

  helpcenter:
    image: reg.gl.swd.im/swarmica/helpcenter:${SW_HELPCENTER_VERSION}
    restart: always
    depends_on:
      - django
    env_file:
      - .env
    volumes:
      - .env:/app/.env
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.helpcenter.loadbalancer.server.port=4000"
      - "traefik.http.routers.helpcenter-router.rule=Host(`${SW_HOSTNAME}`) && (PathPrefix(`/category`)||PathRegexp(`^/article/.*$`)||PathPrefix(`/_next`)||PathPrefix(`/help`)||Path(`/robots/sitemap.xml`)||Path(`/llms.txt`))"
      - "traefik.http.routers.helpcenter-router.priority=11"
      - "traefik.http.routers.helpcenter-router.entrypoints=web"
      - "traefik.http.routers.helpcenter-router.middlewares=compression"
      - "traefik.http.routers.helpcenter-router.service=helpcenter"

4 - Стяните образы и перезагрузите приложение:

docker compose pull
docker compose down
docker compose up -d

Подключите Beeline Облачная АТС (Beeline Cloud PBX) в Swarmica, чтобы регистрировать входящие звонки в виде заявок и сохранять записи звонков в комментарии по их завершению.

Swarmica поддерживает два варианта интеграции – с помощью API токена или через партнерскую CRM-интеграцию

Интеграция Beeline Cloud PBX и Swarmica через Интеграцию CRM (Рекомендуемый вариант)

Вам потребуется подписка на Облачную АТС Beeline, на которой дополнительно подключены дополнительные опции Интеграция CRM - Swarmica и Записи звонков.

Чтобы подключить Интеграцию CRM, выполните следующие действия:

1. Зайдите в личный кабинет АТС Билайн > Услуги
2. Перейдите во вкладку Интеграции
3. Найдите пункт CRM - Интеграции партнеров - Swarmica, подключите его и создайте новый токен

Чтобы подключить Записи звонков, выполните следующие действия:

1. Зайдите в личный кабинет АТС Билайн > Услуги
2. Перейдите во вкладку Контроль сотрудников
3. Найдите пункт Записи звонков и включите его

Интеграция Beeline Cloud PBX и Swarmica через Интеграцию по API

Вам потребуется подписка на Облачную АТС Beeline, на которой дополнительно подключены дополнительные опции Интеграция по API и Записи звонков.

Чтобы подключить Интеграцию по API, выполните следующие действия:

1. Зайдите в личный кабинет АТС Билайн > Услуги
2. Перейдите во вкладку Интеграции
3. Найдите пункт Интеграция по API, включите его и создайте новый токен

Чтобы подключить Записи звонков, выполните следующие действия:

1. Зайдите в личный кабинет АТС Билайн > Услуги
2. Перейдите во вкладку Контроль сотрудников
3. Найдите пункт Записи звонков и включите его

Подготовка на стороне Swarmica

Под учетной записью Администратора системы зайдите в Настройки > Каналы > Билайн АТС и создайте новый канал.

Укажите настройки:

• Название: ЛЮБОЕ_НАЗВАНИЕ, НАПРИМЕР ВАШ НОМЕР
• API URL:
  https://cloudpbx.beeline.ru/integration/core/api/ - если интеграция через партнерский CRM-модуль
  https://cloudpbx.beeline.ru/apis/portal/ - если интеграция по API
• Токен: ТОКЕН из пункта Интеграция CRM или Интеграция по API выше
• Тип интеграции: CRM или API токен, в зависимости от того, какой вариант вы выбрали

Когда вы готовы принимать звонки в виде тикетов, переключите ползунок "Включен" в состояние "Включено" и сохраните изменения.

Убедиться, что в /root/swarmica/.envв FEATURES включены все следующие флаги:

grep FEATURES .env 
FEATURES=ai,__ai_create_draft,__ai_assistant,__ai_mdxeditor,__ai_ticket_classifier,csat_anytime,qa,telegram,chats,wfm,sensitive_data,whatsapp_green,widgets,reporting

В /root/swarmica/.env проверить, что включены следующие метода авторизации:

grep AUTH_PROVIDERS .env 
AUTH_PROVIDERS=email,anonymous,code

Чтобы подключить Whatsapp канал, необходимо сначала подключить соответствующий контейнер по инструкции, затем подключить Whatsapp через Green API по инструкции.

docker compose down && docker compose up -d

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

1. Перейдите в Настройки > API & интеграции
2. Нажмите Создать новый
3. Введите имя и скопируйте код токена.

Симптомы

При попытке настроить IMAP с шифрованием SSL не удается проверить подключение.
Отображается ошибка:

[SSL: SSLV3_ALERT_HANDSHAKE FAILURE sslv3 alert handshake failure (ssl.c:1017)

Решение

Разрешите подключение по менее надежным шифрам SSL:

1. Отредактируйте файл /root/swarmica/.env, чтобы он содержал вот такие строки:

   IMAP_SSL_CUSTOM_CONTEXT=true
   IMAP_SSL_CUSTOM_CIFERS=DEFAULT
   

2. Перезагрузите Swarmica:

   docker compose down
   docker compose up -d
   

Если на сервере IMAP используются самоподписанные сертификаты, тогда необходимо дополнительно выполнить инструкции из статьи #650: Получение почты по IMAP с самоподписанными сертификатами

Причина

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

Симптомы

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

Решение

1. Да, в разделе Участники в созданном тикете есть поле СС. Нажимая туда вы можете писать email нужного пользователя для добавления. Если пользователь уже есть в системе, то появится его email и он сразу же добавится в копию. Если пользователя нет в системе, то у вас появится возможность его Пригласить. Он будет добавлен в копию, но получит доступ только после регистрации (о чем получит уведомление от тикетной системы)
2. Также вы можете разрешить клиентам добавлять в СС других пользователей при создании тикета по емайл. При этом вы можете ограничить их круг тем же самым доменом, что и у создателя заявки или же сделать их круг неопределенным (не рекомендуется с точки зрения защиты от спама)
   

Симптомы

Как установить собственные SSL сертификаты вместо Let's Encrypt?

Решение

Подготовьте файлы сертификатов

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

Обычно архив содержит несколько файлов:

yourdomain.tld.crt - сертификат для вашего адреса

yourdomain.tld.key - ключ, который использовался для создания сертификата

Скопируйте файлы yourdomain.tld.crt и yourdomain.tld.key в папку certs.

Установка сертификатов

1. Отредактируйте файл /root/swarmica/traefik.yml, чтобы получилось так (заменяя строки yourdomain.tld.* на названия ваших файлов):

   tls:
     certificates:
       - certFile: "/etc/traefik/certs/yourdomain.tld.crt"
         keyFile: "/etc/traefik/certs/yourdomain.tld.key"
         stores:
           - default
     stores:
       default:
         defaultCertificate:
           certFile: "/etc/traefik/certs/yourdomain.tld.crt"
           keyFile: "/etc/traefik/certs/yourdomain.tld.key"
     options:
       default:
         minVersion: VersionTLS12
         cipherSuites:
          # Recommended ciphers for TLSv1.2
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
          # Recommended ciphers for TLSv1.3
          - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
       tlsv13only:
         minVersion: VersionTLS13
   

2. Создайте резервную копию файла /root/swarmica/docker-compose.yml:

   cp /root/swarmica/docker-compose.yml{,.backup}
   

3. Отредактируйте файл /root/swarmica/docker-compose.yml для сервиса traefik:

     traefik:
       image: traefik:latest
       restart: always
       depends_on:
         - django
       volumes:
         - ./certs:/etc/traefik/certs:ro
         - ./traefik.yml:/etc/traefik/dynamic.yml:ro
         - traefik_data:/letsencrypt:z
         - /var/run/docker.sock:/var/run/docker.sock:ro
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--providers.file=true"
         - "--providers.file.filename=/etc/traefik/dynamic.yml"
         - "--log.level=INFO"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.web.http.redirections.entrypoint.to=web-secure"
         - "--entrypoints.web-secure.address=:443"
         - "--api.dashboard=false"
       ports:
         - "0.0.0.0:80:80"
         - "0.0.0.0:443:443"
   

4. Замените строчки в /root/swarmica/docker-compose.yml где содержится tls.certresolver=letsencrypt, чтобы они заканчивались на tls.options=default
5. Перезагрузите Swarmica:

   docker compose down
   docker compose up -d
   

Симптомы

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

ERROR 2025-05-06 18:08:15,541 collect_imap_emails 533 140523956472704 Couldn't find host for EMAIL channel (UID) NAME, reason: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1017)

Решение

Для самоподписанных (self-signed) сертификатов подключите корневые сертификаты, использованные при генерации этих сертификатов:

1. Примонтируйте папку с сертификатами и ключами в /etc/ssl контейнера cron, добавив строчку в volumes в docker-compose.yml:

     cron:
       <<: *django
       restart: always
       depends_on:
         - postgres
         - redis
       command: /start-cron
       volumes:
         - /path/to/ssl/folder/custom-certs.crt:/etc/ssl/custom-certs.crt:ro
         - ./.env:/etc/environment:ro
         - swarmica_ai_assistant:/swarmica/swarmica/ai_assistant/articles/:z
         - swarmica_cron_d:/etc/cron.d/:z
         - swarmica_ugc:/swarmica/swarmica/attachments:z
         - swarmica_runtime:/swarmica/swarmica/runtime_scripts/:z
       labels:
         - "traefik.enable=false"
   

2. Аналогично сделайте для django контейнера:

     django: &django
       image: reg.gl.swd.im/swarmica/backend:${SW_BACKEND_VERSION}
       depends_on:
         - postgres
         - redis
       volumes:
         - /path/to/ssl/folder/custom-certs.crt:/etc/ssl/custom-certs.crt:ro
         - swarmica_ai_assistant:/swarmica/swarmica/ai_assistant/articles/:z
         - swarmica_static:/swarmica/swarmica/static:z
   ...
   

3. В /root/swarmica/.env добавьте строчки:

   IMAP_SSL_CUSTOM_CONTEXT=true
   IMAP_SSL_CUSTOM_LOCATIONS="/etc/ssl/custom-certs.crt"
   

4. Перезагрузите Swarmica:

   docker compose down && docker compose up -d
   

Если необходимо так же включить менее защищенные шифры, необходимо сделать следующее:

1. Добавить в .env строчку:

   IMAP_SSL_CUSTOM_CIFERS=DEFAULT
   

2. Перезагрузить Swarmica:

   docker compose down && docker compose up -d
   

Причина

1. Сервер IMAP использует самоподписанный (self-signed) сертификат
2. Используется устаревший набор шифров (RSA) на сервере, которые отключены в Python 3.10 из соображений безопасности

Эти настройки необходимо задать в самом начале работы с системой Swarmica.

Перейдите в раздел "Настройки" в левом меню и выберите раздел "Настройки Swarmica".

Раздел содержит следующие настройки:

Языки интерфейса.

Язык по умолчанию - один язык на выбор, который будет использоваться в интерфейсе до тех пор, пока пользователь не изменит его в своём профиле.

Валюта

Email конфигурация - файл или SMTP. Режим файла используется, как правило, для тестирования и отладки. Для "боевой" конфигурации выбирайте SMTP.

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

Swarmica позволяет подключить прозрачную авторизацию приложения через шифр-пароль, полученный для заданного пользователя с помощью фиксированного алгоритма OTP (one-time-password, одноразовый пароль)

Алгоритм авторизации

1. При успешной регистрации / авторизации в интегрируемом приложении, бэкенд приложения выполняет API вызов /api/auth/otp/code/request, передавая данные пользователя, для которого нужно создать код авторизации. Параметры вызова аналогичны API вызову Создать пользователя.
2. Swarmica находит существующего пользователя с такими данными или же создает новую учетную запись и отдает код авторизации и данные пользователя в ответе.
3. Фронтенд интегрируемого приложения отображает ссылку, которая должна вести на портал Swarmica:
   https://swarmica_address_tld/auth/otp/code/?data=...&errorUrl=...&redirectUrl=...
4. При переходе по ссылке, Swarmica:
   1. В случае успешной авторизации, либо перенаправляет пользователя на указанный redirectUrl, если данный параметр указан, или переводит на базовую страницу внутри Swarmica, соответствующую роли пользователя
   2. В случае ошибки, если указан параметр errorUrl, Swarmica перенаправляет пользователя туда, передав errorMessage в параметры ссылки. Если параметр не указан, то ошибка отображается на странице авторизации Swarmica.

Алгоритм формирования ссылки

Ссылка на фронтенде интегрируемого приложения должна состоять из:

• Адрес портала Swarmica (https://swarmica__address__tld)
• URI страницы авторизации через OTP code (/auth/otp/code)
• Параметры:
  • data - обязательный параметр, содержащий авторизационный шифр в URLEncoded виде
  • errorUrl - URLEncoded адрес, куда пользователя перенаправит в случае ошибки авторизации, необязательный параметр. Сообщение об ошибке будет передано в параметре errorMessage для данной ссылки

    Например, если errorUrl=https%3A%2F%2Fswarmica.ru, то в случае ошибки Request failed with status code 404 пользователь будет перенаправлен на адрес https://swarmica.ru?Request%20failed%20with%20status%20code%20404

  • redirectUrl - URLEncoded адрес, куда пользователя перенаправит в случае успешной авторизации, необязательный параметр

Алгоритм шифрования

Для корректной авторизиции пользователя необходимо зашифровать JSON данные с помощью фиксированного алгоритма шифрования:

{
  "email": "someuser@email.tld",
  "code": "user_auth_code",
  "timestamp": 1742907325
}

Для получения подробной инструкции обратитесь в поддержку Swarmica

Используемый стек:

• Backend - Python 3.13.x
• Frontend - JavaScript (React JS + Typescript)

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

** - только для варианта, когда резервное копирование осуществляется по инструкции из данной статьи.

Решение

Вам необходимо предоставить Swarmica следующую информацию

• Адрес вашего сервера ADFS. Пример adfs.example.com
• Идентификатор клиента для группы приложений Swarmica. Пример 51cf596b-ac85-4d45-988b-2689cc45281f
• Идентификатор проверяющей стороны. Обратите внимание, что если вы не изменили его вручную, он может совпадать с идентификатором клиента. Пример 51cf596b-ac85-4d45-988b-2689cc45281f
• Цепочку сертификатов CA Bundle для вашего сервера ADFS в формате Base-64 encoded X.509 .CER.

  Статьи, которые могут (т.к. авторы и площадки статей могут поменять контент, а также работу самого софта, то эти статьи носят только общий рекомендательный характер) помочь:
  https://techcommunity.microsoft.com/blog/coreinfrastructureandsecurityblog/adfs-deep-dive-onboarding-applications/257783
  https://support.ptc.com/help/identity_and_access_management/en/index.html#page/iam/ADFSAuthenticationExportADFSSigningCertificate.html

Цепочка сертификатов должна состоять из нескольких сертификатов и иметь вид:

-----BEGIN CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----BEGIN CERTIFICATE---—

Идентификатор клиента и идентификатор проверяющей стороны будут показаны в ходе следующего процесса настройки доступа oauth.

Шаг 1

На экране управления AD FS перейдите в AD FS > Группы приложений и нажмите Добавить группу приложений….

Шаг 2

1. Введите имя для группы приложений.
2. Выберите Веб-браузер, получающий доступ к веб-приложению.
3. Нажмите Далее.

Шаг 3

1. Запишите значение Идентификатор клиента.
2. Добавьте значение URI перенаправления, которое соответствует местоположению вашего экземпляра Swarmica.
3. Нажмите Далее.

Шаг 4

1. Выберите Разрешить всем.
2. Нажмите Далее.

Шаг 5

1. Запишите значение Идентификатора проверяющей стороны.
2. Нажмите Далее.

Шаг 6

Нажмите Закрыть. Приложение теперь зарегистрировано в ADFS.

Шаг 7

Щелкните правой кнопкой мыши по созданному приложению и выберите опцию Свойства.

Шаг 8

1. Выберите запись Веб-приложение.
2. Нажмите Изменить.

Шаг 9

1. Выберите вкладку Правила преобразования выпуска.
2. Нажмите кнопку Добавить правило.

Шаг 10

1. Выберите Отправить атрибуты LDAP как утверждения.
2. Нажмите Далее.

Шаг 11

1. Дайте правилу имя.
2. Выберите Active Directory в качестве хранилища атрибутов.
3. Настройте утверждения, как показано ниже.
4. Нажмите Готово.

Шаг 12

Нажмите Применить.

Шаг 13

Перезапустите сервер ADFS. Вы можете использовать консольную команду

Restart-Service adfssrv -Force

например

Описание

Данная статья описывает процедуру резервного копирования (бэкапа/backup) и восстановления (рестора/restore) приложения Swarmica, установленного в контуре заказчика (on-premise) с использованием стандартных функций базовой операционной системы.

В данной статье предлагаются минимальные инструкции для создания резервных копий для восстановления после сбоя или переноса данных на другой сервер без гарантии скорости восстановления (RTO) для всех данных на момент бэкапа.

Что необходимо сохранять:

• Файлы конфигурации, которые находятся в папке установки Swarmica (по умолчанию /root/swarmica)
• База данных (средствами Postgres)
• Пользовательские файлы (Docker Volumes)

Создание резервной копии (backup)

Файлы конфигурации

Сохраните содержимое папки /root/swarmica:

tar -cvjf sw-backup-configs.tbz /root/swarmica\
    /root/.docker/

База данных

Выполните команду pg_dump в контейнере swarmica-postgres:

cd /root/swarmica
source .env
docker exec -it --env-file .env swarmica-postgres pg_dump -Fc --clean -U$POSTGRES_USER $POSTGRES_DB -f /backups/db.`date +%Y%m%d%H%M%S`.sql

При необходимости, скопируйте файл с дампом на сервер (это может понадобиться, если вы планируете восстанавливать только базу данных на каком-то другом сервере, например, для тестирования):

docker cp swarmica-postgres:/backups/db.YOURDATE.sql ./

Пользовательские файлы

Пользовательские данные хранятся в Docker Volume с названиями:

• swarmica_ugc
• swarmica_runtime
• swarmica_cron_d
• swarmica_ai_assistant

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

tar -cvjf sw-backup-files.tbz \
    /var/lib/docker/volumes/swarmica_swarmica_postgres_data_backups/_data/ \
    /var/lib/docker/volumes/swarmica_swarmica_ugc/_data/ \
    /var/lib/docker/volumes/swarmica_swarmica_runtime/_data/ \
    /var/lib/docker/volumes/swarmica_ai_assistant/_data/

ВАЖНО! Убедитесь в наличии свободного места на диске, на котром вы создаете архив с резервной копией - там должно быть достаточно места, чтобы вместить все пользовательские данные.

• Команда для проверки свободного места df -h
• Команда для проверки размера пользовательских данных docker system df | grep Volumes

Восстановление резервной копии (restore)

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

apt-get update && \
apt-get install --no-install-recommends -y \
      curl \
      jq \
      host \
      python3 \
      docker.io \
      docker-compose-v2

dnf install -y \
      curl \
      jq \
      bzip2 \
      python3.12 \
      docker-ce \
      docker-compose

1. Скопируйте на целевой сервер и распакуйте файлы архивов, созданные на предыдущем шаге:

tar -xvjf sw-backup-files.tbz -C /
tar -xvjf sw-backup-configs.tbz -C /

2. Стяните образы контейнеров:

cd /root/swarmica
docker compose pull

Этот шаг можно пропустить, если вы восстанавливаете данные на том же сервере, где создавалась резервная копия

3. Поднимите контейнер с Postgres:

docker compose up -d postgres

4. Если вы восстанавливаете дамп базы на "чистой" инсталляции, то сначала скопируйте его в контейнер:

docker cp db.YOURDATE.sql swarmica-postgres:/backups/

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

5. Восстановите дамп:

cd /root/swarmica
source .env
docker exec -it --env-file .env swarmica-postgres pg_restore --if-exists --clean -U$POSTGRES_USER -d$POSTGRES_DB /backups/db.YOURDATE.sql

6. Поднимите остальные контейнеры:

docker compose up -d

7. Выполните завершающие процедуры:

docker exec --env-file .env -it swarmica-django-1 python manage.py post_start

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

Добавление соглашения

Для добавления нового соглашения перейдите в раздел Настройки - Управление соглашениями и нажмите в правом верхнем углу страницы:

Откроется окно для ввода названия соглашения:

Здесь можно ввести название - заголовок соглашения.

После ввода и сохранения названия открывается окно настройки соглашения. Приведём пример его заполнения:

Название - заголовок соглашения.

Краткое описание - текст, отображаемый на странице после первого залогинивания.

Вот как это выглядит на стороне пользователя:

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

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

Описание - текст соглашения. Если вы используете ссылку на соглашение в пункте "Краткое описание", поле "Описание" можно оставить пустым. Так выглядит страница соглашения без текста:

В верхней части поля "Описание" также доступны опции форматирования:

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

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

Активное - опция, которая активирует соглашение, включает его. Неактивные соглашения могут использоваться как черновики.

Для сохранения настроек нажмите в правом нижнем углу страницы.

Для отмены изменений нажмите в левом нижнем углу страницы.

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

Список соглашений

Список соглашений представлен в виде таблицы со следующими колонками.

Название - внутреннее название соглашения, невидимое для пользователей. По клику на название открывается страница редактирования соглашения.

Краткое описание - текст, отображаемый на странице регистрации.

Описание - превью текста соглашения.

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

Обязательное - включённая или отключённая опция обязательности соглашения. Пользователи смогут использовать систему только если подпишут обязательные соглашения.

Активное - признак активности соглашения. Неактивные соглашения не работают и не видны пользователям.

Удалить - опция удаления соглашения.

В процессе проверки качества сервиса проверяющие оценивают ответы сотрудников в различных заявках по заданным критериям. Критерии подразделяются на категории. Так выглядят критерии и категории на странице проверки качества сервиса:

По нажатию на критерий можно увидеть его описание:

Критерии и категории можно задать в настройках в разделе "Критерии качества сервиса":

Чтобы добавить новую категорию, перейдите на вкладку "Категории QA", введите название категории и нажмите "Добавить" справа от неё. Если категории уже есть, поле для добавления новой категории будет внизу списка категорий.

Названия существующих категорий можно редактировать, а ненужные категории - удалять. Для редактирования названия категории внесите необходимые изменения, и затем нажмите в конце строки с категорией. Для отмены изменений нажмите

Для удаления категории нажмите в конце строки.

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

Откроется окно добавления критерия.

Введите название и описание критерия. Описание критерия будет видно на странице проверки качества сервиса и на странице результатов проверки по нажатию на название критерия:

Вес - индекс значимости критерия. Из веса каждого критерия рассчитывается индекс качества сервиса в процентах. По умолчанию все существующие критерии имеют вес 1. Если у одного из критериев вес будет больше, его выполнение/невыполнение будет больше влиять на индекс качества, чем выполнение/невыполнение критериев, у которых вес меньше.

Категорию тоже нужно будет указать. Если в списке нет нужной вам категории, её можно будет добавить в разделе Настройки - Критерии качества сервиса, на вкладке Категории QA.

Для редактирования существующего критерия нажмите справа от него.

Для удаления критерия нажмите справа от него.

Симптомы

Поддерживает ли Swarmica SSO через OpenID?

Поддерживает ли Swarmica SSO через KeyCloak?

Решение

Да, SSO через OpenID Connect v1 в KeyCloak поддерживается.

Для этого нужно настроить Client в KeyCloak и дать данные доступа в поддержку Swarmica:

• REALM (например, master)
• URL (например, https://mykeycloak.company.tld )
• CLIENT_ID (например, swarmica_app)
• CLIENT_SECRET (тот, что будет сгенерирован автоматически)

Для настройки выполните следующие шаги:

1. Зайдите в административную панель KeyCloak, выберите Realm (и запомните его название - оно будет установлено поддержкой Swarmica в качестве REALM) > Clients > Create client
2. Задайте название для клиентского приложения Client ID (например, swarmica_app) по протоколу OpenID Connect:
3. На следующем экране включите Аутентификацию клиента:
   
4. На следующем экране задайте разрешенные адреса перенаправления, чтобы там был указан адрес вашего инстанса Swarmica. Если у вас есть затруднения с тем, какой адрес указать – обратитесь к нам в поддержку, мы поможем.
   Для случая, когда адрес вашего инстанса yourinstance.domain.tld настройки будут выглядеть вот так:
   
5. Сохраните изменения и в созданном клиентском приложении зайдите на вкладку Credentials, поставьте Client Authenticator в значение Client Id and Secret и скопируйте Client Secret:
   
6. Зайдите на сервер Swarmica по SSH и добавьте в переменную /root/swarmica/.env следующие параметры:
   • Добавить в AUTH_PROVIDERS пункт oidc (в нижнем регистре)
   • OIDC_DEFAULT_ROLE - роль пользователя, если не ставить - будет CUSTOMER
   • OIDC_REALM_NAME - название REALM в Keycloak
   • OIDC_SERVER_URL - сервер keycloak, без слеша на конце
   • OIDC_CLIENT_ID - id клиента внутри REALM на Keycloak, задаётся при создании клиента
   • OIDC_CLIENT_SECRET - секрет клиента, выдаётся на вкладке Credentials внутри клиента Keycloak
   • OIDC_TIMEOUT - сколько ждать ответа от сервера, по-умолчанию 30 сек
7. Сделайте рестарт системы:

docker compose up -d

Вопрос

С какими CRM-системами можно интегрировать Swarmica?

Ответ

Swarmica поддерживает интеграцию с CRM системами с открытым API или через выгрузку/загрузку csv файлов. Примеры CRM систем:

• Microsoft Dynamics CRM
• Битрикс24
• AmoCR

Если вам требуется помощь для интеграции с вашей CRM системой, обратитесь к аккаунт менеджеру.

Вопрос

Поддерживает ли Swarmica интеграцию с решениями Single-sign-on (SSO) ?

Ответ

Да, из коробки поддерживаются:

1. ADFS
2. OpenID/Keycloak

Фильтры это представление вида или списка различных сущностей в соответствующих разделах. Фильтры могут быть сконфигурированы для:

• Заявок
• Чатов
• Статей
• Компаний
• Пользователей
• Лицензионных ключей
• Активов

Фильтры бывают системными, то есть настроенные администраторами системы для определенных ролей, или персональным. Подробнее про настройку персональных фильтров.

В этой статье рассмотрим создание системных фильтров.

Настройка фильтров

Фильтры настраиваются глобально для всех, но могут быть разнесены по ролям. Например можно настроить один список фильтром для Администраторов, другой для Менеджеров и третий для Агентов.

1. Перейдите в раздел Настройки - Управление фильтрами
   
2. Выберите закладку в соответствии с тем для какой сущности вы хотите настроить фильтры. В нашем примере перейдем на вкладку Заявки:
   
3. Нажмите Создать фильтр или зайдите в уже созданный.
4. Введите или поменяйте название название и описание фильтра.
5. Настройте Область видимости для ролей, которым вы хотите сделать доступным данный фильтр.
6. Выберете чек-бокс По умолчанию, если хотите, чтобы данный фильтр открывался по умолчанию при переходе в соответствующий раздел.
7. Перетащите нужные поля из колонки Доступные поля в колонку Выбранные поля.
8. Отсортируйте нужный порядок полей - в таком порядке будут показаны колонки.
9. Выберите дополнительные условия отображения ( статусы, продукты, пользователи, группы).
10. Выберите по какому полю будет отсортирован список по умолчанию.
11. Нажмите Сохранить.Сохраненный фильтр становится доступным для выбора пользователем с ролью, для которой фильтры был сконфигурен, в соответствующем разделе. Например фильтр для сущности "Заявки" будет доступен в разделе Заявки основного меню навигации.

Описание полей в фильтре

В качестве колонок, в фильтре можно добавлять как системные поля, так и кастомные. Кастомные поля - те, что создаются администратором Свормики, подробнее про них в статье.

Системные же поля заложены в Свормике и не меняются. Рассмотрим их подробнее.

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

Также по навыкам можно настроить дополнительную фильтрацию и отчеты.

Настройка навыков

Доступна для роли Администратор.

1. Перейдите в Настройки - Управление навыками.
2. Нажмите кнопку Создать.
3. Введите название, описание и цвет тэга. Нажмите Сохранить.

Добавление навыка в профиль агента

1. Перейдите в Настройки - Управление сотрудника - выберите нужного.
2. В разделе Навыки нажмите на кнопку
3. Добавьте нужные навыки в профиль агента.

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

1. Зайдите в тикет.
2. В колонке с метаданными справа перейдите в блок Навыки.
3. Нажмите для выбора навыков.

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

Вопрос

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

Ответ

1. Перейдите в Настройки > Управление брендом
2. Создайте бренд или используйте существующий.
3. Добавьте код счетчика в поле Код HTML head секции Стили публичного портала базы знаний

Swarmica предоставляет гибкий механизм брендирования, с помощью которого вы можете стилизовать свою систему с помощью css/html и сделать собственные настройки вида для:

• Внешнего портала базы знаний для клиентов.
• Внутреннего вида хелпдеск системы для агентов.
• Стили email писем.

Создание бренда

1. Перейдите в Настройки - Управление брендами
2. Нажмите Создать новый в правом верхнем углу.
3. Введите название и отметьте используемость по умолчанию. Нажмите Сохранить.

Управление брендом

Все поля внутри бренда опциональные. Они делятся на несколько субкатегорий.

Анонимность сотрудников поддержки

Используется если вы хотите, чтобы вместо реального имени агента в тикете, клиенты видели "Псевдоним" (общее название службы поддержки).

• Включить анонимность - чек-бокс для включения/выключения псевдонима.
• Псевдоним - замена имени агентов. Например
  Служба поддержки Swarmica.

Вид веб-страниц

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

• Заголовок HTML -  заголовок HTML, который будет указываться в названии вкладки браузера.
• Стили для темы - цвета, шрифты, стили и т.д, которые можно установить внутри тикетной системы.
  Пример.
• Логотип - логотип для страницы входа.
• Спиннер - индикатор прогресса загрузки в формате GIF.
• Фавикон - иконка для вкладки браузера в формате .ico или .png.

Стили email

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

• Стили CSS - код CSS, который будет вставлен в HTML код почтовых уведомлений.
• Шапка - код HTML, который будет встроен в верхнюю часть почтового уведомления.
• Подвал - код HTMl, который будет вставлен в нижнюю часть почтового уведомления.
• Автоответ - текст автоматического ответа в HTML формате, который система высылает пользователям, пытающимся открыть заявку по почте, если это запрещено настройками системы.

Стили публичного портала базы знаний

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

• Код HTML head - код HTML, который будет вставлен в секцию head на публичном портале, для того, чтобы отобразить метаданные, загрузить дополнительные стили, шрифты и т.д.
• Шапка - код HTML, который будет вставлен в верхнюю часть страницы публичного портала базы знаний.
• Подвал - код HTML, который будет вставлен в верхнюю часть страницы публичного портала базы знаний.

Вопрос

Я хочу кастомизировать тему в Swarmica. Как это сделать?

Ответ

Вам нужно пойти в Настройки > Управление брендом > Название бренда и вставить CSS код с нужными параметрами в поле для кастомизации темы. Ниже приведен пример такого скрипта:

.btn-primary {
    background-color: #F17216;
    color: #ffffff;
    border-color: #F17216;
}

.btn-primary:hover, .btn-primary:focus {
    background-color: #14aa14;
    color: #f2f2f2;
    border-color: #14aa14;
}

.btn-primary:active {
    background-color: #107c22 !important;
    color: #dbdbdb !important;
    border-color: #107c22 !important;
}

.btn-primary:disabled{
 background-color: #c9c9c9;
    color: #ffffff;
    border-color: #c9c9c9;
}

.btn-outline-primary {
    background-color: #F17216;
    color: #ffffff;
    border-color: #F17216;
}

.btn-outline-primary:hover, .btn-outline-primary:focus {
    background-color: #14aa14;
    color: #f2f2f2;
    border-color: #14aa14;
}

.btn-outline-primary:active {
    background-color: #107c22 !important;
    color: #dbdbdb !important;
    border-color: #107c22 !important;
}

.btn-outline-primary:disabled{
 background-color: #c9c9c9;
    color: #ffffff;
    border-color: #c9c9c9;
}

.hex-name{
font-style: italic;
}

a.sidebar-item.active .sidebar-item-icon i{
color: #F17216;
}

a.sidebar-item:hover .sidebar-item-icon i{
color: #F17216;
}

a.sidebar-item:hover, a.sidebar-item.active{
border-left-color: #F17216;
}

a.sidebar-item:hover{
background-color: #ffba18;
}

a{
color: #F17216;
}

.box-wrapper{
background-color: #eaffed;
}

[data-bs-theme=dark] .box-wrapper{
background-color: #265424;
}


html:has([data-bs-theme=light]), body:has([data-bs-theme=light]){
    background-color: #ededf2;
}

html:has([data-bs-theme=dark]), body:has([data-bs-theme=dark]){
    background-color: #3f1c03;
}

.sidebar{
background-color: #fce4d4 !important;
}

[data-bs-theme=dark] .sidebar{
background-color: #3f1e06 !important;
}

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

Это удобно, для вывешивания предупреждений, оповещений о каких-то плановых работах, продуктовых анонсов и так далее.

Для того, чтобы создать оповещение:

1. Перейдите в Настройки > Управление оповещениями
2. Нажмите кнопку Создать в правом верхнем углу.
3. Введите название и текст оповещения. Нажмите Сохранить.
4. Выберите один из вариантов оповещения. В зависимости от выбора блок оповещения будет окрашен в соответствующий цвет для привлечения внимания.
5. Выберите область видимости: Клиенты, Сотрудники или Все. Вы можете видеть предпросмотр оповещения справа в зависимости от выбранных параметров.
6. Нажмите чек-бокс Опубликована для того, чтобы сделать оповещение активным.
7. Нажмите Сохранить.

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

Разделы будут появляться по адресу https://support.yourdomain.tld/help по мере публикации в них новых статей.

Для создания категорий базы знаний:

1. Перейдите в Настройки > Управление разделами базы знаний
2. Нажмите Создать в правом верхнем углу.
3. Введите название раздела и нажмите Сохранить.
4. Отметьте чек-бокс "Публичный", чтобы раздел стал видимым для неавторизованных пользователей.
5. В правой части экрана нажмите на изображение, чтобы добавить и загрузить собственное изображение, которое будет отображаться для данного раздела. Нажмите Сохранить.

В дашбордах и скорекардах Swarmica содержатся различные метрики, у которых есть целевые значения, которые могут определяться либо процессами и продуктом компании, либо рекомендоваться методологией KCS. В последнем случае в большинстве случаев рекомендуется использовать параметры по умолчанию. Только опытным KCS администраторам имеет смысл изменять и подстраивать эти цели для более тонкой настройки.

Целевые значения рекомендованные KCS

• TC / Производительность - ожидаемое увеличение производительности всей команды. Измеряется как процентная разница между текущим общим уровнем производительности и базовым уровнем (на дату старта внедрения KCS).
• LR /Процент связанности - отношение тикетов со связанными статьями ко всему объему тикетов.
• LAI / Точность связанности - качественная оценка связки тикет-статья, которая оценивает релевантность, отсутствие дубликатов, полноту информации и контекста. Оценивается через модуль контроля качества.
• LAI Sample Size / Точность связанности: целевой размер выборки - процент тикетов, в которых есть связь со статьей, обработанных за прошедшую неделю.
• KVN / Отношение заявок с известными проблемами к заявкам с новыми проблемами - оценивается как отношение тикетов, где привязывалась существующая статья к тем тикетам, из которых создавались новые статьи через KCS виджет.
• AQI / Качество контента - индекс качества статей в соответствии с контент-стандартом. Оценивается через модуль контроля качества для опубликованных статей.
• AQI Sample size / Качество контента: целевой размер выборки - процент от количества статей опубликованных за прошедшую неделю.
• VD / Упреждение заявок - процент сессий на форме заведения тикета, где клиент перешел по ссылке на предложенную статью, и либо нажал кнопку "Помогло", либо не заводил тикет в течении часа, по отношению ко всем сессиям с формы заведения тикета.
• IR / Улучшение продукта: доля устраненных заявок - для расчета количества устраненных заявок связанных с первопричиной берется максимальный (пиковый) объем заявок привязанных к статье ( при этом учитываются только те статьи в привязанных тикетах, которых есть связь с задачей в R&D), за последние 12 месяцев и вычитается объем привязанных заявок за текущий месяц. Финальное значение показателя берется по всем статьям, где зафиксировано уменьшение повторного использования статьи относительно максимальных значений. Иначе говоря "Доля устраненных заявок" показывает на какой процент удалось уменьшить объем входящих заявок в службу поддержки за счет улучшения продукта.
• CS / Экономия затрат - показывает разницу между актуальными затратами за последние 12 месяцев и потенциальными затратами, которые рассчитаны, как экстраполяция тренда затрат на поддержку на момент запуска внедрения KCS, без учета оптимизации процессов и уменьшения объема входящих заявок за счет их упреждения с помощью эффективной работы базы знаний.

Целевые значения, зависящие от поддерживаемого продукта

• REUSE / Пороговое значение заявок, связанных с черновиком - один из ключевых параметров KCS. При достижении порогового значения (количества тикетов привязанных к одному черновику), этот черновик автоматически переводится в статус Непроверенная и отправляется на проверку к агентам с ролью KCS Contributor. Подробнее о цикле проверки и публикации читайте здесь.
• FCR / Процент заявок, решенных первым касанием - процент тикетов, где количество ответов агента не больше двух при отсутствии переоткрытия тикета.
• CSAT / Удовлетворенность клиентов - процентное значение оценки обратной связи на базе тикетов с заполненной оценкой. По умолчанию используется 5-бальная система. Процент высчитывается как среднее арифметическое всех полученных оценок отнесенное к пяти и умноженное на 100%.
• TFP / Время до публикации - время от создания до публикации статьи. Идеальная цель по KCS это 0. На практике же более реальные значения это 24 часа.

Настройка SLA политик доступна в меню Настройки - Управление политиками SLA.

Swarmica предлагает гибкую настройку SLA политик c 3-мя разными счетчиками для времени решения и времени ответа.

Время решения

1. Полное время решения - календарное время от момента создания тикета до момента предоставления решения.
2. Время решения без учета нахождения тикета у клиента - показывает сколько времени прошло с момента создания заявки до ее решения, исключая время, которое заявка провела в статусе ожидания ответа от клиента.
3. Время решения в поддержке - показывает время с момента создания заявки и до момента решения, исключая время, которое заявка провела в статусе ожидания ответа клиента или на удержании. Обычно используется, чтобы исключить время Ожидание, когда, например, ожидается багфикс от разработки.

Время ответа

1. Время первого ответа - от создания тикета до первого ответа со стороны поддержки.
2. Время ответа поддержки - показывает сколько времени прошло с момента получения корреспонденции от клиента до ответа поддержки, за вычетом времени, проведенного в статусе Решение предоставлено.
3. Время между ответами - показывает сколько времени проходит между ответами поддержки, получаемыми клиентом, за вычетом времени, проведенного в статусе Решение предоставлено. В метрику также входит время первого ответа поддержки на новую заявку.

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

Создание SLA политики

1. Перейдите в Настройки - Управление SLA политиками - нажмите Создать новую, введите название, описание и отметьте использовать ли эту политику по умолчанию.
2. Заполните только те, счетчики, которые вы хотите учитывать в формате ДД ЧЧ:ММ:CC для требуемых приоритетов. Незаполненные счетчики не будут отображаться в тикете и учитываться в скорекарде.
3. По умолчанию SLA счетчики считаются 24/7. Отметьте чек-боксами те приоритеты, для которых вы хотите, считать SLA только в рабочее время. При этом будет учитываться расписание по умолчанию.
4. Нажмите Сохранить.

Назначение SLA политики

SLA политика может назначаться на различные сущности.

Когда заводится тикет на него назначается SLA политика по следующей логике:

1. Если есть лицензионный ключ и на нем есть политика SLA - то назначается она.
2. Иначе, если есть политика SLA на компании, от которой завели тикет, то назначается она.
3. Иначе, если есть дефолтная политика SLA, то назначается она.

Далее, когда считаются счетчики, смотрится приоритет тикета, и настройки целей СЛА по нему.

Если нужно считать SLA только в рабочее время (то есть, например, для Стандартной политики мы не хотим считать 24/7, а хотим считать только пн-пт с 8 до 17. Тогда тикет, заведенный в пятницу в 16:59 и отвеченный где-то в субботу будет иметь FRT = 1 минуте), то ставится чек-бокс Только рабочее время.

Назначение на компанию

1. Перейдите в Клиенты - Компании - Название компании.
2. Выберите SLA политику в поле Пакет SLA.

Назначение на ключ

1. Перейдите в Клиенты - Лицензионные ключи - Ключ.
2. Выберите SLA политику в поле Пакет SLA.
3. Выставьте дату Истечения SLA.

Алгоритм учета расписания

• Сначала смотрится, а нет ли у пользователя, создавшего тикет расписания (например есть особо важный клиент Иван Иванович в Магадане, и он спрашивает SLA строго по магаданскому времени) - если есть, берется именно это расписание
• Если нет, то смотрим на компанию - например в контракте с компанией X прописано, что SLA считаются только по московскому времени с 10 до 19 пн-пт.
• Если нет, то смотрим в расписание группы, в которую попал тикет (т.к. в группе находятся и агенты, то это есть расписание команды саппорта)
• Если нет, то смотрим в расписание "по умолчанию"

И уже тогда "выкусывается" нерабочее время по выбранному расписанию.

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

1. Групп агентов, которые работают в разных часовых поясах.
2. Клиентов, контракт по выполнению SLA с которыми должен учитывать их временную зону.
3. Внутри SLA политики в зависимости от приоритета заявки.

При создании заявки, к ней прикрепляется расписание по следующей логике:

• Расписание рабочих часов, привязанных к пользователю, от которого поступила заявка
• Если такого нет, то расписание рабочих часов организации пользователя, от которого поступила заявка
• Если такого нет, то расписание рабочих часов группы, куда направлена заявка
• Если такого нет, то расписание, которое указано "по умолчанию"

Далее, если в политике SLA указан подсчет "только в рабочие часы", для расчета применяется выбранное по вышеописанному алгоритму расписание

Для настройки расписания:

1. Перейдите в Настройки > Управление расписаниями.
2. Нажмите Создать новое и введите название расписания. Нажмите Сохранить. Откроется окно конфигурации.

Конфигурация расписания

1. Выберите часовой пояс по которому будет учитываться рабочее время. По умолчанию UTC.
2. Отметьте должно ли это расписание использоваться по умолчанию.
3. Для круглосуточного расписания отметьте чек-бокс 24/7. При выборе круглосуточной работы окно заполнения времени и дней работы сворачивается, но остается возможность добавления выходных и праздничных дней.
4. Если чек-бокс 24/7 не выбран, то доступно заполнение рабочих дней и часов. Заполните только рабочие дни.
5. Для выходных дней (например суббота, воскресенье) оставьте дефолтное время 00:00.
6. Для добавления праздников нажмите Добавить выходной в правом верхнем углу. Заполните даты и время праздничных дней.
7. Нажмите Сохранить.

Назначение расписания

• На группу: перейдите в Настройки > Управление группами > Имя группы.
• На компанию: перейдите в Клиенты > Компании > Имя компании.
• На пользователя: перейдите в Клиенты > Пользователи > Имя пользователя.

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

Для ее конфигурации:

1. Перейдите в Настройки > Настройки формы заведения заявок
2. Нажмите Создать.
3. Введите название и отметьте нужно ли использовать эту форму по умолчанию. Нажмите Сохранить.

После создания вы попадаете в окно конфигурации формы.

Помимо названия и переключателя формы по умолчанию, вам доступна настройка стандартных полей:

• Продукт
• Версия
• Редакция
• Платформа

У этих полей есть два типа переключателей:

• Активное - добавляет/убирает поле на форме заведения тикета.
• Обязательное - включает/выключает обязательность его заполнения клиентом при заведении заявки.

Помимо стандартных атрибутов можно добавлять и дополнительные (кастомные) поля, которые нужно предварительно создать и выставить им зону видимости Клиенты (Редактирование). Тогда такие поля становятся доступными для добавления в форму заведения заявок в нижней секции "Дополнительные атрибуты".

В Swarmica предусмотрено создание кастомных полей разного типа в Настройках - Кастомные поля, которые могут привязываться к следующим сущностям:

• Заявки (тикеты)
• Статьи
• Компании
• Пользователи
• Ключи
• Активы

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

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

Откроется экран редактирования поля:

1. Тип - выбранный тип поля. Его нельзя сменить после создания.
2. Имя - задайте или смените название поля. Название нужно прописать для всех включенных локалей.
3. Значение по умолчанию - позволяет предопределить значение в поле. Например, если тип Чекбокс, то можно значение чекбокса по умолчанию сделать "включен".
4. Доступно для просмотра - выберите роли, которые смогу видеть это поле.
5. Доступно для редактирования - выберите роли, которые смогут не только видеть, но и редактировать поле.
6. Применим к - выберите одну или несколько сущностей, которым будет доступно это поле.
7. Обязателен для - выберите сущности, для которых это поле является обязательным.

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

8. Отображение - превью поля как оно будет выглядеть для каждой из ролей. Например, на скриншоте выше видно, что клиенты и администраторы клиента могут видеть поле, но не могут его редактировать.
9. Сохранить - применить настройки поля.

В зависимости от контекста используемой тикетной системы, в качестве объекта поддержки может выступать какое-то конкретное ПО (Продукт), так и любы сервисы и услуги. Для выбора конкретного объекта поддержки пользователем нужно сконфигурировать список поддерживаемых Продуктов или же другое название это Сервисный каталог.

В Swarmica эта сущность называется Продукт, и доступна для конфигурирования в Настройки -> Управление продуктом.

Для создания нового продукта:

1. Перейдите в Настройки -> Управление продуктом.
2. Введите имя Продукта в обоих локалях.
3. Нажмите Добавить.

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

Дополнительные атрибуты продукта

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

• Версия - числовой и текстовый формат описания. Чек-бокс рядом с версией включает/выключает ее отображение для клиента на форме заведения тикета. Например устаревшие версии можно отключать, чтобы они не смущали клиентов и/или не раздували список.
• Редакция (Компоновка) - может использоваться для различных редакций или компонентов продукта.
• Платформа - как правило операционная система, но может быть использована и в более широком смысле. Платформы создаются отдельно на вкладке Платформы, и далее могут включаться/выключаться чекбоксами для каждого из продуктов.

Разграничение прав

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

Чтобы перейти к управлению прав пользователя нужно перейти в Клиенты -> Пользователи -> Имя пользователя.

Права:

• BLOCKED / Заблокирован - заблокированный пользователь, которые не имеет доступа в систему, но сохранен с целью учета статистики.
• CUSTOMER / Клиент - пользователь, который может видеть только тикеты, созданные им сами, а также публичные статьи.
• CUSTOMER ADMIN / Администратор клиента - пользователь, который помимо своих тикетов может также видеть тикеты, созданные другими пользователями, принадлежащими его компании.
• INTERNAL USER / Сотрудник - пользователь (сотрудник компании) с правами только на чтение, который может видеть все тикеты всех клиентов, писать комментарии, но не может менять статусы, поля, иметь статистику , включаться в workflow и т.д. Таких пользователей можно создавать бесплатно неограниченное количество.
• AGENT / Агент - сотрудник службы поддержки, который может отвечать в тикеты, редактировать их поля. Создавать, связывать и публиковать (в зависимости от KCS роли) статьи в базу знаний. Может видеть свою статистику в персональной карточке.
• MANAGER / Менеджер - пользователь, который может видеть статистику по всем агентам, а также все отчеты и основной дашбоард.
• ADMINISTRATOR / Администратор - пользователь, который может изменять настройки системы.

KCS роли

KCS роли доступны в Настройки -> Управление сотрудниками.

KCS роль влияет на возможности агентов при работе с базой знаний.

• Candidate / Кандидат - как правило новичок, на испытательном сроке. Может искать, создавать и связывать статьи с тикетами.
• Contributor / Опытный - может делать все то же, что и Кандидат, плюс проверять и исправлять статьи базы знаний.
• Publisher / Редактор - может публиковать и снимать с публикации статьи базы знаний.

См. более подробно Алгоритм проверки и публикации статей.

Создание группы

Для создания и управления группами требуются права Администратора.

1. Перейдите в Настройки - Управление группами.
2. В правом верхнем углу нажмите на кнопку Создать новую.
3. Введите название группы.
4. Если вы хотите исключить группу из расчет всех метрик (например это тестовая группа или не относящаяся к службе поддержи, или Спам), то выберите чек-бокс Исключить из расчета всех метрик.

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

5. Нажмите кнопку Сохранить.

Редактирование группы

После создания вы сразу попадаете в окно редактирования группы:

1. Имя - изменить название группы.
2. Внешний ID - системное поле, которое заполняется при миграции группы из другого хелпдеска. При создании группы оставьте его пустым.
3. Режим работы - можно привязать режим работы группы агентов к конкретному расписанию для учета SLA счетчиков только внутри этого расписания.
4. Исключить из расчета всех метрик - исключает все заявки в группе из любой аналитики.
5. Удалена - индикатор того, что группа удалена.
6. Сохранить изменения.
7. Добавить сотрудника - начните вводить его имя, выберете из предложенного списка нужного пользователя для добавления. Присутствие пользователей в конкретной группе позволяет разграничить работу с тикетами в нужной группе, а также группировать статистику по выбранным группам.