Работа с типами ДП в смартах

Работа с числами

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

Результат деления чисел зависит от типов исходных данных (целое или десятичное число) — при делении целых чисел результатом будет целое число; если одно из чисел десятичное, то и результат будет десятичным числом.

Например:

• 1 / 5 = 0

• 1.0 / 5 = 0.2

• 1 / 5.0 = 0.2

• 1.0 / 5.0 = 0.2

При работе с десятичными числами (Decimal) функция Округлить ("Математические" — "Округлить") выполняет операцию округления, но возвращает не целое число, а десятичное с нулями после запятой. Чтобы получить целое число, используйте функцию ВЦелоеЧисло ("Строки" — "Преобразовать" — "ВЦелоеЧисло"):

Для преобразования числа в строку используется функция ВСтроку ("Числа" — "ВСтроку"):

Работа с датами

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

Для получения текущей даты используется функция ТекущиеДатаВремя(). Для формирования даты используется функция НовыеДатаВремя (год, месяц, день, час, минуты, секунды).

Пример: формирование даты последнего рабочего дня месяца и окончания рабочего дня (18 часов).

Для работы со сроками используются встроенные функции из подменю Добавить..., Разница..., Округлить....

Пример: округление даты.

Для преобразования даты в текст используется функция Отформатировать дату (дата, шаблон). Шаблон указывается в виде текстовой строки вида \'dd.MM.yyyy HH:mi\'.

Если пользователи системы территориально находятся в разных часовых поясах, в смарт-выражениях удобно использовать функцию ПеревестиВЧасовуюЗонуПользователя (дата_время, ID пользователя).

Пример: перевод времени, указанного в ДП "Плановое время созвона", во время по часовому поясу заказчика задачи.

Работа со строками

Для последовательного соединения строк можно использовать обычный оператор сложения "+", а для сравнения — знак равенства "=".

Строковые выражения заключаются в одинарные кавычки.

При использовании функции для проверки наличия подстроки в значении ДП в карточке задачи рекомендуется дополнительно применять проверку на пустые значения. Если ДП не заполнен в карточке, его значение становится равным null. В таком состоянии любая операция поиска или сравнения, включая проверку на содержание подстроки, будет возвращать false, даже если логически ожидается иной результат. Функция IsNullString проверяет, является ли строка пустой или null, и если это так, то возвращает значение строки2, которую можно задать как пустую или по умолчанию.

Формат: СтрокаСодержит(IsNullString(\'строка\', \'возвратить если NULL\'), \'что содержит\')

Пример:

Работа с логическими выражениями

Логические выражения могут принимать значения true или false. Логические выражения могут соединяться операторами "И" и "ИЛИ", при необходимости с использованием отрицания "НЕ".

Также возможно использование специальных логических операторов "есть значение", "нет значения" и "есть ложь":

В базе данных приложения для ДП типа "Галочка" (checkbox) хранятся как строковое значение "да" (true) или "нет" (false), так и бинарное значение 1 или 0. Для доступа к бинарному значению надо использовать свойство "Галочка":

Обращаться к нему можно таким образом:

Также можно использовать и текстовое значение:

Работа с ДП "Выбор пользователей"

Значениями ДП "Выбор пользователя" могут быть:

• пользователь или список пользователей;

• группа или список групп;

• элемент орг.структуры или список элементов орг.структуры.

В дереве сущностей для ДП типа "Выбор пользователей" есть отдельные "ветви" для каждого из этих трех типов значений:

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

Для работы с ДП "Выбор пользователей" используются конструкции формата JSON:

'{"Users":{"Deleted":[XX,...,XX],"Added":[XX,...,XX]},"Groups":{"Deleted":[XX,...,XX],"Added":[XX,...,XX]},"OrgUnits":{"Deleted":[XX,...,XX],"Added":[XX,...,XX]}}'

В качестве ключей выступают типы значений — "Users", "Groups", "OrgUnits". Для каждого из них, в свою очередь, используются ключи, обозначающие операцию — добавление ("Added") и удаление ("Deleted") элементов.

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

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

При изменении значения ДП с помощью смарт-автоматизации, если в параметре разрешено добавлять более одного элемента, новые пользователи добавляются к старым значениям, а не замещают их.

Пользователи

Чтобы в ДП "Выбор пользователя" записать одного или нескольких пользователей, надо указать список ID пользователя или список ID в формате {ID1, ID2, ...}. Например:

Орг.единицы

Чтобы в ДП "Выбор пользователя" записать одну или несколько орг. единиц, можно использовать следующие конструкции:

1. Напрямую (где "1234" и "5678" — это ID орг.единиц)

2. С помощью ДП (где "ДП_ID_орг.единицы" — это текстовый ДП, содержащий ID орг.единицы или список ID в формате {ID1, ID2, ...}.)

3. С помощью запроса (пример)

Группы

Чтобы в ДП "Выбор пользователя" записать одну или несколько групп, можно использовать следующие конструкции:

1. Напрямую (где "1234" и "5678" — это ID групп)

2. С помощью ДП (где "ДП_ID_группы" — это текстовый ДП, содержащий ID группы или список ID в формате {ID1, ID2, ...})

3. С помощью запроса (пример)

Работа с ДП "Адресаты Email"

Для работы с адресами E-mail используются конструкции формата JSON:

'{"ValsToAdd":[{"UserID":XX},...,{"Email":XX}],"ValsToDelete":[{"UserID":XX},...,{"Email":XX}]}'

Адресаты могут описываться по ID пользователя (ключ "UserID") или по адресу электронной почты (ключ "Email").

Для добавления адресатов в список используется ключ "ValsToAdd", а для удаления адресатов из списка — ключ "ValsToDelete".

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

Операция Пример записи Добавление пользователя с ID=1821 и внешним адресом электронной почты sdffd@mail.ru '{"ValsToAdd":[{"UserId":1821},{"Email":"sdffd@mail.ru"}]}' Добавление пользователя с ID, получаемым как результат выражения '{"ValsToAdd":[{"UserId":' + ВСтроку( ID заказчика ) + '}]}' Удаление пользователя с ID=14 и внешним адресом электронной почты fdsff@mail.ru '{"ValsToDelete":[{"UserId":14},{"Email":"fdsff@mail.ru"}]}' Если операция выполняется над несколькими пользователями, они перечисляются через запятую '{"ValsToAdd":[{"UserId":2372},{"UserId":2225},{"UserId":2211}]}' Smart-выражение может содержать несколько действий, в этом случае они перечисляются через запятую '{"ValsToAdd":[{"UserId":1821},{"Email":"sdffd@mail.ru"}],"ValsToDelete":[{"UserId":14},{"Email":"fdsff@mail.ru"}]}'

Работа с ДП Lookup

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

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

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

В результате формируется выражение вида:

Если какая-то категория содержит ДП типа Lookup или "Список выбора задач из категории" со ссылкой на данную категорию, то в дереве сущностей появится объект:

(причем для каждого такого ДП в дереве сущностей будет присутствовать отдельный объект)

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

Работа с ДП "Выбор нескольких задач из категории"

Значение ДП типа "Выбор нескольких задач из категории" представляет собой массив ID задач. В явном виде оно записывается так:

{ID1,ID2,...}

Например:

{12345,6789,34567,...}

где 12345, 56789, 34567 и т.д. — ID выбранных задач.

Для работы с ДП типа "Выбор нескольких задач из категории" используются типовые конструкции дерева сущностей:

Если какая-то категория содержит ДП типа "Выбор нескольких задач из категории" со ссылкой на данную категорию, то в дереве сущностей появится объект (причем для каждого такого ДП в дереве сущностей будет присутствовать отдельный объект):

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

Для редактирования значений ДП используются следующие конструкции:

Операция

Синтаксис

Пример

Удаление задачи из списка

'-'+ВСтроку(ID_задачи)

"-123456"

из списка значений ДП "Выбор нескольких задач в категории" удаляется задача с ID = 123456

Удаление нескольких задач из списка

см. пример 2 из пункта "Несколько операций в одном смарт-выражении"

Добавление одной задачи в список

ВСтроку(ID_задачи)

"123456"

в список значений ДП "Выбор нескольких задач в категории" добавляется задача с ID = 123456

Добавление нескольких задач в список

ID задач можно перечислять, используя разделитель ]||[:

ВСтроку(ID_задачи)+'||'+ВСтроку(ID_задачи)

"111111]||[222222]||[333333"

в список значений ДП "Выбор нескольких задач в категории" добавляются задачи с ID 111111, 222222, 333333

Обновление комментария по выбранному значению

'='+ВСтроку(ID_задачи)+'||'+"текст_комментария"

"=123456||текст_комментария"

в списке значений ДП "Выбор нескольких задач в категории" для задачи с ID = 123456 добавляется комментарий с текстом "текст_комментария"

Несколько операций в одном смарт-выражении

Множество операций можно объединять через '#'

"-111111#222222||текст_комментария"

в списке значений ДП "Выбор нескольких задач в категории" удаляется задача с ID = 111111 и добавляется задача с ID = 222222 с комментарием "текст_комментария"

"-111111#-222222#-333333"

из списка значений ДП "Выбор нескольких задач в категории" удаляются задачи с ID 111111, 222222, 333333

Полная замена всех значений

Чтобы полностью заменить текущий набор значений ДП «Выбор нескольких задач из категории», передайте строку со списком ID задач с разделителем ]||[ и префиксом $. В этом режиме существующие значения ДП будут полностью очищены и заменены переданным набором.

Синтаксис: '$' + ВСтроку(ID1) + ']||[' + ВСтроку(ID2) + ']||[' + ...

Например, значение $123]||[456]||[789 полностью заменит текущий набор значений на задачи с ID 123, 456 и 789.

Работа с ДП "Таблица"

Работа с данными в ДП типа "Таблица" осуществляется на уровне строк: если надо добавить или изменить значение в ячейке таблицы, то происходит обращение ко всей строке таблицы. Для работы со строками таблицы используются конструкции формата JSON.

Ячейка таблицы описывается конструкцией вида:

ID_колонки:{"First":ХХ,"Second":YY}

В ключе "First" (вместо XX) указывается вносимое значение. Его тип должен соответствовать типу колонки. При формировании строки значение должно преобразовываться к текстовому виду. Например, для числового значения — с помощью функции ВСтроку(). Текстовые значения должны быть заключены в двойные кавычки.

Ключ "Second" для большинства ячеек может не указываться.

Строка таблицы описывается как набор ячеек:

{"First":"ID_строки","Second":{ID_колонки:{"First":ХХ,"Second":YY},...,ID_колонки:{"First":ХХ,"Second":YY}}}

Перед описанием строки ставится знак операции: "+" для добавления строки, "-" для удаления строки или "=" для изменения значений.

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

ℹ️ При добавлении или изменении строки в ДП "Таблица" с помощью смарт-автоматизаций некоторые символы необходимо экранировать.

Двойные кавычки " необходимо экранировать символом обратного слеша \: '123:{"First":"начало \"ABC\" продолжение"}'. Символ обратного слеша \ необходимо повторять дважды: '123:{"First":"начало \\\\ продолжение"}'. Символ одинарной кавычки \' необходимо повторять дважды (в примере ниже подстрока АВС окружена одинарными кавычками, повторенными дважды): '123:{"First":"начало ''ABC'' продолжение"}'. Перенос строки \n \r экранировать не надо (перенос строки работает только для колонок "Большой текст", в режиме чтения перенос отображается как пробел, в режиме редактирования — как перенос): '123:{"First":"первая строка \n \r вторая строка"}'

Добавление новой строки

При добавлении новой строки достаточно указать только те колонки, где в ячейках есть значения, пустые колонки можно пропустить. Поскольку при добавлении новой строки значение "ID_строки" не известно, оно не указывается. Массив с описаниями ячеек заключается в квадратные скобки [ ]. ID_колонки не берется в кавычки.

'+[{ID_колонки:{"First":ХХ,"Second":YY},...,ID_колонки:{"First":ХХ,"Second":YY}}]'

Пример добавления строки:

'+[{111:{"First":"' + ДП1 + '"},222:{"First":"'+ ВСтроку(ДП2) +'"}}]'

В данном примере 111 и 222 -- ID колонок таблицы (их можно посмотреть в настройках изменяемого ДП "Таблица"). ДП1, ДП2 -- вносимые значения (в данном примере ДП1 — текстовый параметр, а ДП2 — числовой).

Пример добавления строки с ДП Выбор пользователей:

Пример 1: '{"Users":{"Deleted":[XX,...,XX],"Added":[XX,...,XX]},"Groups":{"Deleted":[XX,...,XX],"Added":[XX,...,XX]},"OrgUnits":{"Deleted":[XX,...,XX],"Added":[XX,...,XX]}}'

В данном примере используются конструкции формата JSON. В качестве ключей выступают типы значений — "Users", "Groups", "OrgUnits". Для каждого из них, в свою очередь, используются ключи, обозначающие операцию — добавление ("Added") и удаление ("Deleted") элементов. В качестве значений (вместо XX) подставляются, соответственно, ID пользователей, групп или орг.единиц, преобразованные в текст.

Пример 2: '+[{9:{"First":"{\"Users\":{\"Added\":[2122]}}"}}]'

В данном примере 9 — это ID колонки в ДП "Таблица", а 2122 — ID пользователя, выбранного в ДП "Выбор пользователей".