Oktell AMI Adapter — различия между версиями
м |
|||
| (не показано 38 промежуточных версии этого же участника) | |||
| Строка 3: | Строка 3: | ||
__TOC__ | __TOC__ | ||
| − | + | == Введение == | |
| − | + | '''Oktell AMI Adapter''' - это служба для интеграции '''внешних программ''' и '''Oktell''' по протоколу AMI. | |
| − | + | В настоящее время существует большое количество программ, работающих по протоколу AMI с сервером Asterisk. Протокол AMI часто используют для интеграции с бизнес-процессами и программным обеспечением CRM. Он также может применяться для разнообразных приложений, таких как программы автоматического набора номера и системы click-to-call. | |
| − | ''' | + | |
| + | Благодаря AMI, внешние программы могут осуществлять соединения посредством TCP протокола, инициировать выполнение команд, считывать результат их выполнения, а так же получать уведомления о происходящих событиях в реальном времени. Этими механизмами можно пользоваться, например, в следующих случаях: | ||
| + | * Необходимо узнать текущее состояние системы | ||
| + | * Определить количество активных абонентов, состояние очередей | ||
| + | * Запуск внешнего процесса, дозвона или задачи | ||
| + | * Отправка статистики соединений на электронную почту | ||
| + | |||
| + | |||
| + | '''Oktell AMI Adapter''' позволяет легко перейти с '''Asterisk''' на программный комплекс '''Oktell''' без потери функционала. По сути, продукт эмулирует работу программы '''Asterisk''', принимая сообщения интерфейса AMI и передавая их на сервер '''Oktell''' по постоянному установившемуся TCP-каналу. | ||
| + | |||
| + | |||
| + | Работа адаптера заключается в приеме запросов, поступающих на определенный TCP-порт и передача их на порты Web-сервера '''Oktell'''. При поступлении запроса в '''Oktell''' запускается определенный служебный сценарий, который анализирует сообщение и генерирует ответ обратно в адаптер. Для удобства разбора сообщения, '''Oktell AMI Adapter''' может преобразовывать запрос в XML-формат. | ||
| + | |||
| + | <span style="color:red">ВНИМАНИЕ:</span> Для работы требуется предустановленный '''.NET Framework v4.5''' ([http://go.microsoft.com/fwlink/?LinkId=321331 Скачать]). | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-010.png|center]] | ||
| + | |||
| + | |||
| + | Скачать дистрибутив Oktell AMI Adapter вы можете по ссылке [https://download.oktell.ru/data/Oktell_AMI_Adapter.zip https://download.oktell.ru/data/Oktell_AMI_Adapter.zip] | ||
| + | |||
| + | == Подготовка Oktell== | ||
| + | |||
| + | Настройте способ соединения '''Oktell''' и '''Oktell AMI Adapter''': | ||
* Перейдите в '''Администрирование''' - '''Общие настройки''' - '''Web-интеграция с CRM'''. | * Перейдите в '''Администрирование''' - '''Общие настройки''' - '''Web-интеграция с CRM'''. | ||
* Выберите следующие настройки | * Выберите следующие настройки | ||
| Строка 21: | Строка 44: | ||
| − | + | ==Установка Oktell AMI Adapter== | |
| − | '''Шаг 1.''' '''Регистрация службы Oktell.AMI.Adapter.''' Для этого необходимо воспользоваться программой InstallUtil по адресу C:\Windows\Microsoft.NET\Framework\ | + | '''Шаг 1.''' Скачайте и распакуйте архив в любое место. В примере, архив распаковывается на диск '''C:\''' |
| + | |||
| + | |||
| + | '''Шаг 2.''' '''Регистрация службы Oktell.AMI.Adapter.''' Для этого необходимо воспользоваться программой '''InstallUtil''' по адресу '''C:\Windows\Microsoft.NET\Framework\v4.0.30319''' (на ОС Windows 7). | ||
В командной строке заходим в папку с программой и выполняем команду (в примере '''Oktell.AMI.Adapter.Svc.exe''' находится в папке '''C:\AMI_Adapter'''). | В командной строке заходим в папку с программой и выполняем команду (в примере '''Oktell.AMI.Adapter.Svc.exe''' находится в папке '''C:\AMI_Adapter'''). | ||
| Строка 31: | Строка 57: | ||
[[Файл:AmiAdapter-001.png|center]] | [[Файл:AmiAdapter-001.png|center]] | ||
| + | |||
| + | |||
| + | |||
| + | '''Шаг 3.''' '''Редактирование конфигурационного файла Oktell AMI Adapter'''. Откройте файл '''Oktell.AMI.Adapter.Svc.exe.config'''. | ||
| + | |||
| + | Для работы '''Oktell AMI Adapter''': | ||
| + | * Введите адрес для подключения к web-серверу Oktell: | ||
| + | <add key="OktellWebSocketUrl" value="ws://192.168.0.82:4067" /> | ||
| + | * Введите интерфейс и порт слушателя: | ||
| + | <add key="TcpListenerEndPoint" value="192.168.0.82:8888" /> | ||
| + | * Введите название сценария обработки запросов: | ||
| + | <add key="OktellScriptName" value="AMI_ADAPTER_Script" /> | ||
| + | |||
| + | |||
| + | '''Шаг 4.''' '''Запуск службы Oktell.AMI.Adapter'''. | ||
| + | * Откройте "'''Управление службами'''" ('''Мой компьютер''' "правой кнопкой" ->''' Управление''' -> '''Службы и приложения''' -> '''Службы'''). | ||
| + | * Запустите службу '''Oktell.AMI.Adapter'''. | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-003.png|center|600px]] | ||
| + | |||
| + | |||
| + | == Настройка сценария обработки запросов == | ||
| + | |||
| + | Все запросы, поступающие в '''Oktell AMI Adapter''', пересылаются в '''Oktell'''. При этом запускается сценарий (параметр конфигурационного файла '''OktellScriptName'''), на вход которого передается текст сообщения в XML-формате. Преобразование сообщение в XML-формат задается в конфигурационном файле в параметре '''ConvertAmiToXml'''. | ||
| + | |||
| + | <u>'''Действия сценария при получении запроса:'''</u> | ||
| + | #Разбор и анализ поступившего сообщения | ||
| + | #Выполнение действий и формирование ответа | ||
| + | #Отправка сообщения в '''Oktell AMI Adapter''' | ||
| + | |||
| + | '''Скачать пример:''' [[Media:AMI_ADAPTER_Script.zip|AMI_ADAPTER_Script.zip]] | ||
| + | |||
| + | Создайте сценарий с названием, которое прописано в конфигурационном файле. В примере, '''AMI_ADAPTER_Script'''. | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-004.png |center | 600px]] | ||
| + | |||
| + | |||
| + | |||
| + | Простейший сценарий выглядит следующим образом: | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-005.png|center]] | ||
| + | |||
| + | |||
| + | Сценарий разбирает запросы '''Login''', '''Logoff''' и '''Originate''', формирует и отправляет ответы. При запросе '''Originate''' коммутирует абонентов указанных в полях Exten и Channel. | ||
| + | |||
| + | <u>Компонент '''"Старт 1"'''</u>. В качестве параметра запуска переменная xml (строковая) содержит текст запроса в XML-виде. | ||
| + | |||
| + | <u>Компонент '''"Анализ action"'''</u>. Разбирает '''xml''' структуру, определяет параметр '''Action''' и записывает в соответствующую переменную '''Action'''(строковая). Переход осуществляется к следующему элементу как по основной ветке, так и по ветке "'''Ошибка'''" (тогда в переменной '''Action''' будет пустая строка). | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-006.png|center|600px]] | ||
| + | |||
| + | |||
| + | <u>Компонент '''"Текст action"'''</u>. Отладочное уведомление, выводит текст переменной '''Action'''. | ||
| + | |||
| + | <u>Компонент '''"action?"'''</u>. Меню, в зависимости от параметра '''Action''' формирует ответ и совершает необходимые действия. | ||
| + | |||
| + | <u>Компонент '''"Success"'''</u>. Формирует ответ на запрос. В переменную answer записывается строка (с переносом строки) | ||
| + | |||
| + | Response: Success | ||
| + | Message: Authentication accepted | ||
| + | |||
| + | Аналогично настраивается компонент "'''Goodbye'''". Формат ответа: | ||
| + | |||
| + | Response: Goodbye | ||
| + | Message: Thanks for all the fish. | ||
| + | |||
| + | Формат ответа на "'''Originate'''" | ||
| + | |||
| + | Response: Success | ||
| + | Message: Originate successfully queued | ||
| + | |||
| + | <u>Компоненты '''"Callerid"''' и '''"Exten"''' </u>. Разбирают структуру запроса и выделяют поля '''Callerid''' и '''Exten'''. Далее с помощью компонента "'''Коммутация 1'''" данные абоненты коммутируются. | ||
| + | |||
| + | <u>Компонент "'''Отправка ответа'''"</u>. Отправляет ответ в '''Oktell AMI Adapter''' с помощью компонента "'''Действие/карточка в Plugin или WebCRM'''". | ||
| + | *"'''Модуль, действие'''" - WebCRM - SendAMIMessage. | ||
| + | *"'''Свойства'''" - для выходной переменной модуля message выберите переменную сценария '''answer'''. | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-008.png|center|1000px]] | ||
| + | |||
| + | |||
| + | '''Скачать пример сценария:''' [[Media:AMI_ADAPTER_Script.zip|AMI ADAPTER Script.zip]] | ||
| + | |||
| + | |||
| + | == Проверка работы == | ||
| + | |||
| + | Для проверки работы вы можете использовать компонент Windows "'''клиент telnet'''". Подключение осуществляется в командной строке: | ||
| + | |||
| + | telnet 192.168.0.82 8888 | ||
| + | |||
| + | После входа, введите запрос и нажмите два раза клавишу ввода. | ||
| + | |||
| + | Action: Login | ||
| + | |||
| + | Вам должен прийти ответ от '''Oktell AMI Adapter'''. | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-009.png|center]] | ||
| + | |||
| + | |||
| + | == Конфигурационный файл== | ||
| + | |||
| + | Откройте папку с '''Oktell AMI Adapter'''. Конфигурационный файл '''Oktell.AMI.Adapter.Svc.exe.config''' находится в корне папки, открывается с помощью блокнота (рекомендуется использовать notepad++). | ||
| + | |||
| + | Конфигурационный файл имеет следующие параметры: | ||
| + | *'''OktellWebSocketUrl''' - адрес для web-socket подключения к серверу Oktell. По умолчанию, «'''ws://192.168.0.82:4067'''». | ||
| + | *'''OktellWebSocketUrl_2''' - адрес для web-socket подключения к другому серверу Oktell. Используется для обеспечения отказоустойчивости системы. | ||
| + | *'''OktellWebSocketUrl_3''' - адрес для web-socket подключения к третьему серверу Oktell. Используется для обеспечения отказоустойчивости системы. | ||
| + | *'''TcpListenerEndPoint''' - интерфейс и порт слушателя tcp-подключений. По умолчанию, «'''127.0.0.1:8888'''». | ||
| + | *'''OktellScriptName''' - название сценария обработки запросов. По умолчанию, «'''some_script'''». | ||
| + | *'''EnableAdapterLog''' - логирование работы адаптера. «0» - не активно, «1» - активно. По умолчанию, «'''1'''». | ||
| + | *'''EnableAMIConnectionLog''' - логирование подключений. «0» - не активно, «1» - активно. По умолчанию, «'''1'''». | ||
| + | *'''EnableOktellConnectionLog''' - логирование соединений с сервером Oktell. «0» - не активно, «1» - активно. По умолчанию, «'''1'''». | ||
| + | *'''ConvertAmiToXml''' - преобразование сообщения на языке AMI протокола в XML для удобства парсинга. «0» - не активно, «1» - активно. По умолчанию, «'''1'''». | ||
| + | |||
| + | |||
| + | ==Возможные проблемы== | ||
| + | |||
| + | '''1.''' Если не получается зарегистрировать службу Oktell.AMI.Adapter (ошибка HRESULT: 0x80131515), то откройте свойства файла | ||
| + | Oktell.AMI.Adapter.Svc.exe и разблокируйте содержимое. Затем нажмите ОК. | ||
| + | |||
| + | |||
| + | [[Файл:AmiAdapter-011.png|center]] | ||
Текущая версия на 12:48, 31 марта 2023
Содержание
Введение
Oktell AMI Adapter - это служба для интеграции внешних программ и Oktell по протоколу AMI.
В настоящее время существует большое количество программ, работающих по протоколу AMI с сервером Asterisk. Протокол AMI часто используют для интеграции с бизнес-процессами и программным обеспечением CRM. Он также может применяться для разнообразных приложений, таких как программы автоматического набора номера и системы click-to-call.
Благодаря AMI, внешние программы могут осуществлять соединения посредством TCP протокола, инициировать выполнение команд, считывать результат их выполнения, а так же получать уведомления о происходящих событиях в реальном времени. Этими механизмами можно пользоваться, например, в следующих случаях:
- Необходимо узнать текущее состояние системы
- Определить количество активных абонентов, состояние очередей
- Запуск внешнего процесса, дозвона или задачи
- Отправка статистики соединений на электронную почту
Oktell AMI Adapter позволяет легко перейти с Asterisk на программный комплекс Oktell без потери функционала. По сути, продукт эмулирует работу программы Asterisk, принимая сообщения интерфейса AMI и передавая их на сервер Oktell по постоянному установившемуся TCP-каналу.
Работа адаптера заключается в приеме запросов, поступающих на определенный TCP-порт и передача их на порты Web-сервера Oktell. При поступлении запроса в Oktell запускается определенный служебный сценарий, который анализирует сообщение и генерирует ответ обратно в адаптер. Для удобства разбора сообщения, Oktell AMI Adapter может преобразовывать запрос в XML-формат.
ВНИМАНИЕ: Для работы требуется предустановленный .NET Framework v4.5 (Скачать).
Скачать дистрибутив Oktell AMI Adapter вы можете по ссылке https://download.oktell.ru/data/Oktell_AMI_Adapter.zip
Подготовка Oktell
Настройте способ соединения Oktell и Oktell AMI Adapter:
- Перейдите в Администрирование - Общие настройки - Web-интеграция с CRM.
- Выберите следующие настройки
- Способ соединения с сервером CRM - CRM к Oktell (WebSocket)
- Порт WebSocket Oktell для CRM - выберите порт для WebSocket-соединения. В примере, 4067
- Авторизация - Без авторизации
- Нажмите "Сохранить"
Установка Oktell AMI Adapter
Шаг 1. Скачайте и распакуйте архив в любое место. В примере, архив распаковывается на диск C:\
Шаг 2. Регистрация службы Oktell.AMI.Adapter. Для этого необходимо воспользоваться программой InstallUtil по адресу C:\Windows\Microsoft.NET\Framework\v4.0.30319 (на ОС Windows 7).
В командной строке заходим в папку с программой и выполняем команду (в примере Oktell.AMI.Adapter.Svc.exe находится в папке C:\AMI_Adapter).
C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe C:\AMI_Adapter\Oktell.AMI.Adapter.Svc.exe
Шаг 3. Редактирование конфигурационного файла Oktell AMI Adapter. Откройте файл Oktell.AMI.Adapter.Svc.exe.config.
Для работы Oktell AMI Adapter:
- Введите адрес для подключения к web-серверу Oktell:
<add key="OktellWebSocketUrl" value="ws://192.168.0.82:4067" />
- Введите интерфейс и порт слушателя:
<add key="TcpListenerEndPoint" value="192.168.0.82:8888" />
- Введите название сценария обработки запросов:
<add key="OktellScriptName" value="AMI_ADAPTER_Script" />
Шаг 4. Запуск службы Oktell.AMI.Adapter.
- Откройте "Управление службами" (Мой компьютер "правой кнопкой" -> Управление -> Службы и приложения -> Службы).
- Запустите службу Oktell.AMI.Adapter.
Настройка сценария обработки запросов
Все запросы, поступающие в Oktell AMI Adapter, пересылаются в Oktell. При этом запускается сценарий (параметр конфигурационного файла OktellScriptName), на вход которого передается текст сообщения в XML-формате. Преобразование сообщение в XML-формат задается в конфигурационном файле в параметре ConvertAmiToXml.
Действия сценария при получении запроса:
- Разбор и анализ поступившего сообщения
- Выполнение действий и формирование ответа
- Отправка сообщения в Oktell AMI Adapter
Скачать пример: AMI_ADAPTER_Script.zip
Создайте сценарий с названием, которое прописано в конфигурационном файле. В примере, AMI_ADAPTER_Script.
Простейший сценарий выглядит следующим образом:
Сценарий разбирает запросы Login, Logoff и Originate, формирует и отправляет ответы. При запросе Originate коммутирует абонентов указанных в полях Exten и Channel.
Компонент "Старт 1". В качестве параметра запуска переменная xml (строковая) содержит текст запроса в XML-виде.
Компонент "Анализ action". Разбирает xml структуру, определяет параметр Action и записывает в соответствующую переменную Action(строковая). Переход осуществляется к следующему элементу как по основной ветке, так и по ветке "Ошибка" (тогда в переменной Action будет пустая строка).
Компонент "Текст action". Отладочное уведомление, выводит текст переменной Action.
Компонент "action?". Меню, в зависимости от параметра Action формирует ответ и совершает необходимые действия.
Компонент "Success". Формирует ответ на запрос. В переменную answer записывается строка (с переносом строки)
Response: Success Message: Authentication accepted
Аналогично настраивается компонент "Goodbye". Формат ответа:
Response: Goodbye Message: Thanks for all the fish.
Формат ответа на "Originate"
Response: Success Message: Originate successfully queued
Компоненты "Callerid" и "Exten" . Разбирают структуру запроса и выделяют поля Callerid и Exten. Далее с помощью компонента "Коммутация 1" данные абоненты коммутируются.
Компонент "Отправка ответа". Отправляет ответ в Oktell AMI Adapter с помощью компонента "Действие/карточка в Plugin или WebCRM".
- "Модуль, действие" - WebCRM - SendAMIMessage.
- "Свойства" - для выходной переменной модуля message выберите переменную сценария answer.
Скачать пример сценария: AMI ADAPTER Script.zip
Проверка работы
Для проверки работы вы можете использовать компонент Windows "клиент telnet". Подключение осуществляется в командной строке:
telnet 192.168.0.82 8888
После входа, введите запрос и нажмите два раза клавишу ввода.
Action: Login
Вам должен прийти ответ от Oktell AMI Adapter.
Конфигурационный файл
Откройте папку с Oktell AMI Adapter. Конфигурационный файл Oktell.AMI.Adapter.Svc.exe.config находится в корне папки, открывается с помощью блокнота (рекомендуется использовать notepad++).
Конфигурационный файл имеет следующие параметры:
- OktellWebSocketUrl - адрес для web-socket подключения к серверу Oktell. По умолчанию, «ws://192.168.0.82:4067».
- OktellWebSocketUrl_2 - адрес для web-socket подключения к другому серверу Oktell. Используется для обеспечения отказоустойчивости системы.
- OktellWebSocketUrl_3 - адрес для web-socket подключения к третьему серверу Oktell. Используется для обеспечения отказоустойчивости системы.
- TcpListenerEndPoint - интерфейс и порт слушателя tcp-подключений. По умолчанию, «127.0.0.1:8888».
- OktellScriptName - название сценария обработки запросов. По умолчанию, «some_script».
- EnableAdapterLog - логирование работы адаптера. «0» - не активно, «1» - активно. По умолчанию, «1».
- EnableAMIConnectionLog - логирование подключений. «0» - не активно, «1» - активно. По умолчанию, «1».
- EnableOktellConnectionLog - логирование соединений с сервером Oktell. «0» - не активно, «1» - активно. По умолчанию, «1».
- ConvertAmiToXml - преобразование сообщения на языке AMI протокола в XML для удобства парсинга. «0» - не активно, «1» - активно. По умолчанию, «1».
Возможные проблемы
1. Если не получается зарегистрировать службу Oktell.AMI.Adapter (ошибка HRESULT: 0x80131515), то откройте свойства файла Oktell.AMI.Adapter.Svc.exe и разблокируйте содержимое. Затем нажмите ОК.
