The DecisionStream Connector for SAP R/3 User Guide, describes how to use
..... Connector for SAP R/3 CD contains a sample catalog for the SAP SD and F1.
Cognos
DecisionStream
Connector for SAP
(R)
R/3
(TM)
DecisionStream Connector for SAP R/3
User Guide
Copyright Cognos DecisionStream Connector for SAP (R) R/3 (TM) Version 7.0 This edition published 2002. Copyright (C) 2002 Cognos Incorporated. Portions Copyright (C) Microsoft Corporation, One Microsoft Way, Redmond, Washington 98052-6399 USA. All rights reserved. Portions Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler. Sample product images with the pound symbol (#) in the lower right hand corner are copyright (C) 1998 PhotoDisc, Inc. This software/documentation contains proprietary information of Cognos Incorporated. All rights are reserved. Reverse engineering of this software is prohibited. No part of this software/documentation may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos Incorporated. Cognos, the Cognos logo, Axiant, COGNOSuite, Cognos Upfront, Cognos DecisionStream, Impromptu, NoticeCast, PowerCube, PowerHouse, PowerPlay, Scenario and 4Thought are trademarks or registered trademarks of Cognos Incorporated in the United States and/or other countries. All other names are trademarks or registered trademarks of their respective companies. SAP and R/3 are trademarks and registered trademarks of SAP AG. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to either the product or the document will be documented in subsequent editions. U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or disclosure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, or subparagraphs (C) (1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227-19, as applicable. The Contractor is Cognos Corporation, 67 South Bedford Street, Burlington, MA 01803-5164. This software/documentation contains proprietary information of Cognos Incorporated. All rights are reserved. Reverse engineering of this software is prohibited. No part of this software/documentation may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos Incorporated. Cognos, the Cognos logo, Axiant, COGNOSuite, Cognos Upfront, Cognos DecisionStream, Impromptu, NoticeCast, PowerCube, PowerHouse, PowerPlay, Scenario and 4Thought are trademarks or registered trademarks of Cognos Incorporated in the United States and/or other countries. All other names are trademarks or registered trademarks of their respective companies.
Table of Contents Welcome 5 Chapter 1: Introducing DecisionStream Connector for SAP R/3 7 Access to SAP Data 7 Access to SAP Function Modules 7 Joins 8 Temporary Files 8 Easy to Understand Business Names 8 Chapter 2: Table Selector for SAP R/3 9 The Dictionary File 9 Create a Dictionary File 9 Open a Dictionary File 9 Add Tables to a Dictionary File 10 Delete Tables from a Dictionary File 10 View Dictionary File Properties 10 View Table Properties 11 View Column Properties 11 View Index Properties 11 Chapter 3: Writing an SAP Query 13 SAP ABAP Functions 13 SAP Data Types 14 Chapter 4: Samples Overview 15 Overview of the DecisionStream Connector for SAP R/3 Catalog 15 Connections 15 JobStreams 15 Staging Fact Builds 16 Data Integrity Checking 16 Ragged Hierarchies 16 Product_Hierarchy_Src 16 Customer_Hierarchy 17 Index 19
User Guide iii
iv DecisionStream Connector for SAP (R) R/3 ( T M)
Welcome What is in this Document The DecisionStream Connector for SAP R/3 User Guide, describes how to use DecisionStream Connector for SAP R/3.
Other Documentation The DecisionStream Connector for SAP R/3 documentation set includes Topic
Document
How to install DecisionStream Connector for Installation Guide SAP R/3 printed book, online book How to maintain DecisionStream Connector User Guide for SAP R/3 dictionary file tables online book, online help How to use DecisionStream Connector for SAP R/3
User Guide online book
Questions or Comments? For the fastest response to questions about using DecisionStream Connector for SAP R/3, contact customer support. For information about customer support locations and programs, see Cognos on the Web on the Help menu, or visit the Cognos Support Web site (http://support.cognos.com).
User Guide 5
Welcome
6 DecisionStream Connector for SAP (R) R/3 ( T M)
Chapter 1: Introducing DecisionStream Connector for SAP R/3 Cognos DecisionStream Connector for SAP R/3 is an additional software component that you can install into an existing Cognos DecisionStream environment. It extends the data extraction capability of DecisionStream to include SAP R/3 data sources and allows you to access the data in the same way as any other relational database system. Once data has been extracted from SAP R/3 systems, it can be integrated and merged with other data sources from many corporate database systems. It can then be delivered into data marts or data warehouses. The data can be used to build an analytical application where it can be easily used for Cognos Business Intelligence analysis and reporting. You must use Cognos SQL to write SQL statements, as native SQL is not supported. For information, see Cognos SQL. Accessing SAP using Cognos SQL is far more powerful and capable than OpenSQL in SAP R/3. Before a query is executed by DecisionStream, it is analyzed and potentially decomposed into multiple requests so it can execute in SAP. These phases generate one or more requests to SAP that leverage OpenSQL and some ABAP capabilities.
Access to SAP Data Data in the SAP R/3 system can be difficult to access and extract due to the way it is stored. The SAP R/3 system • Uses different types of data storage tables to store data. As a result, some data is stored in tables that cannot be accessed directly. • Uses buffers to store frequently accessed information that is only written to disk when required by SAP R/3. To extract the data, normally a SAP administrator must write a custom ABAP extraction program, that is installed into the SAP environment, for each required extract. DecisionStream Connector for SAP R/3 enables extraction of SAP R/3 data from within the DecisionStream environment, whilst observing all the security roles within the SAP R/3 system. This is achieved by working through the SAP security layer. DecisionStream Connector for SAP R/3 allows the following types of SAP tables to be brought into DecisionStream in the same way as any other database system table: • transparent tables • pooled tables • clustered tables The SAP R/3 data is accessed using a DecisionStream data source component that can be defined using standard SQL style extraction. You do not need to manage the different types of table structures in the SAP R/3 system and the different limitations associated with each table type.
Access to SAP Function Modules Because much of the structure data in SAP R/3 is accessed using function modules, in addition to transparent, pooled and clustered tables, DecisionStream Connector for SAP R/3 allows access to SAP R/3 function modules. This includes the passing of dynamic parameters to function modules to control the range of data to be extracted. DecisionStream Connector for SAP R/3 allows you to use an SQL interface to extract, join, filter and sort data from the SAP data objects whether they are tables or function modules. User Guide 7
Chapter 1: Introducing DecisionStream Connector for SAP R/3
Joins DecisionStream Connector for SAP R/3 leverages the OpenSQL ability to join tables in queries. The format of the SQL join determines how the join is performed. Explicit join syntax should be used instead of implicit join syntax. For more information, see Cognos SQL. The example SQL queries that follow are equivalent in terms of the final result. • select T1.COLA, T2.COLB from T1 inner join T2 on T1.COLX = T2.COLY This example uses explicit joined table syntax. • select T1.COLA, T2.COLB from T1, T2 where T1.COLX=T2.COLY This example uses an implicit join that is expressed using the WHERE clause. DecisionStream Connector for SAP R/3 determines the type of tables used in the explicit join. If the query contains expressions that can be passed to the SAP application server, then the query is passed to SAP. If the query contains expressions that are not supported by SAP, then the query is decomposed into a set of queries that can be used to retrieve the data. Typically, this involves more than one query being passed to SAP and the result computed by DecisionStream. If joins are expressed using explicit SQL, then DecisionStream Connector for SAP R/3 determines automatically how the query should be resolved. To determine how query decomposition is occurring, click the Executed SQL tab in the SQLTerm window, or use the ExecutedSQL logging option. For more information on using the Executed SQL tab, see Execute an SQL Query in the SQLTerm and SQL Helper chapter of the DecisionStream User Guide. For more information on the logging option, see Save Build Execution Information to a Log File in the Executing Builds chapter of the DecisionStream User Guide.
Temporary Files During query execution, temporary data files may be created on the ABAP server. These temporary files are created in the location defined in the SAP profile. File names are created using the following naming convention where is the name of the workstation where the query initiated, is a unique number inside the process, is the process id of the workstation, and can be either TMP, _PAR, or _C . Note: Temporary files are usually purged automatically. However, program failure may result in them remaining. Your SAP administrator may want to purge these files. Before they do so, all DecisionStream processes and requests within SAP must have completed or have been stopped.
Easy to Understand Business Names SAP R/3 uses acronyms to identify underlying database table and column names. DecisionStream Connector for SAP R/3 integrates with the SAP R/3 dictionary by allowing you to set up a connection to SAP in your preferred language. Metadata is then displayed using the full business names from the SAP dictionary, which allows you to navigate all database tables and columns using readable names. These names are then used within the DecisionStream Designer environment, which allows much better productivity and navigation when building SAP data sources in DecisionStream.
8 DecisionStream Connector for SAP (R) R/3 ( T M)
Chapter 2: Table Selector for SAP R/3 Table Selector for SAP R/3 maintains dictionary files which create specialized views of the same SAP R/3 database showing only the tables of interest. A list of these tables is stored in a file that is used to filter the metadata information presented. Use Table Selector for SAP R/3 to add tables and delete tables from the dictionary file.
The Dictionary File The dictionary file filters the metadata information providing many specialized views of the same database. Before Table Selector for SAP R/3 can update a dictionary file, all other applications that use the dictionary file must be closed.
Create a Dictionary File A new dictionary file is required if you want to create a new view of a SAP R/3 database.
Steps 1. From the File menu, click New. The SAP Dictionary Properties dialog box appears. 2. Click the Properties tab. 3. In the Name box, type a name for the dictionary file. 4. If required, in the Description box, type a description for the dictionary file. 5. Click the Connection tab. 6. Select the Save login info check box so that you are not prompted to enter your user ID and password every time you open the dictionary file. 7. Select the Run in background check box to communicate with the SAP server using a batch job. If you do not select this check box, communication with the SAP server is through a dialog process. Dialog processes are subject to a time limit, typically 10 minutes, after which it is stopped by the SAP system. 8. Enter the remaining information required to connect to the database. 9. Click OK. If the connection is not successful, a message appears informing you of this.
Open a Dictionary File Open a dictionary file to view or modify the selected tables.
Steps 1. From the File menu, click Open. The Open dialog box appears. 2. Click the dictionary file to open. 3. Click Open. Table Selector for SAP R/3 automatically connects to the database.
User Guide 9
Chapter 2: Table Selector for SAP R/3
Add Tables to a Dictionary File You can use Table Selector for SAP R/3 to add transparent tables and pool/cluster tables to a dictionary file. You cannot add internal SAP tables because they are not visible.
Steps 1. From the Edit menu, click Add Tables. 2. Specify how the search is to be performed: •
to specify the type of search information, click Table name, or SAP R/3 Short Text
•
to further define the search information, click Matches, Starts with, Contains, or Ends with
3. Type the search information. Note: Wild cards may not be used. 4. If you clicked SAP R/3 short text in step 2, you can specify whether the search should be case sensitive. 5. Choose whether to include views in the search: •
to include views, select the Include views check box
•
to select only the tables, clear the Include views check box
6. Click Search. All the tables in the database that meet your search criteria are listed. 7. Click the tables that you want to add to the dictionary file. Note: You can only add tables that are not already in the dictionary file. 8. Click Add.
Delete Tables from a Dictionary File Steps 1. Click the table to delete. 2. From the Edit menu, click Remove Table. 3. Click Yes to confirm that you want to delete the table. The table and its column and index information is deleted from the dictionary file.
View Dictionary File Properties You can view the details of the dictionary file, which includes information about database connections for the tables in the file.
Steps 1. Click the file for which you want to view properties. 2. From the Edit menu, click Properties. The SAP Dictionary Properties dialog box appears. 3. Click the Properties tab. The name of the file and a description, which you can change here, appears. For saved files, details such as the file path, the date the file was created, and the date the file was last modified appear. 4. Click the Connection tab. 5. Select the Save login info check box so that you are not prompted to enter your user ID and password every time you open the dictionary file.
10 DecisionStream Connector for SAP (R) R/3 ( T M )
Chapter 2: Table Selector for SAP R/3 6. Select the Run in background check box to communicate with the SAP server using a batch job. If you do not select this check box, communication with the SAP server is through a dialog process. Dialog processes are subject to a time limit, typically 10 minutes, after which it is stopped by the SAP system. 7. Change other connection details if you require. 8. Click OK.
View Table Properties Steps 1. Click the table for which you want to view the properties. 2. From the Edit menu, click Properties. The Table Properties dialog box appears. It shows the table name, the type of table, a description of the table, the last user to modify the table, the date it was last modified and the estimated number of records. If a description was not entered, the short text description automatically appears. 3. Click OK.
View Column Properties Steps 1. Click the column for which you want to view the properties. 2. From the Edit menu, click Properties. The Column Properties dialog box appears showing details about the column. If a description was not entered, the short text description automatically appears. 3. Click OK.
View Index Properties Steps 1. Click the index for which you want to view the properties. 2. From the Edit menu, click Properties. The Index Properties dialog box appears showing the index name and description, and the estimated number of records. 3. Click OK.
User Guide 11
Chapter 2: Table Selector for SAP R/3
12 DecisionStream Connector for SAP (R) R/3 ( T M )
Chapter 3: Writing an SAP Query DecisionStream extracts SAP data using SQL statements in the same way as other supported relational database systems. For information on how to use SQLTerm to construct SQL statements in DecisionStream, see the DecisionStream User Guide. The SQL interface in the DecisionStream Connector for SAP R/3 allows many standard SQL operations, for all table and function types, that are not available within the SAP R/3 system. These include • filtering data • performing SQL-based calculations • inner joins • outer joins • sorting • sub queries For information about the SQL interface, see Cognos SQL. Additional SQL statements are provided to access function modules. Examples of these statements follow in the remainder of this chapter.
SAP ABAP Functions You can use the SELECT statement to query a table returned by an ABAP or BAPI function. You can further filter and manipulate the returned table using the WHERE, GROUP, HAVING, and ORDER BY clauses. The ABAP function is referenced in the FROM clause using a CALL option that can include any required input parameters expressed as literals (strings, numerics, date, and time). Only the first table returned by the ABAP function is returned by the SELECT statement. Output parameters or status values are discarded.
Syntax ::= CALL [ ( ) ] ::= [ [ { , }...] ::= =
User Guide 13
Chapter 3: Writing an SAP Query
Examples •
SELECT T1.SALARY FROM CALL Employee_Info(name='SMITH',age=40) T1
This example reports the salary column returned by the Employee_Info function based on the input values SMITH and 40. •
SELECT T1.SALARY, T1.START_DT, T1.FULLNAME FROM CALL Employee_Info(name='SMITH' ,age=40) T1 WHERE SALARY < 10000 AND START_DT > DATE '2000-12-31' ORDER BY T1.START_DT
This example reports an ordered set of columns returned by the Employee_Info function based on the input values SMITH and 40. It has additional filtering based on the SALARY and START_DT fields in the returned table. •
SELECT * FROM CALL Employee_Info(name='SMITH' ,age=40, startdt= DATE '1999-09-01') T1
This example reports a set of columns returned by the Employee_Info function based on the input values SMITH,40 and 1999-09-01.
SAP Data Types DecisionStream supports these SAP data types. DecisionStream
SAP
CHAR
ACCP CHAR CLNT CUKY LANG LCHR LRAW NUMC PREC RAW UNIT
NUMBER
CURR DEC QUAN
DATE
DATS
DOUBLE
FLTP
INTEGER
INT1 INT2 INT4
14 DecisionStream Connector for SAP (R) R/3 ( T M )
Chapter 4: Samples Overview DecisionStream Connector for SAP R/3 CD contains a sample catalog for the SAP SD and F1 modules. The sample catalog is named SAPConnector and contains fact builds and dimension builds demonstrating techniques and practices that can be employed when developing DecisionStream catalogs for use with SAP R/3. The sample catalog is not a solution to a complete application, but is an example that can be used for moving forward the development of your application. The builds in the catalog are designed for simplicity and are complete loads of data. Before using the SAP Samples catalog, you must have DecisionStream Designer, the DecisionStream engine, DecisionStream Connector for SAP R/3, and the sample data installed on your computer. The SAP samples are automatically installed during a typical installation of DecisionStream Connector for SAP R/3. If you do not have one or more of these components, install DecisionStream for Windows using the Typical install option, or install the required components from the Custom install option. Install DecisionStream Connector for SAP R/3 using the Typical install option, or install the required components from the Custom install option. The DecisionStream Connector for SAP R/3 samples consist of • ds_sap_catalog which is a Microsoft Access MDB containing the sample catalog • ds_sap_target which is a Microsoft Access MDB for the target mart • sap_dictionary.dbm which is a dictionary file By default, the samples can be found in C:\Program Files\Cognos\cer2\samples\SAPConnector.
Overview of the DecisionStream Connector for SAP R/3 Catalog The ds_sap_catalog contains examples for the extraction, transformation, and delivery to a mart for the FI and SD modules.
Connections The catalog contains two connections named Source and Target. The Source connection must be configured to your SAP location. The "The Dictionary File" (p. 9) must also be specified (sap_dictionary.dbm). The Target connection is to the ds_sap_mart Access database which has been provided as part of the installed samples.
JobStreams The JobStream named Complete_Job has four JobStream nodes named Step1_Dimensions, Step2_Dimensions, FI_Fact_Build, and SD_Fact_Builds. They are executed in a specified order to ensure that staging data is processed and dimensions are built before the fact builds are processed as these are dependent on the dimensions. The JobStream nodes named Step1_Dimensions and Step2_Dimensions contain all the staging fact builds and dimension builds that are required for the FI_Fact_Build and SD_Fact_Builds JobStream nodes. The JobStream node named FI_Fact_build contains the fact build FI_Fact_GL_Balance, and the JobStream node named SD_Fact_Build contains the fact builds named SD_Fact_Sales_Order and SD_Fact_Sales_Statistics. Note: Care should be taken executing this JobStream, as it loads the complete data structure.
User Guide 15
Chapter 4: Samples Overview
Staging Fact Builds You use staging fact builds for dimensions that require data from disparate data sources to be unified before building the dimension hierarchy. Lookups are used to include descriptions of attributes that are not accessible from the same data tables as their IDs. This reduces the number of joins required in the SQL and improves performance by allowing DecisionStream to perform the joins in memory. For example, the fact build Stg_account_1 creates the staging table STG_ACCOUNT_1 that is used in the Account hierarchy and Dim_account dimension build.
Data Integrity Checking Lookups that use templates to access the dimension tables in the target data mart are used so that DecisionStream can integrity check the data as fact builds are executed. For example, FI_Fact_GL_Balance contains a lookup named Account_Dim_Lup.
Ragged Hierarchies The sample catalog includes two ragged hierarchies. One named Product_Hierachy_Src in the Product dimension and one named Customer_Hierarchy in the Customer dimension.
Product_Hierarchy_Src In this hierarchy, the levels and parent-child relationships are known. Each member belongs to only one level, so an auto-level hierarchy is not required. The hierarchy has three levels named Main Group, Group, and Sub Group, and each member belongs to only one of these levels. It is possible however, that a member may only have data for Main Group and Group, or just Main Group, but still be a valid member that corresponds to the fact data. It is this aspect that makes this a ragged hierarchy. Main Group
ID
Group
ID
Sub Group
ID
Vehicles
560
Cars
345
Car
857
Paints
234
Solvents
456
Leasing
279
The sample catalog has • An attribute named Product_Hierarchy_Id at the lowest level, to which an attribute from any level can be mapped, providing it is the lowest level attribute. • A hierarchy named Product_Hierarchy_Src to retrieve data and define the parent-child relationships. • A dimension build named Dim_Product_Hierarchy that uses the parent-child relationships to load the data into the dimension table in three passes. The first pass loads all the products that have a member for each level, the second loads products with members for only the Main Group and Group levels, and the third loads products with members for only the Main Group level. • A table that has a populated lowest level that can be used to attach to fact data for reporting purposes and accurate rollup. Main Group ID Vehicles
Group
560 Cars
ID
Sub Group ID
345
Car
16 DecisionStream Connector for SAP (R) R/3 ( T M )
Prod_Hier_Id
857 857
Chapter 4: Samples Overview
Main Group ID
Group
ID
Sub Group ID
Prod_Hier_Id
Paints
234 Solvents 456
456
Leasing
279
279
Customer_Hierarchy Except for the first staging of the data, the Customer dimension is a typical example of a ragged hierarchy. The sample catalog has • A fact build named Stg_Customer_1 to retrieve all the customer hierarchy members and their attributes. It uses lookups to include the descriptions for some attributes. The concatenated fields that are required to construct the parent-child relationships are made in this fact build. • Concatenated key fields named parent_customer_key and customer_key. These are used to create an auto-level hierarchy named CustomerA in the Customer dimension. This hierarchy is used by the dimension build named Stg_Customer_2 to populate a table that includes the parent and level of each customer in the hierarchy as well as the attributes of each customer. The remainder of the ragged hierarchy is built using this table as a source. • A hierarchy named Customer_Hierarchy that has as many levels as there are in the Stg_Customer2 table. For each level, the data source queries data for that specific level from the Stg_Customer2 table and maps the ID, parent, and caption attributes appropriately. • A template named Cust_Levels to represent a flattened view of the hierarchy. That is, it contains an ID and caption for each level and an ID and caption for the lowest level plus the attributes. • A dimension build named Dim_Customer_Hierarchy which was created manually, that is, without using the Dimension Build wizard. It has a table named D_Customer_Hierarchy for each level in the Customer_Hierarchy. The level attributes in each dimension table are mapped to the Cust_Levels template so that each level is defined once as the lowest level. The Exclude Partially Populated Rows check box in the Dimension Table Properties window must be selected to ensure that rows are not delivered for higher level members that have no children. For example, assuming there are seven levels • Table 1 The dataset items of all the levels are mapped. Level 7 columns are mapped to the lowest level, and the dataset items of level 7 are mapped to the attributes. • Table 2 The dataset items of first six levels are mapped. Level 6 is mapped to lowest level, and the dataset items of level 6 are mapped to the attributes. • Tables 3 to 6 The dataset items of the first n levels are mapped. Level n is mapped to the lowest level, and the dataset items of level n are mapped to the attributes. • Table 7 The dataset items of the first level are mapped to the lowest level, and the dataset items of level 1 are mapped to the attributes. This results in a table with columns for each level, and columns for the lowest level that are always populated and can be used to join to the fact data.
User Guide 17
Chapter 4: Samples Overview
18 DecisionStream Connector for SAP (R) R/3 ( T M )
Index A
O
ABAP functions, 13 accessing SAP data, 7 SAP function modules, 7 acronymns, 8 adding tables to dictionary files, 10
opening dictionary files, 9
B
Q
business names, 8
queries writing, 13
C catalogs, 15 connections, 15 fact builds, 16 JobStreams, 15 clustered tables, 7 columns viewing properties, 11 connections, 15 copyright, ii creating dictionary files, 9
P pooled tables, 7 preferred language, 8
R ragged hierarchies, 16 running in background, 9
S
data integrity checking, 16 data types SAP, 14 dictionary files, 9 adding tables, 10 creating, 9 deleting tables, 10 opening, 9 viewing, 10
samples, 15 catalog, 15 connections, 15 data integrity checking, 16 fact builds, 16 JobStreams, 15 ragged hierarchies, 16 SAP ABAP functions, 13 data types, 14 SAP data accessing, 7 SAP queries writing, 13 security layer, 7 staging fact builds, 16
F
T
fact builds, 16 files dictionary, 9 function modules, 7
Table Selector for SAP R/3, 9 table types, 7 tables adding to dictionary files, 10 deleting from dictionary file, 10 deleting from dictionary files, 10 viewing properties, 11 temporary files, 8 transparent tables, 7
D
I index properties viewing, 11 integrity checking, 16
J JobStreams, 15 joins, 8
M
V viewing column properties, 11 database connections, 10 dictionary files, 10 index properties, 11 table properties, 11
modifying tables, 9
User Guide 19
W writing SAP queries, 13
User Guide 20
