Запуск скрипта из дашборда

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

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

• Добавить, удалить или обновить строки таблицы
• Совершить действие в другой системе:
  • Создать задачу
  • Повысить приоритет задачи
  • Отправить сообщение

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

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

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

Добавление действия в Таблицу

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

Создайте или выберите Таблицу, для которой необходимо настроить действие. Откройте вкладку Действия в правой панели и нажмите + Кнопка.

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

Настройка действия

Чтобы настроить действие:

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

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

• Название — отображается на кнопке
• Описание — используется в качестве подсказки на этапе запуска скрипта
• Выполнить скрипт — в раскрывающемся списке отображаются только скрипты, которые возвращают данные
• Параметры — настраиваются для каждого поля из скрипта отдельно. Доступна смена названия и обязательная настройка способа ввода
• Подсказка — текст, который появляется при наведении на кнопку в режиме просмотра. Максимальная длина — 160 символов
• Активация кнопки — это возможность добавить условие, при выполнении которого кнопка в режиме просмотра становится доступной для нажатия. Указать условие для активации можно по формуле или по переменной. При выборе активации по переменной, доступны только переменные типа Статический список. Если установленное в условии значение не соответствует текущему значению переменной, то в режиме просмотра кнопка запуска действия не активна. Дополнительно можно выбрать тип кнопки: основная, второстепенная или ссылка. Также можно настроить базовый цвет обводки кнопки и текста в ней
• Скрывать неактивную кнопку. Доступно для виджета Кнопка
• Автообновление — срабатывает после выполнения скрипта. Можно обновить данные в виджете, из которого запускался скрипт, во всех виджетах и плейсхолдерах образа или отключить параметр

Поведение в режиме просмотра

Если для кнопки задано одно действие, то она становится доступной когда:

• Настроены обязательные параметры
• Выбраны строки Таблицы в режиме просмотре (если необходимо)
• Сработало условие активации

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

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

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

Принцип отображения подсказок:

• Если задана подсказка для кнопки или действия, то при наведении отображается этот текст
• Если заданы подсказки и для кнопки, и для действия, то при наведении отображается подсказка для кнопки

Настройка способа ввода

Из колонки

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

Из переменной

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

Из модели данных

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

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

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

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

Задать формулой

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

Задать агрегацией

С помощью формулы можно передавать результат агрегации в ожидаемое поле скрипта. Результат агрегации должен совпадать с типом ожидаемого поля. В режиме просмотра при выполнении действия поле с этим способом ввода заполняется значением из формулы поля. При выполнении скрипта значение функции передается в ожидаемое поле скрипта. Если ожидаемое поле — массив, то функция должна возвращать массив.

Ввести вручную

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

• Указать описание
• Включить фильтр по строкам
• Настроить пользовательскую валидацию
• Скрыть параметр (не будет отображаться в окне запуска действия)

Статический список

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

Динамический список

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

• Отображаемый список
• Значение по умолчанию
• Фильтр по строкам
• Предустановленные фильтры (кнопка + Фильтр)
• Переключатели:
  • Скрыть параметр — параметр не будет отображаться в окне запуска действия
  • Ввод любых значений — в режиме просмотра в параметр можно вводить и отправлять одно значение, которого нет в динамическом списке. Если ожидаемое поле в скрипте — массив, то переключатель скрыт
  • Валидация — доступно, если активен переключатель Ввод любых значений
  • Учитывать фильтры — в параметр передаются данные с учетом фильтров, назначенных в режиме просмотра

Запуск действия

После настройки действия над таблицей появляется кнопка. Она становится активной в режиме просмотра.

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

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

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

Действие невозможно запустить, когда:

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

Когда скрипт запускается, в правом нижнем углу отображается сообщение Действие «Название действия» запущено. Если скрипт успешно завершает работу, в правом нижнем углу появляется сообщение Действие выполнено. Если скрипт не был выполнен успешно, отображается сообщение об ошибке. В зависимости от причины возникновения ошибки вы можете перейти в журнал выполнений, перезапустить скрипт или закрыть окно.

Примеры запуска скриптов из дашборда

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

Добавить строку

Чтобы добавить строку в таблицу:

1. Создайте новый скрипт в дашборде.
2. Добавьте блок Ручной запуск. В блок добавьте ожидаемые поля, укажите необходимые типы данных и нажмите Продолжить. Используйте названия колонок таблиц из модели данных. Протестируйте блок.
3. Добавьте блок Добавить строки. В блоке выберите необходимую таблицу, а в колонках — указанные в первом блоке ожидаемые поля. Для удобства используйте визуальный маппинг. Протестируйте блок.
4. Опубликуйте скрипт.
5. Откройте дашборд с необходимой таблицей. Добавьте действие во вкладке Действия и укажите для него название. В параметрах каждого поля укажите необходимый способ ввода и колонку. Чтобы результат выполнения отобразился после выполнения скрипта, установите для параметра Обновить после выполнения скрипта значение Этот виджет.
6. Опубликуйте дашборд. В верху таблицы нажмите Добавить строку. Укажите необходимые параметры и нажмите Выполнить.
7. Строка добавлена.

Удалить строки

Чтобы удалить строки из таблицы:

1. Создайте новый скрипт в дашборде.
2. Добавьте блок Ручной запуск. В блок добавьте ожидаемое поле, укажите необходимый тип данных и нажмите Продолжить. Используйте название колонки таблицы из модели данных. Протестируйте блок.
3. Добавьте блок SQL-запрос с запросом на удаление строки. Протестируйте блок. Пример SQL-запроса для удаления строки:
   DELETE FROM case_table
   WHERE incident_id = ${a1.Номер проблемы};
   

4. Опубликуйте скрипт.
5. Откройте дашборд с необходимой таблицей. Добавьте действие во вкладке Действия и укажите для него название. В параметрах поля укажите способ ввода Из колонки. Выберите ту же колонку, что и указана в SQL-запросе скрипта. Чтобы результат выполнения отобразился после выполнения скрипта, установите для параметра Обновить после выполнения скрипта значение Этот виджет.
6. Опубликуйте дашборд. Выберите строки, которые хотите удалить и нажмите Удалить строки над таблицей. Нажмите Выполнить.
7. Строки удалены.

Изменить приоритет

Чтобы изменить приоритет:

1. Создайте новый скрипт в дашборде.
2. Добавьте блок Ручной запуск. В блок добавьте ожидаемые поля, укажите необходимые типы данных и нажмите Продолжить. Протестируйте блок.
3. Добавьте блок Обновить строки. В блоке укажите необходимую таблицу, колонку-ключ и значение ключа, а в колонках — приоритет. Для удобства можно использовать визуальный маппинг. Протестируйте блок.
4. Опубликуйте скрипт.
5. Откройте дашборд с необходимой таблицей. Добавьте действие во вкладке Действия и укажите для него название. В параметрах каждого поля укажите необходимый способ ввода и колонку. Чтобы результат выполнения отобразился после выполнения скрипта, установите для параметра Обновить после выполнения скрипта значение Этот виджет.
6. Опубликуйте дашборд. Выберите строки, для которых хотите изменить приоритет. В верху таблицы нажмите Изменить приоритет. Введите или выберите необходимое значение и нажмите Выполнить.
7. У выбранных задач изменился приоритет.

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

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

1. В образ добавлена таблица с колонками Товар, Оригинальная цена и Комментарий. Настроим для таблицы действие, при котором сможем добавлять новые строки.
2. Создадим в пространстве новый скрипт (в этом примере он называется Новая строка). В качестве первого блока выберем Ручной запуск. Добавим ожидаемые поля Товар, Цена единицы и Комментарий. Протестируем блок.
3. Добавим в скрипт блок Добавить строки. Выберем таблицу с необходимыми данными и укажем для колонок ожидаемые поля.
4. Опубликуем скрипт и вернемся в образ. Выберем таблицу и добавим новое действие. Укажем созданный ранее скрипт.
5. Перейдем к настройке параметров. Для всех параметров необходимо выбрать способ ввода Ввести вручную.
6. Для параметра Цена единицы укажем в поле Валидация формулу:
   if(NOT match($$"Цена единицы", '[0-9]'), 'Значение должно быть целым числом',
       null)
   

   В этой формуле используется синтаксис ClickHouse. Если в поле Цена единицы будут указаны любые значения, кроме цифр от 0 до 9, то под полем появится сообщение об ошибке Значение должно быть целым числом.
7. Нажмем Опубликовать и протестируем работу скрипта. Нажмем на кнопку Новая строка над таблицей. В появившемся модальном окне заполним поля данными. Если указать в поле Цена единицы некорректное значение, то появляется сообщение об ошибке. Кнопка Выполнить останется недоступной до тех пор, пока данные в полях не будут исправлены.

Настройки скрипта и действия в YAML

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

Действия по клику (блок onClick)

В блоке onClick используются ключи из таблицы ниже.

Настройки параметров (блок parameters)

В блоке parameters указываются параметры скрипта.

Настройки цветов кнопки (блоки backgroundColor, borderColor и color)

При настройке блоков backgroundColor, color или borderColor используйте ключи, описанные в таблице ниже.

Условие активации кнопки (блок activateCondition)

В блоке activateCondition указываются условия активации кнопки.

Способ ввода (ключ inputMethod)

Доступны перечисленные способы ввода значения:

• COLUMN — из колонки
• VARIABLE — из переменной
• DATA_MODEL — из модели данных
• FORMULA — задать формулой
• AGGREGATION — задать агрегацией
• MANUALLY — ввести вручную
• STATIC_LIST — статический список
• DYNAMIC_LIST — динамический список

Настройки для способа ввода Из колонки (COLUMN):

Настройки для способа ввода Из переменной (VARIABLE):

Настройки для способа ввода Из модели данных (DATA_MODEL):

Настройки для способа ввода Задать формулой (FORMULA):

Настройки для способа ввода Задать агрегацией (AGGREGATION):

Настройки для способа ввода Ввести вручную (MANUALLY):

Настройки для способа ввода Статический список (STATIC_LIST):

Настройки для способа ввода Динамический список (DYNAMIC_LIST):

Пример использования блока actionButtons

widgets:
  - key: table (1)
    apiVersion: "17"
    type: TABLE
    settings:
      actionButtons:
        - name: Строки
          onClick:
            - type: EXECUTE_SCRIPT
              name: Добавить строки
              scriptKey: bf29c4de-8349-4e59-9e1b-f33c40bb1814
              parameters:
                - name: Товар
                  inputMethod: COLUMN
                  columnName: Товар
                  tableName: product_new
                  displayName: ""
                  isHidden: false
                  dbDataType: String
                - name: Цена единицы
                  inputMethod: COLUMN
                  columnName: Цена единицы
                  tableName: product_new
                  displayName: ""
                  isHidden: false
                  dbDataType: Float64
                - name: Комментарий
                  inputMethod: COLUMN
                  columnName: Комментарий
                  tableName: product_new
                  displayName: ""
                  isHidden: false
                  dbDataType: String
              autoUpdate: THIS_WIDGET
              description: ""
              activateCondition:
                formula: ""
                mode: FORMULA
          buttonType: primary
          color:
            mode: AUTO
          backgroundColor:
            mode: AUTO