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

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

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

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

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

Закладки будут доступны вверху списка статей:

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

Справа от списка фильтров находится окно поиска статей по ключевым словам в заголовке:

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

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

#Номер статьи - присваивается автоматически.

Заголовок - название статьи. По клику на номер или на заголовок статьи можно перейти на страницу статьи для её просмотра и/или редактирования.

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

Автор - ответственный за статью. Может быть изменён на странице статьи.

Заявок (всего) - количество заявок, прикреплённых к статье. Список этих заявок можно увидеть в правой части страницы статьи.

В большинстве столбцов есть возможность сортировки иконкой рядом с названием столбца:

Можно сделать сортировку сразу по нескольким столбцам. Для этого нажмите на кнопку сортировки в первом интересующем вас столбце, затем нажмите Ctrl (на Windows) или Command (на MacOS) и, не отпуская, нажмите на кнопку сортировки на другом столбце. Первая сортировка останется основной, а внутри неё одинаковые показатели будут рассортированы второй сортировкой.

При применении фильтра "Все мои статьи" в список добавляются колонки "AQI" и "FCR":

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

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

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

В Swarmica согласно модели KCS предусмотрена расширенная работа со статьями, которые оказывают помощь клиентам и сотрудникам поддержки. Статьи могут быть как общедоступные (для клиентов и сотрудников), так и внутренние (только для сотрудников). Порядок работы со статьями выглядит так:

Опишем эти этапы подробнее.

Создание статьи и черновик

Если в заявке клиента встретился вопрос, решение которого пока нигде не описано, по его решению прямо в заявке создаётся статья с помощию ИИ Ассистента (1) или вручную по кнопке Создать новую (2):

Подробнее о создании статьи мы рассказали в отдельной статье.

Созданная статья поначалу имеет статус Черновик. Её не видно клиентам, но агенты могут находить её в поиске и привязывать к новым заявкам. На этом же этапе агенты могут дополнять её новыми сведениями, получаемыми в процессе решения других заявок.

• Агент с KCS ролью Кандидат может создавать статьи только в статусе Черновик. При этом он может добавлять или не добавлять решение.
• Агент с KCS ролью Опытный может создавать статьи сразу в статусе Проверенная при условии наличия проверенного решения. Если решения нет или в нем нет уверенности, то статью следует создать в статусе Черновик.
• Агент с KCS ролью Редактор хоть и может создавать статьи сразу в статусе Опубликованная, но рекомендуется создавать также в статусе Проверенная (при наличии решения) для того, чтобы набрать пороговое значение привязанных тикетов.

Статус "Непроверенная"

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

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

• Задача этих агентов - проверить правильность предоставленного технического решения. Если решение правильное, то статья переводится в статус Проверенная.
• Если решение оказывается неполным или неправильным, то агент с ролью Опытный может поправить его на лету.
• Либо оставить в статусе Непроверенная и другие агенты при повторном использовании такой статьи должны обратить особое внимание на контекст проблемы и ее решение. По возможности дополнить или исправить его, и перевести статью в статус Проверенная.

Статус "Опубликованная"

• Статьи в статусе Проверенная попадают на проверку к агентам с KCS ролью Редактор. Ему при наступлении этого события приходит уведомление в личный кабинет и на почту. Задача этих агентов - стилизовать статью в соответствии с критериями контент-стандарта и перевести в статус Опубликованная.

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

• Если агент с с KCS ролью Редактор обнаруживает некорректное решение при публикации статьи, то он может либо поправить его на лету;
• Либо оставить в статусе Непроверенная и другие агенты при повторном использовании такой статьи должны обратить особое внимание на контекст проблемы и ее решение. По возможности дополнить или исправить его, и перевести статью в статус Проверенная.

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

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

Создание статьи

Создать статью можно со страницы заявки двумя способами: в один клик с использованием ИИ Ассистента (1) или вручную по кнопке Создать новую (2). Далее мы подробно рассмотрим 2й вариант.

Если же необходимо создать некую внутреннюю или внешнюю инструкцию без привязки к заявке, это можно сделать из раздела Статьи по кнопке Создать новую:

При наличии несколько шаблонов статей в системе, выбрать нужный можно раскрыв меню:

Создать шаблоны можно в Настройках - Шаблоны статей.

Страница редактирования статьи

По нажатию на кнопку Создать новую открывается страница редактора статей:

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

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

Внизу страницы вы можете выбрать язык статьи (по умолчанию открывается язык из заявки):

Предпросмотр статьи

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

Версии статьи

По нажатию на вкладку Версии над статьёй есть возможность переключиться в режим версий:

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

При наведении курсора на версию будет активна кнопка Сравнить. Таким образом можно сравнить разные версии статьи друг с другом:

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

После восстановления выбранная версия продублируется в качестве последней версии и станет актуальной, а предыдущая актуальная версия станет предпоследней.

Порядок версий можно менять по кнопке над ними:

Поиск и Область видимости

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

Он состоит из следующих полей и опций:

1. Поиск и ИИ функционал Похожие статьи - позволяет быстро проверить, нет ли уже аналогичной статьи в базе знаний.
2. Статус - этап работы со статьёй. Подробнее о статусах написано здесь.
3. Доступ - пользователи, которые имеют доступ до опубликованной статьи: Все - статья доступна всем внешним и внутренним пользователям, а также поисковым роботам. Пользователи - статья доступна только для пользователей, залогиненных в вашем аккаунте Swarmica. Такие статьи не участвуют в стандартной схеме работы со статьями, основанной на модели KCS. Они не направляются на проверку агентам и не требуют публикации. Сегменты - статья доступна определённым сегментам пользователей. Сегменты пользователей добавляются и настраиваются в настройках.
4. Раздел - раздел базы знаний, к которому будет отнесена статья. Разделы базы знаний создаются в Настройках - Управление разделами базы знаний. Они помогают упорядочить статьи на странице /help.
5. Внешние ссылки - ссылки на расположение статьи в публичном пространстве, с указанием языков статьи. Эти ссылки бывают только у статей в статусе Опубликованная.

Свойства

Рядом с полем для текста статьи расположен блок Свойства:

1. Автор - ответственный за статью. На первом этапе работы со статьёй автор = создатель статьи, но в процессе работы другие сотрудники могут для редактирования статьи забирать её себе соответствующей кнопкой Взять себе.
2. Редактор - кто перевел статью в статус Опубликованная.
3. Смотрят статью - перечень сотрудников, у которых открыто окно этой статьи в текущий момент времени. Полезно в случаях, когда со статьями могут работать одновременно несколько сотрудников.
4. Помечена к исправлению - поле для отметки о том, что статья нуждается в исправлении - например, решение не предоставлено. Этой опцией может воспользоваться сотрудник с ролью Кандидат или Опытный, если он увидит ошибку в опубликованной статье.
   При нажатии Отметить к исправлению система запросит его внести внутренний комментарий:
   
5. Отредактирована - время последнего изменения содержания статьи. При наведении курсора показывает точные дату и время:
   
6. Создана - дата и время создания статьи.
7. Подписаться - кнопка позволяет отслеживать изменения в тексте статьи. Подписавшиеся пользователи получают уведомление на email о каждом изменении заголовка или текста статьи. Это может быть полезно, если вы начали статью и передали её кому-то другому для дополнений, так вы сразу узнаете об этих дополнениях.
   Автора система автоматические подписывает на статью.

Продукты

Статью можно соотнести к одному или нескольким продуктам:

1. Добавить - выбрать продукты. Продукты для выбора добавляются в разделе Настройки - Управление продуктами.
2. Если продукт был прикреплён к статье по ошибке, его можно удалить из статьи значком корзины справа от него.

Файлы

В этом блоке перечислены иллюстрации, добавляемые в статью, а также файлы, прикреплённые к статье. Здесь же расположена кнопка добавления файлов, а так же удаления (1) и копирования ссылки (2):

Чтобы файл был виден в общем доступе, его нужно добавить в текст статьи. Для этого сначала добавьте файл по кнопке добавления файла и скопируйте ссылку на него.

Затем в тексте задайте слово или словосочетание, которое будет вести к файлу, выделите его (1), нажмите на кнопку добавления ссылки (2):

В появившемся окне (3) заполните поля:

• URL - сама ссылка.
• Текст ссылки - отредактировать слово из пункта 1.
• Заголовок - добавить слово или фразу, которую будет видно при наведении курсора на ссылку

Вот так будет выглядеть текст со ссылкой на файл:

Комментарии

Под статьёй расположен блок Комментарии, где вы можете увидеть комментарии к статье и добавить свой комментарий.

Для добавления комментария нажмите на выбранный его вариант, введите текст, по необходимости оформите его средствами редактирования и нажмите на кнопку отправки Комментарий:

Можно так же оставить внутренний комментарий. Он будет отмечен специальной отметкой. Его можно отредактировать, нажав на карандаш в правом верхнем углу (1) или удалить (2):

Удалять можно как публичные, так и внутренние комментарии.

События

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

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

Что это

Начиная с версии v6.2.0 в статьях базы знаний можно размещать диаграммы в синтаксисе Mermaid: блок-схемы, диаграммы последовательностей, диаграммы Ганта и другие. Диаграмма описывается текстом, а Swarmica рисует её при просмотре статьи — и в интерфейсе агента, и в публичном хелпцентре.

Например, такой код:

```mermaid
flowchart LR
    A[Новая заявка] --> B{Есть статья в базе знаний?}
    B -- Да --> C[Отправить ссылку на статью]
    B -- Нет --> D[Решить заявку и написать статью]
    C --> E[Заявка решена]
    D --> E
```

превращается в диаграмму:

flowchart LR
    A[Новая заявка] --> B{Есть статья в базе знаний?}
    B -- Да --> C[Отправить ссылку на статью]
    B -- Нет --> D[Решить заявку и написать статью]
    C --> E[Заявка решена]
    D --> E

Как добавить диаграмму

1. В редакторе статьи нажмите на панели инструментов кнопку «Вставить Mermaid диаграмму».
2. Напишите или вставьте код диаграммы.
3. Чтобы проверить результат, наведите курсор на блок диаграммы и нажмите кнопку переключения справа над ним — блок покажет превью. Повторное нажатие возвращает к коду.

В режиме Markdown диаграмму можно добавить и вручную — как блок кода с языком mermaid.

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

Где взять код диаграммы

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

• С помощью ИИ. Опишите диаграмму словами в любом ИИ-ассистенте (ChatGPT, Claude, GigaChat, YandexGPT и др.) и попросите вернуть код Mermaid. Например: «Нарисуй в синтаксисе Mermaid блок-схему обработки заявки: заявка поступает, агент ищет статью в базе знаний; если статья есть — отправляет ссылку, если нет — решает заявку и пишет статью».
• В бесплатных редакторах:
  • Mermaid Live Editor — официальный онлайн-редактор с открытым кодом: пишете код и сразу видите диаграмму, регистрация не нужна;
  • Mermaid AI — визуальный редактор и создание диаграмм с помощью ИИ; в бесплатном тарифе ограничено число диаграмм и ИИ-запросов.

Готовый код скопируйте в блок диаграммы в редакторе статьи.

Синтаксис Mermaid

Полное описание синтаксиса и всех типов диаграмм — в официальной документации Mermaid (на английском). Чаще всего в статьях пригодятся блок-схемы и диаграммы последовательностей.

Если диаграмма не отображается, проверьте код в Mermaid Live Editor — он показывает, в какой строке ошибка.

Подробнее: Создание и редактирование статьи · Выноски и предупреждения в статьях базы знаний

Симптомы

Нумерованные и ненумерованные списки в таблицах не работают в статьях.

Нельзя сделать абзац внутри ячейки таблицы.

Решение

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

Причина

В Свормика мы используем MDXeditor (который использует lexical) + обработчики Github Flavoured Markdown, которые, в свою очередь, не поддерживают списки и абзацы внутри таблиц.

Обработчики Github Flavoured Markdown очень хорошо работают с LLM, что делает возможным максимально эффективно пользоваться статьями в контексте работы ИИ функционала.

Разметка Schema.org описывает содержимое страницы в машиночитаемом виде: что это за документ, о чём он, когда опубликован и обновлён. Поисковые системы используют её для расширенных сниппетов, а ИИ-сервисы — чтобы точнее понимать и цитировать статью.

Что такое JSON-LD

JSON-LD (JSON for Linked Data) — формат записи разметки Schema.org в виде JSON-объекта внутри тега <script type="application/ld+json">. Разметка не влияет на внешний вид страницы. Google и Яндекс рекомендуют этот формат.

В Swarmica разметка задаётся в поле jsonld на вкладке SEO редактора статьи, отдельно для каждого языка. Хелпцентр сам оборачивает значение в тег <script>, поэтому указывайте только JSON:

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Как настроить SMTP канал для почты в Swarmica",
  "description": "Пошаговая настройка исходящей почты через SMTP в Swarmica.",
  "inLanguage": "ru",
  "datePublished": "2026-05-12",
  "dateModified": "2026-09-01",
  "image": "https://support.example.com/attachments/a/b/abc_a/smtp.png"
}

Что такое микроразметка (microdata)

Микроразметка — альтернативный способ описать данные Schema.org с помощью атрибутов itemscope, itemtype и itemprop прямо в HTML-коде страницы.

Хелпцентр сам выводит часть микроразметки: значения полей seo_description и seo_image дублируются в метатегах с атрибутом itemprop. Добавлять микроразметку в текст статьи не нужно: для корректной работы и отображения статей не рекомендуется использовать в них никакие HTML-вставки (см. Можно ли расширять статью произвольным HTML). Для собственной разметки используйте поле jsonld.

Типы Schema.org для статей базы знаний

Типы Organization и WebSite описывают компанию и сайт целиком, поэтому повторять их в каждой статье не нужно. Добавьте их один раз для всего портала базы знаний: Настройки → Основные настройки → Управление брендами → <Бренд по умолчанию> → Стили публичного портала базы знаний → Код HTML head.

В отличие от поля jsonld статьи, в этом поле разметку нужно указывать вместе с тегом <script>:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "name": "Название компании",
      "url": "https://example.com",
      "logo": "https://example.com/logo.png"
    },
    {
      "@type": "WebSite",
      "name": "База знаний компании",
      "url": "https://support.example.com/help",
      "inLanguage": ["ru", "en"]
    }
  ]
}
</script>

Свойства TechArticle

Несколько объектов в одной статье

Чтобы описать несколько сущностей — например, статью и её «хлебные крошки», — используйте массив @graph:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "TechArticle",
      "headline": "Как настроить SMTP канал для почты в Swarmica",
      "inLanguage": "ru"
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "База знаний", "item": "https://support.example.com/help" },
        { "@type": "ListItem", "position": 2, "name": "Настройка системы", "item": "https://support.example.com/category/1" }
      ]
    }
  ]
}

Пример разметки FAQPage:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Можно ли использовать для Telegram прокси кроме SOCKS5?",
      "acceptedAnswer": { "@type": "Answer", "text": "Нет, поддерживается только SOCKS5." }
    }
  ]
}

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

• Разметка должна соответствовать видимому тексту статьи. Не добавляйте в неё вопросы, ответы и факты, которых нет на странице.
• В JSON-LD указывайте абсолютные адреса — с протоколом и доменом.
• Обновляйте dateModified при существенных изменениях статьи.
• Заполняйте разметку для каждого языка статьи на языке этой локали.
• После сохранения проверьте разметку одним из инструментов ниже.

Инструменты проверки

• Schema Markup Validator — проверка разметки на соответствие словарю Schema.org.
• Проверка расширенных результатов Google — показывает, на какие расширенные сниппеты Google может претендовать страница.
• Валидатор микроразметки Яндекс Вебмастера — проверка разметки для поиска Яндекса.

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

Связанные статьи

• Настройка SEO-полей статьи (Open Graph, JSON-LD)
• Использование ИИ-агентов для SEO/GEO/AEO-оптимизации базы знаний

Каждая статья базы знаний Swarmica содержит набор SEO-полей. Они помогают поисковым системам (Google, Яндекс), ответным системам (AEO) и генеративным ИИ-сервисам (GEO) — ChatGPT, Perplexity, YandexGPT и другим — правильно понять, о чём статья, и показать её пользователю.

Где находятся SEO-поля

SEO-поля находятся на вкладке SEO в редакторе статьи. Поля заполняются отдельно для каждого языка статьи.

Данные выводятся в <head> страниц публичного портала базы знаний (хелпцентра). Это работает только для опубликованных статей с доступом Все. Подробнее о хелпцентре — в статье Конфигурация SEO-оптимизированного публичного портала базы знаний.

Описание полей

Если поле пустое, соответствующий тег на страницу не выводится.

Поле html_head

Содержимое поля html_head вставляется в <head> страницы статьи как есть, без проверки. Используйте только теги, допустимые внутри <head>: <meta>, <link>, <script>. Например:

<meta name="robots" content="noindex">

Этот тег запрещает поисковым системам индексировать конкретную статью, при этом она остаётся доступной всем пользователям.

Что Swarmica добавляет автоматически

Помимо SEO-полей, хелпцентр автоматически публикует данные для поисковых систем и LLM:

• На каждой странице статьи есть ссылка <link rel="alternate" type="text/markdown"> на Markdown-версию статьи. Её удобно читать языковым моделям.
• Файлы /llms.txt и /llms-full.txt со списком и текстами публичных статей — см. Включение индексации публичного портала базы знаний для LLM (llms.txt).
• Карта сайта /robots/sitemap.xml и файл robots.txt — см. Карта сайта sitemap.xml и robots.txt публичной базы знаний.

Рекомендации по оформлению текста статьи

Поисковые системы и ИИ-сервисы оценивают не только SEO-поля, но и структуру самой статьи.

• Не используйте в тексте статьи заголовки первого уровня (#). Заголовок статьи на странице хелпцентра выводится как <h1>, а в документе должен быть только один заголовок <h1>. Начинайте структуру текста с заголовков второго уровня (##); вложенные заголовки третьего и следующих уровней (###, ####) использовать можно. Если шаблоны статей содержат заголовки первого уровня, замените их на ## — см. Создание своих шаблонов статей.
• Формулируйте заголовок статьи как вопрос или проблему — так, как её сформулировал бы пользователь.
• Давайте прямой ответ в начале решения. Если статья построена по структуре KCS, сформулируйте краткий прямой ответ в первом абзаце раздела Решение, а подробности приведите ниже. Если такого раздела нет, дайте прямой ответ в первом абзаце статьи. Ответные системы и LLM чаще цитируют короткий ответ, за которым следуют подробности.
• Одна статья — одна проблема. Несколько несвязанных тем в одной статье ухудшают её ранжирование.
• Структурируйте текст: нумерованные шаги, таблицы, блоки кода для команд и конфигураций.
• Не размещайте служебную информацию в публичном тексте. Для сотрудников используйте внутреннюю часть статьи — она не выводится в хелпцентре и в SEO-поля не попадает.

Автоматическое заполнение и контроль

SEO-поля можно заполнять автоматически с помощью ИИ-агента — см. Использование ИИ-агентов для SEO/GEO/AEO-оптимизации базы знаний.

При проверке качества контента (AQI) рекомендуется также проверять заполненность и корректность SEO-полей.

Связанные статьи

• Настройка разметки Schema.org в статьях (JSON-LD, микроразметка)
• Использование ИИ-агентов для SEO/GEO/AEO-оптимизации базы знаний
• Карта сайта sitemap.xml и robots.txt публичной базы знаний
• Включение индексации публичного портала базы знаний для LLM (llms.txt)
• Создание и редактирование статьи

Симптомы

Ошибка при открытии базы знаний:

Ошибка Error: Instance not found!

В логах контейнера swarmica-helpcenter-1 наблюдается ошибка:

[app]  ERROR  { status: 400, method: 'GET', url: 'http://django:5000/api/instance/' }

Или:

[app]  ERROR  { status: undefined,  method: 'GET', url: 'https://my.swarmica.tld/api/instance/' }

Решение

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

1. Добавить значение django через запятую в переменную DJANGO_ALLOWED_HOSTS в файле /root/swarmica/.env, например:

   DJANGO_ALLOWED_HOSTS=my.swarmica.tld,django.
   

2. Раскомментировать строку

   INSECURE_HTTP_SERVER=1
   

3. Установить значение переменной

   NEXT_PUBLIC_HELPCENTER_SERVER_API_URL=http://django:5000
   

4. Перезагрузить контейнеры с помощью команды:

   docker compose down && docker compose up -d
   

Причина

Сервер со Свормикой не доступен сам себе по через внешнюю сеть ввиду сетевых настроек.

Вопрос

Можно ли делать внутри статьи сворачиваемые блоки содержимого?

Ответ

Да. В Markdown Swarmica можно использовать сворачиваемый блок с заголовком:

:::cut{title="Дополнительная информация"}
Текст, список или другие пояснения, которые читатель может раскрыть при необходимости.
:::

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

Подробнее: Управление фильтрами · Встраивание и авторизация веб-виджета в собственном приложении

Симптомы

Можно ли отключить сайдбар навигации категорий и статей в хелпцентре (базе знаний)?

Решение

Чтобы его отключить, откройте Настройки - Управление брендами - выберите нужный и добавьте следующие строки в Стили CSS:

.helpcenter-category-sidebar {
  display: none;
}

Вопрос

Как подключить свой шрифт в Help Center?

Ответ

Шрифт можно подключить так же в стилях для темы через @font-face и применить к разделу .helpcenter, например:

@font-face {
 font-family: "...";
  src: url("...")
   format("..."),
    url("...");
 font-display: auto;
 font-style: normal;
 font-weight: 300;
 font-stretch: normal;
}
.helpcenter {
 font-family: ... !important;
 font-size: 16px !important;
 line-height: 24px !important;
 font-weight: 400 !important;
 color: #353535 !important;
 background-color: #f5f9ff !important;
 display: flex;
 flex-direction: column;
}

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

.helpcenter .article-viewer-container .article-title {
 font-size: 20px !important;
 line-height: 27px !important;
 font-weight: 300 !important;
}

Симптомы

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

Решение

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

Язык определяется по следующему алгоритму:

1. Если тикет создается по API, то берется локаль, которую указали при создании.
2. Если не указали, то смотрится локаль/язык клиента, который завел тикет.
3. Если язык не указан/не определен, то смотрится дефолтная локаль инстанса.

К системе Swarmica можно подключить внешнюю базу знаний из любого источника по API. Содержимое подключенной базы будет доступно для поиска в базе знаний Swarmica и/или на странице заявки.

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

На открывшейся странице впишите параметры API-запроса и параметры парсера.

Примеры запросов

Параметры запроса:

{
  "search_url": "https://www.yourdomain.tld/docs/api/search",
  "http_method": "GET",
  "http_headers": {
    "Content-Type": "application/json; utf-8"
  },
  "search_param": "s"
}

Параметры парсера:

{
  "url_prefix": "https://www.yourdomain.tld",
  "response_mapping": {
    "url": "helpdesk.domain.tld",
// Вместо yourdomain.tld вставьте ваш домен Swarmica
    "body": "text",
    "rank": "rel",
    "title": "name"
  },
  "target_data_field": "*"
}

Вместо helpdesk.domain.tld вставьте ваш домен Swarmica

Далее в нижней части страницы на ваше усмотрение активируйте нужные бегунки.

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

Симптомы

Мы планировали сделать документацию по своему API в виде продукта, и хотим дать на этот продукт ссылку на веб-сайте или напрямую клиентам? Как получить такой URL?

Решение

Начиная с версии 5.7, вы можете передавать UID продукта через параметр ?product=UID в URL хелпцентра.

1. Зайдите в Настройки>Управление продуктами>Ваш продукт

2. Посмотрите в URL UID этого продукта. В нашем примере это SVs2jsdrxqFCSBrr

   

3. Откройте раздел продукта на хелпцентре по прямой ссылке следующего вида https://yourdoamin.tld/help?product=SVs2jsdrxqFCSBrr

Симптомы

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

Решение

С версии 5.7, которая сейчас установлена, мы добавили возможность создавать свои шаблоны статей в Настройках - Шаблоны статей.

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

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

Вопрос

Как создать структуру иерархии разделов в базе знаний? Как сделать подкатегории?

Решение

В Swarmica категоризация статей делается двумя сущностями:

1. Продукт. Продукт (а также его составляющие - версия, редакция и платформа) это единая сущность, которая может быть присвоена как тикетам, так и статьям. В случае использования лейбла продукта для статей это будет верхний уровень категоризации.
2. Категория. Или раздел, в которые можно определять статьи.

ВАЖНО! Продукт и категория НЕ являются вложенной иерархией. Это больше похоже на тэги, по которым фильтруется представление статей на хелпцентре.

Например, у вас в категории Настройка может быть Статья А по продукту 1 и статья Б по продукту 2. Если на хелпцентре выбрать Все продукты и зайти в категорию Настройки, то будут доступны обе статьи. Если же выбрать соответствующий продукт, то отфильтруется только статья по этому продукту.

Симптомы

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

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

Решение

Это поведение обусловлено редактором разметки Markdown - ненужные переносы строк удаляются, а остаются только те отступы, которые отбивают параграфы текста.

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

Вариант быстрого решения в текущем стиле: сделать shift+enter и поставить пару пробелов.

Изменение стиля через брендинг

Визуальное расстояние между блоками в статье (как до, так и после публикации) регулируется стилями, которые заданы в CSS и могут меняться в зависимости от корпоративного стиля (в частности - типографики). Делается это в Настройки > Управление брендами > Имя бренда

Например на уровне CSS можно настроить и отступы именно внутри списка в <theme_css>:

.article-viewer-container ol,
.article-viewer-container ul {
    line-height: 1.5; /* или нужное вам значение */
}

.article-viewer-container li {
    margin-bottom: 13px;
}

.article-viewer-container li:last-child {
    margin-bottom: 0;
}

Симптомы

Часто бывает необходимо добавить в статью инструкции для разных ОС / на разных языках программирования.

Как сделать вкладки, чтобы для каждой ОС / языка программирования была отдельная вкладка?

Решение

Начиная с версии v5.7.x доступна функция создания вкладок.
Чтобы добавить вкладки, переключите редактор в режим Markdown и добавьте следующий исходный код:

::::tabs
  :::tab-item{title="Tab 1"}
  Some content 1
  :::
  :::tab-item{title="Tab 2"}
  Some content 2
  :::
::::

Симптомы

Случайно отправил сообщение в статье KCS но отправил сообщение не внутреннее, а как комментарий. Как сменить статус своего комментария?

Решение

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

Вопрос

• По тексту вроде сходится "устранение" - есть "устранена", проблема в форме слова?
• Если ввести неполное слово, например без окончания, выборка будет пуста.
• При этом с одним неполным словом ("резервн") удалось получить выборку.
• Поиск строго завязан на склонении.

Ответ

Для поиска в KCS виджете мы используем 3rd-party полнотекстовый PostgreSQL движок. Одна из его особенностей заключается в том, что слова приводятся к базовой форме (то есть выполняется лемматизация): "дома" - "дом"

Лемматизация происходит по подключенным языковым словарям.

В связи с этим, не поддерживается поиск по частям слов. Это объясняет, почему по "резервн" выдается 0 результатов, а так же почему не ищется "Настройка Bin" (bin и резервн неполные слова, которые не ищут в словарях).

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

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

Лемматизация работает по-разному, т.е.форма слова может быть по-разному интерпретирована, например, единственное и множественное число (резервнУЮ и резервнЫЕ).

Отсутствие слова в словаре, т.е. PostgreSQL не распознаёт все формы.

Во втором случае, когда не находится слово в словаре, оно ищет вхождения as is, то есть только статьи с окончанием "резервнУЮ".

Судя по тестам, в данном случае это как раз является причиной, слово отсутствует в словаре: результаты поиска "резервная", "резервный", "резервные" и "резервную" - они все разные.При поиске используется метод, который НЕ работает с логическими операторами и префиксным поиском.

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

Альтернатива

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

Симптомы

Как выделять текст различными информационными заметками?

Решение

1. Переключитесь в режим Markdown
2. Используйте вариант разметки из примера ниже.

Пример

:::note
foo
:::

:::tip
Some **content** with _Markdown_ syntax. Check [this component](https://virtuoso.dev/).
:::

:::info
Some **content** with _Markdown_ syntax. 
:::

:::caution
Some **content** with _Markdown_ syntax.
:::

:::danger
Some **content** with _Markdown_ syntax.
:::
`

Симптомы

В редакторе статьи показывается ошибка:

Error parsing markdown: Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`).

You can fix the errors in source mode and switch to rich text mode when you are ready.

Решение

1. Нажмите кнопку
   
   в правом верхнем углу редактора для перехода в режим Markdown
2. Найдите символ(ы), вызывающий ошибку.
3. Удалите его (их).
4. Сохраните статью.
5. Сохраните статью и перейдите в режим WYSIWIG для проверки. Если ошибка не ушла, то повторите пункты 2-4.

Если проблема ушла в одном браузере , а в оригинальном показывает И текст статьи И ошибку, то нажмите "Отменить правки" в редакторе и обновите экран.

Причина

Редактор работает в двух режимах: WYSYWIG и Markdown. Ошибка возникает при использовании недопустимого символа в Markdown коде.

Очень часто это угловые скобки < или другие символы, которые могут фигурировать в ошибке.

Исправили в 4.3.1.

Что такое выноски / предупреждения?

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

Например, вот так:

Как создавать выноски / предупреждения?

1. Переключитесь в режим Markdown, нажав кнопку в правом верхнем углу редактора
2. Добавьте такой блок кода, отделенный переносами строк сверху и снизу:

   :::tip
   тут текст выноски
   :::
   

3. Теперь можно переключиться обратно в визуальный режим, повторно нажав кнопку и продолжить редактирование текста внутри выноски
4. Различные виды оформления можно задавать, меняя слово после первых :::: note, tip, info, caution, danger

Виды выносок

Выноски поддерживают остальные элементы форматирования текста внутри себя, как в режиме Markdown, так и в визуальном режиме

Симптомы

Выставил показатель REUSE=1. Ожидал, что этот показатель отвечает за то, сколько должно быть статей у черновика, чтобы система автоматически предлагала его проверить и опубликовать. Но видимо это как-то не так работает.

Решение

1. Перейдите в Настройки > Управление фильтрами>Статьи> Все статьи требующие проверки
2. Поменяйте параметр Заявок (всего) >= выставленная цель по REUSE.
3. Проверьте , что у вас (или нужного аккаунта) стоит KCS роль Опытный или Редактор
4. Привяжите черновик статьи к тикету количество раз равное или большее, чем пороговое значение RESU (Настройки > Целевые значения метрик).
5. Подождите 24 часа и проверьте наличие почтовых уведомлений и переход статью в статусе Непроверенная в фильтре Все статьи требующие проверки.

Причина

Проверка reuse происходит раз в сутки. При этом выполняются два действия: 1) Статья переходит в статус Непроверенная 2) Агентам с KCS ролями (настраивается в Настройки>Настройки сотрудников) Опытный и Редактор отправляется email уведомления. Статьи также можно видеть в фильтрах , например в Все статьи требующие проверки. Единственный нюанс - если меняете цель по reuse , то настройки фильтра тоже нужно скорректировать (Настройки > Управление фильтрами>Статьи> Все статьи требующие проверки) в условии количества показываемых заявок.

Симптомы

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

Решение

Методология KCS очень настоятельно рекомендует описывать симптомы теми же словами и так, как их видит клиент.

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

Причина

Поисковый движок  PostgreSQL ищет всю фразу, разбивая ее на словоформы.

Клиент ввел слово "Блокировка SIP" , но нужная статья не нашлась, потому что в ней вообще нет слова "Блокировка", хотя в целом она конечно описывает кейс клиента.

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