Common terms for all SAP vocabularies 2017-02-15 © Copyright 2013 SAP SE. All rights reserved. Terms, types, and properties annotated with this term are experimental and can be changed incompatibly or removed completely any time without prior warning. Do not use or rely on experimental terms, types, and properties in production environments. URN scheme to look up the documentation for an object with given type and id in a given system. This example looks up the documentation for data element /iwbep/account in system G1Y_000. UI.TextArrangement If the annotated property is (part of) a foreign key of a resource, the external id is a human readable (part of an) identifier of this resource. There is a one-to-one relationship between each possible value of the annotated property and the corresponding external id. The annotation of a parameter refers to a property of the operation binding parameter. Time zones shall be specified according to the [IANA](https://www.iana.org/time-zones) standard. If this annotation is absent or null or an empty string, points in time are typically interpreted in the current user's or default time zone. The annotation value can be a path expression resolving to a property that may be tagged with [`IsTimezone`](#IsTimezone). Multiple secondary keys are possible using different qualifiers. Unlike [`Core.AlternateKeys`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys), secondary keys need not support addressing an entity in a resource path. Entity representing an n:m association with attributes Shortcut for a multi-segment navigation, contains the long path with all its segments Property contains sensitive data that should by default be masked on a UI and clear-text visible only upon user interaction This tag affects only the presentation to the user. The data are still transmitted in the response and can hence be observed using browser tools. By default a masked property is excluded from responses and instead an instance annotation with this term is sent, containing a masked value that can be rendered by user interfaces. When changes are requested, the value of this annotation in the before-image or after-image of the request plays a role. These may differ if the value is given dynamically in the metadata. A request that - sets the property to null or an empty value or - creates a non-[draft](#DraftRoot) entity and omits the property or - activates a draft entity while the property is null or empty fails entirely if this annotation is `Mandatory` in the after-image of the request. The empty string is an empty value. Service-specific rules may consider other values, also of non-string type, empty. Values in draft entities are never considered empty. Mandatory properties SHOULD be decorated in the UI with an asterisk. Null or empty values can also be disallowed by restricting the property value range with the standard type facet `Nullable` or terms from the [Validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md). A request to change the property to a value that differs from the before-image fails entirely according to [OData-Protocol, section 11.4.3](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_UpdateanEntity) if this annotation is given dynamically as `ReadOnly` in the before-image of the request. To statically mark a property as read-only use term [Core.Computed](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Computed) instead. A request that sets the property to a non-initial non-null value fails entirely if this annotation is `Inapplicable` in the after-image of the request. This value does not make sense as a static annotation value. Example for dynamic use: in a travel expense report the property `DestinationCountry` is inapplicable if trip type is domestic, and mandatory if trip type is international. The name of the message type is service-specific, its structure components are identified by naming convention, following the names of the OData error response structure. The minimum structure is - `code: Edm.String` - `message: Edm.String` - `target: Edm.String nullable` - `additionalTargets: Collection(Edm.String)` - `transition: Edm.Boolean` - `numericSeverity: Edm.Byte` - `longtextUrl: Edm.String nullable` When the value of this annotation dynamically references a property, the service MAY omit that property from the default set of properties and clients SHOULD include it in `$select` when needed. The annotated entity type has one or more containment navigation properties. An instance of the annotated entity type provides the context required for determining the target entity sets reached by these containment navigation properties. SAP Object Node Types define the structure of SAP Object Types, which are a generalization of Business Object, Technical Object, Configuration Object, and Analytical Object. The entities related via this navigation property have an existential dependency on their composition parent. The entity set of the composition parent MUST contain a NavigationPropertyBinding for this navigation property. The entity containing the property and the entity referenced by it will in general have different SAP Object Node Types. Common.QuickInfo `CollectionRoot` must not be specified unless `CollectionPath` is provided. Common.ValueListShowValuesImmediately Common.QuickInfo An empty list means a vacuous filter condition UI.Importance UI.Importance UI.Importance Property encodes a year number as string following the logical pattern (-?)YYYY(Y*) consisting of an optional minus sign for years B.C. followed by at least four digits. The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3}) Property encodes a halfyear number as string following the logical pattern H consisting of a single digit. The string matches the regex pattern [1-2] Property encodes a calendar quarter number as string following the logical pattern Q consisting of a single digit. The string matches the regex pattern [1-4] Property encodes a calendar month number as string following the logical pattern MM consisting of two digits. The string matches the regex pattern 0[1-9]|1[0-2] Property encodes a calendar week number as string following the logical pattern WW consisting of two digits. The string matches the regex pattern 0[1-9]|[1-4][0-9]|5[0-3] Day number relative to a calendar month. Valid values are between 1 and 31. Day number relative to a calendar year. Valid values are between 1 and 366. Property encodes a calendar year and halfyear as string following the logical pattern (-?)YYYY(Y*)H consisting of an optional minus sign for years B.C. followed by at least five digits, where the last digit represents the halfyear. The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})[1-2] Property encodes a calendar year and quarter as string following the logical pattern (-?)YYYY(Y*)Q consisting of an optional minus sign for years B.C. followed by at least five digits, where the last digit represents the quarter. The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})[1-4] Property encodes a calendar year and month as string following the logical pattern (-?)YYYY(Y*)MM consisting of an optional minus sign for years B.C. followed by at least six digits, where the last two digits represent the months January to December. The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})(0[1-9]|1[0-2]) Property encodes a calendar year and week as string following the logical pattern (-?)YYYY(Y*)WW consisting of an optional minus sign for years B.C. followed by at least six digits, where the last two digits represent week number in the year. The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})(0[1-9]|[1-4][0-9]|5[0-3]) Property encodes a calendar date: 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. Property encodes a fiscal year number as string following the logical pattern YYYY consisting of four digits. The string matches the regex pattern [1-9][0-9]{3} Property encodes a fiscal period as string following the logical pattern PPP consisting of three digits. The string matches the regex pattern [0-9]{3} Property encodes a fiscal year and period as string following the logical pattern YYYYPPP consisting of seven digits, where the last three digits represent the fiscal period in the year. The string matches the regex pattern ([1-9][0-9]{3})([0-9]{3}) Property encodes a fiscal quarter number as string following the logical pattern Q consisting of a single digit. The string matches the regex pattern [1-4] Property encodes a fiscal year and quarter as string following the logical pattern YYYYQ consisting of five digits, where the last digit represents the quarter. The string matches the regex pattern [1-9][0-9]{3}[1-4] Property encodes a fiscal week number as string following the logical pattern WW consisting of two digits. The string matches the regex pattern 0[1-9]|[1-4][0-9]|5[0-3] Property encodes a fiscal year and week as string following the logical pattern YYYYWW consisting of six digits, where the last two digits represent the week number in the year. The string matches the regex pattern [1-9][0-9]{3}(0[1-9]|[1-4][0-9]|5[0-3]) Day number relative to a fiscal year. Valid values are between 1 and 371. Operations named in this annotation cannot themselves be invoked. Root entities of business documents that support the draft pattern The action is bound to the draft document root and has no parameters. The action is bound to the draft document root and has no parameters. The action is bound to the draft document root and has no parameters. The action is bound to the active document root node and has the signature of [`Template_EditAction`](#Template_EditAction). The action is bound to the draft document root and has no parameters. The action is bound to the draft document root entity set and has the signature of [`Template_NewAction`](#Template_NewAction). In a [recursive hierarchy](Hierarchy.md#RecursiveHierarchy), the payload may contain a `«Superordinate»@odata.bind` element to specify the parent of the new entity. (The UI5 OData model supplies such an element when its action invocation method receives a `@$ui5.node.parent` parameter.) New drafts may also be created by POSTing an entity with property `IsActiveEntity` = `false` (default) to the entity set. The actions are bound to the draft document root entity set and have the signature of [`Template_NewAction`](#Template_NewAction). The action is bound to the draft document root node and has the signature of [`Template_ShareAction`](#Template_ShareAction). It restricts access to the listed users in their specified roles. If this action is present, the client can receive notifications about changes to the collaborative draft by opening a web socket connection at the [`WebSocketBaseURL`](#WebSocketBaseURL) followed by URL parameters - `relatedService` = base URL (relative to server root) of the OData service of the app - `draft` = draft UUID. Entities in this set are parts of business documents that support the draft pattern The namespace-qualified name of an action, optionally followed by parentheses containing the binding parameter type of a bound action overload to identify that bound overload, or by empty parentheses to identify the unbound overload, like in the `Target` attribute of an `Annotation`. If neither TargetProperties nor TargetEntities are specified, a change to the source property values may have unforeseeable side-effects. An empty NavigationPropertyPath may be used in TargetEntities to specify that any property of the annotated entity type may be affected. Side effects without a `TriggerAction` happen immediately when modifying one of the source properties or source entities. Side effects with a `TriggerAction` are deferred until explicitly triggered via the `TriggerAction`. Special case where the side effect is annotated on an action: here the change trigger is the action invocation, so `SourceProperties` and `SourceEntities` have no meaning, only `TargetProperties` and `TargetEntities` are relevant. They are addressed via the binding parameter of the action, e.g. if the binding parameter is named `_it`, all paths have to start with `_it/`. This can also be used with OData V2 services: the annotation target is a function import that is marked with [`sap:action-for`](https://wiki.scn.sap.com/wiki/display/EmTech/SAP+Annotations+for+OData+Version+2.0#SAPAnnotationsforODataVersion2.0-Elementedm:FunctionImport), and all paths have to start with `_it/`. This side effect type indicates that validation messages may result from changes of source properties or entities. Thus, a validation request can be sent either in conjunction with or separately after a modifying request. Validation messages shall be persisted with the draft and immediately available in a subsequent request without repeating the validation logic. This side effect type declares that changes to source properties or entities may impact the values of any, one or multiple target properties or entities. Upon modification preparation logic is performed that determines additional values to be stored in the draft document. This side effect type specifies that source properties or entities may impact the dynamic field control state of any, one or multiple target properties or entities. Upon modification field control logic is invoked so that meta-information like hidden or read-only is determined. Function to calculate default values based on user input that is only known to the client and "context information" that is already available to the service The default values function must have a bound overload whose binding parameter type matches the annotation target - for an entity set: collection of entity type of entity set - for a navigation property: identical to the type of the navigation property (single- or collection-valued) - for a bound action/function: identical to the binding parameter type of the annotated action/function In addition the overload can have non-binding parameters for values that the user has already entered: - for an entity set or navigation property: each non-binding parameter name and type must match the name and type of a property of the entity to be created - for an action or function: each non-binding parameter name and type must match the name and type of a non-binding parameter of the action or function to be called The result type of the default values function is a complex type whose properties correspond in name and type to a subset of - the properties of the entity to create, or - the parameters of the action or function to call Function import to derive a default value for the property from a given context. Function import has two parameters of complex types: - `parameters`, a structure resembling the entity type the parameter entity set related to the entity set of the annotated property - `properties`, a structure resembling the type of the entity set of the annotated property The return type must be of the same type as the annotated property. Arguments passed to the function import are used as context for deriving the default value. The function import returns this default value, or null in case such a value could not be determined. Function import to derive a default value for the property from a given context in order to use it in filter expressions. Function import has two parameters of complex types: - `parameters`, a structure resembling the entity type the parameter entity set related to the entity set of the annotated property - `properties`, a structure resembling the type of the entity set of the annotated property The return type must be of the same type as the annotated property. Arguments passed to the function import are used as context for deriving the default value. The function import returns this default value, or null in case such a value could not be determined. The items of the annotated entity set or the items of the collection of the annotated entity type are sorted by the first entry of the SortOrder collection. Items with same value for this first sort criteria are sorted by the second entry of the SortOrder collection, and so on. If the annotation referenced by the annotation path does not apply to the same collection of entities as the one being sorted according to the [`UI.PresentationVariant`](UI.md#PresentationVariant) or `Common.SortOrder` annotation, this instance of `UI.PresentationVariant/SortOrder` or `Common.SortOrder` MUST be silently ignored. Analytics.AggregatedProperty Aggregation.CustomAggregate Defines a recursive hierarchy. Property holding the descendant count for a hierarchy node. The descendant count of a node is the number of its descendants in the hierarchy structure of the result considering only those nodes matching any specified $filter and $search. A property holding descendant counts has an integer data type. Property holding the drill state of a hierarchy node. The drill state is indicated by one of the following string values: collapsed, expanded, or leaf. For an expanded node, its children are included in the result collection. For a collapsed node, the children are included in the entity set, but they are not part of the result collection. Retrieving them requires a relaxed filter expression or a separate request filtering on the parent node ID with the ID of the collapsed node. A leaf does not have any child in the entity set. In contrast to the `@odata.mediaEditLink` this URL allows to upload new media content without directly changing a stream property or media resource. The upload request typically uses HTTP POST with `Content-Type: multipart/form-data` following RFC 7578. The upload request must contain one multipart representing the content of the file. The `name` parameter in the `Content-Disposition` header (as described in RFC 7578) is irrelevant, but the `filename` parameter is expected. If the request succeeds the response will contain a JSON body of `Content-Type: application/json` with a JSON property `readLink`. The newly uploaded media resource can be linked to the stream property by changing the `@odata.mediaReadLink` to the value of this `readLink` in a subsequent PATCH request to the OData entity. This annotation MUST be unqualified. Messages sent over the channel follow the [ABAP Push Channel Protocol](https://community.sap.com/t5/application-development-blog-posts/specification-of-the-push-channel-protocol-pcp/ba-p/13137541). To consume a channel, the client opens a web socket connection at the [`WebSocketBaseURL`](#WebSocketBaseURL) followed by URL parameters - parameter name = annotation qualifier, parameter value = channel ID (see below) - parameter name = `relatedService`, parameter value = base URL (relative to server root) of the OData service of the app Supported qualifiers and channel IDs: <dl> <dt>`sideEffects` <dd>Notifications about side effects to be triggered by the client (channel ID = non-null annotation value) </dl> Use this tag on services that do not restrict requests to certain resource paths via [`Capabilities`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.html) or [`Core.RequiresExplicitBinding`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.html#RequiresExplicitBinding) annotations, but that prefer requests with a resource path that contains the navigation properties reflecting the UI structure. For example, entering a cancellation fee into an order item field bound to `CancellationItem/Fee` leads to a `PATCH Orders(23)/Items(5)/CancellationItem` request with `{"Fee": ...}` payload. A record that behaves like the standard referential constraint on the navigation property targeted by a [`ReferentialConstraint`](#ReferentialConstraint) annotation, but the nullability requirement for the dependent property is lifted. It asserts that the principal property _of an existing related entity_ must have the same value as the dependent property.