Перейти к основному содержимому

Общие теги действий для проектов

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

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

Как создать общий тег​

В этой статье будет пошагово рассмотрен процесс разработки тега InputName, который позволит запросить у пользователя его имя и сохранить его в переменную $client.name.

подсказка
Процесс создания тега более подробно рассмотрен в статье Как создать свои теги действий. Рекомендуется ознакомиться с ней прежде, чем приступать к этой.

Шаг 1. Создайте проект​

Создайте новый проект под будущую библиотеку тегов. В этом проекте создайте директории и файлы для тега действия InputName. Итоговая структура проекта может иметь следующий вид:

├── src
│   ├── blocks
│   │   └── InputName
│   │       ├── block.json
│   │       └── block.sc
│   └── main.sc
├── test
│   └── test.xml
└── chatbot.yaml

Шаг 2. Задайте настройки тега​

В файле block.json задайте настройки тега.

подсказка
Чтобы сделать тег общим на аккаунт, укажите поле "sharedForAccount": true.
{
    "tagName": "InputName",
    "startState": "/Blocks/InputName",
    "scenarioFile": "blocks/InputName/block.sc",
    "sharedForAccount": true,
    "parameters": [
        {
            "name": "prompt",
            "type": "string",
            "required": true
        },
        {
            "name": "fallbackName",
            "type": "string",
            "required": true
        },
        {
            "name": "then",
            "type": "state",
            "required": false
        }
    ]
}

Шаг 3. Напишите сценарий​

В файле block.sc напишите сценарий тега.

# В сценарий подключается системный справочник личных имен.
# Он позволяет распознавать имена через именованный паттерн `$Name`.
require: name/name.sc
    module = sys.zb-common

theme: /Blocks

    state: InputName
        script:
            // Значения параметров тега копируются из объекта `$request.data.args` в `$session`.
            // Так к ним можно будет обращаться не только из `InputName`, но и из следующего стейта.
            $session.InputName = $request.data.args;
        # Бот отправляет сообщение с текстом, переданным в параметре `prompt`.
        a: {{$session.InputName.prompt}}

        state: CatchName
            # Стейт срабатывает по событию `noMatch`, поэтому бот попадет в него при любом вводе.
            # Однако отдельно прописана обработка ответа при помощи паттерна `$Name`.
            q: * $Name *
            event: noMatch
            script:
                // В `$client.name` записывается либо распознанное имя из справочника,
                // либо имя по умолчанию, переданное как параметр тега.
                $client.name = $parseTree._Name
                    ? $parseTree._Name.name
                    : $session.InputName.fallbackName;

                // Чтобы выйти из тега в основной сценарий, формируется ответ с типом `context-return`.
                var reply = { type: "context-return", data: {} };
                // Если следующий стейт передан в тег как параметр, он сохраняется как свойство ответа.
                // Иначе подходящий стейт будет определен динамически во время работы бота.
                if ($session.InputName.then) {
                    reply.state = $session.InputName.then;
                }
                // Из ответа формируется массив `$response.replies`.
                $response.replies = [reply];

Кроме того, поскольку бот из данного проекта не будет предполагать обычное взаимодействие, удалите из файла main.sc все заранее созданные стейты. Оставьте только стейт NoMatch со специальной логикой:

theme: /
    state: NoMatch
        event!: noMatch
        script:
            $response.replies = [{ type: "context-return", data: {} }];

Шаг 4. Включите тег​

  1. В секции customTags конфигурационного файла chatbot.yaml укажите путь к файлу с настройками:

    customTags:
      - src/blocks/InputName/block.json

  2. Нажмите в правом верхнем углу, чтобы сохранить изменения, сделанные в редакторе кода.

  3. Нажмите Тестировать бота, чтобы опубликовать сценарий.

подсказка
Если вы увидите в тестовом виджете ошибку Bot stack is empty, не волнуйтесь. Пользователи не будут запускать этого бота напрямую и не столкнутся с этой ошибкой.
предупреждение
Если в дальнейшем вы будете вносить изменения в сценарий тега, всегда сохраняйте и публикуйте их, чтобы они применились в других проектах.

Шаг 5. Используйте тег в других проектах​

Теперь вы можете перейти в любой другой проект и использовать только что созданный тег. Как любой другой тег, он будет доступен и в коде проекта, и в графическом редакторе J‑Graph как блок действия.

state: Start
    q!: $regex</start>
    a: Здравствуйте!
    InputName:
        prompt = Как вас зовут?
        fallbackName = незнакомец
        then = /Start/NiceToMeetYou

    state: NiceToMeetYou
        a: Очень приятно, {{$client.name}}!

Управление контекстом​

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

Переключение контекста​

Если тег действия является локальным (используется в том же проекте, в котором создан), то вызов тега равносилен переходу в начальный стейт этого тега через тег go! или метод $reactions.transition. Вернуться из него в основной сценарий также можно при помощи обычного перехода.

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

Возврат контекста​

Сценарий общего тега всегда должен заканчиваться возвратом контекста при помощи ответа с типом context-return. Пользователь не должен иметь возможности перейти из сценария тега куда-либо еще — для этого в примере выше из main.sc удалены почти все стейты, а возврат контекста добавлен и в глобальный NoMatch.

предупреждение
Если не предусмотреть context-return в общем теге, то пользователь «застрянет» в сценарии тега и не сможет продолжить общение с основным ботом.

Общие теги для всех пользователей​

On-premise

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

  1. Разработчики создают удаленный репозиторий с проектом JAICP, в который добавляют новый тег по инструкции выше. В настройках тега необходимо указать поле "sharedForPlatform": true.
  2. Системные администраторы должны добавить параметры репозитория в переопределяющую конфигурацию компонента EditorBE, после чего перезапустить компонент:
configs/hosts/{env_name}/editorbe/application-override.yml
system-projects:
  projects:
    # Системные проекты по умолчанию…

    - url: https://gitlab.custom.com/custom-tags  # URL репозитория.
      project-id: custom-tags  # ID проекта.
      bot-id: custom-tags  # ID бота. Может совпадать с project-id.
      branch: main  # Ветка в репозитории проекта, по умолчанию master.
подсказка
Для системных проектов с тегами действий всегда указывайте bot-id, чтобы такие проекты были опубликованы и JAICP могла переключать в них контекст через context-switch.
  1. Пользователи вашей установки JAICP смогут использовать новый тег так же, как все остальные встроенные теги.