Skip to Content

This blog describes how to use Web Services Description Language files (in short: WSDLs) in the SOAP adapter. It also explains how to upload WSDLs with external references in the resource view and use them in the SOAP adapter.

Usage of WSDL Files in the SOAP Adapter

You can configure the SOAP adapters with or without WSDLs. A WSDL can be used to configure the exchange pattern and web service security policies. You can also use WSDLs with external references, like for example XSDs.

Note! In the SOAP Sender channel WSDLs with external references can be used, but the WSDL download cannot parse them. This means you can use such WSDLs for runtime execution but if you want to download the WSDL with the generated endpoint to provide it to the service consumer you need to resolve the references in the WSDL and add the schema definition from XSD directly into the WSDL.

Note! Currently WSDLs with external references are not allowed in the mapping step! This is planned. Expect an update here once this is available.

There are different options how to upload the WSDL and XSD files and how to configure them in the different SOAP channels. This blog first describes the general upload and configuration options in the SOAP sender and receiver channels and afterwards provides additional details about special restrictions in the different SOAP adapters.

Upload the WSDL in SOAP Channel

The easiest way to upload a single WSDL file is to use the upload dialog directly in the SOAP adapter configuration. In the SOAP adapter channel select the Connection tab and there use the Select button for the URL to WSDL field:

The Select WSDL Resource dialog opens. Select Upload from File System at the very bottom of the dialog to open the file browser. Select the WSDL from your local file system and upload it.

If multiple operations are available in the WSDL you need to select the one you want to use in the channel in the WSDL selection dialog.

Note that when configuring a SOAP receiver channel you need to have at least one service defined in the WSDL. For the SOAP sender this is not necessary because there the runtime WSDL is generated by Cloud Integration. More details about specific behavior of SOAP sender and receiver below.

During the upload the WSDL is parsed; the fields URL to WSDL, Service, Endpoint and Operation Name are filled automatically based on the content of the WSDL.

In the fields Service, Endpoint and Operation Name a namespace prefix is defined before the actual value. This prefix with the namespace from the WSDL is automatically added to the namespace definitions in the integration flow. This setting can be found in the Runtime Configuration tab in the integration flow in field Namespace Mapping:

The upload imports the WSDL into the wsdl folder of the Schemas section in the Resources view. Verify this by selecting the Resources tab in the integration flow and expanding the Schemas section. You can find the uploaded WSDL there. In the tooltip the complete Access path is shown. You notice that the WSDL is present in the wsdl folder. The Access path is the parameter that is to be specified in the URL to WSDL field in the SOAP adapter (which is set automatically when selecting the WSDL from the file system). You can use it with or without / at the beginning, both is accepted.

If you want to upload the WSDL again, for example after you have done some changes, you can use the same upload option in the SOAP channel. The WSDL is then overwritten during upload.

 

Upload the WSDL in Resources View

The second option to upload WSDL files is to use the Resources view. In this view you can upload single WSDL files and archives having WSDL files with external references together with the referenced files.

Upload Single WSDL in Resources View

Using the Resources view, you can upload single WSDL files. To upload a WSDL, open the integration flow in edit mode and select the Resources view. In the right upper corner select Add –> Schema –> WSDL.

The Add WSDL dialog opens. To upload the WSDL from your local file system select File System as Source and browse for the WSDL. Select Add at the bottom to start the upload. A success message indicates that the WSDL was uploaded successfully.

The uploaded WSDL appears under the Schemas section in the Resources view showing the Access path in the tooltip.

Upload an Archive Containing WSDL and Referenced Files in Resources View

Besides uploading single WSDL files you can also upload archives In the Resources view – for example, when you like to upload WSDL files together with all external resources referenced in the WSDL.

Because all files have to be uploaded in an archive, you first need to wrap (zip) all WSDL and XSD files to an archive.

1. Option: All XSDs/WSDLs are Located in the wsdl Folder

All WSDL and XSD files can be stored directly in the wsdl folder. In the SOAP receiver adapter this is currently the only supported option if you want to use WSDL files with external references. For this you need to wrap all files in a zip file containing all files without any folder structures:

Important Remark:

You need to make sure the import and/or include statements in the WSDL are correctly defined. Best practice is to use relative paths. This means that the path is defined relative to the location of the WSDL or schema where it is included or imported. In the above example this means that the referenced XSD files that are contained in the wsdl folder as well, have to be referenced in the WSDL like this:

Important Remark:

With the 28-October release of Cloud Integration, also the SOAP receiver is supporting WSDL and XSD files in subfolders (see option 2).

2. Option: XSDs/WSDLs are Located in Subfolders of the wsdl Folder

For the SOAP sender and the with the 28-October update also the SOAP receiver the archive can also have subfolders containing the referenced WSDLs and/or XSDs:

Important remark:

You need to make sure the import and/or include statements in the WSDL are correctly defined. Best practice is to use relative paths. This means that the path is defined relative to the location of the WSDL or schema where it is included or imported. In the above example this means that the referenced XSD files that are contained in the xsd subfolder, have to be referenced in the WSDL like this:

In this example, the included schema “empleado.xsd” is itself importing further schemas that also reside in the xsd subfolder. Therefore, those import statements also have to be relative to the importing schema. As all XSDs are located in the same folder the xsd folder must not be mentioned in the import statements in the “empleado.xsd”.

Upload the Archive in Resource View

To upload an archive containing the WSDL file and the referenced files, for example XSDs, open the integration flow in edit mode and select the Resources view. In the right upper corner select Add –> Schema –> WSDL.

The Add WSDL dialog opens. To upload the archive from your local file system, select File System as Source and browse for the archive file. Select Add at the bottom to start the upload. A success message indicates that the archive was uploaded successfully.

All WSDL and XSD files are uploaded to the Schema section into the wsdl folder in the Resources view because the upload was triggered using the Add –> Schema –> WSDL action. When checking the Access path shown in the tooltip, you notice that the folders from the archive (in this case the xsd folder) are created below the wsdl folder.

Select the WSDL in the SOAP Channel

After you have uploaded the WSDL with or without referenced files in the Resources view you can use it in the SOAP channel.

Open the SOAP sender or receiver channel and select the Connection tab. There, use the Select button for the URL to WSDL field to open the WSDL selection dialog:

The Select WSDL Resource dialog opens. From the list of WSDLs contained in the integration flow select the one required for the channel.

If multiple operations are available in the WSDL you need to select the one you want to use in the channel in a second selection screen.

Note that in the SOAP receiver you need to have at least one service defined in the WSDL. In the SOAP sender this is not necessary because there the runtime WSDL is generated by Cloud Integration. More details about the SOAP sender and receiver below.

During the selection of the WSDL the WSDL is parsed; the fields URL to WSDL, Service, Endpoint and Operation Name are filled automatically from the WSDL.

In the fields Service, Endpoint and Operation Name a namespace prefix is defined before the actual value. This prefix with the namespace from the WSDL is automatically added to the namespace definitions in the integration flow. You can find this namespace definition in the Runtime Configuration tab in the integration flow in field Namespace Mapping:

Important Remark:

With one of the next updates of Cloud Integration, the WSDL configured in the SOAP channel can also reside in a subfolder of the WSDL folder. This is not possible at the moment (the main WSDL is expected in the wsdl folder directly).The blog will be updated once this is available.

With one of the next updates, the WSDL selection dialog shows all WSDL files contained in the wsdl folder. If the WSDL resides in a subfolder of the wsdl folder the subfolder is shown as well:

Special Considerations for the Different SOAP Adapters

The different SOAP adapters have slightly different requirements for the used WSDLs. This is described in this section.

WSDL Usage in SOAP 1.x Receiver Adapter

The SOAP 1.x receiver adapter requires a service and port defined in the WSDL, because this is the service definition that is used at runtime.

If you use the WSDL selection dialog for a WSDL without service and port, the port selection dialog shows the message ‘No resource available’.

To solve this problem, define a service and port in the WSDL. Usually the WSDL is provided by the service backend and already contains this information, but it can also be added manually in the WSDL.

As mentioned above, WSDL and referenced XSD files have to be located in the wsdl folder directly, no subfolders are supported before the 28-October release.

With the 28-October release of Cloud Integration, also the SOAP receiver is supporting WSDL and XSD files in subfolders. But the WSDL defined in the SOAP channel needs to reside directly in the wsdl folder, not in a subfolder (this will be allowed in the next update).

Important Remark:

The SOAP 1.x adapter does not support WSRM. Make sure the used WSDL does not contain such policies. In future a check will be introduced raising an error in case WSRM is defined in the WSDL.

WSDL Usage in SOAP 1.x Sender Adapter

The SOAP 1.x sender adapter does not need a service and port defined in the WSDL, because in this case Cloud Integration is the service provider and generates its own runtime WSDL based on the content of the WSDL (if configured) and the definitions in the SOAP sender channel. But if service and port are defined in the WSDL, they are used.

This means that the WSDL selection dialog supports both options. If service and port are defined in the WSDL, those values are taken over into the fields Service and Endpoint together with a namespace definition:

If no service and port are defined in the WSDL those two fields are not filled:

During deployment of the integration flow the runtime WSDL is generated based on the content of the configured WSDL and the settings configured in the channel. Policies, that are contained in the configured WSDL are removed and substituted with Cloud Integration policies.

Important Remark:

The SOAP 1.x adapter does not support WSRM. If the used WSDL contains WSRM policies they are removed automatically during runtime WSDL generation.

This WSDL can be downloaded from the Manage Integration Content monitor in the Monitoring cockpit. In the Manage Integration Content monitor select the integration flow to get its details. In the Endpoints section you find the option to download the WSDL. This is the generated runtime WSDL which can be provided to the consumer of the service. It contains the service description including the URL under which the integration flow can be called.

Note! The WSDL download cannot parse WSDLs with external references. This means you can use WSDLs with external referenced for runtime execution but if you want to download the WSDL with the generated endpoint to provide it to the service consumer you need to resolve the references in the WSDL and add the schema definition from XSD directly into the WSDL. Or the consumer has to be configured without the generated WSDL.

WSDL Usage in SOAP SAP RM Receiver Adapter

Like the SOAP 1.x receiver adapter the SOAP SAP RM receiver adapter requires a service and port defined in the WSDL, because this is the service definition that is used at runtime.

If you use the WSDL selection dialog for a WSDL without service and port the port selection dialog shows the message ‘No resource available’.

To solve this problem, define a service and port in the WSDL. Usually the WSDL is provided by the service backend and already contains those information, but it can also be added manually in the WSDL.

Because the SAP RM protocol is an asynchronous protocol, the SOAP SAP RM sender and receiver adapters only support one-way WSDLs. This means the service definition in the WSDL must not have an output tag, but only an Input tag:

Correct asynchronous one-way service definition:

A synchronous service definition with input and output is not supported:

If you try to use a WSDL with a request-reply service definition, you get an error indicating that this is not supported:

Important Remark:

With the 5th-August-2018 update of Cloud Integration, the WSDL selection screen in the SAP RM receiver adapter only shows the one-way operations. This means, if only request-reply operations are defined in the WSDL the port selection screen provides an empty list. Before the 5th-August-2018 update, also the request-reply operations were shown and taken over, but upon saving the above error is given.

As mentioned above, WSDL and referenced XSD files have to be located in the wsdl folder directly, no subfolders are supported before the 28-October 2018 update.

Important Remark:

With the 28-October release of Cloud Integration, also the SAP RM receiver is supporting WSDL and XSD files in subfolders. But the WSDL defined in the SAP RM channel needs to reside directly in the wsdl folder, not in a subfolder (this will be allowed in the next update).

Important Remark:

The SAP RM adapter does not support WSRM. If the used WSDL contains WSRM policies an error is raised. You need to remove the WSRM policies from the WSDL.

WSDL Usage in SOAP SAP RM Sender Adapter

The SOAP SAP RM sender adapter does not need a service and port defined in the WSDL, because in this case Cloud Integration is the service provider and generates it’s own runtime WSDL based on the WSDL (if configured) and the definitions in the SAP RM sender channel. But if service and port are defined in the WSDL, they are taken.

Because the SAP RM protocol is an asynchronous protocol, the SOAP SAP RM sender and receiver adapters only support one-way WSDLs. This means the service definition in the WSDL must be for an one-way operation, it must not have an output tag, but only an Input tag:

Correct asynchronous one-way service definition:

A synchronous service definition with input and output is not supported in SAP RM adapter:

If you try to use a WSDL with a request-reply service definition, you get an error indicating that this is not supported:

During deployment of the integration flow the runtime WSDL is generated based on the content of the configured WSDL and the settings configured in the channel. Policies, that are contained in the configured WSDL are removed and substituted with Cloud Integration policies.

This WSDL can be downloaded from the Manage Integration Content monitor in the Monitoring cockpit. In the Manage Integration Content monitor select the integration flow to get its details. In the Endpoints section you find the option to download the WSDL. This is the generated runtime WSDL which can be provided to the consumer of the service. It contains the service description including the URL under which the integration flow can be called.

Note! The WSDL download cannot parse WSDLs with external references. This means you can use WSDLs with external referenced for runtime execution but if you want to download the WSDL with the generated endpoint you need to resolve the references in the WSDL and add the schema definition from XSD directly into the WSDL. Or the consumer has to be configured without the generated WSDL.

Important Remark:

The SAP RM adapter does not support WSRM. If the used WSDL contains WSRM policies they are removed automatically during runtime WSDL generation.

To report this post you need to login first.

4 Comments

You must be Logged on to comment or reply to a post.

  1. Ivo Vermeer

    Hello Mandy,

    Thanks fot this blog, it clarified the problems I was having to the extent that I could solve them. My SOAP service is now working😁

    Quick question: My current WSDL has the XSD schema inside of it. I would like to be able to run the XML validator at the start of my iFlow. If I understand that part of your blog correctly, I have to seperate the XSD from the WSDL, add both into a ZIP and upload the ZIP file as WSDL schema. Then I will be able to select my XSD seperatly in the XML Validator.
    – Am I correct?

    (0) 
    1. Mandy Krimmel Post author

       

      Hello Ivo,

      as the XML validator needs an XSD for validation you need to extract it. This is correct. But the XML validator expects the XSD in the xsd folder. You have now two options:

      The easiest way would be to keep the WSDL as is (with schema inside the WSDL) for using in the SOAP adapter and upload the extracted XSD as XSD schema into the xsd folder.

      Another option is to create a zip containing WSDL and referenced XSD. Upload this zip using the WSDL upload. This uploads WSDL and XSD into the wsdl folder. The WSDL can then be used in the SOAP adapter. Unfortunately the XSDs in the WSDL folder can currently not be used in the XML Validator. So you would have to upload the extracted XSD separately as XSD schema into xsd folder anyway.

      Best regards,

      Mandy

      (0) 
      1. Ivo Vermeer

        Hi Mandy,

         

        Thanks for your reply. Too bad this is not (yet) possible. Your solution is a good workaround, I will just have to keep in mind to update the XSD when I update the schema in WSDL and vice versa.

         

        Kr.

        Ivo

        (0) 

Leave a Reply