Adding Vocabulary-Based Annotations to Data Model Artifacts

Explains how to add vocabulary-based annotations to data model artifacts in the Service Builder.

Context

Add vocabulary-based annotations to data model artifacts such as complex types, entity types, and associations, for example, to specify information about a particular artifact that would not be possible using core attributes alone. To add vocabulary-based annotations, you can use the vocabulary files available in the Vocabulary Repository as standard in the /IWBEP namespace or you can define and upload customer-specific vocabulary files. For example, you might want to use ths standard vocabulary Ord.OData.Aggregation.V1 to add the annotations LeveledHierarchy or RecursiveHierarchy to entity types for which otherwise only core attributes could be defined such as Base Type Name and Is Abstract. You can import one or more vocabulary files for use in a data model provided that the data model is created in a Service Builder project of type Service with Vocabulary-Based Annotations.

Ensure that at least one vocabulary file has been uploaded into the Vocabulary Repository. Furthermore, you must have created a Service Builder project of type Service with Vocabulary-Based Annotations into which you have imported one or more vocabulary files from the Vocabulary Repository. To import a vocabulary file, ensure the project is in edit mode, right click the Data Model folder and choose Start of the navigation path Import Next navigation step Vocabulary End of the navigation path .

After you have imported a vocabulary file into your data model, a Vocabularies subfolder is displayed for the data model in the tree view. The Vocabularies subfolder includes:

Imports subfolder that lists the name of the vocabulary files explicitly imported from the Vocabulary Repository to the data model. For each imported vocabulary file, you can expand the data model artifacts for which it applies, for example, complex types and their properties and the defined terms.
Implicit References subfolder that lists the names of the vocabulary files used implicitly since the imported vocabularies reference it. For each implicitly referenced vocabulary file, you can expand the data model artifacts for which it applies, for example, complex types and their properties and the defined terms.

Double-click the Vocabularies subfolder to display the available vocabularies in an overview table in the mass maintenance view. This overview displays the vocabulary ID, version, namespace, and a description (if available). Futher, nestled inside each subfolder for a particular entity type or complex type, for example, in the data model, an Annotations subfolder exists that lists the imported vocabularies and specifies the number of applicable terms each vocabulary defines for the given node. These are the vocabulary-based annotations you can add to these artifacts. If, however, a vocabulary cannot be applied to a given artifact, the vocabulary is displayed in a grey (as opposed to black) font and the following descriptive text is displayed, Vocabulary does not define applicable terms for target node type Entity Type. To see this additional information about imported vocabularies, the hierarchy view must be displayed in full-screen mode. Close any overviews in the mass maintenance area if you cannot see this information.

To add annotations to artifacts for which vocabularies define applicable terms, proceed as follows:

Procedure

Double-click the subfolder that contains the artifacts you want to annotate, for example, Entity Sets. Existing entity sets are listed in the mass maintenance view.
Choose the Annotation pushbutton to see the vocabulary that is valid for these entity sets. If more than one vocabulary defines applicable terms, you can select the vocabulary you want to use to annotate the entity set and, if required, toggle between the different vocabularies. If none of the imported vocabularies includes applicable terms for entity sets, for example, this pushbutton is not enabled. After you have selected the vocabulary you want to use for the annotations, all entity sets are displayed in a table in the mass maintenance view with the name of the applicable vocabulary displayed as a header.
To create annotations for an entity set, select either the entire row to create all available annotations or select the applicable cells for each annotation you want to create and choose the Create Annotation pushbutton. You can select more than one row and more than one cell to enable the mass maintenance of multiple entity sets and annotations, for example. The annotations you have created for a particular artifact are also displayed in the Annotations subfolder, organized according to vocabulary, for each node in the data model's hierarchy view.
To display detailed information (annotation data, term type, and expression value) about an annotation, double-click the annotation. The annotation data is then displayed in an additional table. If you want to display detailed information about all the annotations created for a particular entity set, double-click the entity set itself.
If you want to delete any annotations, select the relevat rows or cells and choose the Delete Annotation pushbutton.
Save your entries. If you want to navigate from the annotation mass maintenance view and see an overview of the core attributes (SAP annotations) that can be defined for the entity set, choose the Core Attributes pushbutton.