Документация›Инженерия контента›6. Кастомные поля от начала до конца

Кастомные поля от начала до конца

Почему это важно. Кастомное поле — это как вы учите SOARForge факту, который платформа не моделирует из коробки, — номер тикета, который назначает ваш ITSM, код бизнес-юнита, вердикт по фишингу, дедлайн ремедиации. Как только поле существует, вы можете маппить в него входящие данные, размещать его на layout-е кейса, читать его в плейбуках и экспортировать. Эта глава прослеживает одно поле весь путь — от экрана определения до значения на живом кейсе.

Эта глава — глубокий спутник обзора Objects Setup из руководства администратора (Objects Setup overview). Она предполагает, что вы можете дойти до раздела Objects Setup; всё ниже — про объект Fields конкретно.

6.1. Где живут определения полей

Маршрут: /admin/incident-types?tab=fields (Settings → Objects Setup → вкладка Fields) · Права: incident_types.view смотреть, incident_types.manage создавать/редактировать/удалять · Модуль: cases

Экран Objects Setup несёт четыре верхнеуровневых вкладки — Types, Fields, Layouts, Classification — плюс переключатель объектов Incidents / Indicators. Кастомные поля инцидентов живут под Incidents → Fields. (Переключение объекта на Indicators заменяет набор вкладок типами индикаторов и исключениями, описанными в гайде администратора §3.4; это другой каталог.)

Вкладка Fields — единая искомая таблица каждого поля, которое знает платформа, — системных полей и ваших собственных — делящих одно пространство имён. Колонки:

Колонка	Значение
Field Name	Отображаемое имя (жирным) с machine-именем под ним.
Type	Подпись типа данных поля (напр. Short text, Grid / Table).
Owner Only	Yes, если значение может редактировать только владелец кейса.
Mandatory	Yes, если поле обязательно.
System	Yes для платформенных/встроенных полей (не редактируемы и не удаляемы).
Content Pack	Откуда пришло определение (Common Types, Incident Built-ins, имя коннектора или Local Content для ваших собственных полей).
Used In	All types или типы инцидентов, к которым поле ограничено.

Над таблицей: поле поиска (совпадает по отображаемому имени, machine-имени, content-паку, описанию и подписи Used In), фильтр по типу и кнопка New Field. Выбор строки (радио) включает Edit, Delete и Export (последняя скачивает определение поля как <machine-name>.incident-field.json). Edit и Delete недоступны для системных полей.

Один общий каталог, два происхождения. Список смешивает ~сотни предзасеянных системных полей (встроенные поля инцидента плюс отраслевая библиотека полей безопасности — sourceip, filesha256, cve и т. д.) с вашими кастомными полями. Системные поля — это read-only каркас, на котором вы строите; менять можно только кастомные поля.

6.2. Создание поля — все свойства

Кликните New Field. Редактор — это одно модальное окно (New Incident Field) с блоком заголовка и двумя вкладками.

Блок заголовка (всегда виден):

Элемент	Что делает
Field Type	Тип данных. Обязателен. Управляет тем, какие дополнительные элементы появляются и как значение отрисовывается повсюду. Полный список см. в §6.3.
Case Sensitive	Чувствительны ли строковые сравнения по значению к регистру.
Mandatory	Значение должно быть заполнено до того, как кейс можно сохранить в форме, которая показывает поле.
Only owner can edit	Ограничивает редактирование значения владельцем кейса.
Field Name	Человекочитаемая подпись. Обязательна.
Machine name	Показывается вживую под именем — выводится, а не набирается. См. врезку ниже.
Tooltip	Всплывающая подсказка рядом с полем на layout-ах.

Как выводится machine-имя. По мере набора Field Name платформа приводит его к нижнему регистру, превращает серии пробелов в одиночные подчёркивания и вырезает всё, что не буква, цифра, ., _ или -. Acme Ticket ID становится acme_ticket_id. Machine-имя — постоянный ключ поля — это то, во что пишут мапперы, что читают выражения плейбуков и на что указывает поле layout-а. Оно фиксируется при создании: переименование отображаемого имени позже его не меняет. Горстка ключей зарезервирована платформой (reason, labels, rawjson, close_notes и внутренние ключи-зеркала fbot_*) и отклоняется с ошибкой конфликта, как и любое имя, сталкивающееся с существующим полем.

Вкладка 1 — Basic Settings

Placeholder — сероватый текст-подсказка внутри пустого ввода.
Для Single select / Multi select / Tags: переключатель режима Values (Static list или Dynamic list) и поле Values (comma separated), засеивающее список опций.
Для Grid / Table: переключатель User can add rows и редактор Columns — по одной колонке в строке как name | type | mandatory | locked (напр. ioc | short_text | true | false).
Для Timer / SLA: SLA Duration (minutes), Risk Threshold (minutes) и пикер Run on SLA breach script (автоматизации с тегом SLA).

Вкладка 2 — Attributes

Script to run when field value changes — автоматизация из каталога скриптов полей. Подпись переключается между (before save) и (after save) в зависимости от переключателя ниже.
Run triggered script after Incident is modified — когда включено, скрипт изменения гоняется после сохранения (пост-модификация), а не до.
Field display script — автоматизация, которая решает в момент отрисовки, показано, скрыто или read-only поле для текущего кейса.
Add to all Incident types — включено по умолчанию (поле универсально). Выключите, чтобы открыть мульти-селект и ограничить поле только конкретными типами инцидентов.
Default display on — где поле появляется по умолчанию: New / Edit, Close или Both.
Make data available for search — включено по умолчанию. Когда включено, сохранённое значение поля матчится свободнотекстовым поиском кейсов (единая строка поиска); выключение исключает поле из этого поиска. Точно про то, что это делает и чего не делает, см. врезку в §6.4.
Read-only теги внизу показывают, System поле или Custom, его Content Pack и его scope Used In.

Новые поля всегда создаются в scope incident (доказательства — отдельная сущность, хранимая в объектном хранилище, а не scope поля). Свободнотекстовое описание не экспонировано в этой ручной форме — оно автогенерируется только для полей, которые платформа обнаруживает из коннектора.

6.3. Справочник типов полей

Все 27 поддерживаемых типов (тот же набор, что принимает API). Тип «почти постоянен»: вы можете сменить его позже, но это меняет только то, как захватывается новый ввод и как отрисовывается значение — оно не перекастовывает значения, уже хранящиеся на кейсах.

Группа	Типы
Text	`short_text`, `long_text`, `markdown`, `html`
Choice	`single_select`, `multi_select`, `tags`
Number / logic	`number`, `boolean`
Date & time	`date`, `date_time`
People	`user`, `role`
Link	`url`
Structured	`grid` (таблица с типизированными колонками), `json`
Attachments	`attachment`, `attachments`
SLA	`timer_sla` (таймер обратного отсчёта с порогами breach/risk)
Lists (многозначные скаляры)	`text_list`, `number_list`, `boolean_list`, `date_list`, `date_time_list`, `url_list`, `user_list`, `role_list`

Choice, grid и SLA несут дополнительную конфигурацию. Только типы select/tags, grid и timer_sla показывают дополнительные элементы Basic-Settings из §6.2; для каждого другого типа эти элементы скрыты.

6.4. Как поле становится доступным

Создание определения — лишь шаг один. Вот где поле появляется дальше — и, что не менее важно, где нет.

Во входящем маппере (как цель). Редактор маппера типа инцидента тянет свой список целей прямо из каталога полей, так что поле, которое вы только что создали, появляется автоматически как маппируемая цель (сгруппированная под Custom field) при следующем открытии маппера — без дополнительной регистрации. Вы направляете на него путь источника, и в момент ingest сопоставленное значение записывается в хранилище custom_fields кейса под machine-именем поля. (Автономная библиотека мапперов вместо этого берёт свободно набранную цель — вы вводите machine-имя сами; назначение то же.) Встроенные цели вроде name, severity, status и tags — исключение: они заполняют нативные колонки кейса, а не custom_fields.

В layout-ах (в библиотеке полей конструктора). Библиотека Fields and Buttons конструктора layout-ов заполняется из того же каталога, так что ваше поле сразу перетаскиваемо на любую секцию. Его путь данных на layout-е — голое machine-имя (acme_ticket_id). Полные детали в Главе 7.

В плейбуках и контексте кейса (incident.*). В представлении Context Data war-room и в рантайме плейбуков кастомные поля сливаются в поддерево incident.*, с точечными machine-именами, развёрнутыми во вложенные объекты. Поле acme_ticket_id читается в плейбуке как ${incident.acme_ticket_id}; поле с именем email.subject становится ${incident.email.subject}. Это канонический путь для автоматизации.

На экране детали кейса. Когда layout отрисовывает поле на странице кейса, значение резолвится из custom_fields кейса по голому machine-имени — на этой поверхности вы ссылаетесь на acme_ticket_id, а не incident.acme_ticket_id (дерево incident.* — это форма плейбука/Context Data, а не форма payload детали кейса).

Что делает «Make data available for search» — и чего не делает. Когда переключатель включён (по умолчанию), сохранённое значение поля матчится свободнотекстовым поиском кейсов (единая строка поиска): набрав значение кастомного поля, вы получите кейсы, которые его несут, наряду с совпадениями по заголовку, описанию, source, source reference, номеру кейса, индикаторам и сырому payload алерта. Выключение переключателя исключает значение этого поля из поиска. Чего переключатель не делает — не добавляет структурированный фильтр: фильтры списка Cases остаются фиксированным набором — status, severity, time range, owner, incident type — без элемента «фильтр по значению кастомного поля». Две границы, о которых стоит знать. Совпадение выполняется как ограниченный Postgres ILIKE по индексируемым ключам кастомных полей (выделенного индекса по значениям пока нет — JSON-индекс GIN не обслуживает подстроковый поиск — так что на очень большой таблице кейсов это может замедлиться до появления trigram-индекса). А кейсы, чьё значение пришло прямо из сырого алерта, без записи в custom_fields, уже достижимы через поиск по сырому payload (OpenSearch), поэтому совпадают в любом случае — этот полнотекстовый поиск по сырому payload идёт через OpenSearch независимо от этого переключателя, так что переключатель управляет только сопоставлением кастомных полей, но никогда — сырого алерта. Кастомные поля также появляются в очереди кейсов как read-only inline-значения превью, когда включены (см. Главу 7 → List View / inline-значения).

6.5. Редактирование и удаление поля с данными

Редактирование. Откройте кастомное поле и измените любое свойство. Смена отображаемого имени или tooltip косметична и безопасна. Смена типа меняет, как поле захватывает и отрисовывает значения с этого момента; она не переписывает и не перекастовывает значения, уже хранящиеся на существующих кейсах — старое значение просто отрисовывается через форматтер нового типа. Сужение Add to all Incident types до подмножества прячет поле на типах, которые вы убрали, но оставляет их хранимые значения нетронутыми.

Удаление. Удаление кастомного поля мгновенно и спрашивает лишь подтверждение. То, что оно убирает, — это определение: поле исчезает из библиотеки, из списков целей маппера и из пикера полей layout-а. То, что оно не трогает, — это данные, уже записанные на кейсы: значения, ранее хранимые в custom_fields кейса, остаются в записи. Поскольку определения больше нет, эти осиротевшие значения больше не отрисовываются через типизированное поле на layout-ах и больше не предлагаются как цель маппера/layout-а, но они не вычищаются. Отмены нет, так что сначала экспортируйте определение (кнопкой Export), если можете захотеть его пересоздать.

Системные поля отказывают в обоих. Любое поле, помеченное System (встроенные поля инцидента, библиотека Common Types, канонические поля коннекторов), нельзя редактировать или удалить — API отклоняет это конфликтом. Это намеренно: layout-ы, мапперы и плейбуки по всей платформе зависят от этих ключей.

6.6. Разобранный пример — «Acme Ticket ID» на кейсе

Сквозной путь на примере short-text поля, несущего внешний номер тикета.

Создайте поле. Objects Setup → Fields → New Field. Field Type Short text, Field Name Acme Ticket ID. Проследите, как machine-имя резолвится в acme_ticket_id. Оставьте Add to all Incident types включённым (или ограничьте его вашими ITSM-питаемыми типами). Сохраните.
Смаппьте данные в него. Objects Setup → Classification → входящий маппер для нужного коннектора. Найдите Acme Ticket ID в списке целей (под Custom field) и направьте на него путь источника, несущий id тикета вендора. Сохраните маппер. Новые кейсы с этого источника теперь попадают с заполненным custom_fields.acme_ticket_id.
Разместите его на layout-е. Objects Setup → Layouts → откройте layout типа инцидента в конструкторе. Из библиотеки Fields and Buttons перетащите Acme Ticket ID в секцию полей (или бросьте поле и задайте его пути данных acme_ticket_id). Сохраните. Про конструктор см. Главу 7.
Увидьте его на кейсе. Откройте кейс этого типа. Поле Acme Ticket ID отрисовывается в секции, куда вы его поместили, показывая сопоставленное значение. В плейбуке для того же кейса ${incident.acme_ticket_id} резолвится в то же значение.

Распространённые ошибки

Machine-имя навсегда. Оно выводится один раз из отображаемого имени и никогда потом не меняется. Задайте отображаемое имя правильно до первого сохранения или удалите и пересоздайте. Переименование отображаемого имени позже оставляет мапперы, layout-ы и выражения ${incident.*} указывающими на исходный ключ.
Поиск матчит, структурированного фильтра нет. С включённым «Make data available for search» значение кастомного поля матчится свободнотекстовым поиском кейсов — но отдельного фильтра по полю в очереди кейсов по-прежнему нет. См. врезку в §6.4.
Префикс incident. контекстно-зависим. Используйте ${incident.acme_ticket_id} в плейбуках и Context Data; используйте голое acme_ticket_id как путь данных поля layout-а. Путаница между ними — самая частая причина «моё поле пустое».
Удаление поля не удаляет его данные. Хранимые значения остаются как осиротевшие записи в custom_fields; исчезает именно определение. Экспортируйте до удаления, если есть шанс, что вы пересоздадите поле.
Системные поля заперты намеренно. Если Edit/Delete серые, поле системное — создайте кастомное поле вместо попытки согнуть встроенное.
Scope сужает видимость, а не историю. Выключение Add to all Incident types прячет поле на исключённых типах, но сохраняет значения, уже записанные на кейсы этих типов.