I have been using SAP Gateway from one month and feel that there is too much of redundancy and Limitations. Let me brief in points :

1) Entity Relationship

ODATA has an obligatory requirement for a Primary Key Relation between in the input and output parameters of the FM......For instance, if there is a INITILIZATION web service created that calls an FM to export 5 tables in the response , the GET ENTITY SET Query executes the FM as many as 5 times to the get the details which could be done with single execution of FM Here each table is addressed as an Entity which is not apt is what I feel...

I had to use ASSOCIATION to get 5 tables and why would anyone do that !

2)Custom Code in the Methods

When it comes to flexibility and altering a code , the custom code written in the methods ( GET , CREATE , DELETE , UPDATE , GET ENTITY SET ) is erased when the user hits a GENERATE button....

3)Redundant Data Returned

There is a set of redundant data that could effect the JSON response size unnecessarily for instance below....why is the metadata is in reponse....can that be avoided.....

"__metadata": {

"id": "/sap/opu/odata/sap/ywebservice/initAhsWebservice('RETURNLINK')",

"uri": "/sap/opu/odata/sap/ywebservice/initAhsWebservice('RETURNLINK')",

"type": "ywebservice.initAhsWebservice"

4)CREATE calls

The POST/CREATE web service does a GET method that calls the FM once more with the same data. This redundant code can be commented out but then the regeneration of the code would get that working again !!!

I want know if am following the right standards or am having half baked knowledge in SAP GATEWAY SERVICES !!!

Please let me know if am going in wrong way all together....

Knowledge prepare:

Topic:Expand in Framework and Data Provider

URI: Expand in Framework and Data Provider - SAP NetWeaver Gateway - SAP Library

A request with a $expand query option enables the reading of entries of an entity together with an associated entity.

Below is some blogs posted in SCN about expand, I would like to show my respect to them here.

Step-by-step guide to build an OData Service based on RFCs – Part 3

Ok, now let us start.

1. Create a Entity Name: ApplicationLog

Entity Set Name: ApplicationLogCollection

2. Set ABAP structure and Properties for Entity Name: ApplicationLog.

3. Create Association Name: Task_To_M_ApplicationLog.

click [Next], fill in Referential Constraints

click [Next]-->click [finish].

4.Click [Generate Runtime Object ] and make sure the message with "Runtime Objects for project 'xxxx' generated".

5. Test metadata

6.Create class: CL_CRM_ODATA_RT_ApplicationLog (Runtime Class for ApplicationLog)

Code Snippet:

Class:CL_CRM_ODATA_RT_ApplicationLog

Method: /IWBEP/IF_MGW_APPL_SRV_RUNTIME~GET_ENTITYSET

DATA: applicationlog_get_entityset TYPE cl_crm_odata_mpc=>tt_applicationlog.

" EntitySet -ApplicationLogCollection

IF iv_entity_set_name = gc_application_log_collection.

applicationlog_get_entityset(

EXPORTING

iv_entity_name = iv_entity_name

iv_entity_set_name = iv_entity_set_name

iv_source_name = iv_source_name

it_filter_select_options = it_filter_select_options

it_order = it_order

is_paging = is_paging

it_navigation_path = it_navigation_path

it_key_tab = it_key_tab

iv_filter_string = iv_filter_string

iv_search_string = iv_search_string

io_tech_request_context = io_tech_request_context

IMPORTING

et_entityset = applicationlog_get_entityset

es_response_context = es_response_context

* Send specific entity data to the caller interface

copy_data_to_ref(

EXPORTING

is_data = applicationlog_get_entityset

CHANGING

cr_data = er_entityset

Class:CL_CRM_ODATA_RT_ApplicationLog

Method: /IWBEP/IF_MGW_APPL_SRV_RUNTIME~GET_EXPANDED_ENTITY

DATA: lr_bupa_provider TYPE REF TO cl_crm_bp_odata_data_provider,

lv_bupa_supports TYPE abap_bool.

CREATE OBJECT lr_bupa_provider.

lv_bupa_supports = lr_bupa_provider->supports_entity( EXPORTING iv_entity_name = iv_entity_name ).

IF iv_entity_name = GC_TASK.

IF go_task_impl IS NOT BOUND.

CREATE OBJECT go_task_impl

EXPORTING

ir_context = mo_context.

ENDIF.

go_task_impl->get_task_expanded_entity(

EXPORTING

iv_entity_name = iv_entity_name

iv_entity_set_name = iv_entity_set_name

iv_source_name = iv_source_name

it_key_tab = it_key_tab

it_navigation_path = it_navigation_path

io_expand = io_expand

io_tech_request_context = io_tech_request_context

IMPORTING

er_entity = er_entity

et_expanded_clauses = et_expanded_clauses " Table of Strings

et_expanded_tech_clauses = et_expanded_tech_clauses " Table of Strings

ELSEIF lv_bupa_supports = 'X'.

CALL METHOD lr_bupa_provider->/iwbep/if_mgw_core_srv_runtime~set_context

EXPORTING

io_context = mo_context.

CALL METHOD lr_bupa_provider->/iwbep/if_mgw_appl_srv_runtime~get_expanded_entity

EXPORTING

iv_entity_name = iv_entity_name

iv_entity_set_name = iv_entity_set_name

iv_source_name = iv_source_name

it_key_tab = it_key_tab

it_navigation_path = it_navigation_path

io_expand = io_expand

io_tech_request_context = io_tech_request_context

IMPORTING

er_entity = er_entity

et_expanded_clauses = et_expanded_clauses

et_expanded_tech_clauses = et_expanded_tech_clauses.

ENDIF.

Class:CL_CRM_ODATA_RT_ApplicationLog

Method: APPLICATIONLOG_GET_ENTITYSET

TRY.

DATA: lv_obj_guid TYPE crmt_object_guid.

FIELD-SYMBOLS <fs_key_set_option> TYPE /iwbep/s_mgw_name_value_pair.

READ TABLE it_key_tab ASSIGNING <fs_key_set_option> WITH KEY name = GC_GUID.

IF <fs_key_set_option> IS ASSIGNED AND <fs_key_set_option>-value IS NOT INITIAL.

lv_obj_guid = <fs_key_set_option>-value.

CALL METHOD gr_task_rt->get_log_data

EXPORTING

iv_object_guid = lv_obj_guid

IMPORTING

et_log = et_entityset.

ENDIF.

CATCH /iwbep/cx_mgw_busi_exception .

CATCH /iwbep/cx_mgw_tech_exception .

ENDTRY.

7. Then you can test for the entity by below 2 kinds of URIs.

(1)/sap/opu/odata/sap/CRM_ODATA/TaskCollection(guid'xxxxx')/ApplicationLogs

(2)/sap/opu/odata/sap/CRM_ODATA/TaskCollection(guid'xxxxx')/?$expand=ApplicationLogs

8.Finished.

Introduction

OData services provide a uniform interface for interacting with their resources, and in addition are self-describing:

The service document (located at the service root) lists the available top-level resources, and
The service metadata document (located at the address $metadata relative to the service root) describes the structure of all resources in the service.

This structural metadata makes it easy to understand a service, and human-readable documentation can be directly embedded into the metadata document, helping developers consume an OData service.

This alone is a huge benefit, yet metadata can be taken one step further by embedding machine-readable additional metadata that can be leveraged by development tools, client libraries, and generic clients to better interact with the service.

One area are semantic annotations that tell which of the OData properties contain e.g. a phone number, a part of a name or address, or something related to a calendar event or an analytic query. This is important for apps running on mobile devices that want to seamlessly integrate into contacts, calendar, and telephony.

The next area are capability annotations that describe which of the possible interactions defined by OData's uniform interface are supported by which parts of a concrete service. These annotations will e.g. tell whether an entity set allows inserts, updates, or deletes, whether it requires a filter, and which properties can be used in filter expressions. They also advertise capabilities that go beyond the base set defined by OData, e.g. whether an entity set allows free-text search via an SAP-defined query option.

AtomPub Service Document

AtomPub allows extending the service document with elements and attributes from XML namespaces other than AtomPub. The following sections describe which elements of the service document (namespace prefix app) can be annotated with attributes and elements from the namespace http://www.sap.com/Protocols/SAPData (namespace prefix sap) and from the namespace http://www.w3.org/2005/Atom (namespace prefix atom), and what these annotations mean.

Element app:service

The app:service element can be annotated with two elements from the atom namespace:

<atom:link rel="self" href="..."/> contains the link to this service document, and
<atom:link rel="latest-version" href="..."/> contains the link to latest version of this service.

If the latest-version link deviates from the self link, a client may inspect the newer version of the service and decide (probably after asking its user) to switch over to the newer service version.

Element app:collection

The app:collection element can be annotated with three elements:

<sap:member-title> contains the human-readable name or caption for a single member of the collection. This typically is the singular form of the content of the <atom:title> element of this collection.
<atom:link rel="search" href="..."/> contains the link to an OpenSearch description document that describes how to use free-text search for this collection. For those not familiar with OpenSearch: just append the SAP-specific query option searchto the URL of the collection.
<atom:link rel=http://www.sap.com/Protocols/SAPData/rel#subscribe href="..."/> contains the link to the collection of the same service that allows subscribing to content changes of the annotated collection. For more information see the HowTo Guides - Subscription & Notification with SAP NetWeaver Gateway - Series.

It can also contain the attribute sap:addressable with the same value as for the corresponding entity set in the metadata document.

Metadata Document

OData's Conceptual Schema Definition Language (CSDL) allows annotating most model elements with XML attributes or elements from foreign XML namespaces. The following sections describe which elements of the metadata document (namespace prefix edm) can be annotated with attributes and elements from the namespace http://www.sap.com/Protocols/SAPData (namespace prefix sap), and what these annotations mean. For binary attributes the meaning is desribed for the value "true".

Element edm:EntityContainer

Entity containers can be annotated with the following attributes. If not stated explicitly, consumers can assume them to have the default value listed in the second column. This default value reflects the "normal" behavior.

Attribute Name	Default Value	Meaning
supported-formats	atom json	A white-space separated list of format shortnames. Possible list items: atom json xlsx The default is sap:supported-formats="atom json".
use-batch	false	Wrap all requests to resources of this service in batch requests; only the service document and the metadata document can be accessed unwrapped.This avoids exposing sensitive data in URLs (even with HTTPS URLs can be visible in log files)

Attribute Name

Default Value

Meaning

supported-formats

atom json

A white-space separated list of format shortnames. Possible list items:

atom
json
xlsx

The default is sap:supported-formats="atom json".

use-batch

false

Wrap all requests to resources of this service in batch requests; only the service document and the metadata document can be accessed unwrapped.This avoids exposing sensitive data in URLs (even with HTTPS URLs can be visible in log files)

Element edm:EntitySet

Entity sets can be annotated with the following attributes. If not stated explicitly, consumers can assume them to have the default value listed in the second column. This default value reflects the "normal" behavior that can be expected from any OData service.

Attribute Name	Default Value	Meaning
label	-	Description, will also be used as atom:title in the service document
creatable	true	New entities can be created in this set
updatable	true	Entities in this set can be updated
updatable-path	-	Entities in this set can be updated or not depending on their state. The value of this attribute is a path expression that identifies a Boolean property in the context of the entity type of the entity set. The value of this property indicates whether the entity can be updated or not.
deletable	true	Entities can be deleted from this set
deletable-path	-	Entities in this set can be deleted or not depending on their state. The value of this attribute is a path expression that identifies a Boolean property in the context of the entity type of the entity set. The value of this property indicates whether the entity can be deleted or not.
searchable	false	Supports custom query option search
pageable	true	Supports system query options $top and $skip
topable	true	Supports system query option $top
countable	true	Supports system query option $inlinecount=allpages and path suffix /$count
addressable	true	Use “false” if this entity set can only be accessed within its containing entity, e.g. SalesOrderItems within SalesOrders through SalesOrders(4711)/Items. Direct access to non-addressable entity collections will result in a 404 response code. The set may however allow access to single entities identified by their key properties values, e.g. SalesOrderItems(OrderID=4711,ItemID=3)
requires-filter	false	Use “true” if this set cannot be queried without providing a $filter expression. If accessed without a filter expression, it will respond with a human-readable error message explaining which kinds of filter expressions are required as a minimum
change-tracking	false	Changes to entities of this set can be tracked. Consumers can subscribe by adding an HTTP Prefer header odata.track-changes to the request. The response will then include a delta link for requesting information about changes in the future.
maxpagesize	-	Maximum number of entities returned in an OData response. If more entities are included in the result of an OData request, the service applies server-driven paging.
delta-link-validity	-	The maximum duration in seconds a delta link in an OData response remains valid. Afterwards, resources associated with the change tracking subscription may be cleaned up and will be no longer available.
semantics	-	See table below

Attribute sap:semantics

This attribute can take the following values in the context of an entity type:

Value	Meaning
aggregate	The entities of this set are automatically aggregated if the query option $select is specified. Each property listed in $select is treated according to its aggregation role, see description of attribute sap:aggregation-role below
fixed-values	The entity set represents a list of fixed values, i.e. it is unlikely to change often, and the list is typically short

Element edm:EntityType

Entity types can be annotated with the following attributes:

Attribute Name	Meaning
label	Description, will also be used as sap:member-title in the service document
semantics	See table below

Attribute sap:semantics

This attribute can take the following values in the context of an entity type:

Value	Meaning
vcard	Entities of this type contain contact information following the vCard standard, see values for sap:semantics on property level
vevent	Entities of this type contain event/appointment information following the iCalendar standard, see values for sap:semantics on property level
vtodo	Entities of this type contain todo/task information following the iCalendar standard, see values for sap:semantics on property level
parameters	This entity type represents parameters for an analytical query
aggregate	Entity sets with this type return result feeds with aggregated values for properties annotated with sap:aggregation-role="measure". The aggregation takes into account the dimension properties specified in the $select system query option of the request. See also description of annotation sap:aggregation-role.
variant	This entity type represents query selection variants bundling parameter selections and filter expressions for obtaining specific query results

Element edm:Property

The annotation sap:labelis required for properties. All other annotations are optional.

Attribute Name	Default Value	Meaning
label	-	A short, human-readable text suitable for labels and captions in UIs
heading	-	A short, human-readable text suitable for column headings in UIs
quickinfo	-	A human-readable text suitable for tool tips in UIs
semantics	-	See table below
creatable	true	Values for this property can be chosen by client when creating an instance. “False” if value is always set by the server, e.g. document number from number range.
updatable	true	Values of this property can be changed. Must be “false” if it is “false” at entity set level. If updatability can change per entity or based on the entities' state, do not use this static annotation and use sap:field-control instead.
sortable	true	Can be used in $orderby system query option.
filterable	true	Can be used in $filter system query option.
required-in-filter	false	Must be used in $filter system query option.
filter-restriction	-	See table below
text	-	A path expression that identifies a property in the context of the entity type containing a human-readable text for the value of this property.
unit	-	A path expression that identifies a property in the context of the entity type containing the currency code or unit of measure for a numeric value.
precision	-	A path expression that identifies a property in the context of the entity type containing the number of significant decimal places for a numeric value.
visible	true	Values of this property are typically visible to end users. If visibility can change per entity or based on the entities' state, do not use this static annotation and use sap:field-control instead.
field-control	3	A path expression that identifies a property containing a numeric value that controls visibility: 0 = hidden, 1 = read-only, 3 = optional, 7 = mandatory See section below for details
validation-regexp	-	Values for this property have to match the specified regular expression. The regular expression is a JavaScript Regular Expression.
display-format	-	There are currently three possible values: “Date” indicates that only the date part of an Edm.DateTime value is relevant "NonNegative" indicates that only non-negative numeric values are provided and persisted, other input will lead to errors "UpperCase" indicates that uppercase values are provided and persisted, lowercase input will be converted
lower-boundary	-	A property holding the upper boundary of a value range includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property holding the related lower boundary.
upper-boundary	-	A property holding the lower boundary of a value range includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property holding the related upper boundary.
aggregation-role	-	See table below
super-ordinate	-	If values of this property are meaningful (unique) only in the context provided by the value of another property, then this attribute holds the name of the context-providing property. The value of this attribute is always the name of another property in the same type.
attribute-for	-	A property representing an attribute of another property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property for which this property is an attribute.
hierarchy-node-for	-	A property holding node IDs for a hierarchy structure of values of some other property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property for whose values the hierarchy is defined.
hierarchy-level-for	-	A property holding level numbers for a hierarchy structure of values of some other property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the related property holding the hierarchy node ID. A property holding level numbers has an integer data type. The root node of the hierarchy is at level 0.
hierarchy-parent-node-for	-	A property holding parent node IDs for a hierarchy structure of values of some other property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the related property holding the hierarchy node ID. For the root node of the hierarchy the parent node ID is null.
hierarchy-parent-navigation-for	-	A navigation property for accessing the parent entity of a node. It offers an alternative method for accessing the parent node ID, if the entity type does not have a dedicated property for that.
hierarchy-drill-state-for	-	A property holding the drill state of a hierarchy node includes this attribute. The drill state is indicated by one of the following values: collapsed, expanded, leaf. The value of this attribute is always the name of another property in the same type. It points to the related property holding the hierarchy node ID. For a collapsed hierarchy node or a leaf, the hierarchy node ID of such an entity does not occur as parent node ID of any other entity in the set.
parameter	-	See table below
is-annotation	false	Represents an instance annotation.
updatable-path	-	If a property can be updated or not depending on the state of its entity, it can be annotated with this attribute. The value of this attribute is always a path expression that identifies a Boolean property in the context of the entity type. This related property indicates whether the annotated property can be updated for the containing entity or not. Note: if used in addition to the more expressive field-control annotation, the values of the two must be in sync.
preserve-flag-for	-	See below
filter-for	-	A property whose value is a $filter expression includes this attribute. The $filter expression must be valid for the entity type specified in this attribute.

Attributes sap:unit and sap:precision

Amounts in a currency or absolute measures MUST be represented as simple properties with an appropriate numeric Edm type, preferably Edm.Decimal. These numeric properties SHOULD refer to a string property containing the ISO currency or unit of measure with the sap:unit attribute. They MAY refer to a numeric property containing the (non-negative) number of decimal places to be used for displaying the amount or measure with the sap:precision attribute.

Example in metadata document:

<Property Name="OrderedQuantity" Type="Edm.Int16"
sap:unit="OrderedUnit" />
<Property Name="OrderedUnit" Type="Edm.String"

sap:semantics="unit-of-measure" />

<Property Name="Currency" Type="Edm.String"

sap:semantics="currency-code" sap:text="CurrencyText" />

Example in Atom entry:

<d:OrderedQuantity>50</d:OrderedQuantity>
<d:OrderedUnit>KGM</d:OrderedUnit>
<d:Price>86.9</d:Price>

<d:DisplayScale>2</d:DisplayScale>

<d:Currency>EUR</d:Currency>
<d:CurrencyText>Euro</d:CurrencyText>

Using a reference attribute instead of predefined complex types like Measure or Money with amount and unit properties allows several amounts to share the same unit. Transporting the amounts as “raw” numeric values instead of preformatted strings allows clients to format them according to device-specific settings (that may well differ from the server-side user settings) or process them on the client (if e.g. the client is Excel).

Attribute sap:field-control

Whether a property can or must contain value may depend on the state of its entity, so it is impossible to express this up-front via metadata annotations. In these cases the "edit state" of the property can be expressed via a separate "field control" property, and the link between data properties and their field-control properties is expressed with the sap:field-control attribute.

Example in metadata document:

<Property Name="Street" Type="Edm.String"

sap:field-control="UX_FC_Address" />

<Property Name="City" Type="Edm.String"

sap:field-control="UX_FC_Address" />

The field-control property can be in the same type as shown above, or it can be in a nested complex type, or in an entity type that is associated 1:1. This allows separating field-control data from "real" data. If for example the field-control property is contained in a complex property or navigation property named UX, the attribute value is contains a path relative to the parent of the annotated property, e.g. sap:field-control="UX/FC_Address".

The possible values for a field-control property are:

Value	Meaning
7	Mandatory - property must contain a value
3	Optional - property may contain a null value
1	Read-only - property cannot be changed
0	Hidden - property should not be visible on user interfaces

Attribute sap:semantics

The possible values in the context of a property are:

Value	Meaning
tel	Telephone number
tel;type=cell,work	Work cellphone number; see explanation below table for more values
tel;type=fax	Fax number
email	Email address
email;type=pref	Preferred email address
url	Web URL
name	Formatted text of the full name
givenname	First name or given name of a person
middlename	Middle name of a person
familyname	Last name or family name of a person
nickname	Descriptive name given instead of or in addtion to the one marked as "name"
honorific	Title of a person (Ph.D., Dr., ...)
suffix	Suffix to the name of a person
note	Supplemental information or a comment that is associated with the vCard
photo	URL of a photo of a person
city	Address: city
street	Address: street
country	Address: country
region	Address: state or province
zip	Address: postal code
pobox	Address: post office box
org	Organization name
org-unit	Organizational unit
org-role	Organizational role
title	Job title
bday	Birth date
summary	Calendar: summary of a calendar component
description	Calendar: description of a calendar component, detailing the summary
categories	Calendar: comma-separated list of categories for a calendar component
dtstart	Calendar: the date and time that a calendar component starts
dtend	Calendar: the date and time that a calendar component ends
duration	Calendar: duration as an alternative to dtend, see xs:duration
due	Calendar: the date and time that a to-do is expected to be completed
completed	Calendar: the date and time that a to-do was actually completed
priority	Calendar: the relative priority for a calendar component, 0 for undefined, 1 for highest, ... 9 for lowest
class	Calendar: access classification for a calendar component
status	Calendar: overall status or confirmation for the calendar component
percent-complete	Calendar: percent completion of a to-do., ranging from 0 to 100 (integer)
contact	Calendar: contact information or alternatively a reference to contact information associated with the calendar component
location	Calendar: the intended venue for the activity defined by a calendar component
transp	Calendar: defines whether or not an event is transparaent to busy time searches
fbtype	Calendar: free/busy time type, see [iCalendar, Section 3.2.9]
wholeday	Calendar: "true" or "false, depending on whether an event is scheduled for an entire day
year	Calendar: year as string following the regex pattern (-?)YYYY(Y*) consisting of an optional minus sign for years B.C. followed by at least four digits
yearmonth	Calendar: year and month as string following the regex pattern (-?)YYYY(Y*)MM consisting of an optional minus sign for years B.C. followed by at least six digits, the last two digits are a number between 01 and 12 representing the months January to December
yearmonthday	Calendar: year, month and day as string following the logical pattern (-?)YYYY(Y*)MMDD consisting of an optional minus sign for years B.C. followed by at least eight digits, where the last four digits represent the months January to December (MM) and the day of the month (DD). The string matches the regex pattern -?([1-9][0-9]{3,}\|0[0-9]{3})(0[1-9]\|1[0-2])(0[1-9]\|[12][0-9]\|3[01]) The regex pattern does not reflect the additional constraint for "Day-of-month Values": The day value must be no more than 30 if month is one of 04, 06, 09, or 11, no more than 28 if month is 02 and year is not divisible by 4, or is divisible by 100 but not by 400, and no more than 29 if month is 02 and year is divisible by 400, or by 4 but not by 100
from	Mail: author of message, see [RFC5322, section 3.6.2]
sender	Mail: mailbox of agent responsible for actual transmission
to	Mai: comma-separated list of primary recipients, see [RFC5322, section 3.6.3]
cc	Mail: carbon copy, comma-separated
bcc	Mail: blind carbon copy, comma-separated
subject	Mail: topic of the message
body	Mail: message body
keywords	Mail: comma-separated list of important words and phrases that might be useful for the recipient
received	Mail: DateTime the message was received
geo-lon	Geolocation: longitude
geo-lat	Geolocation: latitude
currency-code	ISO currency code
unit-of-measure	Unit of measure, preferably ISO
count	Aggregation: the number of leaf entities that have been aggregated into the response entity (count(*) in SQL). Only valid for one property of an entity type that is annotated with sap:semantics="aggregate".

For “tel” the type values are (see [vCard, section 6.4.1]):

"home" to indicate a telephone number associated with a residence
"work" to indicate a telephone number associated with a place of work
“pref" to indicate a preferred-use telephone number
"text" to indicate a telephone number supporting text messages (SMS)
"voice" to indicate a voice telephone number
"fax" to indicate a facsimile telephone number
"cell" to indicate a cellular telephone number
"video" to indicate a video conferencing telephone number
"pager" to indicate a paging device telephone number
"textphone" to indicate a telecommunication device for people with hearing or speech difficulties

For “email” the type values are:

"home" to indicate an email address associated with a residence
"work" to indicate an email address associated with a place of work
“pref" to indicate a preferred-use email address

For “url” and constituents of an address the type values are:

"home" to indicate an address associated with a residence
"work" to indicate an address associated with a place of work
“org" to indicate an address associated with the organization
“pref” to indicate a preferred address “other” to indicate some other address

These type values can be specified as a value list (like "type=work,pref").

Attribute sap:filter-restriction

A property can be annotated with this attribute, if filter restrictions exist. The attribute can take the following values:

Value	Meaning
single-value	Only a single “eq”clause is possible.
multi-value	Several “eq” clauses, separated by or, are possible.
interval	At most one “ge” and one “le” clause, separated by “and”, alternatively a single “eq” clause.

Attribute sap:aggregation-role

A property can be annotated with this attribute, if it has an aggregation role. The attribute can take the following values:

Value	Meaning
dimension	The property represents the key of a dimension. Only valid for properties of an entity type that is annotated with sap:semantics=“aggregate“.
measure	The property represents a measure whose values will be aggregated according to the aggregating behavior of the containing entity type. Only valid for properties of an entity type that is annotated with sap:semantics=“aggregate“.
totaled-properties-list	The property value is a comma-separated list of totaled dimension property names.

Attribute sap:parameter

A property can be annotated with this attribute, if it represents a parameter. The attribute can take the following values:

Value	Meaning
mandatory	A value must be supplied for this parameter.
optional	A value for this parameter can be left out by specifying an empty string (applicable only for parameter properties of type Edm.String). A value for this parameter can be left out by specifying an empty string (applicable only for parameter properties of type Edm.String). For parameters of other types, the default value conveyed in the metadata should be assigned, if the parameter shall be omitted.

Value

Meaning

mandatory

A value must be supplied for this parameter.

optional

A value for this parameter can be left out by specifying an empty string (applicable only for parameter properties of type Edm.String). A value for this parameter can be left out by specifying an empty string (applicable only for parameter properties of type Edm.String). For parameters of other types, the default value conveyed in the metadata should be assigned, if the parameter shall be omitted.

Attribute sap:preserve-flag-for

A property holding the preservation state for another property includes this attribute.

The preservation state is a Boolean flag indicating whether or not the value of a named entity property is protected against updates causedby side-effects of updates to the entity set.

Example:

Consider an entity set holding order items with unit price, quantity, and total amount. All three properties supports preservation, as shown here for the unit price:

For a given order item, a consumer can set the preservation flag for the total amount and update the unit price. This would instruct the provider to recalculate the quantity instead of the total amount.

Element edm:NavigationProperty

Attribute Name	Default Value	Meaning
filterable	true	Can be used as a path segment for properties in $filter system query option

Element edm:FunctionImport

Attribute Name	Meaning
action-for	Value is the qualified name of an entity type in scope. Indicates that the function or action operates on instances of that entity type. The function import MUST have a required parameter for each key property of that entity type. Parameter name and type must be identical to the name and type of the corresponding key property.
applicable-path	Value is a path to a Boolean property in the entity type named in the action-for attribute. The property indicates whether the function import can be invoked for the entity. The path can be the name of a Boolean property, or the name of a complex property followed by a forward slash and the path to a Boolean property in the complex type.
label	Description
planning-function	This function processes or generates plan data that may be exposed by entity sets of aggregate entity types in the same service. Its logic may have side-effects on these entity sets.

Example: a function import that allows approving a leave request. The LeaveRequest entity type has a single key property ID and a complex property ControlData with a Boolean property NeedsApproval that controls the applicability of two alternative actions, approval and rejection:

<FunctionImport Name="LeaveRequestApproval"

ReturnType="ThisModel.ApprovalResult"

                    m:HttpMethod="POST"
                    sap:label="Approve"
                    sap:action-for="ThisModel.LeaveRequest"
                    sap:applicable-path="ControlData/NeedsApproval">

</FunctionImport>

<FunctionImport Name="LeaveRequestRejection"
ReturnType="ThisModel.ApprovalResult"

m:HttpMethod="POST"

                    sap:label="Reject"
                    sap:action-for="ThisModel.LeaveRequest"
                    sap:applicable-path="ControlData/NeedsApproval">

</FunctionImport>

A function import can optionally include an annotation with an sap:value-constraint element.

Element sap:value-constraint

This element describes a dependency of function import parameters to key properties of an entity set, comparable to a referential constraint.

Example: For a function import with two parameters for country and region, the possible arguments can be determined via some Regions entity set.

<sap:value-constraint set="Regions">

<sap:parameter-ref name="Country"/>

<sap:parameter-ref name="Region"/>

</sap:value-constraint>

It has a set attribute that identifies the entity set containing the list of allowed parameter value combinations.

Nested sap:parameter-ref elements link the function import parameters specified with the name attribute to a key property of the entity type of the specified entity set. The sequence of sap:parameter-ref elements matches the sequence of the edm:PropertyRef elements of the Key element.

Element edm:Parameter

Attribute Name	Meaning
label	Description

Element edm:AssociationSet

Attribute Name	Default Value	Meaning
creatable	true	Relations can be created
updatable	true	Relations can be changed
deletable	true	Relations can be deleted

Instance Annotations

An annotation of an element in the OData metadata document adds information at the structural level of the service. Sometimes extra pieces of information are needed in the OData response for individual entities and their properties. To distinguish these two cases the former are called metadata annotations, while annotations of the entities in the OData response are called instance annotations.

Metadata annotations add information to the model structure. They are fully described by adding the appropriate AnnotationElement or AnnotationAttribute to a model element.

For instance annotations, this is different, because it must be possible to add different annotation values for every entity or every entity property, respectively. Therefore, if instance annotations are relevant for instances of some entity type, the structure of the entity type gets extended by properties specifically added for the purpose of holding annotation values in the result entities. These extra properties are also annotated with sap:is-annotation=”true” to identify them as
annotation holders and separate them from the other properties of the entity type.

A single entity can have multiple instance annotations, for each of which an extra property gets added to the underlying type:

Zero or more for the entity itself.
Zero or more for every property contained in the entity.

Properties representing instance annotations are always introduced by AnnotationAttributes in the metadata document. The following sections describe the possible occurrences.

Example:

<Property Name="Street" Type="Edm.String" Nullable="true"

sap:field-control="Address_FC"/>

<Property Name="City" Type="Edm.String" Nullable="true"

sap:field-control="Address_FC"/>

<Property Name="Address_FC" Type="Edm.Byte" Nullable="true"

sap:is-annotation="true"/>

Query Option search

Modern user interfaces typically feature a search box for entering a free-text search term, and how exactly this search term is used to find "matching" things is up to the application. The custom query option search is intended exactly for passing such a free-text search term to the backend and let the backend decide against which properties of each entity in the entity set the term is matched, and how. It may also be matched against properties of related entities, e.g.

GET ~/Orders?search=blue

to find all orders with items that refer to a blue product. Service implementations using SAP NetWeaver Gateway OData Channel will receive the search term in the parameter IV_SEARCH_STRING of method GET_ENTITYSET, see http://help.sap.com/saphelp_gateway20sp06/helpdata/en/7b/7ea4676342455c99072ce8815f799d/frameset.htm for details.

Note that search works similar to $filter: it will return a subset of the entities that are returned when no search term is specified. And it combines with $filter, returning only entities that fulfill both conditions.

SAP NETWEAVER GATEWAY 2.0 — GATEWAY BEP	7
SRA004 1.0		2
SRA008 1.0		2
SRA009 1.0		2

SAP NETWEAVER GATEWAY 2.0 — GATEWAY BEP	7
SRA004 1.0		2
SRA008 1.0		2
SRA009 1.0		2

Component Version			Support Package Level

Component Version			Support Package Level

Introduction

Contents

AtomPub Service Document

Element app:service

Element app:collection

Metadata Document

Element edm:EntityContainer

Element edm:EntitySet

Attribute sap:semantics

Element edm:EntityType

Attribute sap:semantics

Element edm:Property

Attributes sap:unit and sap:precision

Attribute sap:field-control

Attribute sap:semantics

Attribute sap:filter-restriction

Attribute sap:aggregation-role

Attribute sap:parameter

Attribute sap:preserve-flag-for

Element edm:NavigationProperty

Element edm:FunctionImport

Element sap:value-constraint

Element edm:Parameter

Element edm:AssociationSet

Instance Annotations

Query Option search