Question & Answer
Question
This document will address how to migrate your IBM Integrated Web Services (IWS) Server and web services from v1.3/v1.5 to v2.6.
Answer
IMPORTANT - PLEASE READ!!! Please note that this migration path attempts to provide a seamless migration from IWS v1.3/v1.5 to v2.6 without requiring any changes to your web services client application or deployed web service programs. Unfortunately, IBM cannot guarantee this to always be the case. Since IBM cannot control the design of the web services client application, the syntax of the client SOAP envelope, and the deployed web service programs; clients have encountered some situations where the migration from IWS v1.3/v1.5 to v2.6 does require changes to be made to their web services client application and/or deployed web service programs.
If you wish to use the migration process discussed in this document, the migration of web services MUST be completed BEFORE upgrading if your target IBM i OS VRM does not support your source IWS version. For example, you MUST migrate all IWS v1.3 and v1.5 web services to IWS v2.6 BEFORE upgrading to IBM i 7.4 since these IWS versions are not supported at IBM i 7.4.
One observed migration issue with existing deployed web service programs is the program's input and/or output array definitions. Beginning with IWS v2.6, the IWS runtime now automatically detects array length fields by default to mask the array length from the client. When Detect length fields is selected, it will be assumed that any numeric field that immediately precedes an array field with the same name as the array field appended with _LENGTH is a length field that will be used to indicate the actual number of elements in the array. For example, the array field identifier is named "myArray", then the field length for the array would be "myArray_LENGTH". More information on nested array support in IWS v2.6 can be found here.
This migration path is provided only as a temporary solution until you can update your web service client application(s) and deployed web service programs to be fully compatible with IWS v2.6. New web service deployments to IWS v2.6 will use a new WSDL format, SOAP endpoint URL, and must adhere to the new server changes (which include the new detect length field and nested array support).
There are several different migration paths depending on your needs. Two of the most popular paths are...
1) Side-by-side migrations where the old and new servers run at the same time on different ports and with different server names until the new server can be fully tested and then switched over to.
2) In-place migrations where the the old server is decommissioned and the new server is fully migrated to, started, and put in place of the old server using the same ports and server name.
If you choose to perform an in-place migration, you will need to identify the HTTP and Application Server ports used by your IWS v1.3/v1.5 server before you create your new IWS v2.6 server. NOTE: There is no command port for IWS v1.3/v1.5. When creating your new IWS v2.6 server, you will specify a unique command port and then the same HTTP and application server ports as your IWS v1.3/v1.5 server. Before you can start your new IWS v2.6 server, you would need to stop your IWS v1.3/v1.5 server to avoid a port conflict between the servers.
If performing a side-by-side migration (which is the most popular) where your IWS v1.3/v1.5 servers remain active during the migration process; you will not be able to create your new IWS v2.6 servers with the exact same server name and port values as your old IWS v1.3/v1.5 servers. You can, however, change the port values of the new IWS v2.6 server to match the old IWS v1.3/v1.5 server port values when you are ready to fully switch over to the new IWS v2.6 server.
If you require to keep your server names the same, you will need to save your web services and record the port values from your IWS v1.3/v1.5 servers first and then delete them before you create your IWS v2.6 servers. You cannot have 2 IWS servers (no matter the version) with the exact same server name on the same IBM i partition. If you want to keep your IWS v1.3/v1.5 servers active, you will need to use a different and unique name for your IWS v2.6 servers that is not used by another IWS server.
For a side-by-side migration, here is a high-level overview of the steps required.
Pre-requisites:
- IBM i LPP 57xxJV1 Option 17 (JDK 8.0 64 bit) is recommended to be installed.
- Refer to the document, Support of Java Development Kit (JDK) 8.0 on the IBM i OS , for more information on how to download and install the 57xxJV1 Option 17 LPP.
- It is recommend the latest IBM HTTP Server Group PTF level for your IBM i OS VRM is applied before beginning the migration process.
|
IBM i 7.1
|
|
|
IBM i 7.2
|
|
|
IBM i 7.3
|
|
| IBM i 7.4 | SF99662 |
- Ensure the following PTF is applied for your IBM i OS VRM. This is especially important for IBM i 7.1 OS since this PTF updates the restoreWebServices.sh script used on the migration.
| IBM i 7.4 | N/A |
| IBM i 7.3 | SI68746 |
| IBM i 7.2 | SI68745 |
| IBM i 7.1 | SI68785 |
|
1) |
Create a new IWS v2.6 server to replace your IWS v1.3/v1.5 server. You will need to use a different and unique name for your IWS v2.6 servers that does not match any of your IWS v1.3/v1.5 servers. You will also need to temporarily configure your IWS v2.6 servers with port values different than your IWS v1.3/v1.5 servers so you can have your v1.3/v1.5 and v2.6 IWS servers started "side-by-side" for testing purposes. You will be able to change your v2.6 port values to the same values as your v1.3/v1.5 servers later on in the migration process after you are ready to swap over to your IWS v2.6 servers. Refer to the section entitled, "Creating an integrated web services server" in Chapter 6 in the URL, IBM Integrated Web Services Server Administration and Programming Guide , for detailed information on how to create a new IWS server. |
| 2) | Switch the newly created IWS v2.6 JVM to use JDK 8.0 64 bit (if required). NOTE: With the latest IBM HTTP Group PTF, newly created IWS v2.6 servers will use JDK 8.0 64bit by default if installed. Refer to the following IBM Software Technical Document for more information on how to do this. How To Change The IBM Java Development Kit (JDK) Version Used By an IBM Integrated Web Services (IWS) v2.6 Server |
| 3) |
Save and restore your web services from your IWS v1.3/v1.5 to v2.6 servers using the saveWebServices.sh and restoreWebServices.sh commands OR re-deploy your web services to your IWS v2.6 servers using the installWebServices.sh command or WebAdmin GUI. - If migrating from IWS v1.3, ensure the "version13" migration option is specified on the restoreWebServices.sh script for compatibility. i.e. restoreWebServices.sh -migrationOption version13 - The restoreWebServices.sh script also provides the following additional migration options, which might be required to be specified when migrating your web services. soap12 - use SOAP 1.2 (default is SOAP 1.1) IBM i 7.1 - SI68785 |
| 4) |
Modify your IWS HTTP Server configuration to redirect the old web service endpoint URL to the new v2.6 endpoint URL OR modify your web service clients to connect to the new SOAP web service endpoint URL.
IMPORTANT!!! If web services from an IWS v1.3 or v1.5 server version are restored or deployed to an IWS v2.6 server, the SOAP Web Service Endpoint URL will have minor changes, see the document: SOAP Web Service Endpoint URL Changes Between IWS v1.5 and v2.6 . NOTE: If the host and/or port changes in the SOAP Endpoint URL, this would require the re-distribution of the new IWS v2.6 WSDL file to your web services clients, manually changing the SOAP Endpoint URL in each client's WSDL file, or setting up an HTTP Server on the old host and/or port to redirect to the new host and/or port. ============================================= The changes to your web service endpoint URLs between IWS v1.3/v1.5 and v2.6 can be worked around by configuring your IWS HTTP Server to redirect the old SOAP Endpoint URL to the new one while still supporting the new SOAP Endpoint URL using the instructions provided. Let's look at an example. Suppose we wanted clients to successfully execute SOAP requests using the following URL format: http://host:port/web/services/ {web-service} where {web-service} is the web service name. If a user wanted to invoke the ConvertTemp web service, then the following URL would be used: http://host:port/web/services/ConvertTemp And if a user wanted to retrieve the WSDL file, the following URL would be used: http://host:port/wweb/services/ConvertTemp?wsdl So, how do we support both the old and new SOAP Endpoint URLs? By adding the following directives to the IWS HTTP server's configuration file using the following steps. These directives will rewrite the old SOAP Endpoint URL to the new IWS v2.6 URL format, http://host:port/web/services/ {web-service}Service/{web-service>}. RewriteEngine On
RewriteOptions Inherit
RewriteRule ^/web/services/(.*)\.(.*)HttpSoap11Endpoint/\?wsdl$ /web/services/$1Service/$1?wsdl [PT,L] RewriteRule ^/web/services/(.*)\.(.*)HttpsSoap11Endpoint/\?wsdl$ /web/services/$1Service/$1?wsdl [PT,L] RewriteRule ^/web/services/(.*)\.(.*)HttpSoap11Endpoint/$ /web/services/$1Service/$1 [PT,L] RewriteRule ^/web/services/(.*)\.(.*)HttpsSoap11Endpoint/$ /web/services/$1Service/$1 [PT,L] RewriteRule ^/web/services/(.*)Service/(.*)$ /web/services/$1Service/$2 [PT,L] RewriteRule ^/web/services/(.*)\?wsdl$ /web/services/$1Service/$1?wsdl [PT,L] RewriteRule ^/web/services/(.*)$ /web/services/$1Service/$1 [PT,L] To prevent unwanted characters and avoid CCSID (code page) issues, add the above Rewrite* lines
to your IBM HTTP Server configuration using the IBM Web Administration for i console:
Open a web browser and go to the URL, http://<IP_Address or FQDN>:2001/HTTPAdmin OR https://<IP_Address or FQDN>:2010/HTTPAdmin . Then, select Manage -> HTTP Servers -> select your HTTP Server -> Server Properties -> URL Mapping -> URL Rewriting.
Enable URL rewriting and Rewrite options, and add the RewriteRules individually as displayed below.
For example:
 Click the OK button to commit the changes.
OR
- WRKLNK '/www/<IWSServer>/conf/httpd.conf'
- Option 2 to edit. - Add the following lines just below the "Listen" directive. NOTE: IBM recommends you copy the directives to Notepad first and then copy them into your HTTP Server configuration to prevent unwanted characters from copying over. RewriteEngine On RewriteOptions Inherit
RewriteRule ^/web/services/(.*)\.(.*)HttpSoap11Endpoint/\?wsdl$ /web/services/$1Service/$1?wsdl [PT,L] RewriteRule ^/web/services/(.*)\.(.*)HttpsSoap11Endpoint/\?wsdl$ /web/services/$1Service/$1?wsdl [PT,L] RewriteRule ^/web/services/(.*)\.(.*)HttpSoap11Endpoint/$ /web/services/$1Service/$1 [PT,L] RewriteRule ^/web/services/(.*)\.(.*)HttpsSoap11Endpoint/$ /web/services/$1Service/$1 [PT,L] RewriteRule ^/web/services/(.*)Service/(.*)$ /web/services/$1Service/$2 [PT,L] RewriteRule ^/web/services/(.*)\?wsdl$ /web/services/$1Service/$1?wsdl [PT,L] RewriteRule ^/web/services/(.*)$ /web/services/$1Service/$1 [PT,L] - Press F3 twice to save and exit. If there are SSL/TLS endpoints configured via the <VirtualHost> directive, then you will need to add the "RewriteEngine On" directive to the VirtualHost area. For example:
<VirtualHost *:10443>
SSLEngine On SSLAppName QIBM_HTTP_SERVER_IWS26 SSLProtocolDisable SSLv2 SSLv3 RewriteEngine On
</VirtualHost> The RewriteEngine directive enables or disables the runtime rewriting engine. In this case we are enabling it. And the RewriteRule directives do the mapping of the URI to support the old and new SOAP Endpoint URLs. That is it. |
| 5) | Restart your IWS v2.6 instance, test your IWS v2.6 web services, and ensure everything is working properly. |
| 6) | When you are ready to switch over to your IWS v2.6 servers, you can change your IWS v2.6 port values to be the same as your IWS v1.3/v1.5 servers. - Record the HTTP and Application Server Port values for your IWS v1.3/v1.5 servers in the IBM Web Administration for i console. HTTP Server Port Manage -> Application Servers -> Select your IWS v1.3/v1.5 server from the Server list -> Server Properties -> View HTTP Servers.  IWS v1.3/1.5 Application Server Port(s) Manage -> Application Servers -> Select your IWS v1.3/v1.5 server from the Server list -> Server Properties -> Properties -> Ports  - Stop your IWS v1.3/v1.5 servers. - Change the IWS v2.6 HTTP and Application Server Port values to be the same as your IWS v1.3/v1.5 servers using the instructions in the document URL below. How To Change the Ports Used by IBM Integrated Application Servers (IAS) v8.5 and Integrated Web Services (IWS) v2.6 Servers |
| 7) | Restart your IWS v2.6 servers to use the new port values and test. Congratulations! You have completed the migration of your web services to IWS v2.6. |
Related Information
Was this topic helpful?
Document Information
Modified date:
01 October 2021
UID
nas8N1022190