How to use IBM® App Connect with SOAP web services

After you import a SOAP web service into App Connect, you can add it as a target application to your flows.

Web services are software applications that are provided over the internet by using a standardized XML messaging system. Web services are described by using Web Services Description Language (WSDL). You can add SOAP web services to the App Connect catalog by importing WSDL or .zip files that contain definitions for SOAP web services. You can then use App Connect to call the web service from a flow and to pass data between that web service and other applications.

Importing a SOAP web service to App Connect

Import the SOAP web service into the App Connect catalog by following the instructions in Importing SOAP web services.

Connecting App Connect to an imported web service

To pass data between an imported web service and applications or APIs in the App Connect catalog, you must connect App Connect to each web service, API, and application in the flow. The necessary values to connect App Connect to a web service depend on the security scheme that is configured for the web service and whether the endpoint is publicly available or private. You can connect to the web service from the flow editor when you add it as a target application to a flow. The following steps describe how to connect to the web service from the App Connect catalog for the first time.

  1. In the App Connect catalog, expand the web service, then click Connect.
  2. Provide the appropriate connection information for your scenario. (If you don't need authentication or override values to connect to or call the web service, leave the fields empty.)
    • If the web service is secured through the Web Services Security (WS-Security) UsernameToken element, use the WS-Security username and WS-Security password fields to provide a username and password for validation.
    • If HTTP basic authentication is configured for the web service, use the HTTP basic auth username and HTTP basic auth password fields to provide a username and password for validation.
    • To override the hostname and port number of the SOAP address with a publicly available endpoint, set Override the hostname and port of the SOAP address to the endpoint location and leave the Private network connection field blank. (The hostname and port number of the SOAP address are defined by using soap:address location in your WSDL file.)

      Specify the protocol, hostname, or IP address, and the port number of your preferred location in the format http://host:port or https://host:port.

      When you create and run a flow, the hostname and port number in the WSDL SOAP address are overwritten with the specified host and port. With this setting, you can use the same flow to call different endpoints for the web service by setting up multiple accounts with different override URLs.

    • To override the hostname and port number of the WSDL SOAP address with an endpoint in a private network, provide the location of the endpoint and select a private network connection. App Connect uses this private network connection to connect securely to the endpoint.

      In Override the hostname and port of the SOAP address, specify the protocol, hostname, or IP address, and the port number of the endpoint in the format http://host:port or https://host:port. When you create and run a flow, the hostname and port number in the WSDL SOAP address are overwritten with a generated destination hostname and port number. The SOAP request is then routed to the endpoint in your network.

      In Private network connection, select the name of a private network connection. This list is populated with the private network connections that are created on the Private networks page. For more information, see Connecting to a private network.

  3. Click Connect.
    An account is created in App Connect, and the web service moves to the section of connected connectors in the App Connect catalog. By default, the account is named Account 1, but you can use the Account menu to rename it. You can now use the imported web service as a target application in your flows.
    Tip: For usage and error-handling information about your imported web service, see the written documentation for the service.
    The image shows that the Rename Account option is selected from the Account menu for the web service in the App Connect catalog.

Adding an imported web service to a flow

Note: You can add an imported web service as a target application only. You can't use an imported web service as a source application that triggers a flow.
Each operation in the imported WSDL file is available as an action that you can add to a flow. When you select an action, the input parameters that are defined for the associated operation are shown as fields with corresponding data types. You can use these fields to define the information that you want to include in the body of the SOAP request. You can also add HTTP header information in the request if appropriate.
Sample body and header fields for a SOAP request
To complete the body and header fields for an action, complete the following steps.
  1. To include information in the body of the SOAP request, complete the input fields that are shown by default. You can specify static data in plain text, or specify dynamic data by adding mappings from previous nodes in the flow. You can also apply functions (or JSONata expressions) to transform your data. For more information, see Techniques for specifying data to be passed to a target application or API.
  2. Add custom HTTP headers to define more operating parameters for the HTTP transaction that relates to the SOAP request. For example, you might want to specify a client ID value or override the Content-Type value for the message. (The Content-Type header defaults to text/xml; charset=utf-8 in SOAP 1.1 and application/soap+xml; charset=utf-8 in SOAP 1.2.) You can define the header fields as data properties (with a name, String data type, and value). Alternatively, you can specify the header information as a JSON object that consists of comma-separated name and value pairs.
    To add header fields as data properties with defined values, complete the following steps.
    1. In the HTTP request headers section, click Add property + to display the property editor.
    2. Enter the first header field as a property name, then select a data type of String. If necessary, click Add property + to define more header fields as data properties, with a data type of String.
      Sample property names and their data types for HTTP request headers. To properties are added (Content-Type and Content-Length), both with a data type of String.
    3. To make the properties available as fields so that you can specify their values, click Edit mappings.
    4. Specify a value in each of the header fields.
      Sample HTTP request header fields with completed values. The Content-Type field is set to text/xml. The Content-Length field is set to 300.
      Tip: If you need to add or remove properties, click Edit properties to return to the property editor. To update the name or data type of a defined property, ensure that the associated field is blank before you click Edit properties. In the property editor, properties with defined values are disabled so that you can't change them.
    To add header information as a JSON object, click Map to object. In the HTTP request headers field, specify the JSON in the following format: 
    {"header_field1": "value1", "header_field2": "value2", ..., "header_fieldN": "valueN"}
    HTTP request headers field with JSON specified.
    Tip:
    • If you defined one or more property fields under the HTTP request headers section, but want to use JSON instead, first use Edit properties to delete those properties from the property editor. Then, click Map to object to display the HTTP request headers field that you can edit.
    • To remove a completed HTTP request headers field that contains a JSON value, delete the value in the field to display Add property + again. When you click Add property +, the empty HTTP request headers field is replaced with the property editor and a pair of empty fields. You can either complete or delete these fields.
      Property editor for the HTTP request headers

Responses for flows with imported web services

The following information applies to flows that include an imported web service.
  • The response from the web service includes SUCCESS and FAILURE information, which you can map to from subsequent nodes in the flow. The FAILURE information includes any Fault definitions that are modeled in the WSDL file and any unmodeled faults that are returned when the web service is called.
    Sample web service response mappings
  • To map to the status code that is returned, expand the Response information node in the list of available mappings.
    Sample web service status code mapping

Removing an imported web service from the App Connect catalog

To remove an imported web service from the App Connect catalog, complete the following steps.
  1. Ensure that the web service isn't being used by any flows.
  2. On the App Connect catalog, expand the web service and remove all accounts for the web service.
    The image shows that the Remove Account option is selected from the Account menu for the web service in the App Connect catalog.
  3. Click Remove this API.