Oktell AMI Adapter — различия между версиями

Материал из Oktell
Перейти к: навигация, поиск
м
 
(не показано 27 промежуточных версии этого же участника)
Строка 3: Строка 3:
 
__TOC__
 
__TOC__
  
'''Oktell AMI Adapter''' - это служба для интеграции '''Asterisk''' и '''Oktell'''. Взаимодействие происходит путем обмена сообщениями по постоянному установившемуся TCP-каналу.
+
== Введение ==
  
<span style="color:red">ВНИМАНИЕ:</span> Для работы требуется предустановленный '''.NET Framework v4.5''' ([[http://go.microsoft.com/fwlink/?LinkId=321331 Скачать]]).
+
'''Oktell AMI Adapter''' - это служба для интеграции '''внешних программ''' и '''Oktell''' по протоколу AMI.  
  
 +
В настоящее время существует большое количество программ, работающих по протоколу AMI с сервером Asterisk. Протокол AMI часто используют для интеграции с бизнес-процессами и программным обеспечением CRM. Он также может применяться для разнообразных приложений, таких как программы автоматического набора номера и системы click-to-call.
  
=== Подготовка Oktell===
 
  
'''Шаг 1.''' Настройте Web-сервер Oktell. Воспользуйтесь статьей: [[Настройка Web-сервера Oktell]].
+
Благодаря AMI, внешние программы могут осуществлять соединения посредством TCP протокола, инициировать выполнение команд, считывать результат их выполнения, а так же получать уведомления о происходящих событиях в реальном времени. Этими механизмами можно пользоваться, например, в следующих случаях:
 +
* Необходимо узнать текущее состояние системы
 +
* Определить количество активных абонентов, состояние очередей
 +
* Запуск внешнего процесса, дозвона или задачи
 +
* Отправка статистики соединений на электронную почту
  
'''Шаг 2''' Настройте способ соединения Oktell и AMI Adapter.
+
 
 +
'''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'''.  
 
* Выберите следующие настройки  
 
* Выберите следующие настройки  
Строка 24: Строка 44:
  
  
===Установка Oktell AMI Adapter===  
+
==Установка Oktell AMI Adapter==  
  
'''Шаг 1.''' '''Регистрация службы Oktell.AMI.Adapter.''' Для этого необходимо воспользоваться программой '''InstallUtil''' по адресу C:\Windows\Microsoft.NET\Framework\v4.0.30319 (на ОС Windows 7).  
+
'''Шаг 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''').
Строка 37: Строка 60:
  
  
'''Шаг 2.''' '''Редактирование конфигурационного файла Oktell AMI Adapter'''. Откройте файл '''Oktell.AMI.Adapter.Svc.exe.config'''.
+
'''Шаг 3.''' '''Редактирование конфигурационного файла Oktell AMI Adapter'''. Откройте файл '''Oktell.AMI.Adapter.Svc.exe.config'''.
  
 
Для работы '''Oktell AMI Adapter''':  
 
Для работы '''Oktell AMI Adapter''':  
 
* Введите адрес для подключения к web-серверу Oktell:
 
* Введите адрес для подключения к web-серверу Oktell:
  <add key="OktellWebSocketUrl" value="ws://127.0.0.1:4067" />
+
  <add key="OktellWebSocketUrl" value="ws://192.168.0.82:4067" />
 
* Введите интерфейс и порт слушателя:  
 
* Введите интерфейс и порт слушателя:  
  <add key="TcpListenerEndPoint" value="127.0.0.1:8888" />
+
  <add key="TcpListenerEndPoint" value="192.168.0.82:8888" />
 
* Введите название сценария обработки запросов:
 
* Введите название сценария обработки запросов:
 
  <add key="OktellScriptName" value="AMI_ADAPTER_Script" />
 
  <add key="OktellScriptName" value="AMI_ADAPTER_Script" />
  
  
'''Шаг 3.''' '''Запуск службы Oktell.AMI.Adapter'''.  
+
'''Шаг 4.''' '''Запуск службы Oktell.AMI.Adapter'''.  
 
* Откройте "'''Управление службами'''" ('''Мой компьютер''' "правой кнопкой" ->''' Управление''' -> '''Службы и приложения''' -> '''Службы''').  
 
* Откройте "'''Управление службами'''" ('''Мой компьютер''' "правой кнопкой" ->''' Управление''' -> '''Службы и приложения''' -> '''Службы''').  
 
* Запустите службу '''Oktell.AMI.Adapter'''.
 
* Запустите службу '''Oktell.AMI.Adapter'''.
Строка 56: Строка 79:
  
  
=== Настройка сценария обработки запросов ===
+
== Настройка сценария обработки запросов ==
  
Все запросы, поступающие в Oktell AMI Adapter, пересылаются в Oktell. При этом запускается сценарий (параметр конфигурационного файла '''OktellScriptName'''), на вход которого передается текст сообщения в XML-формате. Преобразование сообщение в XML-формат задается в конфигурационном файле в параметре '''ConvertAmiToXml'''.  
+
Все запросы, поступающие в '''Oktell AMI Adapter''', пересылаются в '''Oktell'''. При этом запускается сценарий (параметр конфигурационного файла '''OktellScriptName'''), на вход которого передается текст сообщения в XML-формате. Преобразование сообщение в XML-формат задается в конфигурационном файле в параметре '''ConvertAmiToXml'''.  
  
 
<u>'''Действия сценария при получении запроса:'''</u>
 
<u>'''Действия сценария при получении запроса:'''</u>
 
#Разбор и анализ поступившего сообщения
 
#Разбор и анализ поступившего сообщения
 
#Выполнение действий и формирование ответа
 
#Выполнение действий и формирование ответа
#Отправка сообщения в Oktell AMI Adapter
+
#Отправка сообщения в '''Oktell AMI Adapter'''
  
 +
'''Скачать пример:''' [[Media:AMI_ADAPTER_Script.zip|AMI_ADAPTER_Script.zip]]
  
 
Создайте сценарий с названием, которое прописано в конфигурационном файле. В примере, '''AMI_ADAPTER_Script'''.  
 
Создайте сценарий с названием, которое прописано в конфигурационном файле. В примере, '''AMI_ADAPTER_Script'''.  
Строка 70: Строка 94:
  
 
[[Файл:AmiAdapter-004.png |center | 600px]]
 
[[Файл:AmiAdapter-004.png |center | 600px]]
 +
  
  
Строка 75: Строка 100:
  
  
 +
[[Файл: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++).
 
Откройте папку с '''Oktell AMI Adapter'''. Конфигурационный файл '''Oktell.AMI.Adapter.Svc.exe.config''' находится в корне папки, открывается с помощью блокнота (рекомендуется использовать notepad++).
Строка 96: Строка 175:
 
*'''EnableOktellConnectionLog''' - логирование соединений с сервером Oktell. «0» - не активно, «1» - активно. По умолчанию, «'''1'''».
 
*'''EnableOktellConnectionLog''' - логирование соединений с сервером Oktell. «0» - не активно, «1» - активно. По умолчанию, «'''1'''».
 
*'''ConvertAmiToXml''' - преобразование сообщения на языке AMI протокола в XML для удобства парсинга. «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 (Скачать).


AmiAdapter-010.png


Скачать дистрибутив 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
  • Авторизация - Без авторизации
  • Нажмите "Сохранить"


AmiAdapter-002.png


Установка 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


AmiAdapter-001.png


Шаг 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


Настройка сценария обработки запросов

Все запросы, поступающие в Oktell AMI Adapter, пересылаются в Oktell. При этом запускается сценарий (параметр конфигурационного файла OktellScriptName), на вход которого передается текст сообщения в XML-формате. Преобразование сообщение в XML-формат задается в конфигурационном файле в параметре ConvertAmiToXml.

Действия сценария при получении запроса:

  1. Разбор и анализ поступившего сообщения
  2. Выполнение действий и формирование ответа
  3. Отправка сообщения в Oktell AMI Adapter

Скачать пример: AMI_ADAPTER_Script.zip

Создайте сценарий с названием, которое прописано в конфигурационном файле. В примере, AMI_ADAPTER_Script.


AmiAdapter-004.png


Простейший сценарий выглядит следующим образом:


AmiAdapter-005.png


Сценарий разбирает запросы Login, Logoff и Originate, формирует и отправляет ответы. При запросе Originate коммутирует абонентов указанных в полях Exten и Channel.

Компонент "Старт 1". В качестве параметра запуска переменная xml (строковая) содержит текст запроса в XML-виде.

Компонент "Анализ action". Разбирает xml структуру, определяет параметр Action и записывает в соответствующую переменную Action(строковая). Переход осуществляется к следующему элементу как по основной ветке, так и по ветке "Ошибка" (тогда в переменной Action будет пустая строка).


AmiAdapter-006.png


Компонент "Текст 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.


AmiAdapter-008.png


Скачать пример сценария: AMI ADAPTER Script.zip


Проверка работы

Для проверки работы вы можете использовать компонент Windows "клиент telnet". Подключение осуществляется в командной строке:

telnet 192.168.0.82 8888

После входа, введите запрос и нажмите два раза клавишу ввода.

Action: Login

Вам должен прийти ответ от Oktell AMI Adapter.


AmiAdapter-009.png


Конфигурационный файл

Откройте папку с 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