Skip to main content
Version: 8.1

Set up the SOAP web service integration

Level: intermediate

Integrate custom SOAP services with low-code tools. Creatio will generate and send a request to the web service, receive the response and extract the relevant data. Use the data received from the web service to create or update Creatio records, as well as to set up custom business logic or automation.

Although the general integration setup procedure is the same for all SOAP services, the details largely depend on the web service specifics.

To set up an integration with a new web service:

  1. Add the web service and configure its properties and methods.
  2. Set up the web service authentication (optional step). The authentication setup is similar for both REST and SOAP services.
  3. Test the integration.

You can start using the integration in custom business processes after that.

Example

Set up integration with “PhoneVerify” (https://ws.cdyne.com/phoneverify/phoneverify.asmx) SOAP service to receive the phone number information.

Make sure these parameters are supported:

  • CheckPhoneNumber” – the method that returns the phone number information.
  • PhoneNumber” – request parameter. Use it to pass the phone number. This parameter is required.
  • LicenseKey” – request parameter. Use it to pass the key.
  • Company” – response parameter. Contains the name of the company.
  • Valid” – response parameter. Contains the phone number validity information.

Creatio lets you import WSDL files or set up the integration manually.

note

WSDL files contain SOAP service information. You should be able to download a WSDL file from the open resources related to the service.

Set up the web service properties and methods automatically

  1. Go to the Studio workplace and open the Web services section.

  2. Click New web serviceSOAP service.

  3. Click Select WSDL file or specify the URL of the WSDL file with the web service description in the “SOAP web service quick setup” window.

  4. Select the SOAP service and version in the “SOAP service setup” window. Also specify the methods and method request parameters you need to call. Click Next.

  5. Specify the method response parameters you need to receive in the “SOAP service setup” window. Click Save (Fig. 1).

    Fig. 1 — Setting up the web service automatically
    Fig. 1 — Setting up the web service automatically

This will complete the web service setup. Creatio will populate the properties and methods on the service page automatically. Proceed to testing the SOAP service integration.

The alternative way to set up the web service properties and methods is specified below.

Set up the web service properties and methods manually

  1. Go to the Studio workplace and open the Web services section.

  2. Click New web serviceSOAP service.

  3. Click Skip quick setup in the “SOAP web service quick setup” window.

  4. Study the web service documentation. The following code is used in this example.

    <?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. Fill out the fields on the web service properties page (Fig. 2).

    Field

    Comment

    Example

    Name

    Enter the name that will be displayed in the Which method to call? field for the Call web service business process elements.

    Phone number information service

    Code

    Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.

    UsrPhoneVerifyService

    Namespaces

    Only specify the namespaces used for methods and method parameters. Add the namespace set in the format of “Namespace prefix:” ”Namespace,” separated by a semicolon “;” or a line break. If there is only a single namespace, the prefix is optional. Creatio will apply this namespace to the entire request.

    http://ws.cdyne.com/PhoneVerify/query

    Web service URI

    The complete web service call address will consist of this URI and the settings specified on the method setup page.
    Use the same protocol (HTTP/HTTPS) as your Creatio application.
    If the web service is located in an unmodifiable package, you can still edit its URI.

    http://ws.cdyne.com/phoneverify/phoneverify.asmx?WSDL

    Retries on call failure

    If the web service response returns an error code or times out, Creatio will repeat the request the specified number of times. Keep in mind the response timeout you are going to specify for web service methods when filling out this field.

    By default, “0”

    Package

    The package where Creatio will save this web service integration. The dropdown displays the packages the current user can modify.

    SoapWebServicePackage

    Fig. 2 Filling out the web service properties page
    Fig. 2 Filling out the web service properties page
note

Creatio saves the web service integrations as configuration items. If a web service configuration item is located in an unmodifiable package, you will only be able to edit its URI. To make other changes to such web service integrations, copy the relevant configuration items to user-made packages.

Set up method calling

Set up method calling for each web service integration. You can set up several methods per web service.

note

You can call any number of methods within a single process by using multiple Call web service process elements and mapping incoming and outgoing parameters between them.

  1. Click scr_add_button.png to add methods to the Methods tab of the web service integration setup page.

  2. Study the web service documentation. The following code is used in this example.

    <wsdl:types>
    <s:schema elementFormDefault="qualified" targetNamespace="http://ws.cdyne.com/PhoneVerify/query">
    <s:element name="CheckPhoneNumber"> ... </s:element>
    </wsdl:types>
  3. Fill out the method properties (Fig. 3).

    Field

    Comment

    Example

    Name

    Enter the name that will be displayed in the Which method to call? field of the Call web service business process element properties.

    Validate the phone number

    Code

    Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.

    UsrCheckPhoneNumber

    Message element code

    The name of the root XML node inside <soap:Body>. It often is the same as the operation name in WSDL. For example, the value is “MessageElementName” in this request body:

    <soap:Body>
    <MessageElementName>
    <Parameters> ... </Parameters>
    </MessageElementName>
    </soap:Body>

    CheckPhoneNumber

    SOAP Action

    Use the value specified in the web service documentation. For instance, the “PhoneVerify” web service has a “CheckPhoneNumber” endpoint that returns the information about the phone number.

    http://ws.cdyne.com/PhoneVerify/query/CheckPhoneNumber

    Response timeout, ms

    The time frame before Creatio considers a web service request timed out. If the service returns no response or responds with an error message, Creatio will retry the request after this time frame so long as there are retries available for this service call.

    By default, “5,000”

    Use authentication

    Use the authentication to access the web service. To enable the authentication, set it up on the Authentication detail of the web service integration setup page. Learn more: Web service authentication.

    By default, “false”

    Fig. 3 Web service method properties
    Fig. 3 Web service method properties

Set up the request parameters

Creatio uses the method request parameters to generate the endpoint URL for calling the web service.

The number and type of request parameters depend on the web service specifics. Add the parameters depending on the method.

The following request parameter types are available:

Body parameter

Creatio uses this parameter type to send data of any type (including collections) in the request body. Learn more about the POST request method in Wikipedia.

Header parameter

Creatio uses this parameter type to generate request headers. Learn more about HTTP headers in Wikipedia.

Cookies parameter

Creatio uses this parameter type to pass cookie files in the requests. For example, you can pass a previously-received authentication cookie. Learn more about cookies in Wikipedia.

To set up the request parameters:

  1. Study the web service documentation. The following code is used in this example.

    <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. Add the request parameters:

    1. Click Add parameter on the Request parameters tab.

    2. Add the “Phone number” parameter and fill out its properties (Fig. 4).

      Field

      Comment

      Example

      Name

      The service parameter name.

      Phone number

      Parameter type

      The service parameter type.

      Body parameter

      Path to element

      If the parameter uses a namespace, specify it in the format of “Namespace prefix:” ”Path to the parameter.”

      PhoneNumber

      Code in Creatio

      Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.

      UsrPhoneNumber

      Data type

      The service parameter data type A parameter with nested elements must have an “Object” data type.

      Text

      Is array

      An array parameter value cannot be set in the process designer’s “Call web service” element. Use the “Script task” element instead. The parameter with an “Object” data type must be an array.

      Cleared by default

      Required

      If selected, the parameter will be required in the Process Designer. If you specify a default parameter value, this checkbox will become unmodifiable.

      Checked by default

      Default value

      The default parameter value.

      Constant

      Fig. 4 Setting up the “Phone number” parameter
      Fig. 4 Setting up the “Phone number” parameter
    3. Add the “Key” parameter and fill out its properties (Fig. 5).

      Field

      Comment

      Example

      Name

      The service parameter name.

      Key

      Parameter type

      The service parameter type.

      Body parameter

      Path to element

      If the parameter uses a namespace, specify it in the format of “Namespace prefix:””Path to the parameter.”

      LicenseKey

      Code in Creatio

      Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.

      UsrLicenseKey

      Data type

      The service parameter data type. A parameter with nested elements must have an “Object” data type.

      Text

      Is array

      An array parameter value cannot be set manually in the process designer’s “Call web service” element. Use the “Script task” element instead. The parameter with an “Object” data type must be an array.

      Cleared by default

      Required

      If selected, the parameter will be required in the Process Designer. If you specify a default parameter value, this checkbox will become unmodifiable.

      Selected by default

      Default value

      The default parameter value.

      Constant

      Fig. 5 Setting up the “Key” parameter
      Fig. 5 Setting up the “Key” parameter

Set up the response parameters

To set up the response parameters:

  1. Study the web service documentation. The following code is used in this example.

    <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. Add the response parameters:

    1. Go to the Response parameters tab and click Add parameter.

    2. Add the “Company” parameter and fill out its properties (Fig. 6).

      Field

      Comment

      Example

      Name

      The service parameter name.

      Company

      Parameter type

      The service parameter type.

      Body parameter

      Path to element

      If the parameter uses a namespace, specify it in the format of “Namespace prefix:” ”Path to the parameter.”

      CheckPhoneNumberResponse/CheckPhoneNumberResult/Company

      Code in Creatio

      Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.

      UsrCompany

      Data type

      The service parameter data type. A parameter with nested elements must have an “Object” data type.

      Text

      Is array

      An array parameter value cannot be set in the process designer’s “Call web service” element. Use the “Script task” element instead. The parameter with an “Object” data type must be an array.

      Cleared by default

      Default value

      The default parameter value.

      Constant

      Fig. 6 Setting up the “Company” parameter
      Fig. 6 Setting up the “Company” parameter
    3. Add the “Valid” parameter and fill out its properties (Fig. 7).

      Field

      Comment

      Example

      Name

      The service parameter name.

      Valid

      Parameter type

      The service parameter type.

      Body parameter

      Path to element

      If the parameter uses a namespace, specify it in the format of “Namespace prefix:” ”Path to the parameter.”

      CheckPhoneNumberResponse/CheckPhoneNumberResult/Valid

      Code in Creatio

      Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.

      UsrValid

      Data type

      The service parameter data type. A parameter with nested elements must have an “Object” data type.

      Boolean

      Is array

      An array parameter value cannot be set in the process designer’s “Call web service” element. Use the “Script task” element instead. The parameter with an “Object” data type must be an array.

      Cleared by default

      Default value

      The default parameter value.

      Constant

      Fig. 7 Setting up the “Valid” parameter
      Fig. 7 Setting up the “Valid” parameter

Click OK to save the settings.

Set up the “collection” type response and request parameters

A collection (or an array) is a set of elements. Creatio can pass collections to the web service and parse the service responses that contain collections. You can set up both request and response “collection” parameters, provided the web service can receive and/or send arrays.

Collection parameter types:

  • Simple collection. You can make any parameter a collection by selecting the “Is array” checkbox in the parameter properties. Simple collections are arrays with data of a single type. Each value is a separate collection element. For example, “1, 2, 3” is a simple array of integer values, “Boston, New York, Chicago” is a simple array of string values, etc.
  • Object collection. A root parameter (or an object) that contains nested parameters.

To set up a collection:

  1. Study the web service documentation. The following code is used in this example.

    <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. Add the “CheckPhoneNumbers” method. Read more about the method fields in the Set up method calling step.

  3. Set up the request parameters. Read more about the parameter fields in the Set up request parameters step.

    Keep in mind that, according to the web service documentation, the “ArrayOfString” request parameter has a complex type that comprises an array of “string” elements. To set up collection request parameters:

    1. Select “Body parameter” in the Parameter type field.

    2. Select the Is array checkbox.

    3. Specify “string” in the Sequence element name field (Fig. 8). By default, “item” (for simple arrays).

      Fig. 8 Setting up the request parameters
      Fig. 8 Setting up the request parameters
  4. Study the web service documentation. The following code is used in this example.

    <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. Set up the response parameters. Read more about the method fields in the Set up the response parameters step.

    Select “Object” in the Data type field. This will make the nested parameters available (Fig. 9).

    Fig. 9 Setting up the data type
    Fig. 9 Setting up the data type

Web service response parameters of the collection type can be used as incoming parameters in the “Call web service” business process element. Learn more: Call web service process element.

Test the SOAP service integration

Test the integration setup before using the data received from the web service with custom business logic.

Since Creatio version 7.18.0, you can test a SOAP integration in the UI without creating a test business process.

To test the SOAP web service integration setup:

  1. Go to the Studio workplace and open the Web services section.

  2. Open the page of the web service whose integration you want to test. For example, “Phone number information service.”

  3. Open the “Check the phone number” method on the Methods detail of the web service integration setup page.

  4. Click Send a test request on the method setup page.

  5. Specify the values for the method call parameters.

    Parameter

    Value

    Phone number

    +1 617 765 7997

  6. Click Send request (Fig. 10).

As a result of the test request, the web service will send a response. The values of the response parameters are displayed on the Response parameters tab in the corresponding fields (Fig. 10). View the request and response formatted as XML or raw HTTP on other tabs.

Fig. 10 Testing the SOAP service integration
Fig. 10 Testing the SOAP service integration

If the web service integration is configured with an error, the test request will result in a response with empty parameter values. In this case, check all of the web service’s settings and try again.

Once you test the web service integration, you can start using the service in custom business processes. Read more about this example in the Update currency exchange rates with web service integration article.

Depending on the web service specifics, you may need to authenticate the service before it becomes available. Read more: Set up the web service authentication.


See also

Getting started with low-code web service integration

Set up the web service authentication


Resources

Tech Hour - Integrate like a boss