how to fast-switch integration scenarios between sap pi ......names of installation, upgrade and...

SAP NetWeaver

How-To Guide

How to Fast-Switch Integration

Scenarios between SAP PI Runtimes

Part II: Web Dispatcher

Applicable Releases:

SAP NetWeaver Process Integration 7.1

(Including Enhancement Package 1)

Topic Area:

SOA Middleware

Capability:

Service Bus

Version 1.0

July 2010

© Copyright 2010 SAP AG. All rights reserved.

No part of this publication may be reproduced or

transmitted in any form or for any purpose without the

express permission of SAP AG. The information contained

herein may be changed without prior notice.

Some software products marketed by SAP AG and its

distributors contain proprietary software components of

other software vendors.

Microsoft, Windows, Outlook, and PowerPoint are

registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel

Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390,

OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP,

Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix,

i5/OS, POWER, POWER5, OpenPower and PowerPC are

trademarks or registered trademarks of IBM Corporation.

Adobe, the Adobe logo, Acrobat, PostScript, and Reader

are either trademarks or registered trademarks of Adobe

Systems Incorporated in the United States and/or other

countries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered

trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame,

WinFrame, VideoFrame, and MultiWin are trademarks or

registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or

registered trademarks of W3C®, World Wide Web

Consortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems,

Inc., used under license for technology invented and

implemented by Netscape.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP

NetWeaver, and other SAP products and services

mentioned herein as well as their respective logos are

trademarks or registered trademarks of SAP AG in

Germany and in several other countries all over the world.

All other product and service names mentioned are the

trademarks of their respective companies. Data contained

in this document serves informational purposes only.

National product specifications may vary.

These materials are subject to change without notice.

These materials are provided by SAP AG and its affiliated

companies ("SAP Group") for informational purposes only,

without representation or warranty of any kind, and SAP

Group shall not be liable for errors or omissions with

respect to the materials. The only warranties for SAP

Group products and services are those that are set forth in

the express warranty statements accompanying such

products and services, if any. Nothing herein should be

construed as constituting an additional warranty.

These materials are provided “as is” without a warranty of

any kind, either express or implied, including but not

limited to, the implied warranties of merchantability,

fitness for a particular purpose, or non-infringement.

SAP shall not be liable for damages of any kind including

without limitation direct, special, indirect, or consequential

damages that may result from the use of these materials.

SAP does not warrant the accuracy or completeness of the

information, text, graphics, links or other items contained

within these materials. SAP has no control over the

information that you may access through the use of hot

links contained in these materials and does not endorse

your use of third party web pages nor provide any warranty

whatsoever relating to third party web pages.

SAP NetWeaver “How-to” Guides are intended to simplify

the product implementation. While specific product

features and procedures typically are explained in a

practical business context, it is not implied that those

features and procedures are the only approach in solving a

specific business problem using SAP NetWeaver. Should

you wish to receive additional information, clarification or

support, please refer to SAP Consulting.

Any software coding and/or code lines / strings (“Code”)

included in this documentation are only examples and are

not intended to be used in a productive system

environment. The Code is only intended better explain and

visualize the syntax and phrasing rules of certain coding.

SAP does not warrant the correctness and completeness of

the Code given herein, and SAP shall not be liable for

errors or damages caused by the usage of the Code, except

if such damages were caused by SAP intentionally or

grossly negligent.

Disclaimer

Some components of this product are based on Java™. Any

code change in these components may cause unpredictable

and severe malfunctions and is therefore expressively

prohibited, as is any decompilation of these components.

Any Java™ Source Code delivered with this product is only

to be used by SAP’s Support Services and may not be

modified or altered in any way.

Document History

Document Version Description

1.00 First official release of this guide

Typographic Conventions

Type Style Description

Example Text Words or characters quoted

from the screen. These

include field names, screen

titles, pushbuttons labels,

menu names, menu paths,

and menu options.

Cross-references to other

documentation

Example text Emphasized words or

phrases in body text, graphic

titles, and table titles

Example text File and directory names and

their paths, messages,

names of variables and

parameters, source text, and

names of installation,

upgrade and database tools.

Example text User entry texts. These are

words or characters that you

enter in the system exactly as

they appear in the

documentation.

<Example

text>

Variable user entry. Angle

brackets indicate that you

replace these words and

characters with appropriate

entries to make entries in the

system.

EXAMPLE TEXT Keys on the keyboard, for

example, F2 or ENTER.

Icons

Icon Description

Caution

Note or Important

Example

Recommendation or Tip

Table of Contents

1. Scenario ........................................................................................................................... 1

2. Background Information ................................................................................................. 1

2.1 SAP Web Dispatcher for Multiple Systems ................................................................ 2

2.2 Sample Landscape ................................................................................................... 2

3. Prerequisites.................................................................................................................... 3

4. Step-by-Step Procedure .................................................................................................. 4

4.1 Routing Requests via Modification Handler ............................................................... 4

4.1.1 Configuring Web Dispatcher for Normal Usage ............................................. 4

4.1.2 Configuring Web Dispatcher in Switch Scenario ............................................ 7

4.2 Routing Requests via Access Point ........................................................................... 8

4.2.1 Configuring Web Dispatcher Ports (Normal Usage) ....................................... 8

4.2.2 Configuring Web Dispatcher Ports (Switch Scenario) .................................... 8

4.2.3 Using Different Web Dispatcher IP Addresses .............................................. 9

5. Summary .......................................................................................................................... 9

How to Fast-Switch Integration Scenarios Between SAP PI Runtimes Part II: Web DispatcherIntegration

Scenarios Between SAP PI Runtimes Part II: Web Dispatcher

December 2010 1

1. Scenario

You plan to deploy additional SAP NetWeaver Process Integration (PI) runtime engines (e.g.

Decentral Adapter Engine or full PI instance) in your PI system landscape and you want to be able to

quickly switch the designation of the Adapter Engine runtime and/or route application sender/outbound

requests to the proper PI runtime for many or all your integration scenarios.

For example, in potential SAP NetWeaver PI distributed or federation scenarios, you want to be able

to quickly configure channels to point to the new adapter engine instance once it is stood up and also

quickly route appropriate sender application request to the new adapter engine. As another example,

in a planned (or unplanned) downtime scenario, in order to keep scenarios up and running, scenarios

can be switched from one runtime to another before the downtime takes place and then switched back

once the system is brought back up.

This How-to Guide is the second of a two-part series providing details of how to fast-switch integration

scenarios from one SAP PI runtime to another. This part focuses on how the SAP Web Dispatcher

can be used in order to temporarily route sender application HTTP requests to a different PI runtime in

a non-disruptive manner in planned and unplanned downtime scenarios.

2. Background Information

The SAP Web Dispatcher can serve as an entry point for HTTP(s) requests to one or more SAP

NetWeaver application systems. The SAP Web Dispatcher is essentially a software web switch that

can accept and reject incoming connections and also serve as an effective load balancer across SAP

systems. Also, starting with release 7.2, a single SAP Web Dispatcher can be set in front of multiple

SAP and non-SAP systems. For more information on the SAP Web Dispatcher, please check the SAP

Help Portal: SAP Web Dispatcher.

In a SAP NetWeaver PI landscape with multiple PI runtimes, the Web Dispatcher can be used to

regulate HTTP requests that are targeted for the runtime engines in the PI landscape. If

circumstances arise that require sender applications to route their PI requests to a different PI runtime,

a simple change can be made in the SAP Web Dispatcher settings instead of manually changing all

the destinations in the sender applications themselves.

Note

Since the SAP Web Dispatcher handles only HTTP requests, this guide is relevant mainly for adapters that use the HTTP protocol and directly addressed (i.e. SOAP adapter, plain HTTP adapter, XI proxy adapter). In particular, for RFC protocol based adapters (e.g. IDoc and RFC), the target system settings in the sending SAP application would still need to be maintained (manually or other means) if involved in a switch

scenario.

http://help.sap.com/saphelp_nwce72/helpdata/en/48/8fe37933114e6fe10000000a421937/frameset.htm



December 2010 2

2.1 SAP Web Dispatcher for Multiple Systems

In order to be able to route requests from one SAP PI runtime to another, the SAP Web Dispatcher

has to be configured to serve multiple systems. Starting with the SAP Web Dispatcher 7.2 release,

mechanisms are delivered to enable one Web Dispatcher for multiple systems. Check the SAP Help

Portal for more information on SAP Web Dispatcher for Multiple Systems. Check Note 908097 – SAP

Web Dispatcher: Released releases and applying patches for the latest information on SAP Web

Dispatcher compatibility with SAP NetWeaver releases. As of the release of this guide (November

2010), SAP Web Dispatcher 7.2 integration with backends based on lower released SAP NetWeaver

systems (downward compatibility, e.g. 7.1) is officially supported. Please check Note 908097 for the

latest status on released systems for SAP Web Dispatcher.

Mechanisms for Separating Requests for Different Systems

There are various mechanisms within the SAP Web Dispatcher to separate and designate requests to

different SAP systems. These include:

1. Modification Handler

2. Access Point (combination of host name and port)

3. URL Prefix

However, for the specific purpose of routing requests to a “switched” PI runtime, only the Modification

Handler and Access Point mechanisms are relevant since the URL prefixes used for the various SAP

PI runtimes would be the same when performing a switch.

2.2 Sample Landscape

http://help.sap.com/saphelp_nwce72/helpdata/en/b0/ebfa88e9164d26bdf1d21a7ef6fc25/frameset.htm

https://service.sap.com/sap/support/notes/908097

https://service.sap.com/sap/support/notes/908097



December 2010 3



December 2010 4

3. Prerequisites

The following prerequisites should be considered: ...

System Components

SAP NetWeaver PI system (at least one; any release)

SAP NetWeaver PI Decentral Adapter Engine (at least one)

SAP Web Dispatcher 7.2 (only from 7.2 can a single Web Dispatcher serve multiple

systems)

Administration and operations knowledge of SAP Web Dispatcher

Note

This guide is not intended to provide a detailed introduction to the SAP Web Dispatcher, but rather provide guidance on how the SAP Web Dispatcher can be used specifically to facilitate in routing sender application HTTP requests to a different PI runtime engine in the overall process of performing a mass switch from one PI runtime to another. For more information on the SAP Web Dispatching, please consult the SAP Help Portal: SAP

Web Dispatcher.

Working knowledge of SAP NetWeaver PI

Duplicate configuration – In cases where runtimes are switched between two PI instances (e.g.

XI proxy and HTTP adapter scenarios), on each instance the scenario configuration must

already exist in the Integration Directory and been tested for runtime success prior to attempting

a switch and runtime execution.





December 2010 5

4. Step-by-Step Procedure

Making the necessary changes to the SAP Web Dispatcher configuration in order to route HTTP

requests from one SAP PI runtime to another is relatively quick and simple. The main part is setting

up the Web Dispatcher to support multiple connected systems. The

4.1 Routing Requests via Modification Handler

Using the Modification Handler, rules can be defined in the Web Dispatcher such that target systems

can be specified based on the host name in the HTTP request. DNS aliases for the Web Dispatcher

host must be set up in advance so that each request based on host name alias can be forwarded to

the appropriate target host. For more general information on making modifications to HTTP requests,

check the SAP Help Portal: Modifications of HTTP Requests.

4.1.1 Configuring Web Dispatcher for Normal Usage

Initially, the modification handler should be set up for normal, everyday processing. First the

modification rules file is specified and its location is configured, and then the actual rules are defined.

Specifying the Rules File

1. Access the SAP Web Dispatcher profile and add parameter icm/HTTP/mod_<xx> (if it already

exists, navigate to the configured file location and move on to the next section “Creating the

rules to route requests to each system”).

Recommendation

In order to have the same filter rules on all instances, SAP recommends storing the file with the filter rules in a global directory and setting the parameter in the default profile

“DEFAULT.PFL”.

Example

The filter rules are in file icm_filter_rules.txt in directory $(DIR_GLOBAL)/security/data

icm/HTTP/mod_0 =

PREFIX=/,FILE=$(DIR_GLOBAL)/security/data/icm_filter_rules.txt

2. Save the profile and rules file and restart the SAP Web Dispatcher.

3. Log in and access with a valid administration user the Web Administration Interface via browser

by entering URL: http(s)://<host>:<admin_port>/sap/admin.

4. Verify the changes are made successfully by navigating to link Modification Handler on the left

pane (within HTTP Handler section). Once accessed, the Modification Handler Status should

be active and green and the Name of the rule File and URL Prefix for this Handler should be set

appropriately. For instance, with the icm/HTTP/mod_0 added to the DEFAULT.PFL and set as

in the example above, the Modification Handler page shows the following for an empty rules file:

http://help.sap.com/saphelp_nwce72/helpdata/en/48/9266acaa6b17cee10000000a421937/frameset.htm



December 2010 6

Tip

Using the Web Administration Interface, you can check the active profile settings by accessing link Parameters(Instance Profile | Default Profile).

Also, after making changes (e.g. to the profile or rules file) and restarting the Web Dispatcher, you can look for any potential problems (e.g. syntax error) by checking the

Trace link and searching for “*** ERROR”.

Defining Rules to Route Requests

One of the most straightforward ways to control requests to a particular system is to leverage the

pseudo header field x-sap-webdisp-target-sid and set it to the system to which the request should be

routed. Conditional logic can be used to set x-sap-webdisp-target-sid based on a header field in the

incoming HTTP request such as the host header field. In order for this to work using host header

fields, an alias to the Web Dispatcher host must be created in advance for each target PI runtime

system.

HTTP request header fields can be accessed using predefined variables using syntax %{variable}.

In our case, we use the variable HTTP_HOST in order to access the host header field. See SAP Help

Portal for additional header variables available: Using Variables.

So in our sample landscape, the Web Dispatcher might have alias names wd_pi1, wd_pi2, and

wd_di1 corresponding to systems PI1, PI2, and DI1 respectively. Given this, here‟s how to define the

rules in the modification file. ...

1. Go to the configured modification file (e.g.

$(DIR_GLOBAL)/security/data/icm_filter_rules.txt) and open it for edit.

2. Add the following rules to the file:

#PI1 requests

if %{HTTP_HOST} regimatch wd_pi1*

SetHeader x-sap-webdisp-target-sid PI1 [break]

http://help.sap.com/saphelp_nwce72/helpdata/en/48/926932aa6b17cee10000000a421937/frameset.htm



December 2010 7

#PI2 requests



#DI1 requests

if %{HTTP_HOST} regimatch wd_di1*

SetHeader x-sap-webdisp-target-sid DI1 [break]

Note

The wildcard character „*‟ can be used to account for requests containing fully qualified

domain host name as well.

3. Save changes to the rules file.

4. In the Web Dispatcher profile, confirm that there is a valid Web Dispatcher port configured. If

none exist, add an entry. For example:

icm/server_port_0 = PROT=HTTP, PORT=<wd_port>

5. In addition, all the backend system assignment details must be made using profile parameter

wdisp/system_<xx>. So in our case:

wdisp/system_0 = SID=PI1, MSHOST=<ms_pi1>, MSPORT=<ms_pi1_port>

wdisp/system_1 = SID=PI2, MSHOST=<ms_pi2>, MSPORT=<ms_pi2_port>

wdisp/system_2 = SID=DI1, MSHOST=<ms_di1>, MSPORT=<ms_di1_port>

Note

The message server HTTP port can be verified in the dev_ms file located in the work directory. There you should see a line indicating the message server HTTP port (e.g. ***

HTTP port 8100 state LISTEN ***).

6. Save changes to the profile and restart the Web Dispatcher.

7. Verify that the rules are active by accessing the Web Administration Interface and accessing the

Modification Handler link. The new rules should be visible.



December 2010 8

Now the Web Dispatcher is configured to route requests using modification rules to the appropriate PI

runtime system based on the host aliases contained in the request.

4.1.2 Configuring Web Dispatcher in Switch Scenario

By changing the system mapping assignments in the Web Dispatcher configuration centrally, sender

applications do not have to make individual changes of HTTP addresses to PI runtimes. It can be

changed once on the Web Dispatcher by means of a simple rules change in the modification rules file.

For example, consider that PI1 is planned for downtime (e.g. due to Support Packs application) and

there are Advanced Adapter Engine (AAE) scenarios that can be switched from the Central Adapter

Engine on PI1 to the Decentral Adapter Engine (DI1). In order to route HTTP requests to DI1, the

following change can be made to the rules file so that requests for PI1 go to the DI1 system. ...

1. Access and open for edit the configured modification rules file (e.g.

$(DIR_GLOBAL)/security/data/icm_filter_rules.txt).

2. Change the line “SetHeader x-sap-webdisp-target-sid…” corresponding to the PI1

system.

Old Value:



New Value:


SetHeader x-sap-webdisp-target-sid DI1 [break]

3. Save the changes and restart the Web Dispatcher.

All other existing rules should remain in place. Now incoming requests containing host header

“wd_pi1*” will be routed to the DI1 instance. Once the PI1 downtime is complete, the rule can be



December 2010 9

changed back to the old value so that PI1 can handle the HTTP requests as it normally does. The

same can be done if DI1 is planned for downtime by configuring a similar rules change in reverse.

Note

Similarly, if another PI instance is in the landscape (e.g. PI2), rule changes can be extended to incorporate the additional PI instance in the same manner. For example,

instead of making the change to DI1, the new value would be set to PI2.

When switching between PI instances, remember that it is prerequisite that the relevant

Integration Directory configuration exists in all PI instances where runtime execution is to

take place.

4.2 Routing Requests via Access Point

A unique access point for each connected PI runtime system can be configured based on ports

and/or IP Addresses (if available) of the Web Dispatcher that the request comes into. We again refer

to our sample landscape, but only referring to one SAP NetWeaver PI system (PI1) and its Decentral

Adapter Engine (DI1). Of course, the configuration as described below can be extended for additional

systems (e.g. another PI instance) as necessary.

4.2.1 Configuring Web Dispatcher Ports (Normal Usage)

In the following steps, different Web Dispatcher ports are configured to identify which requests go to

PI1 and which go to DI1.

1. Open the Web Dispatcher profile and add the following parameters to configure two HTTP ports

for the Web Dispatcher.

icm/server_port_0 = PROT=HTTP, PORT=<wd_port_1>

icm/server_port_1 = PROT=HTTP, PORT=<wd_port_2>

2. In addition, port-to-system assignments must be defined using the wdisp/system_<xx>

parameter as follows:

wdisp/system_0 = SID=PI1, MSHOST=<host_pi1>, MSPORT=<ms_pi1_port>,

SRCSRV=*:<wd_port_1>

wdisp/system_1 = SID=DI1, MSHOST=<host_di1>, MSPORT=<ms_di1_port>,


Note

As seen above, property SRCSRV is used to indicate which Web Dispatcher port is mapped to the target system. Wildcard character „*‟ indicates that any valid Web

Dispatcher IP Address or host alias can be used.

3. Save the changes to the profile and restart the Web Dispatcher.



December 2010 10

With the parameters set as above, all requests that enter through port <wd_port_1> go to the PI1

system, and all requests entering through port <wd_port_2> go to the DI1 system.

4.2.2 Configuring Web Dispatcher Ports (Switch Scenario)

Again, by changing the system mapping assignments in the Web Dispatcher configuration centrally,

sender applications do not have to make individual changes of HTTP addresses to PI runtimes. It can

be changed once on the Web Dispatcher by means of a simple change to the profile parameter

wdisp/system_<xx>.

For example, consider that PI1 is planned for downtime (e.g. due to Support Packs application) and

there are Advanced Adapter Engine (AAE) scenarios that can be switched from the Central Adapter

Engine on PI1 to the Decentral Adapter Engine (DI1). In order to route HTTP requests to DI1, the

following change can be made to the Web Dispatcher profile parameter wdisp/system_0 which

corresponds to requests that are supposed to go to the PI1 system.

Old Value:

wdisp/system_0 = SID=PI1, MSHOST=<host_pi1>, MSPORT=<ms_port_pi1>,


New Value:

wdisp/system_0 = SID=DI1, MSHOST=<host_di1>, MSPORT=<ms_port_di1>,


Notice that the SRCSRV property remains unchanged since this is the entry port for PI1 requests. All

other existing rules should remain in place. With this change, requests coming through port

<wd_port_1> will now go to DI1. Once the PI1 downtime is complete, the parameter wdisp/system_0

can be changed back to the old value so that PI1 can handle the HTTP requests as it normally does.

The same can be done if DI1 is planned for downtime by configuring the value of parameter

wdisp/system_1 to refer to the PI1 system.

4.2.3 Using Different Web Dispatcher IP Addresses

If the Web Dispatcher host has multiple IP addresses, controlling requests to connected systems can

also be configured based on the incoming host names mapped to the IP addresses using a Web

Dispatcher port. In switch scenarios, similar changes can be made to the wdisp/system_<xx> profile

parameters to direct requests to a different PI runtime. For an example of configuring the Web

Dispatcher for multiple system using IP addresses, check the SAP Help Portal: SAP Web Dispatcher

for Multiple Systems.

5. Summary

By leveraging a single SAP Web Dispatcher (release 7.2 and beyond), HTTP requests made by

sender applications to PI runtimes (e.g. via SOAP, plain HTTP, or XI Proxy) can be “switched” or





December 2010 11

routed to different PI runtimes as necessary by making a quick change centrally to the Web

Dispatcher configuration.

Routing to the target systems can be achieved using one of two available mechanisms: ...

1. Defining rules in the Modification Handler

2. Configuring separate Web Dispatcher access points (e.g. ports) for each system

By combining capabilities of the Web Dispatcher with Directory API (as specified in How To... Fast-

Switch Integration Scenarios Between SAP PI Runtimes Part I: Directory API), customers have the

capability to efficiently switch between PI runtimes in their federated PI landscapes.

www.sdn.sap.com/irj/sdn/howtoguides

how to fast-switch integration scenarios between sap pi ......names of installation, upgrade and...

Documents