Интеграция OTRS -> Telegram (1)

Только для готовых решений! Пожалуйста, не используйте для вопросов и обсуждений!

Модератор: ykolesnikov

Ответить
samd
OTRS Новобранец
Сообщения: 12
Зарегистрирован: 10 сен 2014, 10:41
Откуда: НСИ-Телеком
Поблагодарили: 1 раз
Контактная информация:

Интеграция OTRS -> Telegram (1)

Сообщение samd » 01 май 2020, 18:55

Пример интеграции OTRS и Telegram основан на примере интеграции OTRS и Slack:
viewtopic.php?f=2&t=927&p=25053#p25053

Основная цель интеграции - получение уведомлений в Telegram о появлении новых или изменении статусов уже открытых тикетов в OTRS. Штатным средством уведомления агентов в OTRS является почта. Получение уведомлений почтой не всегда удобно. Особенно, когда тикетов не так много.
Чтобы дифференцировать тикеты мы будем использовать разные очереди OTRS. За каждой очередью у нас следит отдельная группа инженеров. Таким образом, мы должны будем создать несколько групп в Telegram и подписать на группы отдельных инженеров.

Интеграция протестирована на OTRS версий 5 и 6.
В OTRS 5 для доступа к Telegram Bot API используются настройки Proxy Server для системного UserAgent OTRS, который может использоваться для работы других API. Это может быть критично, в случае наличия последних. Будьте внимательны.
Последний раз редактировалось samd 01 май 2020, 19:09, всего редактировалось 1 раз.
С уважением Дмитрий.
OTRS 5.0.21 CentOS 7 x64 Linux with MySQL 5.7

samd
OTRS Новобранец
Сообщения: 12
Зарегистрирован: 10 сен 2014, 10:41
Откуда: НСИ-Телеком
Поблагодарили: 1 раз
Контактная информация:

Интеграция OTRS -> Telegram (2)

Сообщение samd » 01 май 2020, 18:59

Настройка Telegram Bot

Настройка Telegram Bot осуществляется через специального Bot'a c именем BotFather - крестного отца всех ботов. Просто напишите BotFather команду newbot и следуйте инструкциям.
Подробнее можно почитать тут: https://tlgrm.ru/docs/bots
После создания бота нужно скопировать его BOTToken вида:

Код: Выделить всё

12356789:A2HdqTcvCH1vGWJxfSeofSAs0K5PALDsaw 
Далее нам необходимо создать несколько групп в Telegram с участием созданного бота. Инженеров можете добавить сразу или после отладки.
После создания групп нужно выяснить их ID. ID группы - это отрицательное целое число. Выяснить его можно сформировав http get запрос на API вашего бота:

Код: Выделить всё

https://api.telegram.org/bot<BOTToken>/getUpdates
Основная проблема это недоступность данного адреса из российского сегмента Интернет. Поэтому тут могут пригодиться различные http прокси в браузере или командная строка linux сервера за рубежом.
Отправьте любое сообщение в группу. Затем либо в браузере с настроенным прокси наберите в адресной строке:
https://api.telegram.org/bot<BOTToken>/getUpdates
, либо в консоли вашего сервера:

Код: Выделить всё

curl -i -X POST https://api.telegram.org/bot<BOTToken>/getUpdates
В ответе сервера Telegram есть объект "chat". Его "id" и есть искомое число (в примере -1111111):

Код: Выделить всё

{"update_id":8393,"message":{"message_id":3,"from":{"id":7474,"first_name":"AAA"},"chat":{"id":-1111111,"title":""},"date":25497,"new_chat_participant":{"id":71,"first_name":"NAME","username":"YOUR_BOT_NAME"}}}
Последний раз редактировалось samd 01 май 2020, 19:12, всего редактировалось 3 раза.
С уважением Дмитрий.
OTRS 5.0.21 CentOS 7 x64 Linux with MySQL 5.7

samd
OTRS Новобранец
Сообщения: 12
Зарегистрирован: 10 сен 2014, 10:41
Откуда: НСИ-Телеком
Поблагодарили: 1 раз
Контактная информация:

Интеграция OTRS -> Telegram (3)

Сообщение samd » 01 май 2020, 19:02

Настройка OTRS

[*]Добавление файлов Web Service
В файловую систему OTRS сервера нужно добавить файл:
- TelegramTxt.pm (файл с Invoker модулем, который будет готовить данные для POST-запроса в Telegram:

В приложении архив с необходимым фалом. Скопируйте его на сервер с OTRS.
Создайте директорию, извлеките из архива скопируйте файл:

Код: Выделить всё

mkdir -p /opt/otrs/Custom/Kernel/GenericInterface/Invoker/Telegram
tar xvfz ./GenericInterface.tar.gz
cp ./GenericInterface/Invoker/Telegram/TelegramTxt.pm /opt/otrs/Custom/Kernel/GenericInterface/Invoker/Telegram/
Не забываем о правах. Все файлы каталоги в каталоге OTRS должны принадлежать пользователю, от имени которого выполняется OTRS:

Код: Выделить всё

cd /opt/otrs/Custom/Kernel/
sudo chown -R otrs:apache ./GenericInterface
sudo /opt/otrs/bin/otrs.SetPermissions.pl --otrs-user='otrs' --web-group='apache'
, где
otrs - имя пользователя, от имени которого запущен OTRS,
apache - группа пользователя, от имени которого запущен OTRS.
Вложения
GenericInterface.tar.gz
(9.66 КБ) 18 скачиваний
Последний раз редактировалось samd 01 май 2020, 19:29, всего редактировалось 5 раз.
С уважением Дмитрий.
OTRS 5.0.21 CentOS 7 x64 Linux with MySQL 5.7

samd
OTRS Новобранец
Сообщения: 12
Зарегистрирован: 10 сен 2014, 10:41
Откуда: НСИ-Телеком
Поблагодарили: 1 раз
Контактная информация:

Интеграция OTRS -> Telegram (4)

Сообщение samd » 01 май 2020, 19:05

Регистрация нового WEB Service в OTRS

Для начала необходимо зарегистрировать новый WEB Service. Делается это модификацией файла:
/opt/otrs/Kernel/Config/Files/GenericInterface.xml

Для этого сохраним оригинальный файл:

Код: Выделить всё

cd /opt/otrs/Kernel/Config/Files/
cp -p ./GenericInterface.xml ./GenericInterface.xml.orig
В файл /opt/otrs/Kernel/Config/Files/GenericInterface.xml добавим строки:
Для OTRS версии 5:

Код: Выделить всё

    <ConfigItem Name="GenericInterface::Invoker::Module###Telegram::TelegramTxt" Required="0" Valid="0">
        <Description Translatable="1">GenericInterface module registration for the invoker layer.</Description>
        <Group>GenericInterface</Group>
        <SubGroup>GenericInterface::Invoker::ModuleRegistration</SubGroup>
        <Setting>
            <Hash>
                <Item Key="Name">TelegramTxt</Item>
                <Item Key="Controller">Telegram</Item>
                <Item Key="ConfigDialog">AdminGenericInterfaceInvokerDefault</Item>
            </Hash>
        </Setting>
    </ConfigItem>

Для OTRS версии 6:

Код: Выделить всё

    <Setting Name="GenericInterface::Invoker::Module###Telegram::TelegramTxt" Required="0" Valid="0">
        <Description Translatable="1">GenericInterface module registration for the invoker layer.</Description>
        <Navigation>GenericInterface::Invoker::ModuleRegistration</Navigation>
        <Value>
            <Hash>
                <Item Key="Name">TelegramTxt</Item>
                <Item Key="Controller">Telegram</Item>
                <Item Key="ConfigDialog">AdminGenericInterfaceInvokerDefault</Item>
            </Hash>
        </Value>
    </Setting>
Я ориентировался на преконфигурированный Web Service с именем TestSimple. Он есть в штатной поставке OTRS.
В OTRS 6 для импорта сделанных настроек нужно выполнить:

Код: Выделить всё

sudo -u otrs /opt/otrs/bin/otrs.Console.pl Maint::Config::Rebuild
Делаем "restart httpd":

Код: Выделить всё

systemctl restart httpd
Теперь необходимо включить наш модуль в OTRS, чтобы иметь возможность выбрать его в веб-сервисах.
Для этого необходимо зайти в Администрирование/Конф.системы/GenericInterface --> GenericInterface::Invoker::ModuleRegistration
И поставить галочку напротив сконфигурированного сервиса TelegramTxt.
Последний раз редактировалось samd 01 май 2020, 19:14, всего редактировалось 3 раза.
С уважением Дмитрий.
OTRS 5.0.21 CentOS 7 x64 Linux with MySQL 5.7

samd
OTRS Новобранец
Сообщения: 12
Зарегистрирован: 10 сен 2014, 10:41
Откуда: НСИ-Телеком
Поблагодарили: 1 раз
Контактная информация:

Интеграция OTRS -> Telegram (5)

Сообщение samd » 01 май 2020, 19:08

Настройка Web Service в OTRS

В административной панели OTRS необходимо создать новый сервис:
Admin --> Web Service Management --> Add Web Service
С параметрами:

Код: Выделить всё

General:
    Name: Telegram
    Debug threshold: Debug
OTRS as requester:
    Settings:
        Network transport: HTTP::REST
    Invokers: 
        Name: Telegram
        CONTROLLER: Telegram::TelegramTxt
Далее необходимо сконфигурировать Network transport и Invoker. Кнопки Configure появятся сразу после сохранения выбранных параметров.

Network transport
Здесь важно выдержать параметры в точности, как описано.
Главное:
1) Telegram API работает только через https.
2) Telegram API не доступен в российском сегменте Интернет и поэтому нужно использовать http-прокси.
3) REST-Api OTRS далек от совершенства и не работает без указания пользователя и пароля для Basic Auth в адресе прокси-сервера (хотя должен).

Параметры для OTRS 6:

Код: Выделить всё

Type: HTTP::REST
Endpoint: https://api.telegram.org/bot<BOTToken>
Authentication:
Use Proxy Options: Yes
Proxy Server: http://user:password@ip_address:port
Proxy User:
Proxy Password:
Skip Proxy: No
Use SSL Options: No
Controller mapping for Invoker 'Telegram': sendMessage
Valid request command for Invoker 'Telegram': POST
Default command: POST
Параметры для OTRS 5:

Код: Выделить всё

Type: HTTP::REST
Endpoint: https://api.telegram.org/bot<BOTToken>
Authentication:
Use SSL Options: No
Controller mapping for Invoker 'Telegram': sendMessage
Valid request command for Invoker 'Telegram': POST
Default command: POST
Параметры Proxy Server используются из глобального конфига(Core::WebUserAgent):

Код: Выделить всё

Timeout: 15
Proxy: http://user:password@ip_address:port
DisableSSLVerification: No

Invoker

Код: Выделить всё

Name: Telegram
Invoker backend: Telegram::TelegramTxt
Mapping for outgoing request data: Simple
Mapping for incoming request data: Simple
Event Triggers: 
    EVENT: TicketCreate
    ASYNCHRONOUS: Yes
    CONDITION: No
Simple Mapping for Data
Если вы планируете отправлять сообщения в несколько разных групп Telegram, то здесь нужно сконфигурировать соответствие имен полей и их значений между OTRS и Telegram.
Дело в том, что по умолчанию POST-запрос в теле содержит словарь {ключ: значение}. В нашем случае это будет словарь подобный следующему:

Код: Выделить всё

{
    "text" :    "#2020033007000174
                Customer: ИмяКастомера
                Queue: queue1
                Priority: 3 normal
                State: new
                Owner: root@localhost
                Responsible: root@localhost
                Changed : 2020-03-30 17:50:44

                http://otrs.hostname/otrs/index.pl?Action=AgentTicketZoom;TicketID=73",
    "queue" :   "queue1"
}
Для тех кто не знаком с темой полезно будет протестировать обмен запросами с помощью curl или Postman (предварительно замените адрес запроса на полученный в Mattermost Incoming Webhook:

Код: Выделить всё

curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "[inline URL](http://yandex.ru)"}' https://api.telegram.org/bot<BOTToken>/sendMessage
Последняя пара ключ-значение содержит имя очереди нового тикета. Мы будем её мапить (отображать) в нужную нам группу Telegram.
В моём случае разные очереди в OTRS обслуживаются разными группами агентов (инженеров). Таким образом, каждая из групп агентов будет читать свою группу Telegram.
Чтобы настроить отображение очереди OTRS в группу Telegram нужно настроить Mapping for Outgoing Data в сконфигурированном Invoker'е.

Код: Выделить всё

Default rule for unmapped keys: Keep (leave unchanged)
Default rule for unmapped values: Keep (leave unchanged)

Mapping for Key channel*
    Key mapping:
        Map key: queue
        matching the: Exact value(s)
        to new key: chat_id

    Value mapping:
        Map value: queue1
        matching the: Exact value(s)
        to new value: -333333333

        Map value: queue2
        matching the: Exact value(s)
        to new value: -222222222

        Map value: [\w\W]*
        matching the: Regular expression
        to new value: -111111111
Вы можете настроить свою логику.

Так же необходимо настроить мапинг ответов на наши POST-запросы. Telegram API в случае успешного приема POST-запроса отвечает JSON-сериализоваными данными. Статус как обычно в заголовке и в поле "OK", значение которого 1 или 0.

Настроим маппинг ответов на запросы:

Default rule for unmapped keys: Keep (leave unchanged)
Default rule for unmapped values: Keep (leave unchanged)

Код: Выделить всё

Mapping For Key text*
    Key mapping: 
        map key: ok
        matching the: Exact value(s)
        to new key: text

    Value mapping:
        Map value: 1
        matching the: Exact value(s)
        to new value: ok
    Value mapping:
        Map value: 0
        matching the: Exact value(s)
        to new value: error
Debugging
В интерфейсе настройки Web Service слева нижняя кнопка "Debugger". При нажатии на нее вы можете посмотреть как обрабатывается POST-запрос после появления нового тикета.
Здесь виден и сам сформированный запрос и его отображение в процессе маппинга и ответ на запрос.
С уважением Дмитрий.
OTRS 5.0.21 CentOS 7 x64 Linux with MySQL 5.7

Ответить