xRM может как получать данные из внешних систем, так и отправлять им свои.

За взаимодействие с внешними системами отвечает модуль Integr. Модуль легко настроить на работу с различными системами по протоколу HTTP; он может быть расширен и для работы с другими протоколами. Функции-обработчики пишутся на чистом PL/SQL. Модуль позволяет системе быть как сервером, так и клиентом.

Объекты для взаимодействия с внешними системами можно создать в разделе Разработчик | Интеграция с внешними системами | Внешние системы.

1. Технические подробности

1.1. Объект для взаимодействия с внешними системами

Схематическое представление объекта:

1.2. Прием запроса во входной точке

Запрос приходит на веб-сервер, затем передается в модуль Integr на обработку. Запросы приходят по этому адресу:

/onyma/requests/<настраиваемый путь>

По умолчанию требуется авторизация. Это может быть базовая HTTP-авторизация или авторизация по cookie с ключом сессии. Кроме того, часто используется авторизация на сервере.

В версии 2.0.4 будет поддержка авторизации по URL с ACL для IP-адресов.

1.3. Запрос и ответ в PL/SQL

Для работы с HTTP-запросами на языке PL/SQL создано два объектных типа данных:

1. onm.httpRequest;

2. onm.httpResponse.

Основные атрибуты и методы типов httpRequest и httpResponse и их значения:

1.4. Простейший обработчик запроса

function get_info (p_req in onm.HttpRequest) return onm.HttpResponse is begin   -- ищем ID контрагента из запроса   l_id := get_id_from_Url(p_req.url);   -- пытаемся найти...     return onm.HttpResponse(200, 'Good answer'); exception   when no_data_found then -- не нашли КА     return onm.HttpResponse(404, 'No data found');   when others then -- что-то другое     return onm.HttpResponse(500, 'Unknown error: '||SQLERRM); end;

1.5. Простейший обработчик ответа

FUNCTION process_resp(p_resp IN ONM.HTTPRESPONSE) return number is ... begin -- проверяем, что получили достойный ответif p_resp.status_code != 200 then onm.err.raise(3, onm.tt_varchar('Bad HTTP status'||p_resp.status_code)); end if; -- разбираем данные ответа и делаем с ними то, что нам нужно...-- возвращаем результат с требуемым типом данныхreturn l_ret; end;

1.6. Как вызвать интеграционный метод в PL/SQL?

Асинхронное выполнение:

Вызов метода ставит задачу с сформированным HTTP-запросом в очередь на выполнение. После того, как задача отправит этот запрос и получит ответ, будет вызван обработчик ответа.Синхронное выполнение:

Вызов ставит задачу в очередь и ждет результата выполнения.

1.7. Вывод внешних данных в интерфейсе

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

1.8. Асинхронное взаимодействие

Синхронное выполнение не подходит для длительных задач. Асинхронное выполнение можно наладить двумя способами:

1. Принять запрос, отдать идентификатор задачи и позволить отслеживать состояние задания. Этого можно достичь при помощи MPS;
2. Принять запрос, по окончании выполнения вызывать callback-функцию. Этого можно достичь при помощи модуля Integr в сочетании с MPS или бизнес-процессами.

У отслеживания задачи по ID и callback-функции есть свои достоинства и недостатки.

1.8.1. Отслеживание задачи по ID

1.8.2. Callback-функция

2. Создание новой внешней системы

Перейдите в раздел Разработчик | Интеграция с внешними системами | Внешние системы.

Нажмите кнопку Добавить.

Заполните поля Наименование и Описание. Оба поля — необязательные, но внешняя система без названия будет выглядеть странно. Выберите продукт, для которого создаются настройки интеграции — например, User Extension. Укажите группу. Нажмите Сохранить.

3. Общие настройки

Во вкладке Настройки вы можете указать необходимые параметры внешней системы. Чтобы начать, нажмите кнопку Добавить.

В выпадающем списке Тип параметра выберите одно из следующих значений:

• Базовый путь входной точки. См. Формирование полного URL входной точки;
• URL. URL внешней системы;
• Дополнительные HTTP-заголовки. Параметры запросов для методов интеграции.
• Остальные перечисленные на снимке с экрана значения пока что не обрабатываются.

В поле Значение введите значение для выбранного параметра.

4. Настройки взаимодействия xRM с внешней системой

Во вкладке Методы интеграции можно создать запросы к внешней системе и обработчики ее ответов. Метод состоит из:

• Описания вызова;
• Входных параметров;
• Обработчиков ответа.

4.1. Создание нового метода

Откройте карточку внешней системы, перейдите во вкладку Методы интеграции. Нажмите Добавить. Заполните форму.

В поле Наименование введите краткое название метода.

В списке Тип метода выберите один из следующих типов:

• Простой HTTP GET;
• Простой HTTP POST;
• Простой HTTP PUT;
• Простой HTTP DELETE;
• Программный HTTP-запрос (запрос, формируемый пользовательской функцией)

В поле Вызов впишите адрес запроса. Для простых HTTP-запросов это URL (имя скрипта или полный путь к нему). Если во вкладке Настройки указано значение параметра URL, итоговый путь складывается из значений параметров URL и Вызов.

В поле Тело впишите тело запроса — в форматах JSON, x-www-form-url-encoded и т. д.

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

В списке Задача MPS выберите тип задачи для постановки в очередь. Указывать тип задачи обязательно для проверки метода. Метод можно также вызвать запросом из консоли. В большинстве случаев для этого необходим тип задачи MPS.

Доступные типы:

• STD_INTEGR_HTTP_AQBM. HTTP-запрос, отправляемый через AQ Buffered messaging. Подходит только для синхронных обращений;
• STD_INTEGR_HTTP_MQ. Интеграционный обработчик, посылает запросы через очередь сообщений MPS;
• STD_INTEGR_HTTP_PIPE. Отдельный асинхронный механизм для отправки HTTP-запросов браузером посредством JavaScript. Используется в интеграции с устройствами АРМ;
• STD_INTEGR_HTTP_UTL. Синхронно вызывает удаленную систему через UTL_HTTP (экспериментальная возможность). Требует настройки ACL и Wallet в Oracle.

Выбор типа STD_INTEGR_HTTP_MQ включает запись в журнал всех сведений о вызове (вызов, ответ удаленной системы и пр.). 

Обратите внимание: можно создавать свои собственные типы задач. У новых типов в названии должно быть слово INTEGR. Обычно создание собственных типов требуется, чтобы разделить задания в очереди MPS, и когда вас не устраивают стандартные количество повторов при ошибке или приоритет.

В списке Приоритет задачи MPS выберите приоритет. Указывать приоритет необязательно. Возможные значения:

• Высший;
• Высокий;
• Средний;
• Низкий;
• Очень низкий.

Установите переключатель Логировать в положение Включено (), чтобы включить полную запись истории вызовов. Отображение журнала зависит от выбранного типа задачи.

При проверке метода в журнал записываются полные данные о вызове.

Нажмите кнопку Сохранить.

4.2. Настройки метода

Карточка метода содержит несколько вкладок, нужных для его тонкой настройки. Это:

• Интеграционные методы (основная вкладка);

• Входные параметры;

• Обработчики ответа;

• Лог вызовов;

• Аудит.

4.2.1. Интеграционные методы

Поля основной вкладки — те же, что в карточке нового метода.

4.2.2. Входные параметры

Во вкладке выводится список входных параметров метода. Нажмите Добавить, чтобы создать новый параметр.

Заполните нужные поля. Поле Название в базе не должно быть пустым, Поля Описание и Тип заполняйте при необходимости.

Значения полей:

• Название в базе. Название, используемое в базе;
• Название. Название, используемое в системе;
• Описание. Развернутое описание;
• Позиция. Позиция, необходимая для использования параметра;
• Тип. Тип данных;
• Обязательность. По умолчанию все параметры необязательные. Возможные значения:
  • Обязательное;
  • Необязательное.
• Значение по умолчанию.

Нажмите Добавить, чтобы сохранить новый параметр.

4.2.3. Обработчики ответа

Обработчик ответа — функция, преобразующая ответ внешней системы к удобному для чтения виду. 

Для создания нового обработчика ответа нажмите Добавить. Заполните форму.

В поле Внешний метод выберите метод внешней системы, результат которого нужно обработать.

В поле Тип результата выберите один из двух типов:

1. Получен ответ;
2. Ошибка (обратите внимание: ошибка взаимодействия, а не протокола HTTP).

В поле Ключевое значение укажите  код состояния взаимодействия. Для результата Получен ответ это код HTTP-ответа, для результата Ошибка — код ошибки.

Возможные коды ошибок:

• 367. Превышение разрешенного времени отклика (timeout);
• 309. Ошибка обработчика ответа;
• 310. Остальные ошибки взаимодействия.

Обработать (вывести в нужном формате) непосредственно результат возможно только при получении ответа. При ошибке взаимодействия результат неизменяем, однако можно написать функцию, которая, например, сообщает об ошибке.

В поле Обработчик нажмите кнопку , чтобы выбрать функцию обработки данных.

Заполните поле Группа.

Нажмите кнопку Добавить.

4.2.4. Лог вызовов

Во вкладке Лог вызовов выводится список всех вызовов метода.

4.3. Проверка метода

Проверка метода возможна, только если выбран тип Задачи MPS.

Проверка запускается нажатием кнопки Тест метода. Нажатие на кнопку открывает форму, позволяющую задать значения входных параметров метода.

Результат выполнения запроса будет открыт в новой вкладке браузера.

Запуск проверки всегда попадает в системный журнал, вне зависимости от того, выставлен ли флажок Логировать.

5. Входные точки интеграции. Настройки взаимодействия внешней системы с xRM

В этой вкладке можно создать входные точки для обращений внешних систем к xRM Onyma. Для входной точки интеграции нужно задать:

• URL Pattern;
• Тип HTTP-запроса;
• Функцию-обработчик.

Откройте карточку внешней системы. Перейдите во вкладку Входные точки интеграции. Нажмите Добавить. Заполните карточку новой входной точки.

Укажите Наименование. 

Если нужно, заполните поле URL Pattern. См. Формирование полного URL входной точки.

В поле Обработчик нажмите кнопку , чтобы выбрать функцию обработки данных.

Установите переключатель Логировать в положение Включено (), чтобы включить запись истории вызовов. Если ведение журнала отключено, история взаимодействия с внешней системой записываться не будет.

Нажмите кнопку Добавить.

6. Формирование полного URL входной точки

Полный URL входной точки складывается из следующих частей:

1. Доменное имя;

2. /onyma/requests/;

3. Базовый путь входной точки во вкладке Настройки;

4. URL Pattern в настройках входной точки во вкладке Входные точки интеграции.