Интеграция с Омнидеск

С помощью интеграции вы можете организовать взаимодействие между HelpDesk-системой Omnidesk и BILLmanager.

После настройки интеграции поддержке будут доступны возможности Omnidesk, а клиенты продолжат пользоваться встроенной системой поддержки в BILLmanager.

Настройка на стороне Omnidesk

1. Зарегистрируйтесь в сервисе Omnidesk.
2. Откройте интерфейс Omnidesk → Настройки → API → добавить API-ключ, который будет использовать BILLmanager.
   
3. Для работы с обращениями из BILLmanager создайте собственный канал: перейдите в Кастомные каналы → Добавить кастомный канал → заполните данные формы → кнопка Создать канал.
   В качестве Webhook URL укажите адрес в формате https://URL/mancgi/omnidesk_webhook?secret_key, где secret_key — Секретный ключ сервиса, последовательность символов, которую необходимо сгенерировать самостоятельно.
   

4. Добавьте сотрудника, от имени которого будет происходить взаимодействие между системами BILLmanager и Omnidesk: перейдите в Команда → Сотрудники → кнопка Добавить сотрудника.

   

   Обратите внимание!

   Сотрудник интеграции должен обладать полными правами для работы с кастомными и email-каналами. Подробнее см. в документации Omnidesk.

   
   

5. Добавьте поля обращения, которые будут заполняться данными из BILLmanager: перейдите в Каналы → Управление обращениями → Поля данных → кнопка Добавить поле. Подробнее см. в документации Omnidesk.

   Добавление полей типов Список и Чекбокс

   Чтобы интеграция работала с полями типов Список и Чекбокс, добавьте в файл /usr/local/mgr5/etc/omnidesk/custom_fields_values.json объект с соответствующим SQL-запросом.

   • В списках Omnidesk нумерация элементов начинается с единицы.

   Пример:

   В Omnidesk настроен список:

   

   Объект будет содержать следующий SQL-запрос:

   "attitude": {
       "entity": "user",
       "name": "Характеристика",
       "sql": "SELECT IF(a.attitude = 0, 1, IF (a.attitude = 1, 2, 3)) FROM account a JOIN user u ON u.account = a.id WHERE u.id = '__id__';"
     }

   CODE

   • Чекбоксы могут принимать состояния: true или false.

   Пример:

   В Omnidesk настроен чекбокс:

   

   Объект будет содержать следующий SQL-запрос:

   "have_phone": {
       "entity": "user",
       "name": "Номер заполнен",
       "sql": "SELECT IF (phone IS NULL, 'false', 'true') have_phone FROM user WHERE id = __id__"
     }

   CODE

   Состояние чекбокса будет меняться в зависимости от того, указан номер или нет.

   
   

Настройка на стороне BILLmanager

Установка модуля

Для интеграции BILLmanager с Omnidesk установите соответствующий модуль: Интеграция → Модули → модуль Omnidesk → кнопка Установить.

Установка модуля Omnidesk

Настройка параметров интеграции

Для настройки модуля заполните параметры интеграции: Интеграция → Модули → выберите модуль Omnidesk → кнопка Настроить.

• API URL — URL-адрес личного кабинета Omnidesk в формате yourcompany.omnidesk.ru, либо собственный поддомен. Подробнее см. в документации Omnidesk;

• Email пользователя интеграции — email сотрудника, от имени которого происходит взаимодействие между системами BILLmanager и Omnidesk;

  

  Обратите внимание!

  Для корректной работы интеграции сотрудник должен обладать полными правами на управление запросами. Подробнее см. в документации Omnidesk.

• API ключ — API-ключ для интеграции с BILLmanager;
• Кастомный канал — ID кастомного канала из Omnidesk. Например, cch477;
• Секретный ключ уведомлений — секретный ключ сервиса для проверки подлинности уведомлений. См. раздел Настройка на стороне OmniDesk;
• Синхронизировать запросы с — дата, начиная с которой будут синхронизированы запросы в Omnidesk.

Дополнительные параметры

• Синхронизировать автооветы — активируйте опцию, чтобы передавать автоматические ответы из Омнидеск в BILLmanager. Ответы будут добавляться от лица сотрудника интеграции;
• Синхронизировать заметки — активируйте опцию, чтобы передавать заметки из Омнидеск в BILLmanager и внутренние комментарии из BILLmanager в Омнидеск;
• Секретный маркер — укажите секретный маркер, если вы используете удалённый тип аутентификации. Выполните настройку на стороне Омнидеск:
  • в поле "URL удалённого входа" укажите ссылку вида https://{billmgr_domain}/billmgr?startform=omnidesk.sso;
  • в поле "URL удалённого выхода" укажите ссылку вида https://{billmgr_domain}/billmgr?func=logon.
    Подробнее см. документацию омнидеск;

• Передавать время создания сообщения через — укажите время, в секундах. Омнидеск обрабатывает старые сообщения и новые по разным правилам. Параметр отвечает за определение допустимого времени задержки, чтобы при повторной синхронизации BILLmanager передавал сообщение как новое.

  Пример

  Возникла задержка при синхронизации Омнидеск и BILLmanager в 5 минут.

  Если значение поля "Передавать время создания сообщения через" меньше времени задержки, то BILLmanager отправит в Омнидеск время создания сообщения как при синхронизации старых запросов. Старые запросы Омнидеск обрабатывает без применения правил. Омнидеск выставит сообщению то время, когда оно поступило в BILLmanager.

  Если значение поля "Передавать время создания сообщения через" больше времени задержки, то BILLmanager отправит сообщение без времени создания. Омнидеск применит к сообщению внутренние правила обработки. Сообщению будет выставлено время, в которое оно поступило в Омнидеск, а не в BILLmanager.

Настройка кастомных полей

При добавлении кастомного поля вы устанавливаете связь между полем на стороне Omnidesk и значением в BILLmanager.

1. Создайте сотрудника с email, совпадающим с email пользователя интеграции. Подробнее см. в статье Сотрудники и отделы.
2. Выдайте пользователю права группы Поддержка. Подробнее см. в статье Сотрудники и отделы.
3. Добавьте кастомное поле: Интеграция → Модули →  выберите модуль Omnidesk → кнопка Настроить → кнопка Добавить кастомное поле.
4. Настройте кастомные поля:
   
   1. Сущность — выберите сущность, к которой относится кастомное поле — обращение или пользователь.
   2. Поле в Omnidesk — выберите имя поля в Omnidesk.
   3. Значение — выберите значение сущности в BILLmanager, которое будет передано для "Поля в Omnidesk".
      
      
5. Нажмите кнопку Ok.

Чтобы изменить поле после сохранения, нажмите Редактировать.

Добавление новых значений для полей

Значения формируются на основании данных пользователей и запросов BILLmanager. Доступные значения хранятся в файле /usr/local/mgr5/etc/omnidesk/custom_fields_values.json.

Чтобы добавить новые значения:

1. Сформируйте объект. Каждое значение представляет собой объект вида:

   {
     "client_id": {
      "entity": "user",
      "name": "ID клиента",
      "sql": "SELECT account FROM user WHERE id = __id__"
     }
   }

   CODE
   Пояснения

   где

   • client_id — уникальный ключ для значения;
   • entity — сущность, к которой относится значение. Может принимать два значения: case — для полей обращений, user — для полей пользователей;
   • name — имя поля в BILLmanager, которое будет отображено в интерфейсе при настройке кастомного поля;
   • sql — запрос, который передаёт информацию по связанной сущности. Вместо макроса __id__ будет подставлен ID конкретного обращения (case) или пользователя (user).
   Значения по умолчанию

   {
     "balance": {
       "entity": "user",
       "name": "Баланс лицевого счета",
       "sql": "SELECT GROUP_CONCAT('Статус: ', IF(s.active = 'on', 'Активный', 'Временно отключен'), '\\n\\tБаланс: ', s.balance, ' ', IFNULL(cur.symbol, cur.iso), '\\n\\tГодовой оборот: ', IFNULL((SELECT SUM(subaccountamount) FROM payment WHERE status = 4 AND paydate > '2020-12-13 00:00:00' AND subaccount = s.id), 0), ' ', IFNULL(cur.symbol, cur.iso) SEPARATOR '\\n') FROM user u JOIN account a ON a.id = u.account JOIN subaccount s ON a.id = s.account JOIN currency cur ON cur.id = s.currency LEFT JOIN country c ON c.id = a.country WHERE u.id = __id__"
     },
     "client_id": {
       "entity": "user",
       "name": "ID клиента",
       "sql": "SELECT account FROM user WHERE id = __id__"
     },
     "group": {
       "entity": "user",
       "name": "Группы клиента",
       "sql": "SELECT GROUP_CONCAT(g.name SEPARATOR '\\n') FROM user u JOIN account a ON a.id = u.account JOIN account2group ag ON ag.account = a.id JOIN account g ON g.id = ag.accountgroup WHERE u.id = __id__"
     },
     "note": {
       "entity": "user",
       "name": "Комментарий",
       "sql": "SELECT a.note FROM user u JOIN account a ON a.id = u.account WHERE u.id = __id__"
     },
     "country": {
       "entity": "user",
       "name": "Страна",
       "sql": "SELECT c.name_ru FROM user u JOIN account a ON a.id = u.account JOIN country c ON c.id = a.country WHERE u.id = __id__"
     },
     "reg_date": {
       "entity": "user",
       "name": "Дата регистрации",
       "sql": "SELECT UNIX_TIMESTAMP(a.registration_date) FROM user u JOIN account a ON a.id = u.account WHERE u.id = __id__"
     },
     "ticket": {
       "entity": "case",
       "name": "Номер тикета",
       "sql": "SELECT t.id FROM ticket t WHERE t.id = __id__"
     },
     "project": {
       "entity": "case",
       "name": "Провайдер",
       "sql": "SELECT p.name FROM ticket t JOIN project p ON p.id = t.project WHERE t.id = __id__  "
     },
     "item_ip": {
       "entity": "case",
       "name": "Услуга c IP",
       "sql": "SELECT CONCAT('Услуга: ', i.id, '\\nТариф: ', IFNULL(pl.name_ru, pl.name), '\\nIP: ', IFNULL(ip.value, 'отсутствует')) AS item FROM ticket t LEFT JOIN item i ON i.id = t.item LEFT JOIN pricelist pl ON pl.id = i.pricelist LEFT JOIN itemparam ip ON ip.item = i.id AND ip.intname = 'ip' WHERE t.id = __id__"
     },
     "item": {
       "entity": "case",
       "name": "Услуга",
       "sql": "SELECT i.name_ru FROM ticket t LEFT JOIN item i ON i.id = t.item WHERE t.id = __id__"
     },
     "department": {
       "entity": "case",
       "name": "Отдел",
       "sql": "SELECT IFNULL(u.name_ru, u.name) FROM ticket t join user u ON t.responsible = u.id WHERE t.id = __id__"
     },
   }

   CODE
2. Добавьте объект в файл /usr/local/mgr5/etc/omnidesk/custom_fields_values.json.

Дополнительные настройки

Для синхронизации оценок ответов поддержки с BILLmanager:

1. Откройте интерфейс Omnidesk → вкладка Настройки → Оценка ответов.

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

   

   Обратите внимание!

   В Omnidesk используется три типа оценки: отлично, хорошо, плохо. В BILLmanager только два типа оценки: отлично, плохо.

Настройки оценки качества ответов

Устройство модуля интеграции

База данных

Модуль использует в работе следующие таблицы:

• ticket2external_case — связывает запрос в BILLmanager с обращением Omnidesk;
• ticket_message2external_case_message — связывает сообщения в запросе BILLmanager и обращении Omnidesk;
• user2external_user — связывает пользователя BILLmanager с пользователем Omnidesk.

Логирование

Логи взаимодействия биллинговой платформы с Omnidesk записываются в файлы:

• var/omnidesk_webhook.log — работа CGI для уведомлений;
• var/pmomnidesk.log — взаимодействие между системами BILLmanager и Omnidesk;
• var/billmgr.log — работа библиотеки, подключённой к BILLmanager.

Cron-задание для синхронизации тикетов

Если не удалось синхронизировать тикеты, BILLmanager запустит cron-задание:

25 */4 * * * /usr/local/mgr5/processing/pmomnidesk --command sync_tickets >/dev/null 2>&1