Installing and configuring
In the sections that follow, WBI_folder refers
to the folder containing your current WebSphere InterChange Server
installation. All environment variables and file separators are
specified in the Windows NT/2000 format. Please make the appropriate
changes if running on AIX or Solaris. (for example, WBI_folder\connectors would be WBI_folder/connectors).
Start server and tool
- Start WebSphere InterChange Server (ICS) from the shortcut.
- Start the WebSphere Business Integration System Manager and
open the Component Navigator Perspective.
- Register and connect your server as a Server Instance in the
Interchange Server view.
Load the sample content
From the Component Navigator Perspective:
- Create a new Integration Component Library.
- Import the repos file named WebServicesSample.jar located in: WBI_folder\connectors\WebServices\samples\WebSphereICS\
Compile the collaboration templates
Using WebSphere Business Integration System Manager:
- Compile All of the Collaboration Templates
that were imported from the WebServicesSample.jar repos file.
Configure the connector
- If you have not done so already, configure the connector as
described in this guide and according to your system.
- Using WebSphere Business Integration System Manager, open WebServicesConnector
in Connector Configurator.
- You must also configure WebServicesConnector for the protocol
you want to use with the sample:
Configuring for the SOAP/HTTP protocol scenario
This section shows you how to configure the connector
for the SOAP/HTTP sample scenario. As described in the body of this
document, the connector includes a SOAP/HTTP protocol listener and
SOAP/HTTP-HTTPS protocol handler. The sample scenario exposes SERVICE_ASYNCH_Order_Collab and SERVICE_SYNCH_OrderStatus_Collab collaborations as SOAP/HTTP web services. To expose a collaboration
as a SOAP/HTTP web service, the connector uses the SOAP/HTTP protocol
listener. The sample scenario comes with the CLIENT_ASYNCH_Order_Collab and CLIENT_SYNCH_OrderStatus_Collab collaborations, which are SOAP/HTTP clients of SOAP/HTTP
web services. To invoke a SOAP/HTTP web service, the connector uses
SOAP/HTTPHTTPS Protocol Handler.
In the steps and descriptions that follow, hierarchical connector
configuration properties are represented with the " symbol.
For example, A" B implies A is a hierarchical property,
and B is child property of A.
To configure the SOAP/HTTP protocol listener for this sample:
- In Connector Configurator, click on Connector-Specific Properties for
the WebServicesConnector.
- Expand the ProtocolListenerFramework property
to display the ProtocolListeners child property.
- Expand the ProtocolListeners child property
to display the SOAPHTTPListener1 child property.
- Check the value of SOAPHTTPListener1"Host and SOAPHTTPListener1"Port property.
Make sure there is no other process running on your host and listening on
this TCP/IP port. Optionally, you may want to set the value of SOAHTTPListener1"Host to
the machine name on which you will run the connector.
You need not configure the SOAP/HTTP-HTTPS protocol handler for
the sample.
Configuring for the SOAP/HTTPS protocol scenario
This section shows you how to configure the connector
for the SOAP/HTTPS sample scenario. The connector includes a SOAP/HTTPS
protocol listener and SOAP/HTTP-HTTPS protocol handler. The sample
scenario exposes the SERVICE_ASYNCH_Order_Collab and SERVICE_SYNCH_OrderStatus_Collab collaborations as SOAP/HTTPS web services. To expose a collaboration
as a SOAP/HTTPS web service, the connector uses the SOAP/HTTPS protocol
listener. The sample scenario comes with the CLIENT_ASYNCH_Order_Collab and CLIENT_SYNCH_OrderStatus_Collab collaborations, which are SOAP/HTTPS clients of SOAP/HTTPS
web services. To invoke a SOAP/HTTPS web service, the connector uses
the SOAP/HTTPHTTPS protocol handler.
In the steps and descriptions that follow, hierarchical connector
configuration properties are represented with the " symbol.
For example, A" B implies A is a hierarchical property,
and B is child property of A.
Note:
In addition to the pre-install items listed above
in
Before you start, you should also
have created and tested your keystore and truststore using your
Key and Certificate management software.
Configure SSL connector-specific properties
For SOAP/HTTPS, the connector requires that you configure
the SSL connector-specific hierarchical property.
- In Connector Configurator, click on the Connector-Specific Properties tab
for the WebServicesConnector.
- Expand the SSL hierarchical property to
view all of its children properties. Additionally, check or change
the following child properties of the hierarchical SSL connector-specific
property.
- SSL" KeyStore Set to the complete
path to your keystore file, which you must create using your Key
and Certificate management software.
- SSL"KeyStorePassword Set to the
password required to access your KeyStore.
- SSL"KeyStoreAlias Set to the
alias of the private key in your KeyStore.
- SSL"TrustStore Set to the complete
path of your truststore file which you have created using your Key
and Certificate management software.
- SSL"TrustStorePassword Set to
the password required to access your TrustStore.
Note:
Do not forget to save the changes in Connector Configurator.
Configure the SOAP/HTTPS protocol listener
- In Connector Configurator, click on Connector-Specific Properties for
the WebServicesConnector.
- Expand the ProtocolListenerFramework property
to display the ProtocolListeners child property.
- Expand the ProtocolListeners child property
to display the SOAPHTTPSListener1 child property.
Check the value of the SOAPHTTPSListener1"Host and SOAPHTTPSListener1"Port properties.
Make sure no other processes are running on your host and listening
on this TCP/IP port. Optionally, you may want to set the value of SOAHTTPSListener1"Host to the
machine name on which you are running the connector.
You need not configure the SOAP/HTTP-HTTPS protocol handler for
the sample.
Setting up KeyStore and TrustStore
You can quickly set up KeyStore and TrustStore to use
with the sample scenario. For production systems, you must use third-party
software for to set up and manage keystores as well as certificate
and key generation. No tool is provided as part of the Adapter for
Web Services to set up and manage these resources.
This section assumes that Java Virtual Machine is installed on
your system and that you are familiar with the keytool shipped with
your JVM (Java Virtual Machine). For more information or for troubleshooting
problems with the keytool, please see the documentation that accompanies
your JVM.
To set up KeyStore:
- You create KeyStore using keytool. You must create a key pair
in the KeyStore. To do so, enter the following at the command line:
keytool -genkey -alias wsadapter -keystore c:\security\keystore
- keytool immediately prompts for a password. Specify the password
that you entered for the value of SSL"KeyStorePassword
connector property.
Note that in the above example if you specified -keystore c:\security\keystore in the command line, you would enter c:\security\keystore as the value of the SSL"KeyStore property. Also,
if you specified -alias wsadapter in the command line, you would enter wsadapter as the value of the SSL"KeyStoreAlias connector property.
keytool would then prompt you for the details of the certificate.
The following illustrates what you may enter at each of the prompts,
but is an example only: always refer, and defer, to keytool documentation.
What is your first and last name?
[Unknown]: HostName
What is the name of your organizational unit?
[Unknown]: myunit
What is the name of your organization?
[Unknown]: myorganization
What is the name of your City or Locality?
[Unknown]: mycity
What is the name of your State or Province?
[Unknown]: mystate
What is the two-letter country code for this unit?
[Unknown]: mycountryIs <CN=HostName, OU=myunit, O=myorganization,
L=mycity, ST=mystate, C=mycountry> correct?
[no]: yes
- Note that for What is your first and last name?, you should enter the name of the machine on which you are
running the connector. keytool then prompts you:
Enter key password for <wsadapter> (RETURN if same as keystore password):
- Press Return to use the same password.
If you want to use a self-signed certificate, you may want to export
the certificate created above. To do so, enter following on the
command line:
C:\security>keytool -export -alias wsadapter -keystore c:\security\keystore
-file c:\security\wsadapter.cer
- keytool now prompts for the keystore password. Enter the password
that you entered above
To set up TrustStore:
- To import the trusted certificates into the TrustStore, enter
the following command:
keytool -import -alias trusted1 -keystore c:\security\truststore
-file c:\security\wsadapter.cer
- keytool now prompts for the keystore password. If you entered -keystore c:\security\truststore, make sure that SSL"TrustStore property is set to c:\security\truststore. Also, set the value of the SSL"TrustStorePassword property
to the password you entered above.
Configuring for the SOAP/JMS protocol scenario
This section shows you how to configure the connector
for the SOAP/JMS sample scenario. The sample scenario exposes the SERVICE_ASYNCH_Order_Collab and SERVICE_SYNCH_OrderStatus_Collab collaborations as SOAP/JMS web services. To expose a collaboration
as a SOAP/JMS web service, the connector uses the SOAP/JMS protocol
listener. The sample scenario comes with the CLIENT_ASYNCH_Order_Collab and CLIENT_SYNCH_OrderStatus_Collab collaborations, which are SOAP/JMS clients of SOAP/JMS web
services. To invoke a SOAP/JMS web service, the connector uses the
SOAP/JMS protocol handler.
In the steps and descriptions that follow, hierarchical connector
configuration properties are represented with the " symbol.
For example, A" B implies A is a hierarchical property,
and B is child property of A.
Note:
In addition to the pre-install items listed above
in
Before you start, you should also
have installed a JMS service provider and installed and configured
your JNDI.
Configuring JNDI properties
For SOAP/JMS, you must configure JNDI connector configuration
properties:
- In Connector Configurator, click Connector-Specific Properties for
the WebServicesConnector.
- Expand the JNDI hierarchical property to display its child properties.
Then check or change the child properties to match the values listed
below.
- JNDI"JNDIProviderURL Set this
property to the URL of the JNDI Service provider. Refer to your
JNDI provider documentation.
- JNDI"InitialContextFactory Set
this property to fully qualified class name of the factory class
that will create the JNDI initial context. Refer to your JNDI provider
documentation.
- JNDI"JNDIConnectionFactoryName Set
this property to the JNDI name of the connection factory to lookup
using JNDI context. Make sure that this name can be looked up using
the JNDI.
- Refer to your JNDI documentation to see if any of the following
properties are required by your JNDI provider:
- JNDI"CTX_ObjectFactories
- JNDI"CTX_ObjectFactories
- JNDI"CTX_StateFactories
- JNDI"CTX_URLPackagePrefixes
- JNDI"CTX_DNS_URL
- JNDI"CTX_Authoritative
- JND"CTX_Batchsize
- JNDI"CTX_Referral
- JNDI"CTX_SecurityProtocol
- JND"CTX_SecurityAuthentication
- JNDI"CTX_SecurityPrincipal
- JNDI"CTX_SecurityCredentials
- JNDI"CTX_Language
- Save the changes in Connector Configurator.
Configure the JMS queues and SOAP/JMS protocol listener
The scenario requires that six queues be defined with
your JMS service provider. Before doing so, check your JMS provider
documentation; defining queues varies between providers.
- Define (or make available via JNDI lookup) the following queues:
- ORDER_INPUT
- ORDER_INPROGRESS
- ORDER_ERROR
- ORDER_ARCHIVE
- ORDER_UNSUBSCRIBED
- ORDER_REPLYTO
- From CSM open WebServicesConnector in
Connector Configurator. If you have not done so already, configure
the connector as described in the installation guide for your system.
- Click Application Config Properties in
Connector Configurator.
- Expand the ProtocolListenerFramework property
to display the ProtocolListeners child property.
- Expand ProtocolListeners property to display
the SOAPJMSListener1 child property.
- Check or change the values of the SOAPJMSListner1 child
properties to match those listed below:
- SOAPJMSListener"Protocol Set
to soap/jms
- SOAPJMSListener1"Protocol Set
to soap/jms
- SOAPJMSListener1"InputQueue Set
to ORDER_INPUT
- SOAPJMSListener1"InProgressQueue Set
to ORDER_INPROGRESS
- SOAPJMSListener1"ArchiveQueue Set
to ORDER_ARCHIVE
- SOAPJMSListener1"UnsubscribedQueue Set
to ORDER_UNSUBSCRIBED
- SOAPJMSListener1"ErrorQueue Set
to ORDER_ERROR
- SOAPJMSListener1"ReplyToQueue Set
to ORDER_REPLYTO
- Save the changes in Connector Configurator.
Configure the SOAP/JMS protocol handler
- From System Manager open WebServicesConnector in
Connector Configurator. If you have not done so already, configure
the connector as described in the installation guide for your system.
- Click Connector-Config Properties in Connector
Configurator.
- Expand the ProtocolHandlerFramework property
to display the ProtocolHandlers child property.
- Expand the ProtocolHandlers child property
to display the SOAPJMSHandler child property. Check or change the
values of SOAPJMSHandler child properties to match the those below:
- SOAPJMSHandler"Protocol Set to soap/jms
- SOAPJMSHandler"ReplyToQueue Set
to value ORDER_REPLYTO_HANDLER
- Save the changes in Connector Configurator.
Create user project
- Using WebSphere Business Integration System Manager, create
a new User Project. Select all of the components
from the Integration Component Library that was created in Load the sample content.
Add and deploy the project
- From the Server Instance view, add the User Project created
in Create user projectto WebSphere ICS
- Deploy all of the components from this User Project to the ICS.
Reboot InterChange Server
- Reboot InterChange Server to ensure that all changes take effect.
- Use the System Monitor tool to ensure that all of the collaboration
objects, connector controllers, and maps are in a green state.
