UI Designer

С версии 2.15.260227 появилась возможность для создания кастомных интерактивных веб-форм с помощью продукта UI Designer.

Oktell UI Designer (далее UI Designer) — самостоятельный программный продукт для создания интерактивных веб-форм и диалоговых форм оператора. Он разработан отдельно от коммуникационной платформой «Oktell» (далее Oktell) и не является её модулем, надстройкой или производным продуктом. В этой инструкции описан один из способов применения продукта — интеграция с контакт-центром на базе коммуникационной платформой «Oktell» через открытый механизм веб-форм. Тот же способ подключения подходит и для других систем, умеющих отображать веб-страницу по ссылке.

1. О решении

UI Designer — это конструктор интерактивных веб-форм с визуальным редактором. Он позволяет описывать экран оператора в виде декларативного состояния (JSON) и отображать его в браузере, а также обновлять содержимое формы по запросу — например, при получении новых данных о звонке или заявке. Продукт распространяется в виде отдельных сборок и работает в двух режимах:

– режим просмотра — отображает готовую форму оператору;

– режим редактирования (конструктор) — открывает визуальный редактор формы, доступный по отдельному GET-параметру (см. раздел 6).

Интеграция с внешней системой (в данном случае — с Oktell) выполняется через веб-страницу, которой передаются параметры сессии в адресной строке, и через файл конфигурации, который указывает, какой сценарий на стороне Oktell обрабатывает запросы формы.

2. Что потребуется

– доступ к серверу Oktell, на котором нужно разместить сборку UI Designer;

– права на редактирование файлов в веб-каталоге сервера Oktell (папка WWW);

– текстовый редактор с подсветкой синтаксиса — например, Notepad++;

– доступ к скрипт-конструктору Oktell — для настройки сценария, который будет обрабатывать запросы формы, и для указания ссылки на форму в диалоговом сценарии оператора.

3. Введение

UI Designer входит в состав пакета обновлений Oktell. Убедитесь, что UI Designer установлен – проверьте наличии папки SRV\WWW\UIDesigner на сервере Oktell.Если папка отсутствует на сервере Oktell – обратитесь к партнеру OOO «Телефонные системы» для уточнения возможности получения и применения продукта. Из перечисленных файлов и папок для настройки интеграции важны:

– static — служебные файлы приложения (см. предупреждение в разделе 10);

– form.ajax.js.execsvcscriptplain — конфигурация сценария обработки формы на стороне Oktell (раздел 4);

– state.js — начальное состояние формы (раздел 6);

– index.html — точка входа, по которой форма открывается в браузере.

4. Укажите проект и сценарий обработки формы

Файл form.ajax.js.execsvcscriptplain — текстовый; откройте его в Notepad++ или любом другом текстовом редакторе. В нём указано, какой сценарий Oktell (и в каком проекте) будет обрабатывать запросы, поступающие от формы.

Пример: в Oktell может быть несколько проектов со сценариями — выберите тот, что относится к вашей интеграции.

В файле укажите название вашего проекта (projectname) и название служебного сценария обработки формы (scriptname), например:

Значение scriptname должно точно совпадать с названием сценария в Oktell, который вы настроите на обработку запросов формы (например, _constructor).

5. Настройте обработку событий в сценарии Oktell

Сценарий, указанный на предыдущем шаге, должен уметь обрабатывать события, которые присылает UI Designer — как минимум load (запрос актуального состояния формы) и, при необходимости, загрузку файлов (upload). Ниже — пример типовой структуры такого сценария: приём GET-параметров, разбор запроса и ветвление по типу события.

Пример схемы сценария: приём параметров, разбор запроса и обработка события load:

Логика внутри блоков (что именно отдавать в ответ на load, upload и на ошибочные запросы) зависит от вашей задачи — это обычная часть сценария Oktell, которую вы описываете в скрипт-конструкторе самостоятельно. Со стороны UI Designer важно только то, что ответ должен возвращать состояние формы в ожидаемом формате (см. следующий раздел).

6. Настройте начальное состояние формы

Файл state.js задаёт базовое (первоначальное) состояние формы, которое загружается при первом открытии. Чтобы форма отрисовалась с актуальным состоянием, в главном контейнере main должны быть заданы событие onInit и метод load, который запросит обновлённое состояние с сервера. Пример:

 "main": {
   "type": "container",
   "width": "100%",
   "height": "100%",
   "layout": "row",
   "paddings": {
     "left": "10px",
     "right": "10px",
     "top": "10px",
     "bottom": "10px"
   },
   "childs": [
     "messages-box"
   ],
   "bgColor": "secondary",
   "events": [
     {
       "event": "onInit",
       "method": "load"
     }
   ]
 }

7. Подключите форму к диалоговому сценарию оператора

В диалоговом сценарии Oktell, отвечающем за операторскую задачу, укажите веб-форму по ссылке, сформированной по следующему принципу: http://<ip-адрес сервера>:4055/<имя папки>/index.html?id=<id сессии>&login=<логин>&password=<пароль> где <имя папки> — название, которое вы задали папке со сборкой на шаге 3 (в примерах выше — constructor). Значения параметров id, login и password описаны в справочнике параметров (раздел 9).

8. Откройте режим редактирования формы

Чтобы открыть в браузере сам конструктор (визуальный редактор формы, а не отрисованную готовую форму), перейдите по ссылке: http://<ip-адрес сервера>:4055/constructor/index.html?editor=1&emulateApi=1&persistState=1&syncTabs=1 На заметку GET-параметры передаются как строка, поэтому значения "false" и "true" в них равнозначны — оба приводятся к true. Чтобы включить параметр, укажите любое непустое значение (например, editor=1); чтобы отключить — оставьте его пустым (например, editor=).

9. Справочник GET-параметров

Параметр По умолчанию Описание id — Идентификатор сессии обращения клиента. Передаётся при каждом запросе к серверу. editor false Включает режим редактирования формы (сам конструктор). В дальнейшем планируется разделение на отдельные сборки редактора и просмотрщика. emulateApi false Отключает реальные запросы к серверу — данные эмулируются на стороне клиента. persistState false Сохраняет текущее состояние формы в LocalStorage браузера. Удобно при разработке — не используйте в production. syncTabs false Синхронизирует действия между вкладками одного браузера: действие в одной вкладке повторяется в остальных. Удобно при разработке — не используйте в production, так как замедляет работу. wsDisable false Отключает интеграцию по WebSocket. login — Логин пользователя с разрешённым доступом к web-api. password — Пароль пользователя с разрешённым доступом к web-api, в виде MD5-хэша.

10. Важно при переносе в production

Предупреждение В каталоге static/js собираются файлы вида 0.*.chunk.js, 1.*.chunk.js и main.*.js. Файл 1.*.chunk.js отвечает за работу режима редактирования (editor=1). Если удалить его при подготовке production-сборки, редактор формы перестанет открываться — просмотр готовых форм операторами при этом продолжит работать в обычном режиме. Также для production не рекомендуется использовать параметры persistState и syncTabs — они предназначены для удобства разработки и могут замедлять работу формы у операторов.

11. Итоговый чек-лист

☐ Сборка UI Designer присутствует в папке WWW сервера Oktell.

☐ В form.ajax.js.execsvcscriptplain указаны верные projectname и scriptname.

☐ Сценарий Oktell обрабатывает событие load (и другие нужные события, например upload).

☐ В state.js настроены начальное состояние и событие onInit → load.

☐ В диалоговый сценарий оператора добавлена ссылка на форму с нужными GET-параметрами.

☐ Для production отключены persistState и syncTabs, файл 1.*.chunk.js сохранён.