Перейти к содержанию

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

Каждая модель в InfraVision представлена в базе данных как отдельная таблица, и каждый атрибут модели существует как столбец в этой таблице. Например, площадки хранятся в таблице dcim_site, которая имеет столбцы name, facility, physical_address и так далее. По мере добавления новых атрибутов к объектам в процессе развития InfraVision таблицы расширяются для включения новых столбцов.

Однако некоторым пользователям может потребоваться хранить дополнительные атрибуты объектов, которые носят достаточно специфический характер и не имеет смысла включать в основную схему базы данных InfraVision. Например, предположим, что вашей организации необходимо связать каждое устройство с номером заявки, соответствующим записи во внутренней системе поддержки. Это, безусловно, законное использование InfraVision, но это не настолько распространённая потребность, чтобы добавлять поле для каждой установки InfraVision. Вместо этого вы можете создать пользовательское поле для хранения этих данных.

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

Создание пользовательских полей

Пользовательские поля можно создать, перейдя в раздел Кастомизация > Пользовательские поля. InfraVision поддерживает множество типов пользовательских полей:

  • Текст: Свободный текст (предназначен для однострочного использования)
  • Длинный текст: Свободный текст любой длины; поддерживает рендеринг Markdown
  • Целое число: Целое число (положительное или отрицательное)
  • Десятичное число: Число с фиксированной точностью (4 десятичных знака)
  • Булево: True или false
  • Дата: Дата в формате ISO 8601 (YYYY-MM-DD)
  • Дата и время: Дата и время в формате ISO 8601 (YYYY-MM-DD HH:MM:SS)
  • URL: Будет отображаться как ссылка в веб-интерфейсе
  • JSON: Произвольные данные, хранящиеся в формате JSON
  • Выбор: Выбор одного из нескольких предопределённых вариантов
  • Множественный выбор: Поле выбора, которое поддерживает назначение нескольких значений
  • Объект: Один объект InfraVision типа, определённого в object_type
  • Множественный объект: Один или несколько объектов InfraVision типа, определённого в object_type

Каждое пользовательское поле должно иметь имя. Это должна быть простая строка, удобная для базы данных (например, tps_report), и она может содержать только буквенно-цифровые символы и подчёркивания. Вы также можете назначить соответствующую человекочитаемую метку (например, "TPS report"); метка будет отображаться в веб-формах. Также требуется вес: Поля с большим весом будут располагаться ниже в форме. (Вес по умолчанию — 100.) Если предоставлено описание, оно появится под полем в форме.

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

Пользовательское поле должно быть назначено одному или нескольким типам объектов, или моделям, в InfraVision. После создания пользовательские поля автоматически появятся как часть этих моделей в веб-интерфейсе и REST API. Обратите внимание, что не все модели поддерживают пользовательские поля.

Фильтрация

Логика фильтрации контролирует, как значения сопоставляются при фильтрации объектов по пользовательскому полю. Нестрогая фильтрация (по умолчанию) соответствует частичному значению, тогда как точное сопоставление требует полного совпадения данной строки со значением поля. Например, точная фильтрация со строкой "red" будет соответствовать только точному значению "red", тогда как нестрогая фильтрация будет соответствовать значениям "red", "red-orange" или "bored". Установка логики фильтрации в "отключено" полностью отключает фильтрацию по полю.

Группировка

Связанные пользовательские поля могут быть сгруппированы вместе в интерфейсе путём назначения каждому одного и того же имени группы. Когда хотя бы одно пользовательское поле для типа объекта имеет определённую группу, оно появится под заголовком группы на панели пользовательских полей в представлении объекта. Все пользовательские поля с одинаковым именем группы появятся под этим заголовком. (Обратите внимание, что имена групп должны точно совпадать, иначе каждое появится как отдельный заголовок.)

Этот параметр не влияет на представление данных пользовательских полей в API.

Видимость и редактирование

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

  • Всегда (по умолчанию): Пользовательское поле включается при просмотре объекта.
  • Если задано: Пользовательское поле включается только если значение было определено для объекта.
  • Скрыто: Пользовательское поле никогда не будет отображаться в интерфейсе. Этот вариант рекомендуется для полей, которые не предназначены для использования людьми.

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

  • Да (по умолчанию): Значение пользовательского поля может быть изменено при редактировании объекта.
  • Нет: Пользовательское поле отображается для справки при редактировании объекта, но его значение не может быть изменено.
  • Скрыто: Пользовательское поле не отображается при редактировании объекта.

Обратите внимание, что этот параметр не влияет на REST или GraphQL API: Данные пользовательских полей всегда будут доступны через любой API.

Валидация

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

  • Текст: Регулярное выражение (опционально)
  • Целое число: Минимальное и/или максимальное значение (опционально)
  • Выбор: Должно точно соответствовать одному из предписанных вариантов

Пользовательские поля выбора

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

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

Пользовательские поля объектов

Пользовательское поле объекта или множественного объекта может использоваться для ссылки на определённый объект или объекты InfraVision как на "значение" пользовательского поля. Эти пользовательские поля должны определять object_type, который определяет тип объекта, на который указывают экземпляры пользовательского поля.

По умолчанию поле выбора объекта сделает все объекты этого типа доступными для выбора в выпадающем списке. Список вариантов может быть отфильтрован для отображения только объектов с определёнными значениями путём предоставления словаря query_params в поле фильтра связанного объекта в виде значения JSON. Больше информации о query_params можно найти здесь.

Пользовательские поля в шаблонах

Несколько функций в InfraVision, таких как шаблоны экспорта и вебхуки, используют шаблонизацию Jinja2. Для удобства объекты, поддерживающие назначение пользовательских полей, предоставляют доступ к данным пользовательских полей через свойство cf. Это немного чище, чем доступ к данным пользовательских полей через фактическое поле (custom_field_data).

Например, пользовательское поле с именем foo123 в модели Site доступно на экземпляре как {{ site.cf.foo123 }}.

Пользовательские поля и REST API

При получении объекта через REST API все его пользовательские данные будут включены в атрибут custom_fields. Например, ниже приведён частичный вывод площадки с двумя определёнными пользовательскими полями:

{
    "id": 123,
    "url": "http://localhost:8000/api/dcim/sites/123/",
    "name": "Raleigh 42",
    ...
    "custom_fields": {
        "deployed": "2018-06-19",
        "site_code": "US-NC-RAL42"
    },
    ...

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

{
    "name": "New Site",
    "slug": "new-site",
    "custom_fields": {
        "deployed": "2019-03-24"
    }
}