Anotações de UI

As anotações de UI vão do modelo de dados até a tela em quatro etapas:

1. Um desenvolvedor anota entidades e campos no modelo do back-end: ABAP CDS no SAP S/4HANA ou no ambiente ABAP do SAP BTP, ou arquivos CDS em um projeto CAP.
2. Quando o modelo é exposto como um serviço OData, o back-end converte essas anotações em termos do vocabulário OData em XML, entregues com os metadados do serviço ou como um documento de anotação separado.
3. O app SAP Fiori elements carrega os metadados do serviço mais quaisquer fontes adicionais de anotação declaradas em seu app descriptor (manifest.json).
4. Os templates de floorplan, como o list report e o object page, leem os termos e constroem a página: colunas de tabela a partir de UI.LineItem, campos de filtro a partir de UI.SelectionFields, o título do object page a partir de UI.HeaderInfo.

A SAP descreve o vocabulário UI como algo sobre a forma como os dados são usados em uma interface de usuário, e não sobre controles de UI específicos, e é por isso que a mesma anotação pode definir uma tabela no desktop e uma lista no celular. As anotações de UI são, portanto, um contrato entre o serviço e o template, e não código que o app executa.

Dois detalhes poupam tempo. O ABAP CDS usa uma notação no nível do elemento que a exposição do serviço converte no termo OData no nível da entidade. E um mesmo termo pode existir várias vezes com qualificadores diferentes, por exemplo dois line items para duas tabelas. Conhecer essas seis famílias cobre a maior parte do que um list report e um object page precisam das anotações de UI.

• ABAP CDS (RAP e o modelo que o antecedeu): as anotações de UI podem ficar na data definition ou em uma metadata extension. A SAP recomenda metadata extensions, que mantêm o modelo de dados legível e permitem que os metadados de UI evoluam separadamente.
• CAP: as anotações são escritas em CDS com annotate ... with @(...), usando diretamente os nomes dos termos OData; o CAP recomenda arquivos .cds separados nas pastas dos apps, apartados da definição do serviço.
• Arquivo de anotação local: um arquivo XML dentro do app SAP Fiori, registrado como fonte adicional de anotação no manifest.json.
• Serviços SAP Gateway mais antigos (OData V2): anotações modeladas no repositório de vocabulários do Service Builder (SEGW), ou fornecidas por uma classe annotation provider registrada com /IWBEP/REG_VOCAN.

Quando o mesmo termo existe em um arquivo local e no back-end, a definição local substitui a do back-end termo a termo. A orientação da SAP é manter as anotações de UI no back-end, junto ao modelo de dados e com o mesmo ciclo de vida, e usar arquivos locais quando não há acesso ao back-end ou quando um único app precisa de uma sobreposição.

Trabalhe do serviço para fora antes de mexer na UI:

1. Verifique os metadados do serviço. Abra os metadados ou o documento de anotação do serviço e procure o termo. Se ele não estiver lá, o problema está no back-end.
2. Verifique o tipo de service binding (RAP). Um binding da categoria Web API não carrega metadados específicos de UI. Um app Fiori elements precisa de um binding de UI.
3. Verifique a metadata extension. A entidade precisa permitir extensões com @Metadata.allowExtensions: true, e a extensão precisa estar ativa.
4. Verifique se há uma sobreposição local. Um UI.LineItem em um arquivo de anotação local substitui todo o UI.LineItem do back-end, então uma coluna adicionada no CDS nunca aparece.
5. Verifique os qualificadores. Uma anotação qualificada só é usada onde o qualificador é referenciado.
6. Limpe os caches. Os caches de metadados do Gateway e o navegador podem servir metadados antigos. Execute a /IWFND/CACHE_CLEANUP no hub SAP Gateway e a /IWBEP/CACHE_CLEANUP no back-end (ambas em um sistema embedded) e recarregue o app.

A maioria das anotações de UI ausentes são problemas de exposição ou de precedência, não erros de sintaxe.

As anotações de UI são o motivo pelo qual apps SAP Fiori elements podem ser construídos rapidamente e têm aparência consistente: o layout segue as diretrizes de design do SAP Fiori, acessibilidade e responsividade vêm com o template, e o app permanece estável ao longo dos upgrades do SAPUI5 porque contém pouco código.

O mesmo design impõe os limites:

• Apenas o que o template suporta. As anotações selecionam e organizam; não conseguem inventar um layout que o floorplan não oferece. Qualquer coisa além disso exige extension points ou SAPUI5 freestyle.
• Apresentação, não comportamento. Validações, ações e lógica de autorização ficam no RAP ou no CAP; uma anotação pode exibir um botão, não implementá-lo.
• Espalhadas em várias camadas. Arquivos do back-end, metadata extensions e arquivos locais se combinam em tempo de execução, o que dificulta revisar o resultado final.
• Risco de divergência. Anotações locais quebram silenciosamente quando uma propriedade é renomeada no back-end.

As anotações de UI funcionam melhor quando a equipe as trata como parte do modelo de dados e as revisa junto com ele.