О плагине

Плагин предназначен для интеграции BGERP с мессенджером Telegram и предоставляет функционал:

  • отправка текстовых сообщений пользователям BGERP, а так же в произвольный chat_id

  • привязка процесса к чату группы или чату пользователя Telegram.

  • привязка пользователя к чату группы или чату пользователя Telegram.

  • использование настраиваемого форматирования в тексте отправляемых сообщений.

You can see the plugin enabled in Demo System.

Настройка

  • В BotFather создать своего бота, прописать его название и токен в конфигурации.

  • Создать параметры для пользователя и процесса, где будут храниться id чатов и прописать их в конфигурации.

После запуска найти в телеграм своего бота. И начать с ним диалог.

  • /getid - команда получения chat id. Его можно вписать в параметр своего пользователя или в параметр процесса.

  • /login - бот запросит логин и пароль от пользователя BGERP, а затем произведет заполнение параметра пользователя chat id.

  • /help - команда вывода текста из конфигурации плагина (MsgUrlHelp).

  • /start - команда вывода текста по умолчанию из конфигурации (msgDefaultAnswer).

В случае добавления бота в групповой чат (группа, супер группа, канал) - ему будет доступна отправка сообщений (используя JEXL скрипт sendMessageForProcess). Но при этом в случае ответа на сообщение бота - ни каких действий не будет происходить.

Пример настройки:

telegram:botStart=1

# настройки прокси, в случае необходимости
telegram:proxyHost=111.223.75.181
telegram:proxyPort=8888
# SOCKS5 , HTTP
telegram:proxyType=SOCKS5

# в BotFather создать своего бота, прописать его название и токен
telegram:token=842416376:AAFGsYLCgqG6eKcsZPy6gLCjge_klgUiWHE
telegram:botName=TestBgErp_bot

# параметр пользователя в котором будет храниться chatId
telegram:userParamId=90

# параметр процесса в котором будет храниться chatId
telegram:processParamId=91

Необязательные параметры (позволяют переопределить текст сообщений бота, к примеру для локализации текста под свой язык):
# ошибка неверный пароль
telegram:msgWrongPassword=неверный пароль
# текст после ввода команды /start
telegram:msgAskLogin=введите свой логин
# текст запроса пароля
telegram:msgAskPassword=введите свой пароль
# текст успешной привязки chaid к пользоватею
telegram:msgLinkChange=учетная запись обновлена
# стандартный ответ на текст вне комманд
telegram:msgDefaultAnswer=введите /login или /getid
# тест команды помощи
telegram:msgUrlHelp=Для получения помощи, обратитесь к разделу справки корпоративного портала (раздел BGERP)

Настройка типа процесса

В конфигурации типа процесса может быть настроена автоматизация работы с Telegram с помощью скрипта в doExpression простого обработчика событий. Ниже приведено несколько примеров возможных действий по различным событиям в процессе.

При изменении статуса, отправляется сообщение в чаты всех исполнителей процесса и чат самого процесса:

onProcessEvent.1.events=statusChanged
onProcessEvent.1.doExpression=<<END
    telegram.sendMessage(process, "Изменился статус");
END

При изменении статуса, отправляется сообщение только в чат самого процесса:

onProcessEvent.2.events=statusChanged
onProcessEvent.2.doExpression=<<END
    telegram.sendMessageForProcess(process, "Изменился статус");
END
onProcessEvent.3.events=statusChanged
onProcessEvent.3.doExpression=<<END
    telegram.sendMessage(process, "Изменился статус", "MarkdownV2");
END

Example of sending notifications about done processes to wanted chat IDs

#
STATUS_DONE_ID=4
#@bgerp: -1001285593190 @bgerp-dev: -1001307600319
TLG_GROUP_BGERP_ID=-1001285593190
#
onProcessEvent.11.events=statusChanged:{@STATUS_DONE_ID}
onProcessEvent.11.doExpression=<<END
    // BGERP Task
    if (process.getTypeId() == 6) {
        executorsList = u.getObjectList(ctxUserList, process.getExecutorIdsWithRole(0));
        from = u.toString(executorsList);

        text = "Принято изменение [" + process.getId() + "](https://team.bgerp.org/open/process/" + process.getId() + ")";
        text += " от " + from + ":" + NEW_LINE;
        text += telegram.escapeMarkdown(process.getDescription());

        telegram.sendMessage("{@TLG_GROUP_BGERP_ID}", text);
   }
END

Форматирование текста сообщений

По умолчанию отправка сообщений происходит без какого либо форматирования. В случае желания использовать форматирование - обращаем внимание на экранирование, т.к это частая ошибка приводящая к ошибкам отправки сообщений.

Объект telegram класса org.bgerp.plugin.telegram.ExpressionObject с функциями API предоставляется плагином.