Annotations d'interface

Les annotations d'interface passent du modèle de données à l'écran en quatre étapes :

1. Un développeur annote les entités et les champs dans le modèle back-end : ABAP CDS dans SAP S/4HANA ou dans l'environnement ABAP de SAP BTP, ou fichiers CDS dans un projet CAP.
2. Lorsque le modèle est exposé comme service OData, le back-end traduit ces annotations en termes de vocabulaire OData au format XML, livrés avec les métadonnées du service ou sous forme de document d'annotations distinct.
3. L'application SAP Fiori elements charge les métadonnées du service ainsi que les éventuelles sources d'annotations supplémentaires déclarées dans son app descriptor (manifest.json).
4. Les templates de floorplan, comme le list report et l'object page, lisent les termes et construisent la page : les colonnes du tableau à partir d'UI.LineItem, les champs de filtre à partir d'UI.SelectionFields, le titre de l'object page à partir d'UI.HeaderInfo.

SAP décrit le vocabulaire UI comme portant sur l'usage des données dans une interface utilisateur, et non sur des contrôles d'interface précis ; c'est pourquoi une même annotation peut piloter un tableau sur poste de travail et une liste sur téléphone. Les annotations d'interface sont donc un contrat entre le service et le template, et non du code que l'application exécute.

Deux détails font gagner du temps. ABAP CDS utilise une notation au niveau de l'élément que l'exposition du service transforme en terme OData au niveau de l'entité. Et un même terme peut exister plusieurs fois avec des qualifiers différents, par exemple deux line items pour deux tableaux. Maîtriser ces six familles couvre l'essentiel de ce dont un list report et une object page ont besoin en matière d'annotations d'interface.

• ABAP CDS (RAP et son modèle prédécesseur) : les annotations d'interface peuvent figurer dans la data definition ou dans une metadata extension. SAP recommande les metadata extensions, qui gardent le modèle de données lisible et permettent aux métadonnées d'interface d'évoluer séparément.
• CAP : les annotations s'écrivent en CDS avec annotate ... with @(...), en utilisant directement les noms des termes OData ; CAP recommande des fichiers .cds distincts dans les dossiers de l'application, séparés de la définition du service.
• Fichier d'annotations local : un fichier XML dans l'application SAP Fiori, déclaré comme source d'annotations supplémentaire dans manifest.json.
• Services SAP Gateway plus anciens (OData V2) : annotations modélisées dans le référentiel de vocabulaires du Service Builder (SEGW), ou fournies par une classe annotation provider enregistrée avec /IWBEP/REG_VOCAN.

Lorsque le même terme existe dans un fichier local et dans le back-end, la définition locale remplace celle du back-end, terme par terme. SAP recommande de conserver les annotations d'interface dans le back-end, à côté du modèle de données et avec son cycle de vie, et d'utiliser des fichiers locaux lorsqu'il n'y a pas d'accès au back-end ou qu'une seule application a besoin d'une surcharge.

Partez du service vers l'extérieur avant de toucher à l'interface :

1. Vérifiez les métadonnées du service. Ouvrez le document de métadonnées ou d'annotations du service et recherchez le terme. S'il n'y figure pas, le problème se situe dans le back-end.
2. Vérifiez le type de service binding (RAP). Un binding de catégorie Web API ne transporte aucune métadonnée propre à l'interface. Une application Fiori elements a besoin d'un binding UI.
3. Vérifiez la metadata extension. L'entité doit autoriser les extensions avec @Metadata.allowExtensions: true, et l'extension doit être active.
4. Recherchez une surcharge locale. Un UI.LineItem dans un fichier d'annotations local remplace l'intégralité de l'UI.LineItem du back-end ; une colonne ajoutée en CDS n'apparaît alors jamais.
5. Vérifiez les qualifiers. Une annotation qualifiée n'est utilisée que là où son qualifier est référencé.
6. Videz les caches. Les caches de métadonnées de Gateway et le navigateur peuvent servir d'anciennes métadonnées. Exécutez /IWFND/CACHE_CLEANUP sur le hub SAP Gateway et /IWBEP/CACHE_CLEANUP dans le back-end (les deux dans un système embedded), puis rechargez l'application.

La plupart des annotations d'interface manquantes relèvent de problèmes d'exposition ou de priorité, pas d'erreurs de syntaxe.

Les annotations d'interface expliquent pourquoi les applications SAP Fiori elements se construisent rapidement et présentent un aspect cohérent : la mise en page suit les SAP Fiori design guidelines, l'accessibilité et le responsive sont fournis par le template, et l'application reste stable lors des mises à niveau SAPUI5 parce qu'elle contient peu de code.

Cette même conception en fixe les limites :

• Uniquement ce que le template prend en charge. Les annotations sélectionnent et agencent ; elles ne peuvent pas inventer une mise en page que le floorplan ne propose pas. Tout ce qui va au-delà nécessite des points d'extension ou du SAPUI5 freestyle.
• La présentation, pas le comportement. Les validations, les actions et la logique d'autorisation se trouvent dans RAP ou CAP ; une annotation peut afficher un bouton, pas l'implémenter.
• Une dispersion entre couches. Les fichiers back-end, les metadata extensions et les fichiers locaux se combinent à l'exécution, ce qui complique la revue du résultat final.
• Un risque de dérive. Les annotations locales cessent de fonctionner sans signal lorsqu'une propriété est renommée dans le back-end.

Les annotations d'interface fonctionnent le mieux lorsque l'équipe les traite comme une partie du modèle de données et les revoit avec lui.