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

[samd]

Пример интеграции 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]

Настройка 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

Основная проблема это недоступность данного адреса из российского сегмента Интернет (в 2020 году это уже не актуально). Поэтому тут могут пригодиться различные 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"}}}

В 2020 году можно воспользоваться специальным Ботом: t.me/ShowJsonBot

[samd]

Настройка 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.

[samd]

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

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

Для OTRS версии 5:
Этот файл находится:

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

/opt/otrs/Kernel/Config/Files/GenericInterface.xml

Cохраним оригинальный файл:

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

cd /opt/otrs/Kernel/Config/Files/
cp -p ./GenericInterface.xml ./GenericInterface.xml.orig

В файл /opt/otrs/Kernel/Config/Files/GenericInterface.xml добавим строки:

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

    <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:
Этот файл находится:

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

/opt/otrs/Kernel/Config/Files/XML/GenericInterface.xml

Cохраним оригинальный файл:

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

cd /opt/otrs/Kernel/Config/Files/XML/
cp -p ./GenericInterface.xml ./GenericInterface.xml.orig

В файл /opt/otrs/Kernel/Config/Files/XML/GenericInterface.xml добавим строки:

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

    <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]

Настройка 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)", "chat_id": "-100500"}' 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-запрос после появления нового тикета.
Здесь виден и сам сформированный запрос и его отображение в процессе маппинга и ответ на запрос.

[psina]

Огромный респект за проделанную работу и пост. То - чего не хватало

У меня все взлетело

Одна правка:
Опечатка cd /opt/otrs/Kernel/Config/Files/, заменить на cd /opt/otrs/Kernel/Config/Files/XML

[Screwie]

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

[darkimos]

не могу понять куда это:

Параметры для 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

[darkimos]

и сейчас же без прокси можно ведь

[samd]

Это настройки Admin->Web-Services->Ваш_Сервис

И Да! Теперь можно без прокси.

[walerjahn]

http://prntscr.com/uel9vq

А вот так вот должно быть?

[spike3run]

Я что-то плыву.. Вроде все сделал по инструкции, но бот отправляет мне запрос в стиле : Поступила новая заявка/sendMessage, ито это после настроек в Network Transport https://api.telegram.org/bot<token>/sen ... =Поступила новая заявка

а в Controller mapping for Invoker 'Telegram': я написал sendMessage, его и передает, как слово) Где-то в инвокере недонастроил или не пойму что. просто первый раз поднял отрс, и сейчас развлекаюсь с уведомлениями в телеграмме. прошу прощения за мою тупость.

[spike3run]

http://prntscr.com/uel9vq

А вот так вот должно быть?

по идее да, я тоже так настроил

[samd]

http://prntscr.com/uel9vq

А вот так вот должно быть?

Можно и так.

[samd]

Я что-то плыву.. Вроде все сделал по инструкции, но бот отправляет мне запрос в стиле : Поступила новая заявка/sendMessage, ито это после настроек в Network Transport https://api.telegram.org/bot<token>/sen ... =Поступила новая заявка

а в Controller mapping for Invoker 'Telegram': я написал sendMessage, его и передает, как слово) Где-то в инвокере недонастроил или не пойму что. просто первый раз поднял отрс, и сейчас развлекаюсь с уведомлениями в телеграмме. прошу прощения за мою тупость.

Очевидно, что транспорт не должен содержать слово sendMessage. То есть должен иметь вид:

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

https://api.telegram.org:443/bot435435456:dfredfvcxd-qt0-drfgtredfrtgfdsedfrt

В то же время Controller mapping for Invoker 'Telegram' должен быть:

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

sendMessage

[alexandr.kv]

Доброго вечера!
Подскажите, как можно добавить в оповещении больше информации о заявке?
Штатно выводится вот так:
Customer: $CustomerCompany{CustomerCompanyName}
Queue: $Ticket{Queue}
Priority: $Ticket{Priority}
State: $Ticket{State}
Owner: $Ticket{Owner}
Responsible: $Ticket{Responsible}
Changed : $Ticket{Changed}

Хотелось бы добавить инициатора заявки (OTRS_CUSTOMER_REALNAME) и описание задания (OTRS_CUSTOMER_BODY[30] )
Это возможно?

[alexus]

Хотелось бы добавить инициатора заявки (OTRS_CUSTOMER_REALNAME) и описание задания (OTRS_CUSTOMER_BODY[30] )
Это возможно?

Эти тэги не являются стандартными атрибутами тикета. В уведомлениях для них реализована специальная обработка. Так что тут нужна доработка

[Screwie]

Хотелось бы добавить инициатора заявки (OTRS_CUSTOMER_REALNAME) и описание задания (OTRS_CUSTOMER_BODY[30] )
Это возможно?

Эти тэги не являются стандартными атрибутами тикета. В уведомлениях для них реализована специальная обработка. Так что тут нужна доработка

А чтобы хотябы email отправителя добавить, какой прописать код?

[dorger]

Хотелось бы добавить инициатора заявки (OTRS_CUSTOMER_REALNAME) и описание задания (OTRS_CUSTOMER_BODY[30] )
Это возможно?

Эти тэги не являются стандартными атрибутами тикета. В уведомлениях для них реализована специальная обработка. Так что тут нужна доработка

А чтобы хотябы email отправителя добавить, какой прописать код?

Для этого нужно дописать TelegramTxt.pl.

До формирования ($TeleText{Data}->{text}=qq{ необходимо из OTRS получить CustomerUser, сделать это можно следующим образом:

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

my %CustomerUser = $CustomerUserObject->CustomerUserDataGet(
        User => $Ticket{CustomerUserID} ,
            );

Далее уже в формировании сообщения обращаемся к данному объекту, что бы получить нужные параметры. Например, для имени и фамилии заявителя

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

Person: $CustomerUser{UserFirstname} $CustomerUser{UserLastname}

Полный пример формирования текста:

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

my %CustomerUser = $CustomerUserObject->CustomerUserDataGet(
        User => $Ticket{CustomerUserID} ,
            );
            
($TeleText{Data}->{text}=qq{
    NEW: #$Ticket{TicketNumber}
    Department: $Ticket{CustomerID}
    Person ID: $Ticket{CustomerUserID}
    Person: $CustomerUser{UserFirstname} $CustomerUser{UserLastname}
    Title: $Ticket{Title}
    Type: $Ticket{Type}
    Changed : $Ticket{Changed}
    }) =~ s/^[\t ]*//mg;

[cheba]

Доброго времени суток. А можно как-то вытащить текст заявки? Не титул, а сам текст? И ещё, можно: Department, Person ID, Person, Title передавать в телегу кириллицей?

[alex.t]

Для добавления в сообщение текста, надо в файл TelegramTxt.pm добавить:

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

# Получаем текст первого артикла
    my $ArticleObject = $Kernel::OM->Get('Kernel::System::Ticket::Article');

    my @ArticleList = $ArticleObject->ArticleList(
        TicketID  => $Param{Data}->{TicketID},
        OnlyFirst => 1
    );
    my %Article = $ArticleObject->BackendForArticle( %{$ArticleList[0]} )->ArticleGet( %{$ArticleList[0]} );

До вот этого блока:
    ($TeleText{Data}->{text}=qq{
        #$Ticket{TicketNumber}
	Customer: $CustomerCompany{CustomerCompanyName}
	Queue: $Ticket{Queue}
	Priority: $Ticket{Priority}
	State: $Ticket{State}
	Owner: $Ticket{Owner}

Тут вставляем полученный текст в сообщение:
    Text: $Article{Body}

	Responsible: $Ticket{Responsible}
	Changed : $Ticket{Changed}

        $Host/otrs/index.pl?Action=AgentTicketZoom;TicketID=$Param{Data}->{TicketID}
	}) =~ s/^[\t ]*//mg;

    $TeleText{Data}->{queue}=$Ticket{Queue};
    

[littledpurple]

Здравствуйте! На GitHub есть ещё один скрипт для уведомления в телеге и там есть классная штука, что ссылка на тикет ОТРС сделана кнопкой. Можно ли так сделать и в вашем скрипте? Я пытался добавить параметр после $TeleText{Data}->{text}, но ничего хорошего не получилось

[littledpurple]

Оказалось легче, чем я думал. Если кому-то ещё интересно, надо добавить вот это

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

$TeleText{Data}->{reply_markup}="{\"inline_keyboard\":[[{\"text\": \"Open Ticket\", \"url\": \"$Host/otrs/index.pl?Action=AgentTicketZoom;TicketID=$Param{Data}->{TicketID}\"}]]}";

После вот этого

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

    ($TeleText{Data}->{text}=qq{
        #$Ticket{TicketNumber}
	Customer: $CustomerCompany{CustomerCompanyName}
	Queue: $Ticket{Queue}
	Priority: $Ticket{Priority}
	State: $Ticket{State}
	Owner: $Ticket{Owner}
	Responsible: $Ticket{Responsible}
	Changed : $Ticket{Changed}

        $Host/otrs/index.pl?Action=AgentTicketZoom;TicketID=$Param{Data}->{TicketID}
	}) =~ s/^[\t ]*//mg;

В/opt/otrs/Custom/Kernel/GenericInterface/Invoker/Telegram/TelegramTxt.pm

Но! Возник ещё один вопрос. Что с кодировкой? Можно ли как-нибудь писать в .pm скрипте на русском?

[alexus]

Но! Возник ещё один вопрос. Что с кодировкой? Можно ли как-нибудь писать в .pm скрипте на русском?

Можно, только кодировка должна быть UTF-8

[cheba]

Коллеги, большое спасибо. Текст заявки прикрутил, отлично работает. С кнопкой огромное спасибо, тоже у себя реализовал.
Остался единственный вопрос с кодировкой Поменял кодировку файла, но в телегу всё равно приходят крякозябры

вот такое приходит в телегу если в файле изменить поля на русский текст.

QIP Shot - Screen 057.png (3.69 КБ) 31794 просмотра