Home

	Expand Search

Installation Guide New Era of Networks Adapter for SAP R/3 3.9

Chapter 1 Migrating to Adapter for SAP R/3 Version 3.9

Chapter 1

Migrating to Adapter for SAP R/3 Version 3.9

Process Overview

For Windows, Solaris, AIX, and HP-UX, the following procedures comprise the migration process:

• Transferring configuration information from the old configuration files to the new configuration files using Table 1-1 as a guide for key mapping.

• Running the IDoc format conversion tool (if applicable)

• Loading BAPI formats using the 3.9 adapter and map fields

Preparing for Upgrade

Existing database refers to the database you are currently using.

Target database refers to the database you will use with Adapter for SAP R/3 version 3.9.

Before migrating formats and rules from an existing database to your target database, verify the following:

• Existing database contains valid rules and formats.

• Integration Server is installed.

• Target database and temporary database are instantiated, contain no data, and allows sufficient space for rules and formats.

• Adapter for SAP R/3 version 3.9 is installed.

  Warning!

  When upgrading formats and rules to a target database, you must have three separate database instances: your existing database, a temporary database, and your target database. Do not attempt to rebuild your current database after exporting all the data.

Upgrading from Version 3.0.3 to Version 3.9

Upgrading from Adapter for SAP R/3 version 3.0.3 to version 3.9 consists of the following steps:

• Transfer user-specific configuration information from the version 3.0.3 configuration files to version 3.9 configuration files.

  You can do this manually using the sample configuration files in the SAP-3_9/CFG folder or using the GUI. See "Changes to Configuration Keys" for a table of changes to configuration keys between versions.

• Reload BAPI formats using Adapter for SAP R/3 version 3.9. You must crate new rules for these formats.

• Migrate IDoc formats using the procedure described in "Converting IDoc Formats".

Upgrading from Version 3.8 to Version 3.9

Upgrading from Adapter for SAP R/3 version 3.8 to version 3.9 consists of the following steps:

• Transfer user-specific configuration information from the version 3.8 configuration files to version 3.9 configuration files.

  You can do this manually using the sample configuration files in the SAP-3_9/CFG folder or using the GUI. See "Changes to Configuration Keys" for a table of changes to configuration keys between versions.

• BAPI formats have not changed between versions 3.8 and 3.9. You can continue to use the BAPI formats you used with version 3.8.

• Migrate IDoc formats using the procedure described in "Converting IDoc Formats".

Changes to Configuration Keys

If you use the GUI to import your pre-3.9 configuration files, some of the keys will be automatically mapped to the keys required by 3.9. You will have to make some manual changes to the configuration file before you use it. Alternatively, you can make all changes manually.

Appendix A of the Adapter for SAP R/3 User's Guide contains a list of all currently valid configuration keys.

The following keys and values must be changed in your configuration files. You can use the sample configuration files that are provided with the new installation. Manually transfer existing values for keys from your existing configuration files into the new configuration files based on the sample files provided.

This list contains keys that are typically used in configuration files but may not be all of the keys you have used. See the Adapter for SAP R/3 User's Guide for a specific version for a complete list of configuration keys for that version.

Converting IDoc Formats

You must convert the formats for both IDocs and BAPIs when you move between versions of Adapter for SAP R/3. Custom formats can continue to use names that begin with unique prefixes to differentiate them from standard formats.

You need to migrate your IDoc formats to accommodate the following situations:

• SAP has modified an IDoc structure.

  Even if you made no changes to the adapter, this could happen when you moved to a new version of SAP.

• You have modified an IDoc structure.

  You must convert your modified IDocs when you upgrade to a new version of the adapter or a new version of SAP.

• You are migrating from version 3.0.3 to version 3.9 of the Adapter for SAP R/3.

The format conversion tool that ships with Adapter for SAP R/3 is a valuable resource for you to more easily migrate IDoc formats. Formats are dependent on the field mapping that you have done so you must also migrate those mappings. The purpose of the conversion tool is to preserve the field mappings used for output formats and transfer those current field mapping to the newly loaded format. The tool does this using two format export files as input to produce a new format export file; the new format export file combines the information from the two formats. This is intended to save you time because, after you use the tool to transfer you old field mappings, you need map only the new fields. Formats can be converted without doing rules at the same time, but rules cannot be converted without also converting the associated formats.

To use the IDoc conversion tool, export your old IDoc output format and the new unmapped output format loaded using the version 3.9 adapter. Then edit the conversion tool configuration file to specify the names of the format export files and run the tool. IDoc formats required by version 3.9 into the IDoc conversion tool. The tool then creates one usable format based on the mapping of the two formats.

After you have transferred the field mapping, you may validate the converted format by reformatting previously used messages and confirming that the output message fields contain the expected data. The New Era of Networks utility programs msgtest.exe and ruletest.exe can be used to validate your converted messages and rules.

The IDoc conversion tool for Adapter for SAP R/3 provides the tools to do the following:

• Migrate IDoc formats from a 4.x Formatter database (database used by Adapter for SAP R/3 version 3.0.3) to a 5.4 Formatter database (database used by Adapter for SAP R/3 version 3.8).

• Update an extended IDoc format to a 5.6 Formatter database.

• Update a currently used IDoc format in a 5.x Formatter database to a newer version.

  If you are currently using map objects with formats for either of the last two scenarios, the conversion tool is not necessary because map objects preserve the field mapping from the original format. Map objects are available only with New Era of Networks formatters.

The following procedures must be applied individually to each IDoc format that is being migrated. The conversion tool is able to handle only one IDoc type at a time.

Output formats used by the Broker for IDocs sent into SAP changed between version 3.03 and version 3.8 of the SAP adapter. The segment names used to begin with E2 or Z2 and terminate with a three-digit version number. Segment names now begin with E1 or Z1 to reflect that the IDoc is inbound into SAP. Three-digit version numbers have been dropped.

New input formats can be used as loaded. No information from the old input format needs to be migrated.

1. Do one or both of the following:

   1. Export only the outbound format from the 4.x Formatter database using the NNFie utility provided with Formatter 4.x.

      Example:

       C:\MQI\bin>nnfie -e absen1.oc.4x.exp -m SAP.OC.ABSEN1 -s nnfie

   2. Export the Rules associated with the format using the NNRie utility., if you are converting rules.

      Example:

      C:\MQI\bin.nnrie -e absen1.4x.rules.exp -m SAP.OC.ABSEN1 -s nnfie

      When exporting extended IDoc formats from an 4.x Formatter database, the format name must be in quotation marks because names contain special characters. For example:

      nnfie -e format.exp -m "SAP.OC.MATMAS03^1" -s import

2. Load the outbound format for the same IDoc into a temporary 5.6 database using version 3.9 of Adapter for SAP R/3.

3. Export only the outbound format of the IDoc loaded in the previous step using the NNFie utility provided with Formatter 5.x.

   Example:

   C:\sybase\bin>nnfie -e absen1.oc.5x.exp -m SAP.OC.ABSEN1 -s nnfie

4. Edit the configuration file for the conversion tool to indicate:

   • The names of the two format export files created in step 1 and step 3 of this procedure.

   • The name that you want to use for the converted format. (This name is arbitrary).

5. To run the conversion tool, type the command using the following as an example:

   sap39idoccnvtool -file=<name of configuration file>

   The format export files and the configuration file used to load the 3.9 schema should be placed in the SAP-3_9/bin folder. The command must be run from this same folder.

6. Inspect the log file produced by the conversion utility for errors.

7. Do one of the following:

   1. Import the format created by the conversion utility into the target database using the NNFie utility provided with Formatter 5.x.

      Example:

      C:\ConversionTests\>nnfie -i absen1.oc.conv.exp -g -s nnfie

   2. Import the Rules file created by the conversion utility using the NNRie utility provided with Formatter 5.x. This step is required only if step 1b was used.

8. Review the formats to be sure the converted format has the correct mapping.

   If any formats have not been converted, you must change them manually.

9. Test the format by using it as the target format for reformatting a test message.

1. Export only the original outbound format using the NNFie utility provided with Formatter 5.x.

   Example:

   C:\sybase\bin>nnfie -e absen1.oc.5x.exp -m SAP.OC.ABSEN1 -s nnfie

2. Load the outbound format for the newly extended IDoc into a temporary 5.6 database using the 3.9 SAP adapter. (The example assumes an extended IDoc named ZABSEN1 was made from the base IDoc ABSEN1.)

3. Export only the outbound format of the IDoc loaded in the previous step using the NNFie utility provided with Formatter 5.x.

   Example:

    C:\sybase\bin>nnfie -e zabsen1.oc.5x.exp -m SAP.OC.ZABSEN1 -s nnfie

4. Edit the configuration file for the conversion tool to indicate:

   • The names of the two format export files created in step 1 and step 3 of this procedure.

   • The name that you want to use for the converted format. (This name is arbitrary.)

5. To run the conversion tool, type the command using the following as an example:

    sap39idoccnvtool -file=<name of config file>

   The format export files and the configuration file used to load the 3.9 schema should be placed in the SAP-3_9/bin folder. The command must be run from this same folder.

6. Inspect the log file produced by the conversion utility for errors.

7. Import the format created by the conversion utility into the target database using the NNFie utility provided with Formatter 5.x.

   Example:

   C:\ConversionTests\>nnfie -i zabsen1.oc.conv.exp -g -s nnfie

8. Test the format by using it as the target format for reformatting a test message.

The way extended IDocs are treated is the major consideration for the conversion process between Adapter for SAP R/3 versions 3.8 and 3.9. Extended IDocs are no longer considered special situations.

1. Export only the original outbound format using the NNFie utility provided with Formatter 5.x.

   Example:

   C:\sybase\bin>nnfie -e absen1.oc.5x.exp -m SAP.OC.ABSEN1 -s nnfie

2. Load the outbound format for the new version of the IDoc into a temporary 5.6 database using the 3.9 SAP adapter (the example assumes a new version of ABSEN was released - ABSEN2).

3. Export only the outbound format of the IDoc loaded in the previous step using the NNFie utility provided Formatter 5.x.

   Example:

   C:\sybase\bin>nnfie -e absen2.oc.5x.exp -m SAP.OC.ABSEN2 -s nnfie

4. Edit the configuration file for the conversion tool to indicate:

   • The names of the two format export files created in step 1 and step 3 of this procedure.

   • The name that you want to use for the converted format. (This name is arbitrary.)

5. To run the conversion tool, type the command using the following:

   Example:

   sap39idoccnvtool -file=<name of config file>

   The format export files and the configuration file used to load the 3.9 schema should be placed in the SAP-3_9/bin folder. The command must be run from this same folder.

6. Inspect the log file produced by the conversion utility for errors.

7. Import the format created by the conversion utility into the target database using the NNFie utility provided with Formatter 5.x.

   Example:

   C:\ConversionTests\>nnfie -i absen2.oc.conv.exp -g -s nnfie

8. Test the format by using it as the target format for reformatting a test message.

Example Log File

Source Control Record: SAP.OF.ABSEN1.CR
Destination Control Record: SAP.OF.ABSEN1.CR

Source Segment Name: SAP.OF.E2ABSE1
Destination Segment Name: SAP.OF.E2ABSE1

    Field: SAP.E2ABSE1.BDEGR    OutMap:     InMap: LEG.F1
    Field: SAP.E2ABSE1.MOABW    OutMap:     InMap: LEG.F2
    Field: SAP.E2ABSE1.ZEITY    OutMap:     InMap: LEG.F3
    Field: SAP.E2ABSE1.AGRUN    OutMap:     InMap: LEG.F4
    Field: SAP.E2ABSE1.BEGDA    OutMap:     InMap: LEG.F5
    Field: SAP.E2ABSE1.ENDDA    OutMap:     InMap: LEG.F6
    Field: SAP.E2ABSE1.ATEXT    OutMap:     InMap: LEG.F7

Adjusting for Customization

Make sure that the new format contains the correct default values for control records. (Default values in control records are optional.) The conversion tool transfers user-defined values and mappings, but it does not transfer default values.

If the original format specified default values for the partner profile fields of the control record, then you must manually set the values to those literals. This applies to the literals named SAP.<IDOC TYPE>.* where * is one of the following: RCVPOR, RCVPRN, RCVPRT, SNDPOR, SNDPRN, SNDPRT.

Suggestions for Converting IDocs

• Use descriptive names for the format export files.

• NNFie for 4.x uses the sqlsvses.cfg file, NNFie for 5.x uses the NNFie.cfg in the local directory (if one was created) or it searches for a copy of nnsyreg.dat file. The example commands assume the session name is nnfie.

• Use the which command to be sure that the expected version of nnfie.exe is being referenced.

• The conversion tool can only convert one format at a time, so each export file must contain only one top-level format. (For example, SAP.OC.DEBMAS04)

• The easiest way to provide the information necessary for a user to log into the SAP system is to use a functioning configuration file for the inbound IDoc process. The value of SAPInConfig key should be the name of this file. (For example, the Schema mode configuration file used to load the IDoc with Version 3.9. It should be in the SAP-3_9/bin folder.)

• The saprfc.ini file is required. The file is in the location pointed to by the RFC_INI environment variable.

• The log file created by running the conversion tool reports errors and conversion information. The conversion information is a summary of error messages and a list of items that have been converted. It should indicate that some field mappings were preserved; for example, see the log file at the end of this section (sample log for a run of the conversion tool that preserves mappings).

• The import of the format generated by the conversion tool should use the -g option to ignore the conflicts that are reported when the same components are loaded in multiple converted format files. For example, the Input/Output Control "SAP.Length.3" or the control for some other length value may exist in multiple format definitions. The definitions are identical, so there is no need to reload the component. The NNFie.log reports instances that were ignored.

Example Conversion Tool Configuration File

#--------------------------------------------------# File Name:  ConvTool.cfg
# Sample configuration file for running the IDoc

# format conversion tool.
# The format of this file is important. Session names
# MUST begin at the beginning of the line, the
# associated keys MUST be below the session name
# and indented by spaces or tabs. Comments are

# preceded by #.

#--------------------------------------------------
NNConv

# name of original format as seen in formatter

# database
    FromFormat = SAP.OC.MATMAS03^1

# name of format (loaded using new version of SAP

# adapter) as seen in 5x formatter

    ToFormat = SAP.OC.MATMAS03.ZMATMAS_EXTENSION# must provide connection parameters used by 3.9 SAP

# adapter to connect to SAP use inbound idoc or Schema 

# mode configuration file to get needed params to 

# connect to SAP

    SAPInConfig = in.cfg

# 1=411 0=5x (they could go 5x to 5x)

    SourceFrom411 = 1

# release of user's SAP system

    SourceSAPRelease = 4.6B

# name of export file of format to convert (ONLY one

# format!)

    SourceExtract = matmas_ext.4x.mapped.exp

# name of export file of format freshly loaded in 5.x

# via GUI (ONLY one format!)

RawExtract = matmas_ext.39.raw.exp

# desired name of converted format export file

OutputExtract = matmas_ext.39.conv.exp

# conversion log file

    LogFile = format_conversion.log

#####################################################

# the following keys are for Rules related components

#####################################################

# name of rule export file (from 411) [Optional]

# RulesIn = matmas_ext.rules.4x.exp

# desired name of converted rule export file (into 5x)

# [Optional]

# RulesOut = matmas_ext.rules.conv

# User may specify a new name for Message Type within the 

# Application Group in 5x database (the name is no

# longer limited to 32 characters in length, but may be

# up to 128 characters in length).

# After the input format is imported into the 5x

# database, the user would need to manually rename the

# format to match the new expanded name created using

# this key.

# example:

# name in 4x database: LEG.I.ORIGINAL_LIMITED_SIZE_NAME

# renamed in 5x database to
# LEG.I.MODIFIED_FORMAT_NAME_OF_LARGER_SIZE

# ToRuleInputMessage=SAP.IC.MATMAS03.ZMATMAS_EXTENSION

# defaults to same name [Optional] or change rule name

# RuleNameOut =

# eof

Converting BAPI Formats

You must convert the formats for both IDocs and BAPIs when you move between versions of Adapter for SAP R/3. Custom formats can continue to use names that begin with user-defined prefixes to differentiate them from standard formats.

BAPI formats and rules that you used for version 3.8 of the adapter will work with Adapter for SAP R/3 version 3.9. BAPI formats from version 3.0.3 or earlier are not supported and should be reloaded using the version 3.9 adapter. New rules must be created for these formats.

The term New Formatter Database references any database created using MQSI version 2.0.2, WMQI version 2.1, or e-Biz Integrator versions 3.2x or 3.6x.

The term Old Formatter Database references a database built on earlier versions of these products.

1. Reload all BAPIs into the New Formatter Database.

   New Rules must be created for all formats that are reloaded into a new database.

Upgrading Rules

Review the rules that you are currently using with Adapter for SAP R/3. If they need to be converted for use with version 3.9:

• For converting IDoc rules, see "Converting IDoc Formats".

• For converting BAPI rules used with 3.0.3 formats, manually convert your rules.