SOAP Connectors

Custom SOAP connectors enable you to access third-party web services hosted in the cloud or on-premises environment. You can also invoke a SOAP API in a Flow service by using a SOAP Connector.

The following features are supported for SOAP Connectors:

  • A SOAP connector implementation follows the WS-I Basic Profile 1.1 specification.
  • SOAP connectors can be created by uploading a WSDL file or by using a valid WSDL URL that can be accessed over a network.
  • SOAP connectors can be created with WSDLs that are annotated with WS-Security Policy/Policies.
  • SOAP connectors with SOAP version 1.1 and 1.2 and Style/Use as Document/Literal and RPC/Literal (RPC/Encoded model is not supported for SOAP version 1.2).

The following SOAP Binding types are supported:

  • SOAP over HTTP
  • SOAP over HTTPS
  • Authentication type: HTTP Basic Token.

SOAP connectors have the following restrictions:

  • The WSDL and associated schema(s) must be accessible through a publicly or locally accessible URL.
  • Only WSDLs with WS-Security policies are supported. Any other policies, for example, WS-Addressing, WS-Reliable Messaging, and so on, are not supported. If you create SOAP connectors with WSDLs having non-WS-Security Policies, exceptions may appear while executing Flow services.
  • Manual addition of WS-Security Policies in a SOAP Connector is not supported. SOAP connectors with WS-Security can be created with only policy-annotated WSDLs, that is, WSDLs that already have WS-Security Policies annotated in them.
  • SOAP over JMS is not supported.
  • Only Basic Authentication is supported. Other authentication types such as Digest, NTLM, and Kerberos are not supported.
  • You will not be able to attach or upload a file while executing a service.

Creating SOAP Connectors

The SOAP connectors enable you to access third party Web Services hosted in the cloud or on-premises. The SOAP connector uses a WSDL to create consumer operations. Let us understand how to create a SOAP connector and configure an account.

Note: You cannot add or delete operations to a SOAP connector created from a WSDL.

To create a SOAP connector, navigate to the Connectors tab in your project. From there, click SOAP and then select Add Connector to open the page where you can create a new SOAP connector.

You have two options for creating a SOAP connector:

  1. Import from URL: This option allows you to specify the WSDL URL (the location where the WSDL file is hosted).
  2. Import from file: This option lets you upload a WSDL file directly.
Steps to Create a SOAP Connector Using a URL:

  1. Click the Import from URL option. You can see the text field appearing in the same window.

  2. Specify the URL of the WSDL. The URL should begin with http:// or https://. The URL is used to retrieve the WSDL for the SOAP API.

  3. Click Next. The Define Connector page appears.

  4. In the Define Connector page, complete the following fields:

    • Name: Type a name for the SOAP connector, for example, Soap_connector.
    • Description: Type an optional description for the SOAP connector.
    • Connector Icon: Click Browse next to the Connector Icon if you want to select a different icon for your SOAP connector. The icon must be a PNG file and the size cannot exceed 50 KB, else the default image is displayed.
    • User: Enter the user name if authentication is required to access the WSDL URL.
    • Password: Enter the password if authentication is required to access the WSDL URL.
    • Validate Schema with Xerces: Select this option if you want IBM® webMethods Integration to also use the Xerces parser to validate the schemas associated with the XML Schema definition.
    • Click Save.
      Note: Required fields are marked with an asterisk on the screen.

      The new SOAP connector appears in the SOAP Connectors page. You can edit and remove a SOAP connector from the SOAP Connectors details page. The Used In column displays the Workflow and Flow service where the connector is used.

Steps to Create a SOAP Connector Using a File:

You can create a SOAP connector by using the Import from file option in Create SOAP connector page of the Connectors tab. You will be prompted to choose the Primary WSDL file and add imported WSDLs or XSDs or XML to primary WSDL and then define a connector. The ports that are configured here are listed in the Port Binding drop-down field of the Add Account dialog box while configuring a new account. According to the selected Port Binding value the URL field gets updated with the corresponding link. You can also edit the URL to specify a different web service endpoint.

To edit an existing SOAP connector:

To edit an existing SOAP connector, click the vertical ellipsis icon in the top-right corner of the connector and select Edit. On the Define Connector page that appears, under the Override Existing WSDL? section, choose No, Keep Existing WSDL if you do not wish to modify the WSDL URL or file. Select Yes, Override WSDL if you want to specify a new WSDL URL or upload a new WSDL file in the WSDL source section.
Note:

Updating the WSDL may result in addition or removal of Operations or fields in the Input/Output signature of an Operation. This may lead to incorrect mappings if you have used that Operation in an Workflow or Flow service.

To delete an existing SOAP connector:

To delete an existing SOAP connector, on the SOAP Connectors page, click the vertical ellipsis icon in the right corner of your connector, and click Remove.

To configure an account for the SOAP connector:

  1. To configure an account for the SOAP connector, click the New Account option. The Add Account dialog box appears.

  2. In the Add Account dialog box, fill in the following fields. All fields will be populated with values. You can add or modify the below values if required.

    • Account Name: Type a name for the SOAP connector account. Let us say, for example Soap_connector_1I.
    • Port Binding: Select the bind address from the drop-down list, that is, the concrete protocol and data format specification for the web service.
    • URL: This is the URL for the web service. You can edit the URL to specify a different web service endpoint.
    • Response Timeout: The number of milliseconds IBM webMethods Integration waits for a response before canceling its attempt to connect to the back end. In case the network is slow or the back end processing takes longer than usual, increase the response timeout value. It is recommended to specify a value other than 0. If you specify 0, IBM webMethods Integration will wait indefinitely for a response. If you do not specify a timeout, IBM webMethods Integration will consider 5 minutes as the response timeout. If the connection to the host provider ends before IBM webMethods Integration receives a response, the web service operation ends with an exception and a status code of 408.
    • User: User name used to authenticate the consumer at the HTTP or HTTPS transport level on the host server.
    • Password: The password used to authenticate the consumer on the host server.
    • Keystore Alias: Alias to the keystore that contains the private key used to connect to the Web Service host securely. You can also add a new Keystore from this field.
    • Key Alias: Alias to the key in the keystore that contains the private key used to connect to the Web Service host securely. The key must be in the keystore specified in the Keystore Alias field.
    • WS Security User Name: Name to include with the Username Token, if the Web Service's security policy requires one.
    • WS Security Password: The password to include with the Username Token (must be plain text).
    • WS Security Keystore Alias: The alias for the keystore, which contains private keys and certificates associated with those private keys. You can also add a new Keystore from this field.
    • WS Security Key Alias: The text identifier for the private key associated with the Keystore Alias.
    • WS Security Truststore Alias: The alias for the truststore, which contains the trusted root of a certificate or signing authority (CA). You can also add a new Truststore from this field.
    • WS Security Partner Certificate Alias: The file that contains the partner's self-signed certificate. You can also add a new Partner Certificate from this field.
    • Timestamp Precision: Whether the timestamp placed in the Timestamp element of the security header of an outbound message is precise to seconds or milliseconds. If the precision is set to milliseconds, the timestamp format yyyy-MM-dd'T'HH:mm:ss:SSS'Z' is used. If the precision is set to seconds, the timestamp format yyyy-MM-dd'T'HH:mm:ss'Z' is used.
    • Timestamp TTL: The time-to-live value for an outbound message in seconds. This value is used to set the expiry time in the Timestamp element of outbound messages. The timestamp precision value is used only when WS-Security is implemented through a WS-Policy.
    • Timestamp Max Skew: The maximum number of seconds that the Web Services client and host clocks can differ so that the timestamp expiry validation does not fail. The timestamp precision value is used only when WSSecurity is implemented through a WS-Policy. The inbound SOAP message is validated only if the creation timestamp of the message is less than the sum of the timestamp maximum skew value and the current system clock time.

  3. Click Add.

    Note:
    • Accounts created for SOAP connectors using the Flow Editor do not display the Edit and Delete icons when the same Accounts are displayed on the Connectors page in IBM webMethods Integration. You can use the existing accounts configured using the Flow Editor, but you cannot edit or modify the account details. Ensure that you create a new account for the SOAP connectors if any changes are required for the existing accounts.
    • Further, the accounts created for SOAP connectors using the Flow Editor cannot be used in Workflows, that is, pre-existing accounts will not be available in the Connect to drop-down list while creating a Workflow. Ensure that you create new accounts in such cases.

Invoking a SOAP API in a Flow service using a SOAP Connector

To invoke a SOAP API in a Flow service using a SOAP connector,

  1. From the IBM webMethods Integration navigation bar, click Projects.

  2. Select a project and then select Flow services. Click the "+" icon to start creating a new Flow service.

  3. Provide a name and description of the new Flow service. For example, ExecuteSOAPAPIFlowservices.

  4. On the Flow service, select CONNECTORS.

  5. Type Soap_connector in the search box and select the connector.

  6. Next, in the Type to choose action field, select an operation.

    You cannot add operations in a SOAP connector created from a WSDL. Also, you cannot delete operations from a SOAP connector created from a WSDL.

  7. Select the configured account. You can also create or configure an account inline.

  8. Click the "Map" icon to view the Flow service mapping page.

  9. Save the Flow service and click Run. After running the service, the results displays the data corresponding to your SOAP API