ObjectModel Annotations

Provide definitions of structural as well as transactional related aspects of the business data model

Scope and Definition

@Scope:[#VIEW]
Annotation ObjectModel
 {
   lifecycle
   {
      enqueue
      {
         expiryBehavior : String enum { RELATIVE_TO_ENQUEUE_START; RELATIVE_TO_LAST_CHANGE; } default #RELATIVE_TO_LAST_CHANGE;
         expiryInterval : String;
         notificationBeforeExpiryInterval : String;
      };
      processing
      {
         expiryBehavior : String enum { RELATIVE_TO_PROCESSING_START; RELATIVE_TO_LAST_CHANGE; } default #RELATIVE_TO_LAST_CHANGE;
         expiryInterval : String;
         notificationBeforeExpiryInterval : String;
      };
   };
   modelCategory : String enum { BUSINESS_OBJECT; };
   dataCategory : String enum { TEXT; HIERARCHY; };
   representativeKey : keyElementRef;
   semanticKey : array of elementRef;
   compositionRoot : Boolean default true;
   transactionalProcessingEnabled : Boolean default true;
   transactionalProcessingDelegated : Boolean default true;
   createEnabled : Boolean default true;
   updateEnabled : Boolean default true;
   deleteEnabled : Boolean default true;
   writeDraftPersistence : String;
   writeActivePersistence : String;
   entityChangeStateId : elementRef;
 };
@Scope:[#ELEMENT] 
Annotation ObjectModel
 {
   association
   {
      type : array of String enum { TO_COMPOSITION_CHILD; TO_COMPOSITION_PARENT; TO_COMPOSITION_ROOT; };
   };
   createEnabled : Boolean default true;

   text
   {
      element : array of elementRef;
      association : associationRef;
   };
   hierarchy
   {
      association : associationRef;
   };      
   foreignKey
   {
      association : associationRef;
   };
   readOnly : Boolean default true;
   mandatory : Boolean default true;
   enabled : Boolean default true;
 };

Usage

Annotation	Meaning
`ObjectModel.association.type[ ]`	Defines the association type that is used for defining a compositional view hierarchy. Scope: [ELEMENT] Evaluation Runtime (Engine): SADL: Influences the scope of the OData auto-exposure (`@OData.publish:true`): All views that are included in the view hierarchy are automatically included in the same OData V2-service. BOPF: Influences the scope of the BOPF Business Object generation (`@ObjectModel.transactionalProcessingEnabled : true`): All views that are included in the view hierarchy are automatically included in the same BOPF business object. Values:
	Value	Description
	`#TO_COMPOSITION_CHILD`	Within the compositional hierarchy there must be a `#TO_COMPOSITION_CHILD` association leading to each direct sub view of a given view.
	`#TO_COMPOSITION_PARENT`	Views that do not represent the root of the hierarchy must have an association to their compositional parent view annotated with `#TO_COMPOSITION_PARENT.`
	`#TO_COMPOSITION_ROOT`	Additionally, views that do not represent the root must have a `#TO_COMPOSITION_ROOT` association for performance reasons (for example: authorization checks (instance restrictions) based of information from root views). NOTE: In such a case, the root view of the hierarchy must be annotated with `@ObjectModel.compositionRoot: true` .
`ObjectModel.compositionRoot`	Defines the root of a compositional hierarchy Scope: [VIEW]
`ObjectModel.createEnabled`	If this annotation has value `true`, it is allowed to create new instances. Scope: [VIEW] Evaluation Runtime (Engine): SADL: Exposes this information BOPF: Rejects create requests that do not provide a value `true` for this field (in case of static field control). With the value `'EXTERNAL_CALCULATION'`, the create property is calculated in a BOPF property determination (dynamic field control).
`ObjectModel.dataCategory`	Defines the category of data that is represented by the below-mentioned values. Scope: [VIEW] Evaluation Runtime (Engine): In ABQL joins between a Data- and a Text entity without explicit language key handling will be interpreted as a 1 : (0,1) association, where the language key is defaulted with the logon language. Values:
	Value	Description
	`#TEXT`	Indicates that the annotated entity represents texts. Usually one key element is of type language. NOTE: Within the VDM a text view is always language-dependent.
	`#HIERARCHY`	Indicates that the entity represents the hierarchy-related data. This could be a header information or structure information.
`ObjectModel.deleteEnabled`	If this annotation has value `true`, it is allowed to delete existing instances. Scope: [VIEW] Evaluation Runtime (Engine): SADL: Exposes this information BOPF: Rejects delete requests that do not provide a value `true` for this field (in case of static field control). With the value `'EXTERNAL_CALCULATION'`, the delete property is calculated in a BOPF property determination (dynamic field control).
`ObjectModel.enabled`	If this annotation has the value `true`, the corresponding element (field or association) is supported at runtime. Scope: [ELEMENT] Evaluation Runtime (Engine): SADL: Exposes this information
`ObjectModel.entityChangeStateId`	This annotation is related to a single field that contains the change state of an active document. The change state is always updated as soon as the document is changed. Usually, fields like last changed timestamp, hash values, or version counters are used as `EntityChangeStateIds`. Scope: [VIEW]
`ObjectModel.foreignKey.association`	Defines association to a view that represents a value list/check table of the annotated filed. The annotated field must be valuated as equal to the annotated representative key field of the target view. The maximum target cardinality of the association has to be 1. Scope: [ELEMENT] Evaluation Runtime (Engine): Analytic Manager: Uses associated view as `DIMENSION` view for the annotated field. SADL: Derives a default value help support from the foreign key relationship.
`ObjectModel.hierarchy.association`	This annotation can be added to the key field that specifies the association to a hierarchy view. The hierarchy view defines an external hierarchy for the instances of the current view and is annotated with `@ObjectModel.dataCategory: #HIERARCHY`. Scope: [ELEMENT] Evaluation Runtime (Engine): Analytic Manager: Uses associated view for hierarchical presentation.
`ObjectModel.lifecle.enqueue.expiryBehavior`	The creation of an exclusive draft related to an existing active document causes an exclusive durable lock of the active document. The `lifecycle.enqueue.` annotations allow to overrule the global defaults for the durable lock expiration handling. After a certain period of time, the durable exclusive lock on the active document has to be released. This period of time is defined by the expiration behavior. Enqueue Expiration Behavior: `RELATIVE_TO_ENQUEUE_START` - The period of time starts from the point in time the exclusive durable lock has been initially acquired. `RELATIVE_TO_LAST_CHANGE` - The interval describes the period of inactivity (no modifying roundtrips to the draft document), after that the exclusive durable lock has to be removed Scope:* [VIEW] Evaluation Runtime (Engine): The lifecycle services automatically unlock active documents accordingly to the defined enqueue expiration behavior.
`ObjectModel.lifecle.enqueue.expiryInterval`	Using this annotation, you can specify an interval to overrule the default duration. The value must be compliant to the `dayTimeDuration` format (http://www.w3.org/TR/xmlschema11-2/#dayTimeDuration). Scope: [VIEW]
`ObjectModel.lifecle.enqueue.notificationBeforeExpiryInterval`	To notify the draft processor in advance before the expiration takes place, a notification will be send. The default warning interval can be overruled by the help of annotation `notificationBeforeExpiryInterval` using the valid `dayTimeDuration` format (http://www.w3.org/TR/xmlschema11-2/#dayTimeDuration). Scope: [VIEW]
`ObjectModel.lifecle.processing.expiryBehavior`	After the durable lock expiration phase has been processed for an exclusive draft, the durable lock of its active document is released. However for draft-aware applications it is still not allowed to create a new draft related to the same active document until the processing of the existing draft is expired. The `lifecycle.processing.` annotations allow to overrule the global defaults for the draft processing expiration handling. After a certain period of time, the processor is removed from an exclusive draft and a different user is allowed to create a new draft related to the same active document. In that case, the first draft is deleted. Otherwise, the editing for the first draft can be continued at a later point in time. The default processing expiration settings can be overruled like the `lifecycle.enqueue.` annotations by the help of a behavior, duration interval and notification interval. Scope: [VIEW] Evaluation Runtime (Engine): The lifecycle services automatically set the processing status of a draft accordingly to the defined processing expiration behavior.
`ObjectModel.lifecle.processing.expiryInterval`	Using this annotation, you can specify an interval to overrule the default duration interval. Scope: [VIEW]
`ObjectModel.lifecle.processing.notificationBeforeExpiryInterval`	Using this annotation, you can specify an interval to overrule the default notification interval. Scope: [VIEW]
`ObjectModel.mandatory`	If this annotation has value `true`, the field must be filled by the consumer when executing a modification. Scope: [ELEMENT] Evaluation Runtime (Engine): SADL: Exposes this information BOPF: Rejects modifications that do not provide a value `true` for this field (in case of static field control). With the value `'EXTERNAL_CALCULATION'`, the mandatory property is calculated in a BOPF property determination (dynamic field control).
`ObjectModel.modelCategory`	Each business object can semantically be categorized using this object model setting Scope: [VIEW] Evaluation Runtime (Engine): The model category must not have any runtime effect but is used for a semantic grouping, for example in view browsers. Values:
	Value	Description
	`#BUSINESS_OBJECT`	View that represents a BOPF business object
`ObjectModel.readOnly`	If this annotation has the value `true`, the field must not be updated by the consumer. Scope: [ELEMENT] Evaluation Runtime (Engine): SADL: Exposes this information BOPF: Rejects modifications when updating fields that are defined as `@ObjectModel.readOnly: true` (in case of static field control). With the value `'EXTERNAL_CALCULATION'`, the readonly property is calculated in a BOPF property determination (dynamic field control).
`ObjectModel.representativeKey`	Most specific element (field or managed association) of the primary key (indicated by the keyword KEY) that represents the entity which the view is based on. This element shall be used as the anchor for defining foreign key relationships (except for text views): The foreign key field corresponding to the representative key represents the entity. As such it can be called representative foreign key element. The foreign key association is defined on the representative foreign key element. The name of the representative key typically equals the name of the entity represented by the view. For non-text views it is the key element for which the view serves as a value list/check table. For text views (`@ObjectModel.dataCategory: #TEXT`) it identifies the key element to which the text fields relate to. The representative key element has to be modelled explicitly even if there is only one primary key field (no implicit derivation). A view may only become a target of a foreign key association if it has a representative key element (exception: language dependent text views may not be used as targets of foreign key relationships) Scope: [VIEW] Evaluation Runtime (Engine): Analytic Manager: In analytics, both the grouping by the entity and the hierarchical representation of the entity are handled using the representative foreign key field.
`ObjectModel.semanticKey[ ]`	Identifies an instance of an entity from business perspective using human-readable field values. It does neither contain time-/language-dependent nor other technical components (for example: draft indicator). Thus it may be ambiguous resulting in multiple selected records/instances of a view that may need to be filtered using contextual information (for example: current date, preferred language). For a given entity, only a single semantic key is defined. Scope: [VIEW] Evaluation Runtime (Engine): UI: Uses semantic key for bookmarking and navigation.
`ObjectModel.text.association`	Defines the associated view (annotated with `@ObjectModel.dataCategory: #TEXT`), which provides textual descriptions for the annotated field. NOTE: The usage of this annotation excludes the usage of `@ObjectModel.text.element`. Scope: [ELEMENT] Evaluation Runtime (Engine): SADL - Enriches the OData entity type of the view with the textual description of the target view applying an automated language filtering. The name of the auto-generated text property will be composed out of the annotated field name and the constant suffix _Text. This OData property is mapped onto the first text field of the associated target CDS view annotated with `@Semantics.text:true`. Analytic Manager - Uses the associated view as TEXT view for annotated field.
`ObjectModel.text.element[ ]`	Establishes the conjunction of a field with its descriptive language-independent texts. NOTE: The usage of this annotation excludes the usage of `@ObjectModel.text.association`. Scope: [ELEMENT] Evaluation Runtime (Engine): SADL - First text field listed in the annotation array will be handled as descriptive text of the annotated field in OData exposure scenarios.
`ObjectModel.transactionalProcessingEnabled`	Enables the transactional runtime support. It may only be defined on root view level (`@ObjectModel.compositionRoot: true`). Scope: [VIEW] Evaluation Runtime (Engine): BOPF: Depending on the specified `@ObjectModel.write<…>Persistence` information, we can distinguish the following scenarios: a) `writeActivePersistence`: Active data (defined by that CDS view) is directly modified by the transactional runtime (without having any kind of draft). b) `writeDraftPersistence`: Active data (defined by that CDS view) is only indirectly modified by a draft. c) `writeActivePersistence` & `writeDraftPersistence`: Both the draft and the active data are written by the transactional runtime.
`ObjectModel.transactionalProcessingDelegated`	Indicates that transactional accesses to the view are delegated to the transactional runtime of the underlying view (which is annotated with `@ObjectModel.transactionalProcessingEnabled:true`). It may only be defined on root view level `(@ObjectModel.compositionRoot:true`). Scope: [VIEW] Evaluation Runtime (Engine): SADL: Uses the information to delegate requests to the transactional runtime
`ObjectModel.updateEnabled`	If this annotation has value `true`, it is allowed to update existing instances. Scope: [VIEW] Evaluation Runtime (Engine): SADL: Exposes this information BOPF: Rejects modification requests that do not provide a value `true` for this field (in case of static field control). With the value `'EXTERNAL_CALCULATION'`, the update property is calculated in a BOPF property determination (dynamic field control).
`ObjectModel.writeActivePersistence`	Defines the DDIC database table name of the active view. This requires`@ObjectModel.transactionalProcessingEnabled: true` Scope: [VIEW]
`ObjectModel.writeDraftPersistence`	Defines the DDIC database table name of the draft data. This requires `@ObjectModel.transactionalProcessingEnabled: true` Scope: [VIEW]
`ObjectModel.writeEnabled` - Deprecated!	Enables the transactional runtime support. It may only be defined on root view level (`@ObjectModel.compositionRoot: true`). Caution Do not use this annotation an more! It is replaced by `ObjectModel.transactionalProcessingEnabled`. Scope: [VIEW] Evaluation Runtime (Engine): BOPF - Depending on the specified persistence information, we can distinguish between the folllowing scenarios: a) `writeActivePersistence`: Active data (defined by that CDS view) is directly modified by the transactional runtime (without having any kind of draft). b) `writeDraftPersistence`: Active data (defined by that CDS view) is only indirectly modified by a draft. c) `writeActivePersistence` & `writeDraftPersistence`: Both the draft and the active data are written by the transactional runtime.

Examples

Example 1

This example demonstrates how you can define a compositional hierarchy.

Sample Code

@ObjectModel.modelCategory: #BUSINESS_OBJECT
@ObjectModel.compositionRoot: true
define view I_SalesOrder 
  	association [0..*] to I_SalesOrderItem as _Item ... {
		@ObjectModel.association.type: #TO_COMPOSITION_CHILD
		_Item, ...
}

define view I_SalesOrderItem
 	association [1..1] to I_SalesOrder as _SalesOrder ... { 
		@ObjectModel.association.type: [#TO_COMPOSITION_ROOT, 
                                #TO_COMPOSITION_PARENT]
		_SalesOrder, ...
}

Example 2

This example demonstrates how you can define foreign key relationship.

Sample Code

define view I_SalesOrderItem 
  association [0..1] to I_Material as _Material 
    on $projection.Material = _Material.Material ... { 
      @ObjectModel.foreignKey.association: ’_Material’
      Material,
      _Material, ...
}

@ObjectModel.representativeKey: ’Material’
define view I_Material ... { 
     key Material, ...
}

Example 3

This example demonstrates how you can define language-dependent texts

Sample Code

define view I_Material 
  association [0..*] to I_MaterialText as _Text ... { 
      @ObjectModel.text.association: ’_Text’
      key Material, 
      _Text, ...
}

@ObjectModel.dataCategory: #TEXT
@ObjectModel.representativeKey: ’Material’
define view I_MaterialText ... { 
      key Material, 
      @Semantics.language: true
      key Language,
      @Semantics.text: true
      MaterialName,
      @Semantics.text: true
      MaterialDescription, ...
}

Example 4

This example demonstrates how you can define language-independent texts

Sample Code

define view I_Plant ... { 
      @ObjectModel.text.element: [’PlantName’]
      key Plant, 
      @Semantics.text: true
      PlantName, ...
}

Example 5

This example demonstrates how you can define the transactional behavior

Sample Code

@ObjectModel.compositionRoot: true
@ObjectModel.transactionalProcessingEnabled: true
@ObjectModel.writeDraftPersistence: ‘<DraftDDICTable>’
define view I_MaterialWithDraft ... { 
   ...
}