You are on page 1of 16

Web Service Tool UIU Contribution Interfaces

SAP CRM 7.0


Target Audience System administrators Technology consultants

Document version: 2.0 - December 2008

SAP AG Dietmar-Hopp-Allee 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.com

Copyright 2007 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. SAP Library document classification: PUBLIC 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. Any Java Source Code delivered with this product is only to be used by SAPs Support Services and may not be modified or altered in any way. Documentation in the SAP Service Marketplace You can find this documentation at the following address:
http://service.sap.com/

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

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.

Terms for Included Open Source Software


This SAP software contains also the third party open source software products listed below. Please note that for these third party products the following special terms and conditions shall apply. 1. This software was developed using ANTLR. 2. gSOAP Part of the software embedded in this product is gSOAP software. Portions created by gSOAP are Copyright (C) 2001-2004 Robert A. van Engelen, Genivia inc. All Rights Reserved. THE SOFTWARE IN THIS PRODUCT WAS IN PART PROVIDED BY GENIVIA INC AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3. SAP License Agreement for STLport SAP License Agreement for STLPort between SAP Aktiengesellschaft Systems, Applications, Products in Data Processing Neurottstrasse 16 69190 Walldorf, Germany (hereinafter: SAP) and you

(hereinafter: Customer) a) Subject Matter of the Agreement A) SAP grants Customer a non-exclusive, non-transferrable, royalty-free license to use the STLport.org C++ library (STLport) and its documentation without fee. B) By downloading, using, or copying STLport or any portion thereof Customer agrees to abide by the intellectual property laws, and to all of the terms and conditions of this Agreement. C) The Customer may distribute binaries compiled with STLport (whether original or modified) without any royalties or restrictions. D) Customer shall maintain the following copyright and permissions notices on STLport sources and its documentation unchanged: Copyright 2001 SAP AG E) The Customer may distribute original or modified STLport sources, provided that: o The conditions indicated in the above permissions notice are met; o The following copyright notices are retained when present, and conditions provided in accompanying permission notices are met: Copyright 1994 Hewlett-Packard Company Copyright 1996,97 Silicon Graphics Computer Systems Inc. Copyright 1997 Moscow Center for SPARC Technology. Copyright 1999,2000 Boris Fomitchev Copyright 2001 SAP AG Permission to use, copy, modify, distribute and sell this software and its documentation for any purposes is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Hewlett-Packard Company makes no representations about the suitability of this software for any purpose. It is provided as is without express or implied warranty.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Silicon Graphics makes no representations about the suitability of this software for any purpose. It is provided as is without express or implied warranty. Permission to use, copy, modify, distribute and sell this software and its documentation for any purposes is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Moscow Center for SPARC makes no representations about the suitability of this software for any purpose. It is provided as is without express or implied warranty. Boris Fomitchev makes no representations about the suitability of this software for any purpose. This material is provided "as is", with absolutely no warranty expressed or implied. Any use is at your own risk. Permission to use or copy this software for any purpose is hereby granted without fee, provided the above notices are retained on all copies. Permission to modify the code and to distribute modified code is granted, provided the above notices are retained, and a notice that the code was modified is included with the above copyright notice. Permission to use, copy, modify, distribute and sell this software and its documentation for any purposes is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. SAP makes no representations about the suitability of this software for any purpose. It is provided with a

limited warranty and liability as set forth in the License Agreement distributed with this copy. SAP offers this liability and warranty obligations only towards its customers and only referring to its modifications. b) Support and Maintenance SAP does not provide software maintenance for the STLport. Software maintenance of the STLport therefore shall be not included. All other services shall be charged according to the rates for services quoted in the SAP List of Prices and Conditions and shall be subject to a separate contract. c) Exclusion of warranty As the STLport is transferred to the Customer on a loan basis and free of charge, SAP cannot guarantee that the STLport is error-free, without material defects or suitable for a specific application under third-party rights. Technical data, sales brochures, advertising text and quality descriptions produced by SAP do not indicate any assurance of particular attributes. d) Limited Liability A) Irrespective of the legal reasons, SAP shall only be liable for damage, including unauthorized operation, if this (i) can be compensated under the Product Liability Act or (ii) if caused due to gross negligence or intent by SAP or (iii) if based on the failure of a guaranteed attribute. B) If SAP is liable for gross negligence or intent caused by employees who are neither agents or managerial employees of SAP, the total liability for such damage and a maximum limit on the scope of any such damage shall depend on the extent to which its occurrence ought to have anticipated by SAP when concluding the contract, due to the circumstances known to it at that point in time representing a typical transfer of the software. C) In the case of Art. 4.2 above, SAP shall not be liable for indirect damage, consequential damage caused by a defect or lost profit.

D) SAP and the Customer agree that the typical foreseeable extent of damage shall under no circumstances exceed EUR 5,000. E) The Customer shall take adequate measures for the protection of data and programs, in particular by making backup copies at the minimum intervals recommended by SAP. SAP shall not be liable for the loss of data and its recovery, notwithstanding the other limitations of the present Art. 4 if this loss could have been avoided by observing this obligation.

F) The exclusion or the limitation of claims in accordance with the present Art. 4 includes claims against employees or agents of SAP. 4. Adobe Document Services Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and / or other countries. For information on Third Party software delivered with Adobe document services and Adobe LiveCycle Designer, see SAP Note 854621.

Typographic Conventions
Type Style Example Text Description 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 Technical names of system objects. These include report names, program names, transaction codes, table names, and key concepts of a programming language when they are surrounded by body text, for example, SELECT and INCLUDE. Output on the screen. This includes file and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system. Keys on the keyboard, for example, F2 or ENTER.

Icons
Icon Meaning Caution Example Note Recommendation Syntax

EXAMPLE TEXT

Additional icons are used in SAP Library documentation to help you identify different types of information at a glance. For more information, see Help on Help General Information Classes and Information Classes for Business Information Warehouse on the first page of any version of SAP Library.

Example text

Example text

<Example text>

EXAMPLE TEXT

Contents
1 Procedure ............................................................................................8
1.1 Customize Web Service Tool ................................................................ 8 1.2 Provide Logical Key and Technical Key............................................... 9
1.2.1 Logical Key .............................................................................................................. 9 1.2.2 Technical Key........................................................................................................... 9

1.3 Customize the GenIL Model ................................................................ 10


1.3.1 Objects................................................................................................................... 10 1.3.2 Relationships.......................................................................................................... 11 1.3.3 Relationship Names ............................................................................................... 11

1.4 Implement Interface: IF_GENIL_WEBSERVICE_SUPPORT .............. 11

2 Time and Date Conversion in the Web Service..............................14 3 ISO Conversion .................................................................................15 4 Sample Implementation....................................................................16
4.1 Testing the Generated Web Service ................................................... 16

<December 2008>

1 Procedure

1 Procedure
To enable objects for Web service, complete the steps outlined in the following sections.

1.1 Customize Web Service Tool


To enable BOL objects in the Web service tool, you must add the BOL objects to the Web service tool Customizing. To do so, make the following entries in the CRMD_WS_METHODS table using the CRMV_WS_METHODS customizing view (transaction SM30): BOL object name and object kind, as defined in the generic interaction layer (genIL) model GenIL component name Root and access objects Ensure that you fill in the logical key structure (it must be a structure). Update Create, Read, Query, and Change to True according to the operations that are included as part of Web service generation for each object. If you are allowed to create, but not change, your root object, set the WS_CREATE flag to true and the WS_CHANGE flag to false for that root object. If you are allowed to create and change a dependent object, set the WS_CREATE and WS_CHANGE flags to true for that dependent object. This results in a change service that changes the root object and creates, changes, or deletes a dependent object. MODIFY_REQUIRED If the child objects of an object can only be processed in a change and create Web service, and genIL MODIFY was executed for the parent, set the flag MODIFY_REQUIRED for the object. This means that during the processing of a change or create Web service, the MODIFY_REQUIRED flag saves the object before child objects are processed. This is required for applications where all of the objects cannot be processed at the same time (one genIL MODIFY at the end). READ_PARENT_OBJ If an object requires information from the parent object for the processing of CHANGE or CREATE, set the flag READ_PARENT_OBJ for the object. Example: CRMD_WS_METHODS Table External Object Name Component Name Object Kind Structure Name Create Read Query Change AdvOrderQuery SAMP_N G N/A False False True False Order SAMP_N A CRMT_GENIL_ORDER_LOGIC AL_KEY True True False True

<December 2008>

1 Procedure

Text Note

Advanced (Dynamic) Search of Orders

Order

For query objects, the entry in CRMD_WS_METHODS is optional. The entry is only needed for the query description that is used on the UI of the Web service tool.

1.2 Provide Logical Key and Technical Key


1.2.1 Logical Key
For root and access objects, you must provide a logical key in CRMD_WS_METHODS. A logical key can be referred to as a semantic key. It is a meaningful object used to represent a more technical object. The user can understand the logical key more easily than the technical key. The following are examples of technical keys and their corresponding logical keys: A product is identified technically by a GUID and semantically the key consists of four possible fields A business partner is identified technically by a GUID and semantically the key is the partner number A business transaction is identified technically by a GUID and semantically the key is the transaction number and transaction type You can map an object ID to a logical key by doing the following: 1. Map an object ID to a technical key (for example, a business partner GUID) using the CL_CRM_GENIL_CONTAINER_TOOLS class and the GET_KEY_FROM_OBJECT_ID method. 2. Map the technical key to a logical key (for example, a business partner number). You can map a logical key to an object ID by doing the following: 1. Map a logical key (for example, business partner number) to a technical key (for example, a business partner GUID). 2. Map the technical key to an object ID using the CL_CRM_GENIL_CONTAINER_TOOLS class and the BUILD_OBJECT_ID method.

1.2.2 Technical Key


You must maintain the key structure field in the genIL model of your genIL component for every root object, access object, and dependent object. The key should be the same as the one used in the application coding. The following are possible cases when the key structure is a structure: Key structure is fully available in attribute structure The key structure is only generated into the Web service once (in the attribute structure). Key structure is partially available in attribute structure The parts of the key structure that are not available in the attribute structure are generated into the Web service separately.

<December 2008>

1 Procedure

Key structure is not available in attribute structure (disjunct) The full key structure is generated into the Web service structure separate from the attribute structure. For the key structure, the following rules apply: If fields in the attribute structure and key structure are semantically identical but have different names, the same semantic key is generated into the Web service twice. If the key structure has the type structure inside of it, this must be resolved before the comparison of attribute structure and key structure. If the key structure is a data element and not a structure, it can be difficult to determine which should be the corresponding field from the attribute structure or which name should be generated into the Web service structure for a generic application. If the key structure has only one field, the Web service tool uses the field as the key structure. The following are possible cases where the key structure is a data element: Name of data element is not available in attribute structure as Type No additional field is generated in the Web service structure. The application must provide a key structure that contains the correct keys. Name of data element is available only once in attribute structure as Type The key structure is generated in the Web service structure only once. No additional field is generated for the key data element. If this is not appropriate for the application, it must provide a key structure that contains the correct keys. Name of data element is available more than once in attribute structure as Type No additional field is generated in the Web service structure. The application must provide a key structure that contains the correct keys.

1.3 Customize the GenIL Model


The following sections show you how to update the methods IF_GENIL_APPL_MODEL~GET_MODEL and IF_GENIL_APPL_MODEL~GET_OBJECT_PROPS of your component.

1.3.1 Objects
1. Update the following properties of the CRMT_OBJECT_PROPERTIES internal table for all objects that support web service operations. Example: CRMC_OBJ_BTIL Component WS_ENABLED Component Type CRMT_GENIL_BOOLEAN Description Object enabled for Web Service

While the Business Object Layer (BOL) and GenIL handle queries dynamically, a service generated by the Web Service Tool must define a specific interface for each query. Therefore you need to know the input and output of a query in advance (for example, at the time of design or generation).

10

<December 2008>

1 Procedure

The CRMT_OBJ_PROPERTIES structure is expanded by one additional component containing the BOL object type of the query result. This field should be filled in for BOL objects of the Search Object (D) type, and Dynamic Search Object (G) type if the query result is not a list of mixed object types. Only query objects supplying this information may be used for Web service generation by the Web service tool. No other queries are service-enabled. 2. Update the following properties of the CRMT_OBJECT_PROPERTIES internal table for all query objects that support web service operations. Example: IF_GENIL_APPL_MODEL~GET_OBJECT_PROPS: BTQ1Order BTQR1Order Component RESULT_OBJ_NAME Component Type CRMT_EXT_OBJ_NAME Description This field should be filled for BOL objects of types Search Object (D) and Dynamic Search Object (G) if the query result is not a list of mixed object types.

1.3.2 Relationships
Update the following properties of line type CRMT_RELATION_DETAIL of CRMT_RELATION_DETAIL_TAB internal table for all object relationships that support Web service operations: Component NOT_WS_ENABLED Example: BuilAddressRel Object A Relationship Name Object B Component Name Relationship Name BuilHeader BuilAddressRel BuilAddress BP Addresses Component Type CRMT_GENIL_BOOLEAN Description Relationship not enabled for Web service

1.3.3 Relationship Names


Make entries in the CRMD_WS_OBJ_REL table using the CRMV_WS_OBJ_REL Customizing view (transaction SM30). Enter object A, relationship name, and object B as in the model table CRMT_RELATION_DETAIL. Enter the component name and a speaking name in the relationship description.

1.4 Implement Interface: IF_GENIL_WEBSERVICE_SUPPORT


The implementation class of the component must implement this interface to support Web service. This means that any class that implements IF_GENIL_APPL_INTLAY and IF_GENIL_APPL_MODEL must implement the IF_GENIL_WEBSERVICE_SUPPORT interface. To do this, you must use the following:

<December 2008>

11

1 Procedure

GET_OBJECT_ID_FROM_LOGICAL_KEY This returns the object ID from the logical key. The data types used for building the Object ID when implementing GET_OBJECT_ID_FROM_LOGICAL_KEY must match those used for BOL implementation. This means that data types of importing and returning parameters of BUILD_OBJECT_ID must be identical in the Web service and the existing BOL implementation. Data formatting (for example, to truncate or add leading zeros) before calling BUILD_OBJECT_ID must be identical in the Web service and the existing BOL implementation. Example: CL_CRM_BTIL Parameter IS_LOGICAL_KEY OBJECT_NAME RV_RESULT Type Importing Importing Returning Pass Value N/A N/A Yes Type Method Type Type Type Type ANY CRMT_EXT_OBJ_NAME CRMT_GENIL_OBJECT _ID

For more information, see Logical Key. GET_LOGICAL_KEY_FROM_OBJECT_ID This returns the logical key from the object ID. Example: CL_CRM_BTIL Parameter IV_OBJECT_ID OBJECT_NAME ES_LOGICAL_KEY Type Importing Importing Exporting Pass Value N/A N/A Yes Type Method Type Type Type Type CRMT_GENIL_OBJECT_ ID CRMT_EXT_OBJ_NAME ANY

For more information, see Logical Key. GET_MAP_CREATE_STRUCTURE This returns mapping for create structure attributes. Parameter OBJECT_NAME ET_CREATE_MAP Type Importing Exporting Type Method Type Type Type CRMT_EXT_OBJ_NAME CRMT_WS_CREATE_MAP

If the BOL root object meets the following conditions, implementation is not required: Fields in create structures have the same field names as in the root object and are present in the root object (for example, BuilHeader) Fields in create structures are part of the logical key structure and have the same names, or when they are part of the root object and have the same names as in the root object

12

<December 2008>

1 Procedure

A unique identification of a dependent object from a collection of instances is not possible, so all the fields from the create structure are created as part of the root object structure (may result in duplicate attributes with different names) Example WebService inbound (creation of Product A): Product: Product_ID= A

|-->ProductCategory: Category_ID = 1 |-->ProductCategory: Category_ID = 2 |-->ProductCategory: Category_ID = 3 The create structure has the field RootCat_ID, but during interface implementation it cannot be determined which category (1, 2 or 3) should be mapped into the RootCat_ID. We recommend that you use the following methods from CL_CRM_GENIL_CONTAINER_TOOLS to implement the above APIs: BUILD_OBJECT_ID GET_KEY_FROM_OBJECT_ID

<December 2008>

13

2 Time and Date Conversion in the Web Service

2 Time and Date Conversion in the Web Service


Inbound XML Field ISO Timestamp containing time zone ISO Timestamp without time zone Backend Fields Fill the fields using the time zone from the ISO time stamp Assume the time zone in XML is UTC and fill the fields accordingly Backend TIMEZONE Field (if present) Not filled

Fill with UTC

Outbound XML Field Create ISO time stamp with users local time zone Backend Fields Assume it is users local time zone Backend TIMEZONE Field (if present) Always ignored

14

<December 2008>

3 ISO Conversion

3 ISO Conversion
The following ISO conversions are used: Domain All fields with RAW16 data types (as well as all fields with SYSUUID_C, SYSUUID_X, and SYSUUID domains) are converted to char36 (CSEQUENCE) at design time. LAND1 Conversion cl_gdt_conversion=>guid_outbound/inbound

cl_gdt_conversion=>country_code_outbound/inbound

SPRAS

cl_gdt_conversion=>language_code_outbound/inbound

WAERS_CURC

cl_gdt_conversion=>currency_code_outbound/inbound

MSEHI

cl_gdt_conversion=>unit_code_outbound/inbound

FLAG, RM_BOOLEAN, BOOLEAN, XFELD, or COM_BOOLEAN SYDATS, TZNTSTMPL, TZNTSTMPS, or SYTIME

cl_gdt_conversion=>indicator_outbound/inbound

cl_gdt_conversion=>date_time_outbound/inbound

<December 2008>

15

4 Sample Implementation

4 Sample Implementation
The BOL component SAMP_N from component set SAMPLE_NEW is an example of a Web service-enabled component and is only used for illustrative purposes. The CRMD_WS_METHODS Customizing table contains information about the SAMP_N objects that are Web service-enabled. In the CRMT_OBJECT_PROPERTIES internal table, which is returned by the method IF_GENIL_APPL_MODEL~GET_OBJECT_PROPS, class CL_CRM_GENIL_SAMPLE_COMP_NEW, some of the BOL objects are marked as Web service-enabled (attribute WS_ENABLED=ABAP_TRUE) and the result object name is provided for query objects (attribute RESULT_OBJ_NAME). The central class CL_CRM_GENIL_SAMPLE_COMP_NEW implements the interface IF_GENIL_WEBSERVICE_SUPPORT. Two methods of that interface have a nonempty implementation: GET_OBJECT_ID_FROM_LOGICAL_KEY and GET_LOGICAL_KEY_FROM_OBJECT_ID.

4.1 Testing the Generated Web Service


The Web service can be tested using transaction WSADMIN or SOAMANAGER. The generated function modules can be tested using transaction SE37 (or by a call in a report). A client proxy can be generated and used for testing (test functionality in SE80). To generate a client proxy, start transaction SE80 and do the following: 1. Choose Create Enterprise Service / Web Service Proxy Object.

2. Select URL / HTTP Destination and enter the WSDL of the generated Web service. 3. Enter the package where the client proxy should be created and a prefix (optional). The package $tmp is recommended for local tests. 4. Save and activate the proxy. Ignore warnings that appear for naming conventions. You can now use the test button in SE80. Note The client proxy can also be called in a report. You can select the proxy in the navigation tree of SE80 and drop it into the report. The coding is then generated automatically.

16

<December 2008>

You might also like