Anotaciones de UI

Las anotaciones de UI viajan del modelo de datos a la pantalla en cuatro pasos:

1. Un desarrollador anota entidades y campos en el modelo del back-end: ABAP CDS en SAP S/4HANA o en el entorno ABAP de SAP BTP, o archivos CDS en un proyecto CAP.
2. Cuando el modelo se expone como servicio OData, el back-end traduce esas anotaciones a términos del vocabulario OData en XML, que se entregan con los metadatos del servicio o como un documento de anotaciones independiente.
3. La aplicación SAP Fiori elements carga los metadatos del servicio y las fuentes de anotaciones adicionales declaradas en su app descriptor (manifest.json).
4. Las plantillas de floorplan, como el list report y la object page, leen los términos y construyen la página: las columnas de tabla a partir de UI.LineItem, los campos de filtro a partir de UI.SelectionFields y el título de la object page a partir de UI.HeaderInfo.

SAP describe el vocabulario UI como relativo a cómo se usan los datos en una interfaz de usuario, no a controles de UI concretos, y por eso la misma anotación puede definir una tabla de escritorio y una lista en un teléfono. Por tanto, las anotaciones de UI son un contrato entre el servicio y la plantilla, no código que la aplicación ejecuta.

Dos detalles ahorran tiempo. ABAP CDS usa una notación a nivel de elemento que la exposición del servicio convierte en el término OData a nivel de entidad. Además, un mismo término puede existir varias veces con distintos qualifiers, por ejemplo dos line items para dos tablas. Conocer estas seis familias cubre la mayor parte de lo que un list report y una object page necesitan de las anotaciones de UI.

• ABAP CDS (RAP y su modelo predecesor): las anotaciones de UI pueden estar en la data definition o en una metadata extension. SAP recomienda las metadata extensions, que mantienen legible el modelo de datos y permiten que los metadatos de UI evolucionen por separado.
• CAP: las anotaciones se escriben en CDS con annotate ... with @(...), usando directamente los nombres de los términos OData; CAP recomienda archivos .cds separados en las carpetas de la aplicación, aparte de la definición del servicio.
• Archivo de anotaciones local: un archivo XML dentro de la aplicación SAP Fiori, registrado como fuente de anotaciones adicional en manifest.json.
• Servicios SAP Gateway más antiguos (OData V2): anotaciones modeladas en el repositorio de vocabularios del Service Builder (SEGW) o proporcionadas por una clase annotation provider registrada con /IWBEP/REG_VOCAN.

Cuando el mismo término existe en un archivo local y en el back-end, la definición local sustituye a la del back-end término por término. La recomendación de SAP es mantener las anotaciones de UI en el back-end, junto al modelo de datos y con su mismo ciclo de vida, y usar archivos locales cuando no hay acceso al back-end o una sola aplicación necesita una sobrescritura.

Trabaje desde el servicio hacia fuera antes de tocar la UI:

1. Compruebe los metadatos del servicio. Abra el documento de metadatos o de anotaciones del servicio y busque el término. Si no está, el problema está en el back-end.
2. Compruebe el tipo de service binding (RAP). Un binding de la categoría Web API no incluye metadatos específicos de UI. Una aplicación Fiori elements necesita un binding de UI.
3. Compruebe la metadata extension. La entidad debe permitir extensiones con @Metadata.allowExtensions: true, y la extensión debe estar activa.
4. Compruebe si hay una sobrescritura local. Un UI.LineItem en un archivo de anotaciones local sustituye todo el UI.LineItem del back-end, de modo que una columna añadida en CDS nunca aparece.
5. Compruebe los qualifiers. Una anotación con qualifier solo se usa donde se hace referencia a ese qualifier.
6. Vacíe las cachés. Las cachés de metadatos de Gateway y el navegador pueden servir metadatos antiguos. Ejecute /IWFND/CACHE_CLEANUP en el hub de SAP Gateway y /IWBEP/CACHE_CLEANUP en el back-end (ambas en un sistema embedded) y, después, vuelva a cargar la aplicación.

La mayoría de las anotaciones de UI que no aparecen se deben a problemas de exposición o de precedencia, no a errores de sintaxis.

Las anotaciones de UI son la razón por la que las aplicaciones SAP Fiori elements pueden construirse rápido y tener un aspecto coherente: el diseño sigue las directrices de diseño de SAP Fiori, la accesibilidad y el diseño adaptable vienen con la plantilla, y la aplicación se mantiene estable en las actualizaciones de SAPUI5 porque contiene poco código.

El mismo diseño marca los límites:

• Solo lo que la plantilla admite. Las anotaciones seleccionan y organizan; no pueden inventar un diseño que el floorplan no ofrece. Todo lo que vaya más allá necesita puntos de extensión o SAPUI5 freestyle.
• Presentación, no comportamiento. Las validaciones, las acciones y la lógica de autorización residen en RAP o CAP; una anotación puede mostrar un botón, no implementarlo.
• Repartidas entre capas. Los archivos del back-end, las metadata extensions y los archivos locales se combinan en tiempo de ejecución, lo que dificulta revisar el resultado final.
• Riesgo de desalineación. Las anotaciones locales dejan de funcionar sin avisar cuando se cambia el nombre de una propiedad en el back-end.

Las anotaciones de UI funcionan mejor cuando el equipo las trata como parte del modelo de datos y las revisa junto con él.