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! 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 the 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. These 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, WSDL files with external references, and also whole archives having several WSDL files and 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 in 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 2nd-September-2018 update of Cloud Integration, also the SOAP receiver is expected to support 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 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 them 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 the 2n-September-2018 update of Cloud Integration, the WSDL configured in the SOAP channel can also reside in a subfolder of the WSDL folder. This was not possible before (the main WSDL was always expected in the wsdl folder directly).

After the 2n-September update, 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 those 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.

Important Remark:

With the 2nd-September-2018 update of Cloud Integration, also the SOAP receiver is expected to support WSDL and XSD files in subfolders (see option 2 above).

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.

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.

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 synchronous 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 are 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.

Important Remark:

With the 2nd-September-2018 update of Cloud Integration, also the SAP RM receiver is expected to support WSDL and XSD files in subfolders (see option 2 above).

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 asynchronous 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 synchronous 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.

To report this post you need to login first.

Be the first to leave a comment

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

Leave a Reply