Справочник переменных смарт-действий¶

Переменные вида @ContextID, @EventParam0, @cycle_value и т.д., которые подставляются в SmartExpressions (T-SQL / ESQL), смарт-фильтрах, CustomFlex SQL. Одно место для поиска вместо обхода трёх разных доменных файлов.

Переменные @authorId, @subcatId в таблице ниже — SQL-параметры хранимых процедур и JS-скриптов, не SMART-переменные платформы. Они включены со сноской для полноты.

Таблица переменных¶

Переменная	Регистр	Тип	Значение	Где доступна	Источник
`@ContextID`	регистронезависим (`@ContextId` = то же)	int	ID текущей задачи (TaskID)	SmartExpression T-SQL, ESQL-обёртка `WrapCommandTextInContext()`	`docs/domains/smart-filters/backend.md:341`, `docs/domains/smart-actions/academy-patterns.md:291`
`@EventParam0`	регистронезависим	зависит от события	Параметр 0 текущего события; для события подписи — ID задачи-акцептанта	SmartExpression с привязкой к событию (`eventId != null`)	`docs/domains/smart-actions/academy-patterns.md:292,352`
`@EventParam1`	регистронезависим	зависит от события	Параметр 1 события; для события «открытие задачи» — контекст открытия; для ДП Lookup — ID текущей категории	SmartExpression с привязкой к событию; ДП Lookup смарт-фильтр	`docs/domains/smart-actions/known-issues.md:64`, `docs/domains/ext-params/lookup/settings-reference.md:35`
`@EventParam2`	регистронезависим	зависит от события	Параметр 2 события; для ДП Lookup — ID задачи-источника; для портала (каскадный dropdown) — выбранное значение родительского параметра	SmartExpression с привязкой к событию; каскадные dropdown в портале	`docs/domains/ext-params/lookup/settings-reference.md:36`, `docs/domains/portal/admin.md:105`
`@EventParam3`	регистронезависим	string (JSON)	Параметр 3 события; для ДП Lookup — JSON значений строки таблицы (если Lookup в колонке ДП Таблица)	ДП Lookup смарт-фильтр	`docs/domains/ext-params/lookup/settings-reference.md:37`
`@EventParam4`	регистронезависим	int	Параметр 4 события; для ДП Lookup — ID блока	ДП Lookup смарт-фильтр	`docs/domains/ext-params/lookup/settings-reference.md:38`
`@EventParam{N}`	регистронезависим	зависит от события	Параметр с индексом N (от 0); именуются `@EventParam0`, `@EventParam1`, ...	SmartExpression с eventId; T-SQL — через `AddNeededQueryParams()` по тексту	`docs/domains/smart-filters/backend.md:154–155`
`@eventParamRaw{N}`	регистронезависим	любой (TVP-compatible)	«Сырой» вариант параметра события N; поддерживает TVP для `IEnumerable<int/string/DateTime>`	SmartExpression T-SQL (только через RawParamsProvider, не в XSLT/ESQL)	`docs/domains/smart-filters/backend.md:164`
`@cycle_value`	строчный	string	Текущее значение итератора в цикле пакета действий	SmartExpression внутри циклического пакета (`IsCyclic = true`)	`docs/domains/smart-filters/backend.md:185,339`, `docs/domains/smart-filters/backend.md:80`
`@cycle_idx`	строчный	int	Индекс текущей итерации (от 0)	SmartExpression внутри циклического пакета	`docs/domains/smart-filters/backend.md:184,340`
`@CurrentSessionUserID`	строчный	int	ID текущего пользователя (сессионный); в ShowTasksFeed текстово заменяется на `@UserID` до исполнения	SmartExpression T-SQL; CustomFlex SQL в ShowTasksFeed	`docs/domains/smart-filters/backend.md:342`, `docs/domains/grids/showtasksfeed.md:381`

Примечание: переменные в JS-скриптах и SP (не SMART-переменные платформы)¶

Следующие идентификаторы встречаются в SQL-параметрах SP и JS-скриптах Анфисы — это обычные SQL-параметры, не «подстановочные» переменные платформы SmartExpressions:

Идентификатор	Контекст	Источник
`@authorId`	SQL-параметр в JS-скриптах Анфисы (agent-tools-user.js, agent-persist.js)	`docs/domains/ai/scripts/module-agent-tools-user.js:54`
`@subcatId`	SQL-параметр SP и JS-фильтров Анфисы	`docs/domains/ai/scripts/module-agent-tools-user.js:196`
`@SubcatID`	SQL-параметр большинства системных SP (ShowTasksFeed, tc_SubcategoryDenormalize и др.)	`docs/domains/grids/showtasksfeed.md:88`
`@UserID`	SQL-параметр ShowTasksFeed; итоговое имя после замены `@CurrentSessionUserID`	`docs/domains/grids/showtasksfeed.md:387`

Механизм подстановки¶

T-SQL ветка (TSqlContent)¶

Провайдеры сканируют текст T-SQL на наличие своих имён параметров (AddNeededQueryParams) и добавляют ObjectParameter[]:

ExpressionParamsProvider — @EventParam0..@EventParamN
RawParamsProvider — @eventParamRaw0..@eventParamRawN
CycleExpressionVarsProvider — @cycle_value, @cycle_idx
ExpressionVarsProvider — именованные переменные из результатов предыдущих действий пакета

ESQL ветка (XML Content)¶

XSLT-трансформация ExpressionXmlToESQL.xslt генерирует ESQL-строку. Затем WrapCommandTextInContext() оборачивает в:

SELECT value (<expr>) FROM Tasks as t WHERE t.TaskID = @ContextID

XML-узлы и соответствующие провайдеры:

XML-узел	Результат в SQL
`<eventparameter index="N">`	`@EventParamN`
`<cyclevariable name="X">`	`@cycle_value` / `@cycle_idx`
`<variable name="X">`	`@X_` (результат действия пакета)

Источник: docs/domains/smart-filters/backend.md:134–137

Примеры контекстов¶

SmartExpression T-SQL: расчёт срока по контекстной задаче¶

SELECT
   CASE
       WHEN Extparam84NativeValue IS NOT NULL
            AND Extparam71NativeValue > GETDATE()
       THEN dbo.tc_AddWorkingDays(Extparam71NativeValue, 1)
       ELSE dbo.tc_AddWorkingDays(GETDATE(), 1)
   END
FROM TasksInSubcat21Denormalized
WHERE Taskid = @ContextID

Источник: docs/domains/smart-actions/academy-patterns.md:300–313

SmartExpression T-SQL: проверка акцептантов подписи¶

Для акцептантов контекст задачи передаётся через @eventParam0 (не @ContextId):

if exists (
    select u.UserID
    from TasksInSubcat22Denormalized t22 (nolock)
    join ExtParamSelectUsersValues epvu (nolock)
        on t22.TaskID = epvu.TaskID and epvu.ExtParamID = 76
    join Users u (nolock)
        on u.UserID = epvu.UserID
    where t22.TaskID = @ContextId      -- ← обычный контекст
        and u.IsFired_2 = 0
    )
  select 1
else
  select 0

Для случая подписи: параметр задачи — @eventParam0, не @ContextId.

Источник: docs/domains/smart-actions/academy-patterns.md:331–352

SmartExpression T-SQL: циклический пакет¶

select ExtParam1567NativeValue
from TasksInSubcat1725Denormalized
where taskid = try_cast(@cycle_value as int)

@cycle_value — текущий элемент итератора (string). Используется try_cast, так как тип итератора — string.

Источник: docs/domains/smart-filters/backend.md:78–80

ESQL ветка (XML Content): сравнение параметра события с полем задачи¶

<?xml version="1.0" encoding="utf-16"?>
<smartfilter>
  <property name="TaskID" />
  <operator key="eq" />
  <eventparameter index="1" />
</smartfilter>

Результат ESQL: t.[TaskID] = @EventParam1, обёрнутый в:

SELECT value (t.[TaskID] = @EventParam1) FROM Tasks as t WHERE t.TaskID = @ContextID

Источник: docs/domains/smart-filters/backend.md:56–70

ДП Lookup: смарт-фильтр с контекстными параметрами¶

При открытии карточки задачи SmartFilter ДП Lookup получает:

@eventParam1 — ID текущей категории (SubcatId)
@eventParam2 — ID задачи-источника (TaskId)
@eventParam3 — JSON значений строки таблицы (если Lookup в колонке ДП Таблица)
@eventParam4 — ID блока

Источник: docs/domains/ext-params/lookup/settings-reference.md:35–38

Событие «Открытие задачи»: нетипичное использование @eventParam¶

Событие WhenOpenTask передаёт контекст открытия в @eventParam1 (не @eventParam0). @eventParam0 у данного события не используется — нетипичное поведение.

Источник: docs/domains/smart-actions/known-issues.md:64

Ограничения¶

@ContextID в фильтре расписания. Фильтр расписания — T-SQL, возвращающий список задач (не boolean). @ContextID в нём не имеет смысла: нет «текущей задачи». Если WHERE TaskID = @ContextID остался от конвертации смарт-выражения в TSQL — убрать. Источник: docs/domains/smart-actions/action-package-pitfalls.md:101
@EventParam{N} доступен только при наличии eventId. ExpressionParamsProvider создаётся только если eventId.HasValue. В SE без привязки к событию @EventParamN — не подставляется. Источник: docs/domains/smart-filters/backend.md:150
@cycle_value и @cycle_idx — только в циклическом пакете. CycleExpressionVarsProvider создаётся только при ActionPackContext.CycleContext != null. В обычном пакете эти переменные недоступны. Источник: docs/domains/smart-filters/backend.md:182–185
@cycle_value — строка, не int. Тип string; при использовании как ID задачи применять try_cast(@cycle_value as int). Источник: docs/domains/smart-filters/backend.md:254
@cycle_value не может быть null. Если итератор возвращает null-элемент — CycleExpressionVarsProvider выбрасывает ArgumentNullException (известная ошибка, не пофиксена). Источник: docs/domains/smart-filters/backend.md:263–283
@CurrentSessionUserID — текстовая замена в ShowTasksFeed. В SmartExpression это SQL-параметр. В SP ShowTasksFeed он текстово заменяется на @UserID (строка 263 SP) до вызова sp_executesql. Источник: docs/domains/grids/showtasksfeed.md:381
generateDummyParams: true подставляет @ContextId = -1. При тестировании SE через Admin API с этим флагом JOIN на контекстную задачу вернёт пустой результат, но синтаксическая валидация пройдёт. Источник: docs/domains/smart-filters/admin.md:182,206
Регистр переменных. В T-SQL-ветке провайдеры сканируют текст без учёта регистра (@ContextID, @ContextId, @contextid — одно и то же). В ESQL-ветке регистр определяется XSLT. На практике — писать как угодно, платформа найдёт.

Связанные документы¶

academy-patterns.md — практические паттерны SmartExpressions и T-SQL
admin.md — настройка SmartActions, событий, пакетов
../smart-filters/backend.md — провайдеры параметров, XSLT, ESQL-механика
../smart-filters/admin.md — Admin API, тестирование SE, dummy params
../ext-params/lookup/settings-reference.md — контекстные @eventParam в ДП Lookup
../grids/showtasksfeed.md — CustomFlex SQL параметры, @CurrentSessionUserID

Review log¶

(Заполнит main Claude при ревью.)