С помощью интеграции вы можете организовать взаимодействие между 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.

pmomnidesk.log:

  • libmgr ERROR Error: Type: 'constraint_update' Object: 'ticket2external_case' Value: 'ticket='0'' — попытка добавить в BILLmanager письмо, пришедшее по email. Причина: пользователь в BILLmanager, от которого пришло письмо, деактивирован;
  • libmgr ERROR Error: Type: 'emailvalidation_clientticket_deny' Object: '' Value: '' — попытка добавить в BILLmanager письмо, пришедшее по email. Причина: пользователь не подтвердил email;
  • libmgr ERROR Error: Type: 'rpc' Object: '400' Value: 'message_not_found' — попытка оценить в BILLmanager ответ поддержки, который был удален в Omnidesk.

omnidesk_webhook.log:

  • libmgr ERROR Error: Type: 'constraint_update' Object: 'ticket_message2external_case_message' Value: 'ticket_message='0' — в запрос в Omnidesk добавлено новое системное сообщение. В запросы BILLmanager добавляются только ответы сотрудников.

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

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

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

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