Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions content/documentation/admin/actions/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,11 +105,11 @@ With this request body, the expression `{{ .property.project_id }}` is replaced

For built-in actions, the "Request body" parameter is part of the action configuration, and a configuration example is available.

### User form
### Properties

#### Parameters
#### Property settings

The "User form" section specifies the parameters that the user can fill in when launching the action. Property types are described in the [Properties](../../user/properties/) section.
The "Properties" tab specifies the parameters that the user can fill in when launching the action. Property types are described in the [Properties](../../user/properties/) section.

The following options are available for each parameter:

Expand Down
113 changes: 104 additions & 9 deletions content/documentation/admin/actions/overview.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,30 +109,125 @@ project_id: {{ .property.project_id }}

Для встроенных типов действий параметр «Тело запроса» является конфигурацией действия, при этом доступен пример данной конфигурации.

### Пользовательская форма
### Параметры

#### Параметры
#### Настройка параметров

В разделе «Пользовательская форма» указываются параметры, доступные пользователю для заполнения при запуске действия. Типы параметров описаны в разделе [«Параметры»](../../user/properties/).
На вкладке «Параметры» задаются параметры, доступные при запуске действия. Типы параметров описаны в разделе [«Параметры»](../../../user/properties/).

Для каждого параметра доступны опции:

- «Редактируемый» — позволяет изменить значение параметра при запуске действия. Если опция выключена, значение изменить нельзя.
- «Обязательный» — требует указания значения при запуске действия.
- «Скрытый» — параметр не отображается в пользовательской форме при запуске действия.
- «Редактируемый параметр» — позволяет изменить значение параметра при запуске действия. Если опция выключена, значение изменить нельзя.
- «Обязательный параметр» — требует указания значения при запуске действия.
- «Скрытый параметр» — параметр не отображается в пользовательской форме при запуске действия.

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

Действие принимает только параметры, объявленные в пользовательской форме. Если при запуске, например из процесса или через API, передан параметр, которого нет в форме, запуск завершается ошибкой `action "<slug>" does not declare property <name>`.

{{< alert level="info" >}}
Задайте значение по умолчанию для нередактируемых и скрытых параметров: при запуске действия пользователь не сможет их изменить.
Если обычный скрытый или нередактируемый параметр не заполняется автоматически, задайте значение по умолчанию.
При запуске действия пользователь не сможет его изменить.
{{< /alert >}}

Описание параметра отображается при запуске действия по кнопке со значком «info». Заполните описание: оно помогает понять назначение параметра и снижает риск ошибок при запуске.

В значениях параметров можно использовать шаблонные функции [Go template](https://pkg.go.dev/text/template). Например, выражение `{{ .entity.name }}` в значении параметра означает, что при запуске действия будет подставлено название сущности, для которой оно запускается.

#### Связанные сущности

Параметр типа «RelatedEntities» получает данные напрямую связанных сущностей.
Он настраивается на вкладке «Параметры» и используется при самостоятельном запуске,
в процессах и сценариях.

Для параметра доступны настройки:

- «Ресурс исходной сущности» — ресурс сущности, для которой запускается действие.
- «Направление связи» — «Родители — сущность действия на стороне потомка» получает родителей,
«Потомки — сущность действия на стороне родителя» — потомков.
- «Тип связи» — связь ресурсов, по которой выбираются сущности.
- «Количество результатов» — «Любое» допускает коллекцию, «Ровно одна сущность» требует один объект.
При автоматическом заполнении проверяется количество совпадений после отбора,
при ручном выборе — количество выбранных объектов.
- «Условия отбора» — необязательные условия для каждой связанной сущности.
«Объединение условий» определяет, должны ли выполняться все условия или хотя бы одно.

При создании параметр скрыт, нередактируем и получает все подходящие сущности автоматически.
Опции «Редактируемый параметр» и «Скрытый параметр» определяют способ заполнения:

| Редактируемый параметр | Скрытый параметр | Заполнение при запуске |
| --- | --- | --- |
| Выключен | Любое значение | Автоматически передаются все подходящие сущности; переданное через API значение игнорируется |
| Включён | Выключен | Пользователь выбирает одну или несколько сущностей; первоначальный выбор пустой |
| Включён | Включён | Без переданного значения автоматически используются все подходящие сущности; переданный через API выбор проверяется и учитывается |

Для ручного выбора включите «Редактируемый параметр» и выключите «Скрытый параметр».
Даже если подходит одна сущность, выберите её в форме запуска.
При значении «Любое» обязательность выбора задаёт опция «Обязательный параметр»;
при значении «Ровно одна сущность» выбор обязателен.
Для автоматического параметра опция «Обязательный параметр» выключена;
режим «Ровно одна сущность» всё равно требует ровно одно совпадение после отбора.

При передаче редактируемого параметра через API укажите UUID строкой для «Ровно одна сущность»
или массив UUID для «Любое». Для скрытого редактируемого параметра отсутствие ключа означает
автоматическое заполнение, а явно переданное пустое значение — пустой выбор.
Некорректные, повторяющиеся, несвязанные и исключённые отбором UUID отклоняются.

В условиях `.item` обозначает связанную сущность, `.entity` — сущность запуска.
Для сравнения с входными значениями доступны обычные параметры `.property`, параметры сценария
`.workflow`, процесса `.process`, контекст запуска `.context`, переменные `.global`, `.team`
и хранилище `.store`. Условия не могут обращаться к другим параметрам «RelatedEntities»,
учётным данным или ответу действия.

Например, для отбора по логическому параметру `primary` укажите
`{{ .item.properties.primary }}` в поле «Проверяемое значение» и выберите операцию «Истина».
Чтобы отбирать по параметру запуска `environment`, сравните
`{{ .item.properties.environment }}` с `{{ .property.environment }}` на равенство.

Нажмите «Проверить источник», выберите исходную сущность и нажмите «Показать связанные сущности».
Проверка показывает количество найденных и подходящих сущностей, результат отбора и JSON каждого объекта.
Она не запускает действие и не изменяет параметры сущностей.
Для проверки условий с входными значениями раскройте «Дополнительно: входные данные для проверки».
Для примера с `environment` задайте контекст:

```json
{
"property": {
"environment": "production"
}
}
```

Эти значения используются только для проверки отбора.

Результат параметра с идентификатором `related` доступен в `.property.related` и всегда является массивом,
в том числе при выборе одной сущности. Каждый объект содержит поля `slug`, `name`, `uuid` и `properties`.
При ручном выборе сохраняется порядок переданных UUID; автоматически полученная коллекция
упорядочена по идентификатору сущности, затем по UUID.

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

| Источник | Параметр сущности |
| --- | --- |
| `{{ (index .property.related 0).slug }}` | `related_slug` |
| `{{ (index .property.related 0).name }}` | `related_name` |

Целевые параметры должны быть объявлены в ресурсе исходной сущности.
Правила применяются после успешного выполнения действия.
Для записи всей коллекции как JSON-текста используйте источник `{{ .property.related | toJson }}`.
Для передачи массива следующим задачам настройте [запись в хранилище процесса](../processes/store/#сохранение-связанных-сущностей).

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

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

#### Условия параметров

Параметры могут автоматически скрываться или отображаться в пользовательской форме в зависимости от значения параметра типа `Boolean`. Настройка выполняется в разделе «Условия параметров», где задаются правила показа или скрытия для выбранных параметров.
Expand All @@ -145,7 +240,7 @@ project_id: {{ .property.project_id }}

| Контекст | Описание | Пример |
| ----------- | ------------------------------------------------------------------------ | ------------------------------------ |
| `.property` | Значения из пользовательской формы | `{{ .property.repo }}` |
| `.property` | Параметры действия, включая связанные сущности | `{{ .property.repo }}` |
| `.response` | Разобранный ответ действия (JSON) | `{{ .response.id }}` |
| `.entity` | Параметры сущности каталога, для которой выполняется действие | `{{ .entity.slug }}` |
| `.workflow` | Параметры сценария | `{{ .workflow.branch }}` |
Expand Down
Loading
Loading