Developer Scenario NetWeaver 2013 - ABAP Gateway-OData ...€¦ · ABAP BACKEND IMPLEMENTATION AND FUNCTION MODULES AS DATA PROVIDER ... ABAP Gateway Service Name (SEGW): /IWBEP/EPM_DEV_SCENARIO_2

Developer Scenario NetWeaver 2013 - ABAP Gateway-OData-Services A User Guide for Consumers of the Gateway-ODATA-Services Author: Matthias Wahl, SAP AG, http://scn.sap.com/people/matthias.wahl

http://scn.sap.com/people/matthias.wahl

Developer Scenario NetWeaver 2013 - ABAP Gateway-OData-Services

2

TABLE OF CONTENTS

OBJECTIVES .................................................................................................................................................... 3

ABAP GATEWAY ODATA SERVICE NAME (SEGW): /IWBEP/EPM_DEVELOPER_SCENARIO_SRV/ .... 4 OData Service Description of the Entity Sets and supported functionality .............................................. 4 Entitype Product .............................................................................................................................................. 5 Entitype ProductCategory .............................................................................................................................. 6 Entitype SalesOrderHeader ............................................................................................................................ 6 Entitype SalesOrderItem ................................................................................................................................. 7 Entitype Customer ........................................................................................................................................... 8 Function Import ‘GetCustomerByEmailAddress’ ......................................................................................... 9

ABAP GATEWAY ODATA SERVICE NAME (SEGW): /IWBEP/EPM_DEV_SCENARIO_2 ........................ 10 Entitype SalesOrderHeader .......................................................................................................................... 11 Entitype SalesOrderItem ............................................................................................................................... 12 Entitype Stock ................................................................................................................................................ 12 Entitype Supplier ........................................................................................................................................... 13 Entitype PurchaseOrderHeader ................................................................................................................... 13 Entitype PurchaseOrderItem ........................................................................................................................ 15 Entitype Product ............................................................................................................................................ 16 Function Import ‘ConfirmSalesOrder’ ......................................................................................................... 17 Function Import ‘CancelSalesOrder’ ........................................................................................................... 17

ABAP BACKEND IMPLEMENTATION AND FUNCTION MODULES AS DATA PROVIDER ..................... 18 ABAP Gateway Service Name (SEGW): /IWBEP/EPM_DEVELOPER_SCENARIO_SRV/ ........................ 18 ABAP Gateway Service Name (SEGW): /IWBEP/EPM_DEV_SCENARIO_2 ............................................. 18


3

OBJECTIVES The Netweaver 2013 Demo Developer Scenario has been provided to showcase a minimal End-To-End Cloud Application from UI to Database and publish and run each developed increment on NetWeaver Cloud Server. Parts of this scenario are the ABAP Gateway-OData-Services that will be described in this document. The services are based on the NetWeaver Enterprise Procurement Model which is a simple, ABAP based application that gives consumers the ability to build a procurement or sales scenario. It offers database tables which can be filled by a data generator and business objects, which are capsuling the database layer and providing the business logic. The ABAP Gateway OData Services are delivered with SAP_BASIS component to releases 7.40 SP5 and above.

Purpose of this document is to give you an overview about the Services and their definition, but not, how to create or configure them. If you are interested to configure and activate these services in your own system, please take a look to the referred documents.

The supported functionality is described and you get the information where you can find the Gateway Services in the ABAP Backend as well as the data providing ABAP Function Modules.

Note: The currency units of all entities are fix set to EUR on the OData interface. Internally EPM is not able to convert currencies and to calculate with it. E.g. when the sum of amounts for all sales order items is calculated, a simple cumulating functionality is processed that does not take notice of currencies.

Related SCN documents:

How to Develop a Gateway-Service using Code based Implementation http://scn.sap.com/docs/DOC-43030

Gateway Setup for Enterprise Procurement Model http://scn.sap.com/docs/DOC-41819

Developer Scenario Gateway-OData-Services Installation Guide http://scn.sap.com/docs/DOC-46868

http://scn.sap.com/docs/DOC-31458





4

ABAP GATEWAY ODATA SERVICE NAME (SEGW): /IWBEP/EPM_DEVELOPER_SCENARIO_SRV/ Service Metadata document URI: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV/$metadata

OData Service Description of the Entity Sets and supported functionality

Entity Set

GetEntity (Read single)

GetEntitySet

(Read Set)

Create Update Delete Pagable

SalesOrderHeaders Yes - Yes (deep insert

incl. Items) - - - SalesOrderOrderItems - Yes - - - - Customers Yes - - - - - Products - Yes - - - - ProductCategories - Yes - - - -

Function Import: ‘GetCustomerByEmailAddress’


5

Entitype Product

Property Characteristics Remark

ProductId

Keyfield

Sortable($orderby)

Filterable($filter)

The unique key of a product, e.g. ‘HT-1000’

Name Sortable($orderby)

Filterable($filter) Name of the product

Category Filterable($filter)

Relation to product category(manually)

Product category of this specific product

CategoryName Language dependent name of the product category

ShortDescription Filterable($filter) Short description of the product

LongDescription Long description of the product

Price Sortable ($orderby) The price of the product

CurrencyCode The currency code is always EUR to the outside world. This is possible because within EPM there is no currency conversion implemented. That means e.g. 1€ = 1$ = 1 SFR

SupplierId ID of the supplier of this product

SupplierName Name of the supplier of this product

QuantityUnit The unit counting the product. That may be pieces, liters, …

Weight Weight of the product

WeightUnit Weight unit of the product

DimensionWidth Width of the product

DimensionDepth Depth of the product

DimensionHeight Height of the product

DimensionUnit Dimension of the product

PictureUrl That is a relative URL and must be concatenated with the WebAs prefix to access the picture. ABAP and Java may have different URLs here.

Example URI: Retrieval of product data according to category: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV/Products?$filter=Category eq ’Beamers ’ Product data retrieval according to category and sorted by price ascending: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV/Products?$filter=Category eq ’Notebooks’ &$orderby=Price asc


6

Entitype ProductCategory


Category Keyfield Language independent enumeration of the product category

MainCategory The main category groups the categories. Main category is not visible to other applications. So there is no search implemented based on main categories

MainCategoryName Language dependent name of the product main category (only English supported)

NumberOfProducts The number of products of this category

Example URI: Retrieval of product categories and number of products per category: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV/ProductCategories?

Entitype SalesOrderHeader


SalesOrderId Key Field ID of the created sales order, read only. Will be

returned after sales order is created.

CustomerId Own business partner ID

CurrencyCode Read only – currency code is fix € for all entities,

independent of the database entry. GrossAmount Read only, will be returned after sales order is

created. NetAmount Read only, will be returned after sales order is

created. TaxAmoint Read only, will be returned after sales order is

created. Association (1..*) SalesOrder_HeaderTo_Items

Association (1..*)

Example URI: Retrieval Sales Order Header: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV//SalesOrderHeaders (’500000000 ’)?


7

Entitype SalesOrderItem

Creating items is supported with a “Deep Insert” at the Sales Order Header, but not at the item entitiy. Filtering and sorting is not supported, items are implicitly sorted on the item position. Expand is possible to retrieve the Product of a Sales Order Item.

Property Characteristics Remark SalesOrderId

Key Field ID of the created sales order, read only. Will be returned after sales order is created. (deep insert via create on SalesOrderHeader)

ItemNumber

Key Field Second part of the key of the created sales order Item, read only. Will be returned after sales order is created. (deep insert via create on SalesOrderHeader)

ProductId ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on SalesOrderHeader)

The unique key of a product entity. Can be used for access to a Product entity.

CurrencyCode ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on SalesOrderHeader)

Read only – currency code is fix € for all entities, independent of the database entry

GrossAmount GrossAmount = NetAmount * 1.19

NetAmount TaxAmount TaxAmount = NetAmount *0.19

DeliveryDate ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on SalesOrderHeader)

UTC based Timestamp.

Quantity ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on SalesOrderHeader)

Number of products based on quantity unit.

QuantityUnit ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on SalesOrderHeader)

The unit counting the product. That may be pieces, liters, …

Example URI: Retrieval Sales Order Header Items: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV//SalesOrderHeaders (’500000000’)?$expand=SalesOrderItems


8

Entitype Customer

The service supports the creation of a customer. With the known customer ID or email address a specific data set can be selected via GET. Because of security reasons, searching is not allowed at all for this entity.

Property Characteristics Remark CustomerId

Key field

‘Not creatable’ because it is generated at creation time of an entity instance‘

Unique key visible to device. The key is created on the backend and only relevant for reading

DateOfBirth ‘Creatable’ because values will be passed at creation time of an entity instance

Mandatory for Create

Date of birth of a contact

EmailAddress ‘Creatable’ because values will be passed at creation time of an entity instance


Unique field for the E-Mail address of the consumer. If a user already exists with this mail ad-dress, then an error is returned

PhoneNumber ‘Creatable’ because values will be passed at creation time of an entity instance

Phone number of the customer

City ‘Creatable’ because values will be passed at creation time of an entity instance


Address fields of business partner entity used

PostalCode ‘Creatable’ because values will be passed at creation time of an entity instance

The postal code is not checked on service level. Backend errors are ignored.

Street ‘Creatable’ because values will be passed at creation time of an entity instance


Street name

HouseNumber ‘Creatable’ because values will be passed at creation time of an entity instance


House number of the customer

Country ‘Creatable’ because values will be passed at creation time of an entity instance


Country name of the customer

FirstName ‘Creatable’ because values will be passed at creation time of an entity

First name of the consumer – is not checked with existing names in the data base


9

instance


LastName ‘Creatable’ because values will be passed at creation time of an entity instance


Last name of the consumer – is not checked with existing names in the data base

Example URI: Retrieval of Customer data by his Id: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV/Customers (’100000000 ’)? Example URI: Retrieval of Customer data by his E-Mail address: <service root URI>/sap/opu/odata/IWBEP/EPM_DEVELOPER_SCENARIO_SRV/ GetCustomerByEmailAddress?EmailAddress=%[email protected]%27

Function Import ‘GetCustomerByEmailAddress’

This function is provided for selecting the data of a Business Partner by its E-Mail address. The returning value is a Customer Entity.


10

ABAP GATEWAY ODATA SERVICE NAME (SEGW): /IWBEP/EPM_DEV_SCENARIO_2

OData Service Description of the Entity Sets and supported functionality

Entity Set

GetEntity (Read single)

GetEntitySet

(Read Set)

Create Update Delete Pagable

SalesOrderHeaders Yes Yes - - - - SalesOrderOrderItems - Yes - - - - PurchaseOrderHeaders

Yes - Yes (deep insert

incl. Items - - -

PurchaseOrderOrderItems

- Yes

Yes (deep insert PO Header incl.

Items - -

Suppliers Yes - - - - - Customers Yes - - - - -

Stocks Yes Yes - Yes - -

Products - Yes - - - -

Function Imports: CancelSalesOrder and ConfirmSalesOrder

Service Metadata document: <service root URI>/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/$metadata


11

Entitype SalesOrderHeader


SalesOrderId Key Field ID of the created sales order, read only.

Will be returned after sales order is created.

CustomerId Sortable($orderby)

Filterable($filter) $expand=Customers

Own business partner ID

CurrencyCode Read only – currency code is fix € for all

entities, independent of the database entry.

GrossAmount Read only, will be returned after sales order is created.

NetAmount Read only, will be returned after sales order is created.

TaxAmoint Read only, will be returned after sales order is created.

Association (1..*) SalesOrder_HeaderTo_Items

Association (1..*)

Example URI: Retrieval Sales Order Header: {Server URL}/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/SalesOrderHeaders?$top=10


12

Entitype SalesOrderItem

Access to SalesOrderItems only via $expand from SalesOrderHeader. The Items are implicitly sorted on the item position. Expand is possible to retrieve the Product of a Sales Order Item.

Property Characteristics Remark SalesOrderId

Key Field ID of the created sales order, read only. Will be returned after sales order is created. (deep insert via create on SalesOrderHeader)

ItemNumber

Key Field Second part of the key of the created sales order Item, read only. Will be returned after sales order is created. (deep insert via create on SalesOrderHeader)

ProductId $expand to Product

The unique key of a product entity. Can be used for access to a Product entity.

CurrencyCode Read only – currency code is fix € for all entities, independent of the database entry

GrossAmount GrossAmount = NetAmount * 1.19

NetAmount TaxAmount TaxAmount = NetAmount *0.19

DeliveryDate UTC based Timestamp.

Quantity Number of products based on quantity unit.


Example URI: Retrieval Sales Order Header Items: {Server URL}/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/ SalesOrderHeaders?$top=10&$filter=LifeCycleStatus eq 'N' &$expand=SalesOrderItems

Entitype Stock

Returns the quantity of products in stock.

Property Characteristics Remark ProductId

Keyfield

Sortable ($orderby)

Filterable ($filter)

The unique key of a product, e.g. ‘HT-1000’

Quantity Sortable($orderby)

Filterable($filter) Actual quantity of the product in stock

MinStock updatable Minimum stock quantity for a product

LotSize Default value for purchase order item quantity

QuantityLessMin Sortable ($orderby)

Filterable ($filter) Short description of the product

Product (1..1) Navigate to Product($expand)

Example URI for Retrieval of Stock + Products: <service root URI>/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/Stocks?$expand=Product


13

Entitype Supplier

The service is used to navigate from the Product ID(PurchaseOrderHeader) to a Supplier List

Property Characteristics Remark SupplierId

Keyfield Unique key visible to device. The key is created on the backend and only relevant for reading. (Number range: 100000000; 100000001; …)

SupplierName Name of the supplier

EmailAddress Unique field1 for the mail address of the consumer. If a user already

exists with this mail address, then an error is returned.

PhoneNumber Phone number of the customer.

City Address fields of business partner entity used

PostalCode The postal code is not checked on service level. Backend errors are ignored.

Street Street name of the consumer

HouseNumber House number of the consumer

Country Country name of the consumer

Example URI for Retrieval of a Supplier: {Server URL}/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/Suppliers(‘100000000’)

Entitype PurchaseOrderHeader

Create + Read Implementation

$expand= PurchaseOrderItems

Property Characteristics Remark PurchaseOrderId

Keyfield ID of the created purchase order, read only, not mandatory. Will be returned after sales order is created. (Number range: 300000000; 300000001; …)

SupplierId creatable Mandatory - Create enabled: Supplier

CurrencyCode Read only – currency code is fix € for all entities, independent of the database entry.

GrossAmount Read only, will be returned after Purchase Order is created.

NetAmount Read only, will be returned after Purchase Order is created.

TaxAmount Read only, will be returned after Purchase Order is created.

PurchaseOrderItems (1..1) – only one item / PO

Navigate to PurchaseOrderItem($expand)

Example for Retrieval of a Purchase Order Header + Supplier + Items: <service root URI>/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/PurchaseOrderHeaders (‘300000000’)?$expand=Supplier&$expand=PurchaseOrderItems

1 New functionality to be implemented in EPM core: mail address must be an unique key and query interface

has to be extended by mail address


14

Example for Retrieval of Sales Order Header + Customer + Items: <service root URI>/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/SalesOrderHeaders (‘500000000’)?$expand=Customer&$expand=SalesOrderItems


15

Entitype PurchaseOrderItem

Creating items is supported with a “Deep Insert” at the Purchase Order Header, but not on item entity. Filtering and sorting is not supported, items are implicitly sorted on the item position. Expand is possible to retrieve the Product of a Purchase Order Item.

Create(deep insert) + Read Implementation

$expand= Products

Property Characteristics Remark PurchaseOrderId

Key Field ID of the created purchase order, read only. Will be returned after purchase order is created. (Number Range: 300000000; 300000001; …)

ItemNumber

Key Field ID of the created purchase order item, read only. Will be returned after purchase order is created. (Item positions: 10;20;30;40; …)

ProductId ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on PurchserOrderHeader)

Mandatory: The unique key of a product

CurrencyCode ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on PurchserOrderHeader)

Thus it is create enabled, the currency code is fix € for all entities, independent of the database entry.

GrossAmount Read only, will be returned after Purchase Order is created. GrossAmount = NetAmount *1.19

NetAmount Read only, will be returned after Purchase Order is created.

TaxAmount Read only, will be returned after Purchase Order is created. TaxAmount = NetAmount *0.19

Quantity ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on PurchserOrderHeader)

Mandatory: Number of products based on quantity unit.

QuantityUnit ‘Creatable’ because a value will be passed at creation time of an entity instance (deep insert via create on PurchserOrderHeader)

The unit counting the product. That may be pieces, liters, … Read only, fixed to each (EA)

Products (1..1) – only one item / PO

Navigation to Products via ProductId


16

Entitype Product

Read Implementation

$expand= Supplier

Property Characteristics Remark ProductId

Keyfield The unique key of a product, e.g. ‘HT-1000’

Name Name of the product

Category Product category of this specific product

CategoryName Language dependent name of the product category

ShortDescription Short description of the product

LongDescription Long description of the product

Price The price of the product

CurrencyCode The currency code is always EUR to the outside world. This is possible because within EPM there is no currency conversion implemented. That means e.g. 1€ = 1$ = 1 SFR

SupplierId ID of the supplier of this product

SupplierName Name of the supplier of this product


Weight Weight of the product

WeightUnit Weight unit of the product

DimensionWidth Width of the product

DimensionDepth Depth of the product

DimensionHeight Height of the product

DimensionUnit Dimension of the product

PictureUrl That is a relative URL and must be concatenated with the WebAs prefix to access the picture. ABAP and Java may have different URLs here.

Supplier(1..1) Navigation to Supplier via SupplierId

Example URI for Retrieval of a Product: <service root URI>/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/Products(‘HT-1000’) Example URI for Retrieval of all Products: <service root URI>/sap/opu/odata/IWBEP/EPM_DEV_SCENARIO_2_SRV/Products


17

Function Import ‘ConfirmSalesOrder’ This function sets the SalesOrderHeader LifeCycleStatus from ‘New’ to’ In Process’. The returning value is a SalesOrderHeader Entity.

Function Import ‘CancelSalesOrder’ This function sets the SalesOrderHeader LifeCycleStatus from ‘New’ to’Cancelled’. The returning value is a SalesOrderHeader Entity.


18

ABAP BACKEND IMPLEMENTATION AND FUNCTION MODULES AS DATA PROVIDER

The Backend implementation is separated into the Data Provider (Remote Function Modules RFC using EPM Business Objects for data access) and the OData Gateway services that can be displayed and configured with transaction SEGW.

Function Modules for data access are located in ABAP Package (sap_basis): S_EPM_GATEWAY

Function Group: SEPM_GATEWAY_SERVICES

ABAP Gateway Service Name (SEGW): /IWBEP/EPM_DEVELOPER_SCENARIO_SRV/

Function Modules

SEPM_GWS_BP_CREATE: Create a Business Partner (triggered by an EPM GW-Service)

SEPM_GWS_BP_GET_DETAIL: Read data of a Business Partner ( triggered by an EPM GW-Service )

SEPM_GWS_PO_CREATE: Create a Purchase Order (triggered by an EPM GW-Service)

SEPM_GWS_PO_GET_DETAIL: Retrieval of Purchase Order Data (triggered by an EPM GW-Service)

SEPM_GWS_PRODUCTS_GET: Retrieve product data (triggered by an EPM GW-Service)

SEPM_GWS_PRODUCTS_GET_BY_CATEG: Retrieve product data by category (triggered by an EPM GW-Service)

SEPM_GWS_PRODUCT_CATEGS_GET: Retrieve product categories (triggered by an EPM GW-Service)

ABAP Gateway Service Name (SEGW): /IWBEP/EPM_DEV_SCENARIO_2

Function Modules:

SEPM_GWS_STOCK_GET: Retrieve Stock Data ( triggered by an EPM GW-Service )

SEPM_GWS_STOCK_GET_DETAIL: Retrieval of Sales Order Data ( triggered by an EPM GW-Service )

SEPM_GWS_STOCK_UPDATE: Update Stock Data ( triggered by an EPM GW-Service )

SEPM_GWS_BP_GET_DETAIL: Read data of a Business Partner ( triggered by an EPM GW-Service )

SEPM_GWS_PO_CREATE: Create a Purchase Order ( triggered by an EPM GW-Service )

SEPM_GWS_PO_GET_DETAIL: Retrieval of Purchase Order Data ( triggered by an EPM GW-Service )

SEPM_GWS_PRODUCTS_GET: Retrieve product data (triggered by an EPM GW-Service)

SEPM_GWS_SALES_ORDERS_GET: Retrieve Sales Order Header data ( triggered by EPM GW-Service )

SEPM_GWS_SO_EXECUTE_ACTION: Executes a Sales Order action ( triggered by an EPM GW-Service )

© 2014 SAP AG. All rights reserved.

SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP

BusinessObjects Explorer, StreamWork, SAP HANA, 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 Software Ltd. Business Objects is an SAP

company.

Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL

Anywhere, and other Sybase products and services mentioned herein

as well as their respective logos are trademarks or registered

trademarks of Sybase Inc. Sybase is an SAP company.

Crossgate, m@gic EDDY, B2B 360°, and B2B 360° Services are

registered trademarks of Crossgate AG in Germany and other

countries. Crossgate 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.

www.sap.com

Documents

Developer Scenario NetWeaver 2013 - ABAP Gateway-OData ...€¦ · ABAP BACKEND IMPLEMENTATION AND FUNCTION MODULES AS DATA PROVIDER ... ABAP Gateway Service Name (SEGW): /IWBEP/EPM_DEV_SCENARIO_2