SAP NetWeaver
How-To Guide
How To... Migrate Custom Portal
Applications to SAP NetWeaver 7.3
Applicable Releases:
SAP NetWeaver 7.30 SP03 and above
SAP NetWeaver 7.31 SP02 and above
IT Practice / Topic Area:
SAP NetWeaver Portal
Version 1.0
February 2012
© Copyright 2012 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, Excel, Outlook, and PowerPoint are
registered trademarks of Microsoft Corporation.
IBM, DB2, DB2 Universal Database, System i, System i5,
System p, System p5, System x, System z, System z10,
System z9, z10, z9, iSeries, pSeries, xSeries, zSeries,
eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400,
AS/400, S/390 Parallel Enterprise Server, PowerVM,
Power Architecture, POWER6+, POWER6, POWER5+,
POWER5, POWER, OpenPower, PowerPC, BatchPipes,
BladeCenter, System Storage, GPFS, HACMP, RETAIN,
DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex,
MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity,
Tivoli and Informix are trademarks or registered
trademarks of IBM Corporation.
Linux is the registered trademark of Linus Torvalds in the
U.S. and other countries.
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 and Java are registered trademarks of Oracle.
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.
SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign,
SAP BusinessObjects Explorer, StreamWork, SAP HANA,
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 other countries.
Business Objects and the Business Objects logo,
BusinessObjects, Crystal Reports, Crystal Decisions, Web
Intelligence, Xcelsius, and other Business Objects products
and services mentioned herein as well as their respective
logos are trademarks or registered trademarks of Business
Objects Software Ltd. Business Objects is an SAP company.
Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL
Anywhere, and other Sybase products and services
mentioned herein as well as their respective logos are
trademarks or registered trademarks of Sybase, Inc. Sybase
is an SAP company.
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.
i
Document History
Document Version
Description
1.00
First official release of this guide
ii
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
Important
Note
Recommendation or Tip
Example
iii
Table of Contents
1.
Business Scenario ..........................................................................................................1
2.
Acronyms.........................................................................................................................1
3.
Prerequisites....................................................................................................................1
4.
Step-by-Step Procedure ..................................................................................................2
4.1 Sample Application ...................................................................................................2
4.2 Importing Application Source Code to NWDS ............................................................3
4.3 Updating JAR Locations for Build Time .....................................................................5
4.3.1 Finding Public APIs JARs .............................................................................5
4.3.2 Finding Relevant JARs for Imported Classes ................................................6
4.3.3 Adding JARs.................................................................................................6
4.4 Handling Deprecated APIs ........................................................................................7
4.5 Adjusting Code to Support JDK 1.6 ...........................................................................8
4.6 Setting Runtime Dependencies in Portalapp.xml .......................................................8
4.7 Building and Deploying Application .........................................................................10
4.8 Testing Application at Runtime ................................................................................ 11
iv
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
1.
Business Scenario
This guide helps you to migrate your custom portal applications from SAP NetWeaver 7.0x to 7.3 by
presenting the required steps, potential obstacles and recommended solutions.
Migrating Portal Applications provides information about enabling your existing applications to run in
the new environment.
The procedures described in the guide enable you to modify your applications in the future.
Note
This guide does not focus on the development infrastructure aspects. If you are using NWDI, see
Migrating Tracks Content from SAP NetWeaver 7.0 to a Higher Version.
2.
Acronyms
AS – Application Server
API – Application Program Interface
DC – Development Component
GPAL - Generic Portal Application Layer
EAR – Enterprise Archive
JAR – Java Archive
JDK- Java Development Kit
NWDS – SAP NetWeaver Developer Studio
NWDI – SAP NetWeaver Development Infrastructure
PAR - Portal Archive
SCA- Software Component Archive
3.
Prerequisites
SAP NetWeaver 7.3 is installed (used for deployment and runtime tests)
NWDS 7.3 is installed
JDK 1.6 is installed
Source code of a working application is available
February 2012
1
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
4.
Step-by-Step Procedure
This section describes all the steps necessary for migrating custom portal applications .
4.1
Sample Application
To illustrate these steps, we use a sample application com.myCompany.MigrationTest, developed
and deployed in a SAP NetWeaver 7.0x portal.
The application looks as follows:
When the application is loaded, the title displays the full name of the current user: “Hello <user
name>”. Entering the user ID and clicking OK displays the full UME ID and navigation tree of the user
with active links.
February 2012
2
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
4.2
Importing Application Source Code to NWDS
To import the source code of the application to NWDS 7.3, perform the following steps:
1. To open the Enterprise Portal perspective in NWDS, choose Window
Other, and then Enterprise Portal.
Open Perspective
2. To import the project, choose File Import…
3. Select Existing Projects into Workspace and choose Next.
February 2012
3
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
4. Select the folder in which your project is located, and choose Finish.
The imported project should appear in the Package Explorer.
February 2012
4
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
4.3
Updating JAR Locations for Build Time
In SAP NetWeaver 7.3, the public APIs are packaged in JAR files, that are now stored in different
locations. To ensure that your application has access to the public APIs it uses, you need to update
the locations of the JAR files in your project.
In the application code, you can see the import errors that result from the change of location of the
public JARs.
To resolve these errors, perform the steps described in the following sections.
4.3.1 Finding Public APIs JARs
1. In the NWDS installation folder, open the plugins subfolder, and check for all the plugins
(JARs) that start with com.sap.tc.ap.*
Each of these files represents an SCA and contains the public API JARs. The name pattern of a
JAR file is com.sap.tc.ap.<sca name>_<version number>.jar.
There may be more than one version for each SCA, of which you should use the latest.
2. Open a JAR and set the display option to Flat Folder View.
The JARs are located under
SCA>\DCs\sap.com\tc\<comp>\<app>\api\_comp\gen\default\public\api\lib\java.
3. In your file system, create a folder in which you want to store the public APIs.
4. In this folder, create a subfolder with the name <comp>_<application>.
5. Copy all the required JARs into this subfolder.
For example:
1. Open com.sap.tc.ap.epruntime_7.3.0.111019142240.jar.
2. Locate com.sap.portal.navigation.api_service.jar under EPRUNTIME\DCs\sap.com\tc\ep\navigation\api\_comp\gen\default\public\api\lib\java,
and copy it to the ep_navigation subfolder.
Repeat these steps for all required JARs.
February 2012
5
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
4.3.2 Finding Relevant JARs for Imported Classes
1. In the Javadocs section at SAP Help Portal, choose the relevant version of SAP NetWeaver
7.3, and then Enterprise Portal.
2. Find an imported class, for example, AbstractPortalComponent, and open the link.
3. Under Access Rights see the location of the JAR: in EP-BASIS-API under ..../epbc/prt/api/...
4.3.3 Adding JARs
1. In NWDS, right-click the project and choose Properties.
2. In the Properties dialog, choose Add External JARs.
3. Select tc~epbc~prt~api.jar in the epbc_prt folder, and choose OK.
4. Verify that the class references are now resolved, since all
com.sapportals.portal.component* APIs are included in the same JAR.
February 2012
6
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
5. Repeat the above steps to resolve com.sap.portal.navigation* by adding
com.sap.portal.navigation.api_service.jar, and com.sapportals.htmlb* by adding
com.sapportals.htmlb.jar, located under FRAMEWORKEXT\DCs\sap.com\com.sapportals.htmlb\_comp\gen\default\public\default\lib\java.
4.4
Handling Deprecated APIs
Deprecated means that, although an API is still available and supported, it will be phased out in the
subsequent releases, therefore you should avoid using it, and use the suggested alternative API.
We recommend using the new 7.3 reference DC in the new projects.
1. Repeat the steps described in the previous section for
com.sapportals.portal.prt.service.usermanagement.IUserManagementService.
In the Javadoc for the IUserManagementService interface, you can see that it is deprecated
and replaced by the IUserManagementEngine interface, located in the
com.sap.ip.portal.service.ume package.
2. In the imports statement, replace
com.sapportals.portal.prt.service.usermanagement.IUserManagementService
with com.sap.ip.portal.service.ume.IUserManagementEngine.
3. Add the JAR com.sap.portal.usermanagement.jar from EP-BASIS, as described above.
4. In your code, make the necessary changes where this interface is used.
For example:
1. Replace all IUsermanagementService with IUserManagementEngine.
There is still an error with com.sapportals.portal.security.usermanagement.IRoleFactory.
2. Check the Javadocs at
http://help.sap.com/javadocs/NW73/SPS05/CE/se/com.sap.se/index.html
for IRoleFactory under com.sap.security.api. You need to replace
com.sapportals.portal.security.usermanagement.IRoleFactory
with com.sap.security.api.IRoleFactory and import com.sap.security.api.IRoleFactory
instead of com.sapportals.portal.security.usermanagement.IRole.
February 2012
7
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
3. Set a reference to the relevant tc~je~usermanagement~api.jar under ENGFACADE.
4. To resolve IRole, add the imports com.sap.security.api.IRole statement.
5. The strikethrough on UserManagementException indicates that it is deprecated.
In the imports statement, replace
com.sapportals.portal.security.usermanagement.UserManagementException with
com.sap.security.api.UMException.
Replace UserManagementException with UMException from com.sap.security.api.
6. Use the NWDS quick fix to replace the unidentified method role.getUMEID() with
getUniqueID().
4.5
Adjusting Code to Support JDK 1.6
SAP NetWeaver 7.3 uses JDK 1.6, which means that all custom code should comply with the
JDK 1.6 standard.
In the imports list, there are errors for the com.sapportals.htmlb.enum* objects,
because enum is a reserved word in JDK1.6. It should be replaced with
com.sapportals.htmlb.enums*, and all instances of enum in the code should be replaced
with another string, for example, enum1.
4.6
Setting Runtime Dependencies in Portalapp.xml
Make sure that the application descriptor, portalapp.xml, located under dist PORTAL-INF,
complies with the standard defined in Deployment Descriptor (portalapp.xml).
In our example, portalapp.xml looks as follows:
<application>
<application-config>
<property name="PrivateSharingReference"
value="com.sap.portal.htmlb, com.sap.portal.navigation.service,
com.sap.portal.navigation.api_service"/>
<property name="Vendor" value="mycompany.com"/>
February 2012
8
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
<property name="SecurityArea" value="NetWeaver.Portal"/>
</application-config>
<components>
<component name="MigrationTest">
<component-config
<property name="ClassName"
value="com.my.company.migration.test.MigrationTest"/>
</component-config>
<component-profile/>
</component>
</components>
<services/>
</application>
To enable referencing the portal APIs used in your application, you must define the relevant
PrivateSharingReference and/or PublicSharingReference properties. In SAP NetWeaver 7.3,
references should be made via the facade DC rather than directly to the components..
For portal applications you should convert the DC name to reference.
For example, if the DC name in the Javadocs is [sap.com] tc/epbc/prt/api, the reference
should be com.sap.tc~epbc~prt~api. For a J2EE library, the prefix should be SAPJ2EE::library:.
Portalapp.xml in our example should look as follows:
<application>
<application-config>
<property name="PrivateSharingReference"
value="com.sap.tc~epbc~prt~api,
SAPJ2EE::library:com.sapportals.htmlb,
com.sap.tc~ep~navigation~api"/>
<property name="Vendor" value="mycompany.com"/>
<property name="SecurityArea" value="NetWeaver.Portal"/>
</application-config>
<components>
<component name="MigrationTest">
<component-config
<property name="ClassName"
value="com.my.company.migration.test.MigrationTest"/>
</component-config>
<component-profile/>
</component>
</components>
<services/>
</application>
February 2012
9
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
4.7
Building and Deploying Application
After resolving all errors, build your application and create a deployable object (EAR).
Note
If you are using NWDI, the process is different. For more information, see Migrating Tracks
Content from SAP NetWeaver 7.0 to a Higher Version.
1. Right-click the project and select Export.
2. Select SAP NetWeaver Portal
EAR File and choose Next.
3. Select the project from the list and choose Next.
4. Define the Name and Location properties and choose Next.
5. Verify that the EAR file is created in your project.
Deploy the application and verify there are no deployment errors.
1. To configure the 7.3 NetWeaver Portal Server for deployment, go to Window
SAP AS JAVA.
2. To open the Deploy View, go to Window Show View Deploy View.
3. Add the EAR file you have created, and deploy it.
4. Verify that deployment completed successfully (with no errors or warnings)
Preferences
For more information about deployment of applications, see Application Lifecycle and Deployment.
February 2012
10
How To... Migrate Custom Portal Applications to SAP NetWeaver 7.3
4.8
Testing Application at Runtime
Following the successful deployment, test your application at runtime and verify that its
behavior is the same as in NetWeaver 7.0.
1. Log on to the portal as a Content Administrator, and navigate to Content
Administration Portal Content Management.
2. Choose Portal Applications to open the GPAL repository.
3. Right-click the deployed application, and choose Preview.
Verify that the application functions as expected.
Note
If the application requires parameters, it will not run properly in preview. You need to
create a wrapping iView by copying the application into the PCD, and set the required
parameters.
For more information, see Working with GPAL Repositories.
February 2012
11
www.sdn.sap.com/irj/sdn/howtoguides