How-to Guide How-to Guide SAP NetWeaver 7.0 (2004s) SAP NetWeaver 7.0 (2004s)

How To…

How To… Load a File into BI-Integrated Planning Version 2.4 – February 2008 Applicable Releases: SAP NetWeaver 7.0 (2004s) BI Business Information Management Business Planning and Analytical Services

© Copyright 2006 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, and Informix are trademarks or registered trademarks of IBM Corporation 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, 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.

1 Business Scenario You are using SAP NetWeaver BI Integrated Planning and have the requirement to load external data into your planning application. Typically data is loaded into SAP NetWeaver BI using the data staging functionality. However, you are looking for an easier way to upload data from a file that can be performed by business planners. This paper describes a solution that allows business planners to load a file directly into their planning application using a web browser. The following screen shows the user interface. The planner is prompted for the file name and simply chooses Upload. The system will load the file and validate its content. If there are no errors the planner can save the changes. The newly loaded data is immediately available in planning applications and queries.

The updated solution also provides a way for planners to download data in various file formats. The download files can be edited and uploaded in the same format.

- 1 -

Additional features:

• Various file formats: tab-delimited, fixed length, or XML • Various codepages: Unicode, UTF-8, UTF-16, and other codepages • Option for overwriting of or appending to existing data including delta mode • Text files with or without header line • Conversion of numbers and dates according to user settings • Conversion of characteristic value according to conversion routine (for example

ALPHA conversion or external to internal material numbers) • Conversion of amounts according to currency format configuration • Flexible definition of fields and field order in upload file • Support for virus scanning (if installed with SAP NetWeaver) • Direct upload and download of file with out any prompts (for example from BEx

Analyzer) After the initial implementation there are no program changes required in order to use these features. All options can be configured using the Planning Modeler. Please download the ZIP file from SAP Developer Network at: https://www.sdn.sap.com/irj/sdn/go/portal/prtroot/docs/library/uuid/9080f58e-7bf2-2910-71a0-b48c4363be63 For up-to-date information about this solution please check the following blogs: https://www.sdn.sap.com/irj/sdn/weblogs?blog=/pub/wlg/6671 and https://www.sdn.sap.com/irj/sdn/weblogs?blog=/pub/wlg/7708

- 2 -

2 Introduction The solution has three parts: a planning function type for processing the loaded data, a planning function that contains the configuration of the file format, and a user interface for uploading a file. The first part is a new planning function type. This new upload function type is implemented in ABAP and contains the logic to process the loaded data. It converts the data from various external formats into the internal format of SAP NetWeaver and also performs several consistency checks. Just like any other planning function type, the upload function type validates the data against characteristic relationships and performs checks against data slices. The second part is a planning function based on the newly defined upload planning function type. In this planning function you configure the characters set (Unicode, non-Unicode, or codepage), whether the file data should overwrite or be added to existing data, and whether the file contains a header line or not. The final part is a Web Dynpro application which provides a self-explaining user interface for uploading files. This application allows the user to enter the file name or browse for the file on his computer and then execute the upload. The application will display any messages generated by the upload function. If there are errors the user can correct the mistakes and load the file again. If the upload is successful the application allows the user to save the changes into the corresponding InfoCube. Note that the solution is not intended for mass data uploads. Processing large files with the upload function can take a long time. It is recommended to use the standard data staging functionality of SAP NetWeaver BI to load those large files instead. Similarly, three parts exist for the file download: a planning function type for compiling the data into a file structure, a planning function that contains the configuration of the file format, and a user interface for downloading a file.

- 3 -

3 The Step By Step Solution Part 1 – Planning Function Type Part 1a – Check Prerequisites Part 1b – Import Objects Part 1c – Maintain Master Data Part 2 – Planning Model Part 3 – User Interface

3.1 Planning Function Type

3.1.1 Check Prerequisites

1. Go to transaction RSA1. For the example we will use InfoCube 0DBPS_C01. Check that the InfoCube exists and is active. If it does not exist in your system, activate it from the BI Content.

2. Check that InfoArea ts and is active.

ote: The new objects will be

0BWTCT_PLAN exisIf it does not exist in your system, activate it from the BI Content. Ncreated in this InfoArea.

- 4 -

3. Go to transaction RSD1. Characteristic 0TCTIOBJNM will be used for the parameter definition of the planning function. Check that the InfoObject exists and is active. If it does not exist, activate it from the BI Content. Optionally, load the master data and texts for characteristic 0TCTIOBJNM. This will make it easier to select the InfoObjects that you want to include in the upload file.

3.1.2 Import Object

1. All necessary objects are included in a transport. Unzip the files and copy them into the transport directory of your BI system (K9*.BIR into COFILES directory, R9*.BIR into DATA directory). Then go to transaction STMS, select your system, add the new transport to the import queue, and finally import the transport. For more information please see SAP note 13719.

- 5 -

2. Go to transaction SE24 and check that ABAP classes ZCL_RSPLF_FILE_UPLOAD and ZCL_RSPLF_FILE_DOWNLOAD exist and are active.

3. Go to transaction RSPLF1 and check that planning function types ZRSPL_FILE_UPLOAD and ZRSPL_FILE_DOWNLOAD exist and are active.

4. Go to transaction SICF and check that the services for ZRSPLF_FILE_UPLOAD and ZRSPLF_FILE_DOWNLOAD are activated. You can find the services under /default_host/sap/bc/webdynpro/sap/ Right-click on it and select Activate service.

- 6 -

3.1.3 Maintain Master Data

1. Go to transaction RSA1 and maintain the master data for the following characteristics: Character Format (ZIP_ENCOD) Convert Amounts (ZIP_CONVA) Convert Fields (ZIP_CONVF) Overwrite Data (ZIP_OVERW) Skip Header (ZIP_SKIPH) You can find the texts as an attachment in the ZIP file for easy cut and paste into your system.

3.2 Planning Model

1. Launch the Planning Modeler (transaction RSPLAN) and select the InfoProvider that you want to load data into. The example in this how-to paper uses InfoProvider 0DBPS_C01.

2. Go to “Aggregation Level” tab and create an aggregation level. Example: FILE_LVL.

- 7 -

3. Select the fields you want to upload. Example: 0CURRENCY 0FISCVARNT 0FISCYEAR 0D_REVEN 0D_CUSTOMER 0D_VERSION Save and activate the aggregation level.

4. Go to “Filter” tab and create filter. Example: FILE_FLT.

5. For example, add “Version” to the filter and restrict it to variable 0D_PVERS. Typically you will include fields for organizational criteria as well here. Note: The filter is used for locking data. If you do not include any variables, all data will be locked!

6. Save the filter.

- 8 -

7. Go to the “Planning Function” tab and create function using the “File Upload” type. Example: FILE_UPL.

8. Set the parameters for the planning function. Example: Character Format = DEFAULT Overwrite Data = X Skip Header Line = X Convert Fields = X Convert Amounts = X File Format = 0D_VERSION 0FISCVARNT 0FISCYEAR 0D_CUSTOMER 0CURRENCY 0D_REVEN File Name = (leave empty) Tip: Add the technical name under "Settings" for the File Format. Now you can enter the InfoObjects manually and don't have to pick them from the value help.

9. Go to the “Planning Sequence” tab and create a new planning sequence. Example: FILE_SEQ.

- 9 -

10. Add the upload planning function as a step to the sequence and save it. Tip: If required you may add other planning functions to the sequence to run before or after the upload. For example you could add a FOX function to validate the uploaded data against business rules.

11. Repeat steps 7 to 10 for the "File Download" planning function. Example: Planning function = FILE_DWN Function type = File Download Planning sequence = FILE_SEQ2 Use the same parameter settings as for the upload.

3.3 Example for "File Upload"

1. In order to launch the application, choose Web Dynpro Application Execute. This will bring up the file upload application in a web browser. The URL is displayed in the properties of the Web Dynpro application (see above). Append the parameter for the planning sequence to the URL. The parameter for message types is optional (see also appendix).

General format of the start URL:

http://<server>:<port> /sap/bc/webdynpro/sap/zrsplf_file_upload? planning_sequence=<name_of_sequence> &show_messages=<message_types>

- 10 -

2. Start the Web Dynpro application. Paste the URL into the address bar of your browser. The URL can be assigned to a portals role or stored as a local bookmark.

3. Select the upload file and start the upload. Enter the file name or choose the “Browse” and select the file. Then choose “Upload”. The system will now read the file and start the planning function to process the file contents. The data will be stored in the OLAP buffer (same as with any other planning function). If you want don't like the result, you choose "Undo". Note: "Undo" is only possible before you save the changes.

- 11 -

4. Save the data Choose “Save” to store the data in the InfoProvider. The system will display either a success or an error message.

5. Exit the application by closing the browser window.

3.4 Example for "File Download"

6. In order to launch the application, choose Web Dynpro Application Execute. This will bring up the file upload application in a web browser. The URL is displayed in the properties of the Web Dynpro application (see above). Append the parameter for the planning sequence to the URL. The parameter for message types is optional (see also appendix).

General format of the start URL:

http://<server>:<port> /sap/bc/webdynpro/sap/zrsplf_file_download? planning_sequence=<name_of_sequence> &show_messages=<message_types>

- 12 -

7. Start the Web Dynpro application. Paste the URL into the address bar of your browser. The URL can be assigned to a portals role or stored as a local bookmark.

8. Select the file format and start the download. The system will now read the data and start the planning function to compile the data into a file.

9. Click on the "Download File" link. The browser will open another window which contains the file content. You can now save the file on to your PC (for example with File > Save As in Microsoft Internet Explorer).

10. Select "Next" to download more data or exit the application by closing the browser window.

- 13 -

4 Appendix

4.1 Example Files Assumption for the example:

a) First line of the text file contains a header line. This information is just a reference and ignored during the upload.

b) Version field has leading zeros

c) Decimal point is used for amounts

d) Amounts are given in external value (amount conversion is turned on) Note: Compared to the initial how-to paper, two records have been appended to the example file in order to demonstrate handling of currency amounts that do not have 2 decimal places (JPY = no decimals, PKT = three decimals). Example text file with tab separator: 0d_version(3) 0fiscvarnt(2) 0fiscyear(4) 0d_customer(10) 0currency(5) 0d_reven(23)

001 K4 2006 DS1000 EUR 1234.56

001 K4 2006 DS2000 USD 789.01

001 K4 2007 DS1000 EUR 23.45

001 K4 2007 DS2000 USD 67.89

001 K4 2008 DS1000 JPY 123456

001 K4 2008 DS2000 PKT 123.456

Example text file with fixed length: AAABBCCCCDDDDDDDDDDEEEEEFFFFFFFFFFFFFFFFFFFFFFF 001K42006DS1000 EUR 1234.56 001K42006DS2000 USD 789.01 001K42007DS1000 EUR 23.45 001K42007DS2000 USD 67.89 001K42008DS1000 JPY 123456 001K42008DS2000 PKT 123.456

- 14 -

Example XML file: <?xml version="1.0" encoding="utf-8" ?> <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0"> <asx:values> <DATA> <item> <_--30D_VERSION>001</_--30D_VERSION> <_--30FISCVARNT>K4</_--30FISCVARNT> <_--30FISCYEAR>2006</_--30FISCYEAR> <_--30D_CUSTOMER>DS1000</_--30D_CUSTOMER> <_--30CURRENCY>EUR</_--30CURRENCY> <_--30D_REVEN>1234.56</_--30D_REVEN> </item> <item> <_--30D_VERSION>001</_--30D_VERSION> <_--30FISCVARNT>K4</_--30FISCVARNT> <_--30FISCYEAR>2006</_--30FISCYEAR> <_--30D_CUSTOMER>DS2000</_--30D_CUSTOMER> <_--30CURRENCY>USD</_--30CURRENCY> <_--30D_REVEN>789.01</_--30D_REVEN> </item> <item> <_--30D_VERSION>001</_--30D_VERSION> <_--30FISCVARNT>K4</_--30FISCVARNT> <_--30FISCYEAR>2007</_--30FISCYEAR> <_--30D_CUSTOMER>DS1000</_--30D_CUSTOMER> <_--30CURRENCY>EUR</_--30CURRENCY> <_--30D_REVEN>23.45</_--30D_REVEN> </item> <item> <_--30D_VERSION>001</_--30D_VERSION> <_--30FISCVARNT>K4</_--30FISCVARNT> <_--30FISCYEAR>2007</_--30FISCYEAR> <_--30D_CUSTOMER>DS2000</_--30D_CUSTOMER> <_--30CURRENCY>USD</_--30CURRENCY> <_--30D_REVEN>67.89</_--30D_REVEN> </item> <item> <_--30D_VERSION>001</_--30D_VERSION> <_--30FISCVARNT>K4</_--30FISCVARNT> <_--30FISCYEAR>2008</_--30FISCYEAR> <_--30D_CUSTOMER>DS1000</_--30D_CUSTOMER> <_--30CURRENCY>JPY</_--30CURRENCY> <_--30D_REVEN>123456</_--30D_REVEN> </item> <item> <_--30D_VERSION>001</_--30D_VERSION> <_--30FISCVARNT>K4</_--30FISCVARNT> <_--30FISCYEAR>2008</_--30FISCYEAR> <_--30D_CUSTOMER>DS2000</_--30D_CUSTOMER> <_--30CURRENCY>PKT</_--30CURRENCY> <_--30D_REVEN>123.456</_--30D_REVEN> </item> </DATA> </asx:values> </asx:abap>

- 15 -

4.2 URL Parameters Parameter Description planning_sequence=<sequence> Technical name of the planning sequence that is

used to upload or download the data. show_messages=<message types> show_messages=WEXA show_messages=WEXAS show_messages=WEXASI

List of message types shown in log. Warning and errors (default). Show also parameter definitions. Show also intermediate info messages.

4.3 File Formats Format Description Text Records:

Each line in the file represents one record for the upload function. End of line: The end of line can be denoted by CR, LF, LFCR, or CRLF. Note: This is automatically detected by upload function. Field separation: If the file contains several columns, there are two options:

1. The fields are separated by horizontal tabs 2. The fields are contained in the file in their full fixed field

length. File is limited to data types CHAR, NUMC, DATE and TIME.

Note: This is automatically detected by upload function: If there is one horizontal tab included in the file, then the first option is assumed by the upload function. Field conversion: If the "Convert Fields" setting is turned on, field values are interpreted according to user settings (see below). Note: If field conversion is turned off then no conversion exits are called. For example, if a characteristic has leading zeros, then the leading zeros also must be supplied in the file.

XML Default ABAP transformation schema (see example above). One <DATA> node per file (upper case), one <item> node per record (lower case), one node per field. Field node names are based on technical name of characteristic in upper case with “_--3” as a prefix. Attention: The tags in the XML file are case sensitive!

- 16 -

Note: It’s possible to upload any XML file by providing an XSL transformation. Simply adapt the CALL TRANSFORMATION in method IF_RSPLFA_SRVTYPE_IMP_EXEC~EXECUTE and replace “ID” with your own XSL or simple transformation. Please refer to the ABAP help documentation for more details: SAP XSLT Processor Reference Simple Transformations

Note: If the filter is restricted to a single value for characteristic and that characteristic is not included as part of the file format, the data will be loaded with the single value restricted in the filter instead of reading from the file format.

4.4 Function Parameter: Character Encoding Setting Description DEFAULT UTF-8 in a Unicode system and NON-UNICODE in a non-

Unicode system. UTF-8 In the input buffer, characters are displayed in UTF-8 format. NON-UNICODE

In the input buffer, characters are displayed in the codepage that is defined by the text environment at the time when the Read method was called (see SET LOCALE LANGUAGE). A non-Unicode codepage is also used for the input buffer on a Unicode system.

<nnnn> 4-digit number of SAP codepage. (The function module SCP_CODEPAGE_BY_EXTERNAL_NAME provides the SAP codepage number for an external character set name, for example "iso-8859-1". The function module NLS_GET_FRONTEND_CP returns the front-end codepage for a language.) See table TCP00.

4.5 Function Parameter: Overwrite Data (Upload Only) Setting Description # (Default) Add file data to existing data. D Delta mode: Overwrite existing data with file data. If record is not

included in file it will be retained. X Overwrite existing data with file data. If record is not included in

file it will be deleted.

4.6 Function Parameter: Skip Header Setting Description # (Default) File does not contain a header line. X File contains a header line.

Note: This setting is used only for text files (not XML).

- 17 -

4.7 Function Parameter: Field Conversion Setting Description # (Default) No conversion.

Note: Since version 2.4 key figure values must always be formatted according to the decimal notation defined in the user settings.

X The following applies for the different data types:

1. Integer, Numeric, Packed Decimals, or Floating Point: numbers must be formatted according to the decimal notation defined in the user settings.

2. Dates: The date must be formatted according to the date format defined in the user settings.

3. Times: The time must be formatted as hh:mm:ss.

4. Characteristics with Conversion Routines: The data can be loaded in external format and the upload will convert it to the correct internal format. Example: 0D_VERSION is configured with ALPHA conversion. If "Field Conversion" is turned on, you can load the value "1". It will be converted to and stored as "001".

Note: Conversion of numbers, dates, and times are only executed for files in text format (not for XML).

4.8 Function Parameter: Amount Conversion Setting Description # (Default) No conversion. Amounts have to be given in the SAP internal

format. Example: To load 1000 JPY include the value 10.00 in the file.

X Amounts are converted according to the currency decimal places maintained in table TCURW. Example: To load 1000 JPY include the value 1000 in the file.

4.9 Function Parameter: File Format Setting Description <InfoObject> List of InfoObjects in the order they appear in the upload or

download file. If the InfoObject is not included in the aggregation level, then it will be ignore during the upload or empty in the download file.

- 18 -

4.10 Function Parameter: File Name This parameter is only used if you use SAPGUI based file upload (for example from BEx Analyzer) and not the Web Dynpro application. You can also use the parameter for the download function to specify the default filename of the download file. Setting Description Empty (Default) If no file name is given, then the upload function will look for the

file SAP_BEX_FILE_UPLOAD.txt in the SAP work directory (typically C:\Documents and Settings\<user>\SapWorkDir). If no file name is given for the download function, then the system will use SAP_BEX_FILE_DOWNLOAD.txt as a default. The default directory depends on the setting of the browser.

<Filename> Upload: Complete file name and path of the upload file as it's stored on the frond-end. Example: C:\My_Documents\My_Upload_File.txt Download: File name that is used as a default for the download file.

4.11 Virus Scanning (Upload Only) The upload function use the virus scan interface via virus scan profiles. A virus scan profile contains a list of scanner groups to be used to check a document. A virus scan profile also allows you to predefine configuration parameters for the virus scanner. The upload function uses the /SIHTTP/HTTP_UPLOAD profile. For more information on virus scan integration please check SAP note 817623 and related notes.

- 19 -

4.12 Integration into Planning Application To integrate the upload or download into an existing planning application, simply add a URL link to your application. This is trivial for web-based applications. Tip: Include a button to switch between "Change Mode" and "Display Mode". This way you can avoid locking issues by switching to "Display" before you run the upload or download. For Excel-based application you have two options:

1. Add a BEx button for executing the planning sequence and store the data in SAP_BEX_FILE_UPLOAD.txt in the SAP work directory (or provide a file name and path in the "File Name" parameter of the planning function). The download function will save the data in SAP_BEX_FILE_DOWNLOAD.txt in the SAP work directory (or provide a file name and path in the "File Name" parameter of the planning function). Note: You must also turn on "Log on with Attached SAPGUI" in the BEx workbook settings.

2. Add a command button to your workbook and use the VBA coding provided in the

ZIP file to launch the Web Dynpro application.

4.13 Known Limitations Limitation Description CSV Format The solution is not able to handle files with comma separated

values (see note 1066919).

4.14 Notes If there are any problems with the solution, please check the following notes: 13719 Preliminary transports to customers (note for customers) 517484 Inactive services in the Internet Communication Framework 817623 Integrating a virus scan in SAP applications 882548 User session (HTTP/SMTP/..) closed after timeout 938809 Web Dynpro ABAP checklist for creating problem messages 999999 References to important notes about Web Dynpro ABAP 1066919 Showcase GUI_UPLOAD: Comma separated value (CSV) file 1066952 Working with legacy data files in LSMW (Unicode, OM, FTP) 1070655 Termination msg CL_RSPLFR_CONTROLLER=>GET_READ_WRITE_PROVIDS

- 20 -

- 21 -

5 Version History Version Description 1.0 – April 2007 Initial release of this how-to solution. 2.0 – August 2007 • Added option for SAPGUI based file upload (for example

from BEx Analyzer) • Disabled variable and file browse fields after selecting

"Upload" • Fixed incorrect data during merge phase when field

conversion is turned on • Fixed runtime error CALL_FUNCTION_CONFLICT_

GEN_TYP when field conversion is turned on • Added automatically conversion of URL parameter to upper

case • Added chapter with important notes

2.1 – October 2007 • Maximum of 500 message in output log to prevent seemingly hanging uploads with many errors

• New planning function type for "File Download" • Removed limitation on InfoObjects

2.2 – November 2007 • Support for variables with multiple values, intervals, or selection options

• Fixed rounding errors when uploading currency amounts with three or more decimals

• Corrected key figure values in new example files 2.3 – December 2007 • Support of user exit variables

• Fixed error when variable is restricted to single value but field is not included in file

2.4 – February 2008 • Support for key figure values with thousand separator • Fixed error when uploading key figure values with decimal

comma

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