Duet Enterprise Feature Pack 1 Developer Guide Consuming OData Services via BDC Browser

Transcription

1 Duet Enterprise Feature Pack 1 Developer Guide Consuming OData Services via BDC Browser Applies to: Duet Enterprise FP1 SP03, Consuming OData Service via BDC Browser in SharePoint2010 Summary This paper explains how Duet Enterprise FP1 SP03 can be used to consume OData Service created with SAP Netweaver Gateway. BDC Browser s capabilities have been enhanced to include OData service as one of the data sources. The tool provides no-code approach to get SharePoint2010 BDC models. Author: Advay Borkar and Alexander Puettner Company: SAP Created on: 14 September 2012 Author Bio Advay is working in Duet Enterprise Product Devleopment team in SAP Labs India. Alexander is part of Duet Enterprise Solution Management team in SAP Labs Toronto SAP AG 1

2 Table of Contents Overview Pre-requisite BDC Browser Service Settings Service Implementation Workbench Settings OData Service Import EDMX File MPC Class changes DPC Class changes Register OData Service with Gateway system Test OData Service from Gateway System Creating BDC model from OData Service Creating BDC models and SOAP services Testing - Generated SOAP Service Deploying BDC model on SharePoint Exporting BDC Models from SAP System Importing BDC Models in SharePoint Creating External List Custom UI in SharePoint Maintaining Entity to Entity Relationship (Custom Coding in ABAP and SharePoint) Troubleshooting and Best Practices OData Service BDC Browser Configurations Issues Copyright SAP AG 2

3 Overview OData Services SAP Netweaver Gateway is provisioning access to SAP data via OData services, which is a standard way of accessing SAP data for future use. BDC Browser s capability is enhanced to use OData Services as the data source to create BDC models. The generated BDC models will be exactly similar to the ones which were generated with GW data models. To make use of this new feature following are the starting points Pre-requisite BDC Browser Service Settings Service Implementation Workbench Settings OData Service Creating BDC models out of OData Services using BDC Browser Deploying BDC models Custom UI in SharePoint Enabling entity to Entity Relationship Troubleshooting and Best Practice Use Case: EPM Sales Order entity is used to showcase the CRUDQ functionality. EPM Sales Order is a pre-delivered Sales Order business Object. The functionality includes Query list of Sales Order Headers View details of a Sales Order Header Update of Sales Order Header Delete Sales Order Query list of Sales Order Items for a Sales Order Header View details of Sales Order Item Create a Sales Order Header Along with Sales Order Items 1. Pre-requisite These are certain pre-requisite which must be followed. Software Pre-requisites SAP NetWeaver Gateway SP05 IW TNG SP03 Configuration Pre-requisite for Service Builder Tool Install IW_BEP component (part of GW SP05)in the SAP backend system Provide required authorization to user running the Service Builder tool Configurations Pre-requisites for BDC Browser tool ESR Configuration should be done BDC Browser -> Service settings should be updated (as explained in chapter 2) Service Implementation workbench settings (as explained in chapter 3) 2011 SAP AG 3

4 2. BDC Browser Service Settings BDC Browser now supports creation of SOAP service and BDC models from Gateway Data Model (Generic channel approach) OData Service (OData Approach) In order to support both data sources, 2 different configurations have to be maintained in BDC browser Service settings. Above figure indicates 2 separate service settings used in BDC browser and only one is marked as Active. For each Service setting corresponding SIW configuration has to be defined. SIW configuration explained in chapter 3. If you have previously worked with BDC browser, then same service settings can be copied for OData related settings. (Service settings can be viewed from /IWTNG/BDC_BROWSER transaction). Note: Service settings should be maintained using the BDC browser configuration guide. ESR configuration steps include creation of software component, namespace and generic global data types. Follow the steps provided in how-to- guide (from page 3 to 20) to complete the configuration until the service settings SAP AG 4

5 3. Service Implementation Workbench Settings The active configuration ID (SAP_GW_ODC_CONFIG) is referred in Service Implementation Wrokbench IMG. (Go to transaction SIMGH and open IMG structure Service Implementation Wrokbench -> Define Configuration). Check the entry corresponding to active configuration ID. Make sure Config Class entry is maintained to /IWFND/CL_MGW_SB_SIW_CONFIG. For the GW data model approach this entry should be /IWFND/CL_DST_SIW_FLAT_CONFIG Following screenshot shows Config Class for each Configuration ID. 4. OData Service OData Service can be created via Service Builder tool (installed via IW_BEP component in backend system). Use the attached EDMX file to import it into service builder tool. Follow the steps to create and configure OData Service. 4.1 Import EDMX File Download the attached Data Model file (EPM_SO.xml) to local system. Login to backend system, make sure that backend system has IW_BEP component installed (part of GW SP05). Login to backend system Go to transaction SEGW Click on New Project 2011 SAP AG 5

6 Provide a name and description for the project. Save it as a local object. A new empty project will be created. Right Click on the data model and Click on Import and choose Data model This step asks for location of the Data model file (EPM_SO.xml). Use the file browser to locate the downloaded EDMX file in your system. Once you choose the file and click on OK, the data model will be imported in Service Builder tool SAP AG 6

7 The imported data model now contains 2 Entities, SOHeader and SOItem. An Association is provided between SOHeader and SOItem. Expand nodes SOHeader and SOItem to navigate to various properties. 4.2 MPC Class changes As soon as the changes are saved, click on Generate Runtime Objects button, on the top menu. This action will generate the runtime artifacts for OData Service SAP AG 7

8 A dialog box will pop up with pre-defined class names and service names. Click on OK. Add these objects in local objects. After generation, you should find the following objects getting added to your project, under Runtime Artifacts node SAP AG 8

9 The ZCL_SALESORDER_MPC class has the generated definition of the OData Service. The additional code has to be written in ZCL_SALESORDER_MPC_EXT class. Right click on ZCL_SALESORDER_MPC_EXT and select on Workbench option. This will open the class ZCL_SALESORDER_MPC_EXT in ABAP Workbench. Select Source code Based option and then click on Edit button. DELETE entire existing code. Copy entire code from ZCL_SALESORDER_MPC_EXT.txt and paste here. Click on Save. Check for any errors, you should not get any errors. Click on the Form Based button on top menu. Save and Activate the class. Define method should already have the code now, activate your changes. Even though following properties are maintained in Service builder tool, they are again explicitly marked. Explicitly marking entities SOHeader and SOItem as creatable, updatable and deletable. SALESORDERID and CustomerID are marked as Filterable properties in the SOHeader. SALESORDERID is marked as filterable property for SOItem SAP AG 9

10 The Define method should look like this 4.3 DPC Class changes The generator will also generate DPC (Data Provider class). The data provider class will provide methods to perform CRUDQ calls for each Entity. We need to add code to call BAPIs to from corresponding method of DPC class. In the generated artifact, look for class ZCL_SALESORDER_DPC_EXT, right click on select Workbench option. This action will open class ZCL_SALESORDER_DPC_EXT in ABAP workbench. Once you are in class window, go to Source Code-Based option and click on Edit button. Delete any existing code in the source code based view. Copy entire code (CTRL+A) from ZCL_SALESORDER_DPC_EXT.txt and paste it SAP AG 10

11 Save your changes. Go back to Form Based view and observer the some of the methods are redefined. Now activate your changes. A number of inactive objects exist this time. Activate them all. Make sure that activation is successful 2011 SAP AG 11

12 A number of methods should now be redefined in your data provider class. From the Methods tab, you can see the list of redefined methods. Their names should appear in black color (opposed to the blue non-redefined methods). Here the complete list of redefined methods: SOHEADERS_CREATE_ENTITY SOHEADERS_DELETE_ENTITY SOHEADERS_GET_ENTITY SOHEADERS_GET_ENTITYSET SOHEADERS_UPDATE_ENTITY SOITEMS_GET_ENTITY SOITEMS_GET_ENTITYSET /IWBEP/IF_MGW_APPL_SRV_RUNTIME~CREATE_DEEP_ENTITY 2011 SAP AG 12

13 4.4 Register OData Service with Gateway system After updating ZCL_ZSALESORDER_MPC_EXT and ZCL_ZSALESORDER_DPC_EXT classes, even if you regenerate the service, these classes will not be affected. The generated artifact also contains the OData service. This service can be directly added to your Gateway System via configuration or it can be done manually. Login to Gateway System Go to transaction /IWFND/MAINT_SERVICE. Service maintenance screen will be displayed. Click on add service to add a service from Backend system. Provide system alias and the service name, in our case, ZSALESORDER_SRV. Click on the Technical Service name. Provide the package ($TMP) information and click on continue SAP AG 13

14 Click Back button and verify that the newly created service is added to the list. 4.5 Test OData Service from Gateway System Navigate to OData service ZSALESORDER_SRV using transaction /IWFND/MAINT_SERVICE. Under ICF nodes, ODATA should be green; system alias should be assigned to service. Click on Call Browser button SAP AG 14

15 A browser will try to open the service definition, Service Metdata can be obtained with atom link as the bottom appended with $metadata Similarly, Sales Order Headers can be obtained via URL Make sure that your service is obtaining data before proceeding further with BDC Browser SAP AG 15

16 5. Creating BDC model from OData Service 5.1 Creating BDC models and SOAP services BDC Browser tools runs in SAP NetWeaver Gateway system. 1. Once OData service is registered in Gateway system, BDC browser can be run to get the corresponding BDC model. Use transaction /N/IWTNG/BDC_BROWSER to open BDC browser tool. 2. Create a new Business scenario and add it to a customizing transport request. 3. Right click on newly created Business Scenario and select Create BDC Model from ODATA service 2011 SAP AG 16

17 4. In the above screen, Service Identifier is nothing but OData Service Identifier. Use F4 to get the identifier corresponding to ZSALESORDER_SRV. 5. Select ZSALES_ORDER_SRV_001 from the F4. Press ENTER. 6. Use a prefix (ZSO_), this prefix will be used in all the generated objects. 7. Use $TMP as the package name or use your own package. 8. Click on EXECUTE button SAP AG 17

18 9. Do not select any association; the selected association is for F4 helps. The selected association is used when a F4 or value help needs to be added. If a association required between source and target entities use the arrow to move from available associations to Selected associations. 10. Provide the customizing and workbench requests. Choose F4 to select corresponding requests. 11. BDC browser will take some time to finally create SOAP Service and BDC models. 12. In the end you must get a success message. 13. The SOAP service and BDC models are successfully created. 5.2 Testing - Generated SOAP Service The generated web service can be tested via created Server Proxy. Navigate to server proxy in the package that was specified during the object creation. Use the SE80 object navigator to navigate to generated proxy. Go to SE80 -> package ($tmp) -> Enterprise Services -> Server Proxies SAP AG 18

19 Click on the Test icon on the top menu to test the generated SOAP service. Select Query Operation QUERY_SOHEADER_BY_ELEMENTS, don t change any other option, click on Execute button. Go to change mode and remove initial values from the request. Request should look like this Use XML Editor Button to change Request input SAP AG 19

20 Click on Execute button on the top You must get the response below: Similarly test all other operations. Test Read Sales Order Method Go to change mode and enter a sales order id. Click on execute button. Use XML Editor Button to change Request input SAP AG 20

21 Response for Read Sales Order Header. Test Update Sales Order Method Select Update method and provide values for Update Request. Only currency and Note fields can be updated in EPM Sales Order. Use XML Editor Button to change Request input SAP AG 21

22 A successful output is returned. Test Deep Create Sales Order. Select method CREATE_DEEP_SOHEADER SAP AG 22

23 Use XML Editor Button to change Request input SAP AG 23

24 Querying Sales Order Item Navigate to Sales Order Item Service Interface in the object navigator. Click on the Test icon Select QUERY_SOITEM_BY_ELEMENTS method and Click on Execute button. Go to change mode and provide value for Sales Order Header 2011 SAP AG 24

25 Remove values for other fields and provide Sales Order ID value which was created in the DEEP CREATE response. Click on Execute button. The response contains sales items for sales order header id Copy an item key from the response ITEM_KEY _ This ITEM_KEY value will be used in read operation of Sales Order Item SAP AG 25

26 Read Sales Order Item Use the ITEM_KEY value for in the request of Read Sales Order Item method 6. Deploying BDC model on SharePoint 6.1 Exporting BDC Models from SAP System BDC models are imported from BDC Browser tool in SAP system. Go to transaction /IWTNG/BDC_BROWSER. Navigate to Business scenario and right click. Select the Export Business Scenario option SAP AG 26

27 A Models.zip is ready for download. Download it to local system. Models.zip contains Model files for SOHeader and SOItem Entities. SOHeader.xml and SOItem.xml can be imported in SharePoint. 6.2 Importing BDC Models in SharePoint The generated BDC models can be deployed on SharePoint. The out of the box forms will be rendered. Login to SharePoint server and go to central admin page. Click on Business Data Connectivity Service Click on Import button. Here browse and select file SOHeader_Model.xml from the local directory. Click Import SAP AG 27

28 SOHeader BDC model should be successfully imported. Similarly import SOItem_Model.xml file. 6.3 Creating External List External list is created under site pages. You can use already created site page for Duet Enterprise. Click on List and then Create, select External List. Provide a name for external list, e.g. Sales Order Header and select the external content type ZSALESORDER_SRV_SOHeader. As soon as the external list is created, it will be displayed SAP AG 28

29 Use the ECB menu to view an item. Edit item; try to update Note for an item and click on save. The item will be updated SAP AG 29

30 Similarly create external list for Sales Order Items. But the list will not be displayed for Sales Item. A sales order id is required to display sales order items SAP AG 30

31 From the ribbon menu, click on modify view and in data source filters, provide value for a sales order id (copy it from external list of sales order header). Now all the sales order items for this specific sales order header will be displayed. Select View Item from ECB menu to see details of sales order item. 7. Custom UI in SharePoint For deep create (creating header and item together), a custom solution is required on SharePoint. The DEEP _CREATE method is shipped as generic invoker method in BDC model. SharePoint custom code must call this Generic Invoker method for achieving Deep Create functionality. MSDN documentation on Generic Invoker SAP AG 31

32 8. Maintaining Entity to Entity Relationship (Custom Coding in ABAP and SharePoint) A Sales Order header can have multiple Sales Order Items. Here Sales Order Header is parent entity and Sales Order Item is child entity. This can be achieved in SharePoint via custom coding or via BDC association method Entity to Entity relationship can be maintained via two ways Approach 1 o Use Custom Code on SharePoint. o The custom code will refer QUERY method of Child entity as the association method. o Advantage here is no additional coding on ABAP is required. Existing service should be able to provide you association related data o Important point to note is that for Child entity, always specify Parent ID as filter in MPC class Approach 2 o Add a new method in Child Entity in ESR service. o Activate the service in GW system and provide an implementation for the new method. o The implementation is same as the Query method o Update BDC model of Child entity with Association method. o A web part can be added without doing any additional coding on SharePoint. The web part will get all related Sales Order Items for selected Sales Order Header. Approach 1 is highly recommended. 9. Troubleshooting and Best Practices Following are some key points/best practices to make sure your scenario is working perfectly. 9.1 OData Service Service Registration in Gateway Make sure that OData Service is properly registered in GW system. Service must be of type BEP; the ICF node ODATA should be green. A system alias must be assigned to OData service No Reverse Association in OData Service In the Service builder tool, association can be made circular, but Duet Enterprise does not support such circular associations. Only forward associations are supported SAP AG 32

33 In the above example, only forward association is supported i.e. Sales Items can be obtained from Sales Order Header. DateTime Handling Date fields must be converted into timestamp fields in the MPC class. To convert a date into timestamp, precision values must be used as specified as specified above. Precision value 8 for a date field indicates it s a Timestamp field. Make sure each date field is converted into Timestamp in the Service Builder tool. (This is mandatory step because SharePoint understands only DATETIME objects). Also note that datetime field should be marked as Nullable. Case 1. RFC exposes a timestamp field If RFC exposes a timestamp field then it can be directly mapped in the DPC class (to corresponding timestamp field of OData service). Case 2. RFC exposes DATS 8 field. In this case, explicit conversion of DATS to DATETIME is required, For Query/Read operations, DATS must be converted into DATETIME while returning data back. CONVERT DATE <ls_data>-created_on TIME lv_time INTO TIME STAMP <ls_data>-created_on TIME ZONE lv_tz. For Create/Update Operations, incoming request DATETIME must be converted into DATS CONVERT TIME STAMP <ls_data>-created_on TIME ZONE lv_tz INTO DATE <ls_data>-created_on TIME lv_time. In any case, MPC class will expose a timestamp field and the conversion will happen in DPC class SAP AG 33

34 Handling Complex Key SharePoint works with single identifier for a BDC model: Because of this constraint, complex keys has to be flattened For example Sales Order Scenarios: To uniquely identify a Sales Order Item, two keys are required: Sales Order Header ID and Sales Order Item ID is required. Such scenarios can be handled by creating a flattened key in Service builder. Example: Sales Order Header ID: Sales Order Item ID: Flattened Key: _ Example: ITEMKEY as added as the new flattened key. It will hold a concatenated key of Sales Order Header ID and Sales Order Item ID separated by the underscore symbol (e.g _ ) Forming Dummy key in READ methods (for QUERY AND READ methods of DPC class) CONCATENATE ls_salesorderitem-salesorderid '_' ls_salesorderitem-salesorderitem INTO ls_salesorderitem-itemkey. Getting individual Keys (for UPDATE method of DPC class) SPLIT ls_salesorderitem AT '_' INTO ls_salesorderitem-salesorderid ls_salesorderitem-salesorderitem SAP AG 34

35 9.2 BDC Browser Configurations Issues Service Setting should be maintained correctly Transaction /IWTNG/BDC_BROWSER => Tools => Service Settings Maintain 2 Configuration IDs, one for Gateway data model as data source and other for OData service as Data source Make sure that only one of them is (for OData as data source) is marked as Active. The active configuration ID will be used in SIW Configuration. The Config class should be /IWFND/CL_MGW_SB_SIW_CONFIG SAP AG 35

36 Copyright Copyright 2012 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9, iseries, pseries, xseries, zseries, eserver, z/vm, z/os, i5/os, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server, PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trademarks of IBM Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle 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 Oracle Corporation. JavaScript is a registered trademark of Oracle Corporation, used under license for technology invented and implemented by Netscape. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP Business ByDesign, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects S.A. in the United States and in other countries. Business Objects is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty SAP AG 36