Выражение Языка

Язык выражений (произносится как «эксперт» без буквы «т») — это простой язык, который позволяет указать «выражение» или формулу, которая рассчитывается для задачи или другого элемента.

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

• Столбцы формулы — выражение вычисляется для каждой видимой строки в отображаемой структуре или результате запроса.
• Автоматизация — формулы можно использовать для фильтрации структуры (Фильтрация по атрибуту), сортировки структуры (Сортировка по атрибуту) или группировки задач (Группировка по текстовому атрибуту) на основе результатов формулы.
• Эффекторы — результаты формулы можно записать в поле Jira с помощью эффектора поля «Атрибут для задачи».

Основы Expr просты в изучении, и все же язык достаточно мощен для решения сложных задач. Следующее руководство охватывает основные требования языка Expr.

Для более глубокого изучения см. Справочник по языку Expr и Справочную документацию по формулам.

Языковые компоненты

Выражение может содержать одно или несколько из следующего:

• Переменные — они сопоставляются с атрибутами, такими как поля задач, настраиваемый прогресс или значение из другого столбца.

• Арифметические и логические операции — сложение, вычитание, умножение, деление или сравнение элементов.
• Числа
• Текстовые строки
• Вызовы функций — применяют определенные вычисления к предоставленным аргументам и возвращают результат, который будет использоваться в выражении.
• Доступ к свойствам — получение значения определенного свойства элемента, например даты выпуска версии исправления.
• Условные («ЕСЛИ») выражения — вычисляют разные результаты на основе заданного набора критериев.

Есть и более продвинутые конструкции:

• Агрегатные функции — вычисление агрегата (например, суммы или среднего) значений выражения, рассчитанных для нескольких элементов в структуре.
• Локальные переменные — введите значение и повторно используйте его в формуле несколько раз.
• Пользовательские функции — определение функции или функционального выражения для повторного использования в формуле или применения к массиву значений.
• Запросы JQL и S-JQL внутри формулы — обусловливают результаты в зависимости от того, соответствует ли элемент запросу.
• Комментарии — документируйте большие формулы.

Типы значений

С помощью Expr вы можете создавать формулы, которые работают с:

• Базовые значения — числа и текст, которые либо являются частью формулы, либо считываются из простого атрибута или поля Jira, например из сводки задачи или пунктов истории.
• Элементы — значения, представляющие конкретный объект, например «Пользователь», «Проблема», «Журнал работ», «Статус» и другие, и обычно считываемые из соответствующего поля Jira.
• Значения массива — последовательность значений, позволяющая представлять поля с несколькими значениями, такие как Fix Versions или несколько Entities, в случае атрибута рабочих журналов.
• Значения пользовательской функции — представляют часть формулы, которая обычно применяется к каждому элементу массива, например, для фильтрации.
• Карты ключ-значение — в редких случаях эти значения создаются предоставленными функциями, такими как GROUP.
• Неопределено (“Undefined”) — специальное значение, означающее «ничего» или «нет значения».
• Значения ошибок – выдаются, если возникла проблема с вычислением формулы.

Переменные

 Переменные — это определяемые пользователем имена, которые представляют атрибуты, такие как:

• Поля задач Jira
• Вычисляемые атрибуты, такие как Progress
• Атрибуты, специфичные для структуры, такие как тип элемента
• Атрибуты, предоставляемые другими приложениями Jira
• Другая формула
• Значения из другого столбца структуры

Именование переменных

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

 Примеры:

• priority
• sprintName
• remaining_estimate
• abc11

Пока вы пишете формулу, Structure пытается сопоставить ваши переменные с известными атрибутами. Например, указанная выше переменная «remaining_estimate» будет автоматически сопоставлена с полем «Оставшаяся оценка». Дополнительные сведения см. в разделе Отображение переменных.

Вызовы функций

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

 Примеры:

• SUM(-original_estimate, remaining_estimate, time_spent)
• CASE(priority, 'High*', 5, 1)
• TODAY()

Имена функций нечувствительны к регистру. Вы можете написать TODAY()

или Today()

В Structure доступно более 100 стандартных функций — полный список см. в Справочнике по функциям Expr.

i)

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

i)

Сцепленные вызовы функций

Сцепленная нотация позволяет вам легко применять последовательность функций к значению, просто перечисляя каждую функцию одну за другой, разделяя их точкой ( . ).

• Стандартное обозначение: F3(F2(F1(x)))
• Обозначение цепочки: x.F1().F2().F3()

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

Например:

КОД
created.FORMAT_DATETIME("yyyy").CONCAT(" year issue")

В этом примере FORMAT_DATETIME принимает значение даты в поле «создано» и форматирует его на основе аргумента в скобках («yyyy»). CONCAT берет результат из FORMAT_DATETIME и объединяет его с " year issue" «задачей года».

Числа и текстовые строки

Числа

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

Текстовые строки

Текстовые строки представляют собой последовательность символов, заключенную либо в одинарные ('), либо в двойные кавычки ("). Примеры:

• 'текст в одинарных кавычках может содержать " (двойная кавычка)"
• "текст в двойных кавычках может содержать '(одинарную кавычку)"
• ""

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

• Последовательность из двух обратных косых черт (\\) преобразуется в одну обратную косую черту (\).
• Последовательность обратной косой черты и одинарной кавычки (\') преобразуется в символ одинарной кавычки (') для текстовых значений, заключенных в одинарные кавычки.
• Последовательность обратной косой черты и двойной кавычки (\") преобразуется в символ двойной кавычки (") для текстовых значений, заключенных в двойные кавычки.

Фрагменты текста

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

Фрагмент должен быть заключен в """ (три двойных кавычки, в начале и в конце)

Фрагмент выражения вводится с помощью символа «$» и должен быть заключен в фигурные скобки { }

CODE
1 """ $var1 + $var2 = ${var1 + var2} """
2
3 """ this $glass is half-${IF optimist: 'full' ELSE: 'empty'} """

Операции

Expr обеспечивает основные арифметические операции, сравнения, текстовые операции и логические операции.

Порядок операций

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

1. Арифметические операции
2. Текстовые операции (CONCAT)
3. Операции сравнения
4. Логические операции.

Подробную спецификацию см. в справочнике по языку Expr.

Доступ к свойствам

Формулы могут получить значение свойства элемента, используя следующую нотацию: object.property

CODE
fixVersion.releaseDate // /возвращает дату релиза fixVersion

Вы также можете связать несколько вызовов свойств вместе:

CODE
project.lead.emailAddress //возвращает адрес электронной почты лида для проекта

Полный список поддерживаемых свойств см. в разделе Справочник по свойствам элемента.

Условное выражение

Простые выражения «ЕСЛИ» могут быть объявлены с помощью функции ЕСЛИ(), но для более сложных случаев ЕСЛИ, с несколькими условиями и/или требующих опции ELSE, можно использовать условное выражение.

CODE
WITH total = x + y:
IF total > 0:
x / total
ELSE : error

Примечание: «:» после «ELSE» не является обязательным — в приведенном выше примере мы включили его для удобства чтения.

Расширенные конструкции

Локальные переменные

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

КОД
IF time_spent + remaining_estimate > 0 :
time_spent / (time_spent + remaining_estimate)

Вы можете видеть, что в этой формуле мы используем «затраченное время + оставшаяся_оценка» дважды — один раз, когда мы проверяем, что это не ноль (чтобы мы не делили на ноль), и снова, когда мы делим на него.

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

КОД
WITH total_time = time_spent + remaining_estimate :
IF total_time > 0 :
time_spent / total_time

Вы можете последовательно определить несколько локальных переменных. Вы также можете использовать ранее определенные локальные переменные при определении дополнительных локальных переменных. Например:

КОД
WITH total_time = time_spent + remaining_estimate :
WITH progress = (IF total_time > 0 : time_spent / total_time) :
IF(progress > 0.5, "Great Progress!", progress > 0.2, "Good Progress", "Needs Progress!")

ü

Обратите внимание на положение двоеточия (":") — оно должно стоять там, где заканчивается определение каждой локальной переменной.

ü

Агрегатные функции

Агрегатная функция вычисляет некоторое совокупное значение (например, сумму или минимум) на основе значений в ряде строк, как правило, для всех подпроблем. Агрегатные функции написаны очень похоже на стандартные функции, за исключением того, что они используют фигурные скобки: SUM{x}.

 Примеры:

• SUM { remaining_estimate + time_spent }— вычисляет общие усилия (оценочные и фактические) для проблемы и всех ее подзадач.
• MAX { resolved_date - created_date }— вычисляет максимальное время, которое потребовалось для решения проблемы, среди проблемы и ее подзадач.

Они также могут содержать модификаторы, влияющие на работу агрегации:

• SUM#all { business_value }— это заставит функцию включить значения из всех повторяющихся элементов в итог. (По умолчанию дубликаты игнорируются.)

Полный список доступных агрегатных функций и модификаторов см. в справочнике по агрегатным функциям.

Пользовательские функции

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

КОД
WITH square(x) = x * x :
square(impactField) / square(storyPoints)

В этом примере пользовательской функции дается имя («квадрат»), а затем она используется для выполнения одних и тех же вычислений в нескольких полях. Чтобы узнать больше, см. справочник по языку.

Пользовательские функции для массивов — использование символа «$»

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

КОД
worklogs.FILTER($.author = ME())

В этом примере "$" указывает структуре применить "author = ME()" к каждому элементу в рабочих журналах - если автор является текущим пользователем, он возвращает true, и этот рабочий журнал будет включен в результаты FILTER.

Этот метод становится очень мощным, когда вы объединяете вместе несколько пользовательских функций. Чтобы узнать больше, см. справочник по языку.

Встроенные запросы (JQL и S-JQL)

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

1 (истина), если текущая строка соответствует запросу

0 (ложь) иначе

Например:

КОД
// Соберите общее количество баллов за все подзадачи, назначенные членам группы Team2, если только истории не находятся в папке «Особые».
SUM {
IF JQL { assignee in membersOf("Team2") } :
IF NOT SJQL { descendant of folder("Special") } :
storyPoints
}

Поскольку JQL — это запрос на основе Jira, он будет работать только с задачами; результат будет 0 для других типов элементов. S-JQL можно использовать для более сложных запросов, применимых ко всей структуре.

Комментарии

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

Чтобы добавить одну строку комментария, начните комментарий с //

Чтобы добавить несколько строк комментария, начните комментарий с /* и завершите комментарий */

Пример:

КОД
// Это однострочный комментарий.
/* Это многострочный комментарий.
Это может быть полезно для более длинных объяснений. */

По материалам Atlassian JIRA Structure: Expr Language