Настроить интеграцию с веб-сервисом SOAP

Продукты
Все продукты

Creatio поддерживает интеграцию с пользовательскими SOAP-сервисами с помощью инструментов low-code. Creatio сгенерирует и отправит запрос веб-сервису, получит ответ и предоставит необходимые данные. Данные, полученные от веб-сервиса, можно использовать для создания или обновления записей в Creatio, а также для реализации пользовательской бизнес-логики или автоматизации.

Общая последовательность настройки одинакова для всех SOAP-сервисов, детали во многом зависят от специфики веб-сервиса.

Этапы настройки интеграции с веб-сервисом:

  1. Добавление веб-сервиса и настройка его свойств и методов.
  2. Настройка аутентификации веб-сервиса (опциональный шаг). Настройка аутентификации идентична для REST и SOAP-сервисов.
  3. Проверка настройки интеграции с веб-сервисом.

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

Пример. Настроить интеграцию с SOAP-сервисом “PhoneVerify” (https://ws.cdyne.com/phoneverify/phoneverify.asmx) для получения информации по номеру телефона.

Необходимо реализовать поддержку следующих параметров:

  • “CheckPhoneNumber” — метод, который возвращает информацию по номеру телефона.
  • “PhoneNumber” — параметр запроса. В него необходимо передать номер телефона. Обязательный параметр.
  • “LicenseKey” — параметр запроса. В него необходимо передать ключ.
  • “Company” — параметр ответа. Содержит название компании.
  • “Valid” — параметр ответа. Содержит информацию о корректности полученной информации.

Creatio позволяет импортировать wsdl-файл или настроить интеграцию вручную.

На заметку. wsdl-файл содержит документацию SOAP-сервиса. wsdl-файл можно получить из открытых источников сервиса, с которым планируется интеграция.

Автоматическая настройка свойств и методов веб-сервиса 

  1. Перейдите в рабочее место Студия и откройте раздел Веб-сервисы.
  2. Нажмите Добавить веб-сервис —> SOAP сервис.
  3. В окне “Быстрая настройка SOAP веб-сервиса” нажмите Выбрать файл или добавьте ссылку на wsdl-файл с описанием веб-сервиса, интеграцию с которым необходимо настроить.
  4. В окне “Настройка SOAP веб-сервиса” выберите, какой сервис и версию SOAP использовать. Также настройте методы, которые необходимо вызывать, и параметры вызова методов. Нажмите Далее.
  5. В окне “Настройка SOAP веб-сервиса” выберите необходимые параметры ответов методов. Нажмите Сохранить (Рис. 1).
    Рис. 1 — Автоматическая настройка веб-сервиса
    scr_add_soap_web_service_blur.gif

Настройка веб-сервиса выполнена. Все свойства и методы на странице сервиса будут заполнены автоматически. Далее переходите к проверке интеграции с SOAP-сервисом.

Ниже приведен альтернативный способ настройки свойств и методов веб-сервиса.

Ручная настройка свойств и методов веб-сервиса 

  1. Перейдите в рабочее место Студия и откройте раздел Веб-сервисы.
  2. Нажмите Добавить веб-сервис —> SOAP сервис.
  3. В окне “Быстрая настройка SOAP веб-сервиса” нажмите Пропустить быструю настройку.
  4. Изучите документацию веб-сервиса. В нашем примере используется следующий код. 
    <?xml version="1.0" encoding="utf-8"?>
<wsdl:definitions xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://ws.cdyne.com/PhoneVerify/query" xmlns:s1="http://ws.cdyne.com/PhoneVerify/query/AbstractTypes" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" targetNamespace="http://ws.cdyne.com/PhoneVerify/query" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
...
</wsdl:definitions>
  5. Заполните поля страницы свойств веб-сервиса (Рис. 2).
    Поле Комментарий Пример
    Название Название будет отображаться в поле Какой сервис вызывать? области свойств элемента процесса Вызвать веб-сервис. Сервис получения информации по телефонному номеру
    Код Используется разработчиками для взаимодействия с веб-сервисом в программном коде Creatio. В данном случае уникальное имя интеграции с веб-сервисом состоит из его названия и префикса “Usr”. UsrPhoneVerifyService
    Пространства имен Необходимо указывать только пространства имен, которые используются для методов и их параметров. Набор пространств имен задается в формате “Префикс пространства имен”:“Пространство имен”, разделенных символом “;” или переводом строки. Если пространство имен только одно, то его можно задать без префикса. Это пространство имен будет применено ко всему запросу. http://ws.cdyne.com/PhoneVerify/query
    URI сервиса Полный адрес вызова веб-сервиса будет состоять из этого URI и настроек, указанных на странице настройки метода.
    Используйте такой же протокол (http/https), как и у сайта вашего приложения Creatio.
    Если веб-сервис содержится в недоступном для редактирования пакете, то его URI будет доступен для редактирования.    		 http://ws.cdyne.com/phoneverify/phoneverify.asmx?WSDL
    Повторов вызова при ошибках Если ответ от веб-сервиса пришел с кодом ошибки или истек тайм-аут ответа, то запрос будет повторен указанное количество раз. При заполнении этого поля учитывайте тайм-аут ответа, который будет указан для методов веб-сервиса. По умолчанию — 0
    Пакет Пакет, в котором будет сохранена данная интеграция с веб-сервисом. В списке отображаются пакеты, которые доступны для изменения текущим пользователем. SoapWebServicePackage
    Рис. 2 — Заполнение страницы свойств веб-сервиса
    scr_soap_web_service.gif

На заметку. Интеграции с веб-сервисами сохраняются в виде элементов конфигурации. Если такой элемент конфигурации находится в пакете, который недоступен для редактирования, то вы сможете изменить только URI веб-сервиса. Для внесения других изменений (например, для добавления методов) в такие интеграции с веб-сервисами скопируйте соответствующие элементы конфигурации в доступный для редактирования пакет.

Настроить вызов метода 

Для каждого веб-сервиса необходимо настроить вызов методов. При этом для одного веб-сервиса можно настроить несколько методов.

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

  1. На детали Методы страницы настройки интеграции с веб-сервисом при помощи кнопки scr_add_button.png добавьте методы.
  2. Изучите документацию веб-сервиса. В нашем примере используется следующий код. 
    <wsdl:types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://ws.cdyne.com/PhoneVerify/query">
        <s:element name="CheckPhoneNumber">
        ...
        </s:element>
</wsdl:types>
  3. Заполните свойства метода (Рис. 3).
    Поле Комментарий Пример
    Название Название будет отображаться в поле Какой сервис вызывать? области свойств элемента процесса Вызвать веб-сервис. Проверить номер телефона
    Код (на английском) Используется разработчиками для взаимодействия с веб-сервисом в программном коде Creatio. В данном случае уникальное имя интеграции с веб-сервисом состоит из его названия и префикса “Usr”. UsrCheckPhoneNumber
    Код элемента сообщения Название узла XML, который является корневым внутри <soap:Body>. Часто совпадает с названием операции в WSDL. Например, это будет “MessageElementName” в следующем теле запроса: 
    <soap:Body>
    <MessageElementName>
        <Parameters>
        ...
        </Parameters>
    </MessageElementName>
</soap:Body>
    		CheckPhoneNumber
    SOAP Action Для определения данного значения используется документация веб-сервиса.
    Например, у веб-сервиса “PhoneVerify” есть “конечная точка” “CheckPhoneNumber”, которая возвращает информацию по номеру телефона.    		 http://ws.cdyne.com/PhoneVerify/query/CheckPhoneNumber
    Тайм-аут ответа, мс Время ожидания ответа от веб-сервиса. Если после отправки запроса не был получен ответ, либо был получен код ошибки, то по истечении этого времени Creatio повторит запрос (если еще остались неиспользованные попытки повторного вызова). По умолчанию — 5 000
    Использовать аутентификацию Использовать аутентификацию для доступа к веб-сервису. Необходимо настроить аутентификацию на детали Аутентификация страницы настройки интеграции с веб-сервисом. Подробнее: Аутентификация веб-сервиса. По умолчанию — false
    Рис. 3 — Свойства метода веб-сервиса
    scr_soap_web_service_method_properties.png

Настроить параметры запроса 

Параметры запроса используются для генерации URL-адреса конечной точки, который Creatio будет использовать при вызове веб-сервиса.

Количество и типы параметров запроса определяются спецификой веб-сервиса. Параметры необходимо добавлять относительно метода.

Доступны следующие типы параметров запроса:

Параметр тела Этот тип параметра используется для отправки любых типов данных (включая коллекции) в теле запроса. Подробнее о методе POST запроса читайте в Википедии.
Параметр заголовка Этот тип параметра используется для генерации заголовка запроса. Подробнее об HTTP-заголовках читайте в Википедии.
Параметр cookies Параметры этого типа используются для передачи файлов cookie в запросах к сервису. Например, можно передать полученный ранее cookie для аутентификации. Подробнее о cookie читайте в Википедии.

Для настройки параметров запроса:

  1. Изучите документацию веб-сервиса. В нашем примере используется следующий код. 
    <s:element name="CheckPhoneNumber">
    <s:complexType>
        <s:sequence>
            <s:element minOccurs="0" maxOccurs="1" name="PhoneNumber" type="s:string" />
            <s:element minOccurs="0" maxOccurs="1" name="LicenseKey" type="s:string" />
        </s:sequence>
    </s:complexType>
</s:element>
  2. Добавьте параметры запроса:
    1. На вкладке Параметры вызова нажмите кнопку Добавить параметр.
    2. Добавьте параметр “Номер телефона” и заполните его свойства (Рис. 4).
      Поле Комментарий Пример
      Название Название параметра сервиса. Номер телефона
      Тип параметра Тип параметра сервиса. Параметр тела
      Путь к элементу Если для параметра используется пространство имен, то оно указывается в формате “Префикс пространства имен”:“Путь к параметру”. PhoneNumber
      Код в Creatio Используется разработчиками для взаимодействия с веб-сервисом в программном коде Creatio. В данном случае уникальное имя интеграции с веб-сервисом состоит из его названия и префикса “Usr”. UsrPhoneNumber
      Тип данных Тип данных параметров сервиса. Параметр с вложенными элементами должен иметь тип данных “Объект”. Текст
      Является массивом Значение параметра-массива нельзя задать в элементе “Вызвать веб-сервис” в дизайнере процессов. Необходимо использовать элемент “Задание-сценарий”. Параметр с типом данных “Объект” обязательно должен быть массивом. По умолчанию признак снят
      Обязательный При установленном признаке параметр будет обязательным в дизайнере процессов. Признак недоступен для редактирования при выборе значения по умолчанию. По умолчанию признак установлен
      Значение по умолчанию Значение параметра по умолчанию. Константа
      Рис. 4 — Настройка параметра “Номер телефона”
      scr_soap_web_service_parameter1_properties.png

    3. Добавьте параметр “Ключ” и заполните его свойства (Рис. 5).

      Поле Комментарий Пример
      Название Название параметра сервиса. Ключ
      Тип параметра Тип параметра сервиса. Параметр тела
      Путь к элементу Если для параметра используется пространство имен, то оно указывается в формате “Префикс пространства имен”:“Путь к параметру”. LicenseKey
      Код в Creatio Используется разработчиками для взаимодействия с веб-сервисом в программном коде Creatio. В данном случае уникальное имя интеграции с веб-сервисом состоит из его названия и префикса “Usr”. UsrLicenseKey
      Тип данных Тип данных параметров сервиса. Параметр с вложенными элементами должен иметь тип данных “Объект”. Текст
      Является массивом Значение параметра-массива нельзя задать в элементе “Вызвать веб-сервис” в дизайнере процессов. Необходимо использовать элемент “Задание-сценарий”. Параметр с типом данных “Объект” обязательно должен быть массивом. По умолчанию признак снят
      Обязательный При установленном признаке параметр будет обязательным в дизайнере процессов. Признак недоступен для редактирования при выборе значения по умолчанию. По умолчанию признак установлен
      Значение по умолчанию Значение параметра по умолчанию. Константа
      Рис. 5 — Настройка параметра “Ключ”
      scr_soap_web_service_parameter2_properties

Настроить параметры ответа 

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

  1. Изучите документацию веб-сервиса. В нашем примере используется следующий код. 
    <wsdl:types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://ws.cdyne.com/PhoneVerify/query">
        <s:element name="CheckPhoneNumberResponse">
            <s:complexType>
                <s:sequence>
                    <s:element minOccurs="1" maxOccurs="1" name="CheckPhoneNumberResult" type="tns:PhoneReturn" />
                </s:sequence>
            </s:complexType>
        </s:element>
        <s:complexType name="PhoneReturn">
            <s:sequence>
                <s:element minOccurs="0" maxOccurs="1" name="Company" type="s:string" />
                <s:element minOccurs="1" maxOccurs="1" name="Valid" type="s:boolean" />
                ...
		    </s:sequence>
        </s:complexType>
	...
</wsdl:types>
  2. Добавьте параметры обработки ответа:
    1. На вкладке Обработка ответа нажмите кнопку Добавить параметр.
    2. Добавьте параметр “Компания” и заполните его свойства (Рис. 6).
      Поле Комментарий Пример
      Название Название параметра сервиса. Компания
      Тип параметра Тип параметра сервиса. Параметр тела
      Путь к элементу Если для параметра используется пространство имен, то оно указывается в формате “Префикс пространства имен”:“Путь к параметру”. CheckPhoneNumberResponse/CheckPhoneNumberResult/Company
      Код в Creatio Используется разработчиками для взаимодействия с веб-сервисом в программном коде Creatio. В данном случае уникальное имя интеграции с веб-сервисом состоит из его названия и префикса “Usr”. UsrCompany
      Тип данных Тип данных параметров сервиса. Параметр с вложенными элементами должен иметь тип данных “Объект”. Текст
      Является массивом Значение параметра-массива нельзя задать в элементе “Вызвать веб-сервис” в дизайнере процессов. Необходимо использовать элемент “Задание-сценарий”. Параметр с типом данных “Объект” обязательно должен быть массивом. По умолчанию признак снят
      Значение по умолчанию Значение параметра по умолчанию. Константа
      Рис. 6 — Настройка параметра “Компания”
      scr_soap_web_service_response_parameter1_properties.png
    3. Добавьте параметр “Валидно” и заполните его свойства (Рис. 7).
      Поле Комментарий Пример
      Название Название параметра сервиса. Валидно
      Тип параметра Тип параметра сервиса. Параметр тела
      Путь к элементу Если для параметра используется пространство имен, то оно указывается в формате “Префикс пространства имен”:“Путь к параметру”. CheckPhoneNumberResponse/CheckPhoneNumberResult/Valid
      Код в Creatio Используется разработчиками для взаимодействия с веб-сервисом в программном коде Creatio. В данном случае уникальное имя интеграции с веб-сервисом состоит из его названия и префикса “Usr”. UsrValid
      Тип данных Тип данных параметров сервиса. Параметр с вложенными элементами должен иметь тип данных “Объект”. Логическое
      Является массивом Значение параметра-массива нельзя задать в элементе “Вызвать веб-сервис” в дизайнере процессов. Необходимо использовать элемент “Задание-сценарий”. Параметр с типом данных “Объект” обязательно должен быть массивом. По умолчанию признак снят
      Значение по умолчанию Значение параметра по умолчанию. Константа
      Рис. 7 — Настройка параметра “Валидно”
      scr_soap_web_service_response_parameter2_properties.png

Нажмите кнопку Ок для сохранения настроек.

Настроить параметры запроса и ответа типа “коллекция” 

Коллекцией (или массивом) является набор элементов. Creatio может передавать коллекции данных в веб-сервис и обрабатывать его ответы, содержащие коллекции. Если веб-сервис поддерживает получение и/или отправку массивов данных, то параметры типа “коллекция” можно использовать как для вызова веб-сервиса, так и для обработки его ответа.

Типы параметров коллекции:

  • Простая коллекция. Любой параметр можно представить в виде коллекции, установив в свойствах параметров признак “Является массивом”. Простые коллекции являются массивами значений одного типа данных. Каждое значение является отдельным элементом коллекции. Например, “1, 2, 3” — это простой массив значений целых чисел, а “Бостон, Нью Йорк, Чикаго” — простой массив текстовых значений.
  • Коллекция объекта. Коллекция представляет собой корневой параметр (т. н. объект), который содержит вложенные параметры.

Для настройки коллекции:

  1. Изучите документацию веб-сервиса. В нашем примере используется следующий код. 
    <s:element name="CheckPhoneNumbers">
    <s:complexType>
        <s:sequence>
            <s:element minOccurs="0" maxOccurs="1" name="PhoneNumbers" type="tns:ArrayOfString" />
            <s:element minOccurs="0" maxOccurs="1" name="LicenseKey" type="s:string" />
        </s:sequence>
    </s:complexType>
</s:element>
<s:complexType name="ArrayOfString">
    <s:sequence>
        <s:element minOccurs="0" maxOccurs="unbounded" name="string" nillable="true" type="s:string" />
    </s:sequence>
</s:complexType>
  2. Добавьте метод “CheckPhoneNumbers”. Поля методов описаны на шаге Настроить вызов метода.

  3. Настройте параметры запроса. Поля параметров описаны на шаге Настроить параметры запроса.

    Обратите внимание, что в соответствии с документацией веб-сервиса параметр запроса “ArrayOfString” — комплексный тип, который состоит из массива элементов “string”. Для настройки параметров запроса, который является коллекцией:

    1. В поле Тип параметра выберите “Параметр тела”.
    2. Установите признак Является массивом.
    3. В поле Название элемента массива укажите “string” (Рис. 8). По умолчанию — “item” (для простых массивов).
      Рис. 8 — Настройка параметров запроса
      scr_add_collection_parameter.png
  4. Изучите документацию веб-сервиса. В нашем примере используется следующий код. 
    <s:element name="CheckPhoneNumbersResponse">
    <s:complexType>
        <s:sequence>
            <s:element minOccurs="0" maxOccurs="1" name="CheckPhoneNumbersResult" type="tns:ArrayOfPhoneReturn" />
        </s:sequence>
    </s:complexType>
</s:element>
<s:complexType name="ArrayOfPhoneReturn">
    <s:sequence>
        <s:element minOccurs="0" maxOccurs="unbounded" name="PhoneReturn" type="tns:PhoneReturn" />
    </s:sequence>
</s:complexType>
<s:element name="PhoneReturn" type="tns:PhoneReturn" />
<s:element name="ArrayOfPhoneReturn" nillable="true" type="tns:ArrayOfPhoneReturn" />
<s:complexType name="PhoneReturn">
    <s:sequence>
        <s:element minOccurs="0" maxOccurs="1" name="Company" type="s:string" />
        <s:element minOccurs="1" maxOccurs="1" name="Valid" type="s:boolean" />
        ...
	</s:sequence>
</s:complexType>

  5. Настройте параметры ответа. Поля методов описаны на шаге Настроить параметры ответа.

    В поле Тип данных выберите “Объект”. После этого станут доступны вложенные параметры (Рис. 9).

    Рис. 9 — Настройка типа данных
    scr_add_collection_response_parameter.png

Параметры ответа веб-сервиса типа “коллекция” могут использоваться в качестве входящих параметров элемента бизнес-процесса Вызвать веб-сервис. Подробнее: Элемент процесса Вызвать веб-сервис.

Проверить настройку интеграции с SOAP-сервисом 

Для дальнейшего использования данных от сервиса в пользовательских бизнес-задачах необходимо проверить настройку интеграции.

Начиная с версии 7.18.0 появилась возможность проверить настройку интеграции с SOAP-сервисом из интерфейса приложения, без создания тестового бизнес-процесса.

Чтобы проверить настройку интеграции с SOAP-сервисом:

  1. Перейдите в рабочее место Студия и откройте раздел Веб-сервисы.
  2. Откройте страницу веб-сервиса, интеграцию с которым необходимо проверить. В нашем примере это “Сервис получения информации по телефонному номеру”.
  3. На детали Методы страницы настройки интеграции с веб-сервисом откройте метод “Проверить номер телефона”.
  4. На странице настройки метода нажмите Отправить тестовый запрос.
  5. Задайте значения параметров вызова метода.
    Параметр Значение
    Номер телефона +1 617 765 7997
  6. Нажмите Отправить запрос (Рис. 10).

В результате выполнения тестового запроса будет получен ответ от веб-сервиса. Значения параметров ответа отображены на вкладке Параметры ответа в соответствующих полях (Рис. 10). Другие вкладки позволяют посмотреть запрос и ответ на запрос на языках XML и HTTP (формат данных raw).

Рис. 10 — Проверка интеграции с SOAP-сервисом
scr_send_test_request.gif

Если при настройке интеграции с веб-сервисом была допущена ошибка, то в результате тестового запроса будет получен ответ с пустыми значениями параметров. В этом случае проверьте все настройки сервиса и повторите попытку.

После проверки вы можете использовать интеграцию с веб-сервисом в пользовательских бизнес-процессах. Подробнее данный пример описан в статье Использовать интеграцию с веб-сервисами для автоматического обновления курсов валют.

В зависимости от особенностей веб-сервиса, прежде чем он станет доступным для использования, может потребоваться выполнить процедуру аутентификации. Подробнее: Настроить аутентификацию веб-сервиса.

Смотрите также
Начало работы с low-code интеграцией веб-сервисов
Настроить аутентификацию веб-сервиса
Онлайн-курсы
Tech Hour: Настраивай интеграции like a boss в Creatio, часть 1