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).

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.

Example 2

This example demonstrates how you can define foreign key relationship.

Example 3

This example demonstrates how you can define language-dependent texts

Example 4

This example demonstrates how you can define language-independent texts

Example 5

This example demonstrates how you can define the transactional behavior