Произвольные источники данных¶

Произвольный источник данных — это табличный список (грид) поверх объекта базы данных: таблицы, представления, функции или хранимой процедуры. Он выводит данные прямо в интерфейс «Первой Формы», где их можно просматривать, фильтровать, выбирать нужные поля и выгружать в Excel. Так администратор даёт пользователям удобный доступ к большим объёмам данных и сложной аналитической отчётности — как из самой системы, так и полученной через интеграции, — не заставляя их работать с базой напрямую.

Источники настраиваются в AdminSPA: на главном экране отображается список всех произвольных источников, а по каждому из них открывается окно настроек с вкладками «Общие», «Колонки», «Действия», «Настройки тулбара» и «Общий вид».

Список произвольных источников данных

Как добавить и отредактировать источник¶

Чтобы добавить новый источник данных, нажмите кнопку «Добавить» — откроется модальное окно создания источника. Обязательные для заполнения поля выделены красным цветом.

Окно создания произвольного источника

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

⚠️ При создании нового источника необходимо настроить и сохранить колонки (вкладка «Колонки»).

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

Вкладка «Общие»¶

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

Редактирование произвольного источника, вкладка «Общие»

Типы источника данных¶

Таблица
Представление
Функция
Хранимая процедура (на PostgreSQL работает через одноимённую функцию)
Хранимая процедура без явного ResultSet (доступно только на MSSQL) — используется, когда в зависимости от контекста меняется количество возвращаемых колонок. Такой источник не описывает структуру возвращаемых данных и не определяет количество столбцов, поэтому часть пользовательских функций — сортировка, фильтрация, группировка, разбиение на страницы — будет недоступна.

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

⚠️ При изменении состава колонок в хранимой процедуре или функции произвольного источника требуется обновить колонки на вкладке «Колонки».

Примеры кода:

-- Функция
CREATE FUNCTION customDataSourceFunc ( @UserId int null )
RETURNS TABLE AS RETURN ( SELECT DisplayName, LastName from Users )

-- Хранимая процедура
CREATE PROCEDURE customDataSourceProc @UserId int null AS
BEGIN SELECT DisplayName, LastName from Users END

Параметры вкладки¶

Параметр	Описание
Тип источника данных	Вариант объекта БД (см. «Типы источника данных» выше).
Источник данных*	Сам объект-источник в БД.
Загружать данные при открытии	Если настройка неактивна, при открытии отображается пустой список с уведомлением «Данные не были загружены автоматически» и кнопкой «Загрузить». По умолчанию активировано.
Название	Название произвольного источника.
Алиас*	Наименование источника (псевдоним).
Путь	Полный путь до произвольного источника с учётом текущего алиаса. Заполняется автоматически после указания алиаса.
Описание	Описание произвольного источника.
Группы	Список групп, которым выданы права на источник.
Специальный тип	Произвольный источник можно открыть как отдельным роутом, так и из БИ. При выборе типа «Блок используется» к пути добавляется `spa/ds/{alias}?taskId=`. Обязательные параметры табличной функции для БИ: `UserID` (int) — ID пользователя, `TaskID` (int) — ID задачи.

Поля, отмеченные *, обязательны для заполнения.

Особенности работы с хранимой процедурой¶

Источником данных может являться хранимая процедура SQL. К таким процедурам предъявляется ряд требований.

Входные параметры хранимой процедуры:

Обязательно: @UserID (int) — ID текущего пользователя.
Опционально: @TaskID (int) — ID текущей задачи.

Если процедура принимает другие параметры, они не должны быть обязательными — при вычислении им будет передано значение NULL.

Хранимая процедура может возвращать произвольные данные и произвольный набор колонок. Названия колонок должны быть на латинице без пробелов.

Пример процедуры:

create PROCEDURE [dbo].[bi_sp_simple_example]
  @Userid int null,
  @TaskID int null
AS
BEGIN
  declare @result table (
    Taskid    int null,
    Userid    int null,
    SomeText  varchar(max) null
  );

  insert into @result
  select top 10
    t.TaskID,
    t.UserID,
    t.Description
  from Tasks t with(nolock)
  where t.TaskID = @TaskID;

  select TaskID, UserID, SomeText from @result;
END

Вкладка «Колонки»¶

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

Редактирование произвольного источника, вкладка «Колонки»

Кнопка «Обновить колонки» — данные о колонках будут обновлены в соответствии с указанным источником. ⚠️ При изменении состава колонок в хранимой процедуре или функции обязательно обновите колонки этой кнопкой.
Кнопка «Сброс настроек всех пользователей» — персональные настройки табличного вида пользователей будут сброшены к виду по умолчанию.

Настройки колонки:

Параметр	Описание
Колонка в БД	Название колонки в БД. Подтягивается автоматически, поле недоступно для редактирования. ⚠️ При настройке произвольного источника используйте значения колонок именно в том виде (с сохранением регистра), в котором они передаются в поле «Колонка в БД».
Название	Название колонки. Рядом с названием отображается иконка локализации — по клику на неё открывается окно для задания названий колонки в разных локалях. ⚠️ Если необходимо открывать ссылки, в название колонки нужно указать TaskID.
Тип	Тип данных колонки. Доступные варианты: Число, Строка, Дата, Дата и время, Html, Html без тегов, Чекбокс.
Настройки фильтра	Тип фильтра для колонки: Базовый или Мультивыбор (см. ниже).
Доступно	Доступ поля для пользователей.
Детализируется	Клик по строке в списке отобразит целиком значения столбцов, для которых активна настройка (детализация, drill-down).

Настройки фильтра¶

Доступные типы фильтра: Базовый и Мультивыбор. Фильтр с типом «Мультивыбор» для колонки в списке задач категории позволяет дополнительно выбирать несколько значений из множества.

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

Пример функции — источника фильтра:

CREATE OR ALTER FUNCTION [dbo].[testBoytsova] (@UserId int)
RETURNS @Table TABLE(
  name  nvarchar(300),
  value nvarchar(300)
)
AS
Begin
  insert into @Table (name, value)
    select s.Description, s.Description
    from States s
    where s.StateID IN (1,2,3,4)
  RETURN
END

Вкладка «Действия»¶

Вкладка позволяет добавлять кастомные кнопки действий со строкой, которые отображаются в отдельной колонке «Действия». Настройка кнопок задаётся в формате JSON со следующими параметрами:

icon — название иконки из набора, она будет отображаться на кнопке. Список доступных иконок — по ссылке /spa/icons.
name — название кнопки.
showInMenu — отображение кнопки в меню: true (отображать) / false (не отображать).
showInActions — отображение кнопки в тулбаре действий: true (отображать) / false (не отображать).
type — тип кнопки: OpenUrl (открыть ссылку из параметра url), Request (запрос), OpenComponent (открыть компонент — в настоящее время не поддерживается).
options:
url — ссылка, которая открывается при нажатии на кнопку. Помимо статичной ссылки можно задать ссылку на конкретную строку таблицы в формате {params:колонка} — вместо колонка указывается название колонки, из которой нужно получить значение в этой строке.
openMode — режим отображения: CurrentWindow (в текущем окне), NewWindow (в новом окне), ModalWindow (в модальном окне).
params — может содержать элементы http-запроса: headers, credentials, body и т.п. Наиболее распространённое значение — method (API-метод: GET, POST).
showResponse — отображение результата запроса: true / false.
isAvailable — настройка доступа в формате (params, ctx) => params.id === 123 && ctx.userId === 11.

Редактирование произвольного источника, вкладка «Действия»

⚠️ Параметры в ссылке передавайте в нижнем регистре. Пример: /admin/extparams/ExtParamsMainFrame.aspx?ExtParamID={params:extparamid}

Пример настройки:

[
  {
    "icon": "vh-tasks-add-24",
    "name": "Получить кэш",
    "showInMenu": null,
    "showInActions": null,
    "type": "Request",
    "options": {
      "url": "/spa/ds/films",
      "params": { "method": "POST" },
      "showResponse": true,
      "isAvailable": "(params, ctx) => params.id == 3 && ctx.userId == 8323"
    }
  },
  {
    "icon": "",
    "name": "Открыть группу",
    "showInMenu": null,
    "showInActions": null,
    "type": "OpenUrl",
    "options": {
      "url": "/spa/ds/films?f_id={params:id}",
      "openMode": "ModalWindow"
    }
  }
]

Пример настройки действий

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

Отображение кнопок действий со строкой в пользовательском интерфейсе

Вкладка «Настройки тулбара»¶

Вкладка позволяет добавлять кастомные кнопки действий в панели инструментов табличного вида. Настройка задаётся в формате JSON с теми же параметрами, что и на вкладке «Действия» (icon, name, showInMenu, showInActions, type, options с url, openMode, params, showResponse, isAvailable). В отличие от действий со строкой, кнопки тулбара не привязаны к конкретной строке, поэтому url задаётся как статичная ссылка. Настройки тулбара задаются объектом с ключом actions (в отличие от вкладки «Действия», где список кнопок — это массив).

Редактирование произвольного источника, вкладка «Настройки тулбара»

Пример настройки:

{
  "actions": [
    {
      "icon": "vh-tasks-add-24",
      "name": "Группы",
      "showInMenu": null,
      "showInActions": null,
      "type": "OpenUrl",
      "options": {
        "url": "/groups.aspx",
        "openMode": "ModalWindow"
      }
    },
    {
      "icon": "vh-tasks-add-24",
      "name": "Получить настройки",
      "showInMenu": null,
      "showInActions": null,
      "type": "Request",
      "options": {
        "url": "/app-settings.json",
        "params": { "method": "GET" },
        "showResponse": true
      }
    }
  ]
}

Пример настройки тулбара

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

Отображение кнопок действий в пользовательском интерфейсе

Вкладка «Общий вид»¶

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

Редактирование произвольного источника, вкладка «Общий вид»

Панель инструментов табличного вида:

Кнопка	Описание
Обновление данных	Обновляет данные в таблице.
Выбор колонок	Выбор нужного состава колонок для отображения.
Режим выбора	Переход в режим выбора задач, когда рядом с каждой задачей отображается флажок для выбора. Над выбранными задачами могут выполняться действия с помощью пакетной обработки.
Пакетная обработка	Пакетная обработка выбранных задач.
Выгрузка в Excel	Выгрузка данных в файл Excel. ⚠️ В системе нельзя экспортировать более 50 000 задач!
Сброс персональных настроек	Сброс персональных настроек табличного представления, сделанных пользователем (сортировка, группировка, список и порядок колонок), и возврат к настройкам таблицы, определённым по умолчанию для данной категории/раздела системным администратором.

⚠️ Кнопки «Режим выбора» и «Пакетная обработка» доступны только у источников, в которых есть колонка TaskID.

После внесения изменений нажмите кнопку «Сохранить».

Удаление источника¶

Чтобы удалить источник данных, нажмите кнопку с крестиком в конце соответствующей строки. Для подтверждения удаления нажмите «Ок», для отмены — «Отмена».

Где хранится настройка (таблица DataSourceSettings, ключи, типы источника) — в Таблицы (grids) → Произвольные источники данных.