Web services are software applications that are provided over the internet using a standardized XML messaging system and described using Web Services Description Language (WSDL). You can add SOAP web services to the IBM App Connect catalog by importing WSDL or ZIP files that contain definitions for SOAP web services into App Connect.

You can then use App Connect to call the web service from a flow and to pass data between that web service and other apps – automatically, in real time. You can do so using configuration and data mapping techniques (without any need for coding), and can achieve a return on your investment in minutes or hours, rather than days or months.

This guide shows you how.

Additional reference: For usage and error handling information about your imported web service, see the written documentation for the service.

If you can’t find what you want, or have comments about the “how to” information, please either add comments to the bottom of this page or .

What should I consider first?

  1. To use App Connect with an imported web service, you must have a WSDL or ZIP file that defines all the resources and operations of your SOAP web service. Web services that use SOAP 1.1 and SOAP 1.2 are supported.
    More information: WSDL definition restrictions
  2. Next, use the “Add an API or Web Service” panel to import the WSDL or ZIP file into the App Connect catalog. The imported file is added as a web service with a set of actions that you can use in App Connect.
    More information: Importing a WSDL or ZIP file into App Connect as a web service
  3. Finally, connect App Connect to the imported web service so you can use it in your flows.
    More information: Connecting App Connect to your imported web service

WSDL definition restrictions

There are a number of restrictions on the WSDL files that can be imported into App Connect.

  • A ZIP file must contain only a single WSDL service.
  • The following XSD element types are modeled as a string: anyURI, base64Binary.
  • Any wsdl or xsd references being imported via a URL need to be publicly available.
  • The following definitions are not supported:
    • RPC-encoded WSDL definitions
    • WSDL services defining multiple WSDL ports
    • WSDL services defining multiple WSDL porttypes
    • WSDL definitions or XML schemas that require you to disambiguate between several different derived types
    • WSDL definitions that import schemas using any of the following XSD features:
      • anyType
      • substitutionGroup
      • choice
      • any
      • anyAttribute
      • union

Importing a WSDL or ZIP file into App Connect as a web service

Complete these steps to add an imported web service to App Connect:

  1. From the App Connect Catalog page, click the APIs tab.
  2. If necessary, scroll to the bottom of the tab, and then click the Add your API or web service now link.
  3. From the “Add an API or Web Service” panel, specify the file you want to import by completing either of the following steps. The file can be in a local or network drive, or accessible from a publicly available URL, and can have either of these file extensions: .wsdl (for a single monolithic WSDL file) or .zip.
    • Drag and drop the file from its location in an open file browser into the boxed area, or click within the boxed area to open a file browser and locate the file. You’ll see the file name in the boxed area, as shown in the following example.

      WSDL file added to the 'Add an API or Web Service' panel

    • Enter a valid fully qualified URL for the file you want to import. Only the HTTP and HTTPS transports are supported. If you are importing a web service by using a .zip file, any XSD files that are linked to must be publicly available. The URL must end in ?wsdl; for example:
      
      http://myserver.com/services/MyService?wsdl
      

      URL specified in the 'Add an API or Web Service' panel

  4. Specify a unique name (up to 30 characters) by which your web service can be identified on the APIs tab on the Catalog page or within the flow editor.
  5. Optional. Add a description that summarizes the function of the web service.
  6. Click Add API.

    Your web service is displayed on the APIs tab and is tagged with an ‘imported’ label Imported label for APIs. You can expand the web service to view the available actions and can use these actions in your flows.

Connecting App Connect to your imported web service

To create an integration flow that passes 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 app in the flow. You can connect to an imported API or web service from the APIs tab on the App Connect Catalog page, or when you add the API or web service or to a flow. You can connect to an app either from the Applications tab on the App Connect Catalog page, or when you add the app to a flow.

The values required to connect App Connect to a web service are dependent on the security scheme configured for the web service, and whether the endpoint is publicly available or private. To connect App Connect to your imported web service:

  1. Connect from the Catalog page as follows:
    1. From the Catalog page, click the APIs tab. You’ll see a list of:

      Shared and imported APIs and web services on the APIs tab

    2. Locate and click the imported web service.
    3. Click Connect to display the connection fields.
  2. Alternatively connect from the flow editor when adding the web service as a target application:
    1. From the flow editor, go to the APIs tab and select the imported web service.
    2. Select the action that you want to add.
    3. Click Connect to display the connection fields.
  3. Complete the connection fields as follows:
    • If basic authentication is configured for the web service via the Web Services Security (WS-Security) UsernameToken element, use the WS-Security user name and WS-Security password fields to specify a user name and password that can be used for validation.
      • Example of completed fields for WS-Security authentication

        Example of completed fields for connecting to a web service using WS-Security authentication

    • If the web service is secured on a system that uses Windows NT LAN Manager (NTLM) authentication to verify the identity of a user or client application that requires access:
      • Use the NTLM user name and NTLM password fields to specify credentials for a user account that can make calls to the web service.
      • If required, specify the domain name in the NTLM domain field and the workstation name in the NTLM workstation field.

        Note: NTLM authentication will take precedence over WS-Security authentication.

      • Example of completed fields for NTLM authentication

        Example of completed fields for connecting to a web service using NTLM authentication

    • If you want to override the host and port of the SOAP address (defined using soap:address location in your WSDL file) with values that point to a publicly available endpoint, use the Override the host name and port of the SOAP address field to identify this location. Specify the protocol, host name 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 host and port in the WSDL SOAP address will be overwritten with the specified host and port. This setting enables you to use the same flow to call different endpoints for the web service by setting up multiple accounts with different override URLs. For information about setting up multiple accounts, see Managing accounts in App Connect.

      • Example of completed fields with an override SOAP address

        If basic authentication is configured for the web service, you can also complete the the WS-Security user name and WS-Security password fields with a user name and password.

        Example of completed fields for connecting to a web service using an override SOAP address

    • If you want to override the host and port of the WSDL SOAP address with values that point to an endpoint in a private network (for example, behind a firewall in an on-premises location), you’ll need to set up a gateway that App Connect will use to securely access the endpoint. You can use a natively installed IBM Secure Gateway Client to set up the required network connection for making a call to the protected endpoint.

      Tip:

      To connect to an endpoint in a private network, complete both of these fields:

      • Override the host name and port of the SOAP address: Specify the protocol, host name or IP address, and the port number of the protected location in the format http://host:port or https://host:port. When you create and run a flow, the host and port in the WSDL SOAP address will be overwritten with a generated destination host and port, which will enable the SOAP request to be routed through the Secure Gateway, to the protected endpoint.
      • Network name: Specify the name of the network that was configured using the IBM Secure Gateway Client.
      • Example of completed fields with an override SOAP address for a protected endpoint

        If basic authentication is configured for the web service, you can also complete the the WS-Security user name and WS-Security password fields with a user name and password.

        Example of completed fields for connecting to a web service using an override SOAP address for a protected endpoint

    • If no authentication and no override values are required for connecting to or calling the web service, leave all the fields blank.
  4. Click Connect again to add the account.

Tip: Immediately after you connect, rename your account with a meaningful name that helps you identify which endpoint and credentials the account relates to. You’ll find this useful if you’d like to set up multiple accounts that enable access to multiple endpoints (in a public or private network) for the web service. You can rename an account only from the Applications tab on the Catalog page, and before it’s used in a flow. For information about renaming accounts and setting up multiple accounts, see Managing accounts in App Connect.

Using an imported web service in a flow

An imported web service can be used as a target application only, and cannot be used as a source application that triggers a flow.

Each operation in the imported WSDL file is exposed 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 displayed 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, and can also optionally add HTTP header information in the request.

Sample body and header fields for a SOAP request

To complete the body and header fields for an action:

  1. Add information that you want to include in the body of the SOAP request by completing the ‘input parameter’ fields. You can specify text values, select mapped fields from previous nodes in the flow, or apply JSONata expressions to transform the data.
  2. Optional. Add custom HTTP headers to define additional 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. You can define the header fields as data properties (with a name, String data type, and value) or you can specify the header information as a JSON object that consists of comma-separated name/value pairs:
    • To add header fields as data properties with defined values:
      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 and then select a data type of String. If required, click Add property to define additional header fields as data properties, with a type of String.

        Sample property names and their data types

      3. To expose the properties as fields so you can specify their values, click Edit mappings.
      4. Specify a value in each of the header fields.

        Sample HTTP header fields with specified values

        Tip:

        • You can add or remove properties by clicking Edit properties to switch back to the property editor.
        • If you want 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 grayed out and cannot be changed.)
    • To add header information as a JSON object, click Map to object. In the HTTP request headers field that is shown, specify the JSON in the following format:
      
      {"header_field1": "value1", "header_field2": "value2", ..., "header_fieldN": "valueN"}
      

      For example:

      HTTP request headers field with JSON specified

      Tip: If you’ve already defined one or more property fields under the HTTP request headers section, but would prefer to use JSON instead, first click Edit properties to delete those properties from the property editor, and then click Map to object to display the HTTP request headers field that you can type into.

Responses and error case handling for flows

The following details apply for flows that include an imported web service:

  • The response from the web service will include SUCCESS and FAILURE information, which you can map to in subsequent nodes in the flow. The FAILURE information will include any Fault definitions that are modeled in the WSDL file, and any unmodeled faults that are returned when the web service is invoked.

    Web service response

  • You can also map to the status code that is returned by expanding the Response info node in the list of available inputs.

    Web service status code

Removing an imported web service from the App Connect catalog

If no longer needed, you can delete an imported web service from the APIs tab on the Catalog page by clicking the Remove this API link for that web service. This link is visible only if the web service is not being used in any flows and if all accounts for the web service have been removed.

For information about deleting flows, see Starting, stopping, editing, viewing, sorting, and deleting flows. For information about removing accounts, see Managing accounts in App Connect.

Join The Discussion

Your email address will not be published. Required fields are marked *