En este blog quiero mostrar el modelo CAP y compartir lo que pienso que fue interesante durante mi aprendizaje en este tema. Quiero agradecer al equipo de developer advocates de SAP y a Amar Ubhe por su pregunta en uno de los posts. Yo segui videos de you tube, sap tutorials, github repos y lei mucho acreca del tema, las cadenas de todos los recursos que utilize mas abajo. Para leer este blog en ingles, ve aqui

Con mi background en aplicaciones Fiori y en XSA APIs me ayudo a entender ciertas partes del rompe cabezas al momento de trabajar en este ejercicio (como entender los archivos mta yaml file, las dependencias de módulos npm, el instalar módulos npm, también saber como correr scripts de npm, el middleware proxy, y la línea de comandos, command line.

Antes de entar al tema de CAP, decidi buscar otras cosas que se referian a las siglas CAP; suficiente interesante encontré esto:

• Definicion: una cubierta para la cabeza con visor – me recuerda del BTP cockpit el cual cubre lo que sucede dentro de la cuenta de uno en el BTP y puede ayudar a visualizar las aplicaciones y servicios bajo el visor.

• Definicion 2: una capa de piedra dificil de penetrar – fijate que si, pues al usar el servicio XSUAA a tu proyecto CAP, veras por ti mismo la situación que algunas veces no puedes accederlo tu mismo lol (riete por un segundo, lo resolveremos en este blog)

• Como siglas en ingles: CAP se refiere a Civil Air Patrol y tambien a Combat Air Patrol. Me gustan estas definiciones debido a que ambas se refieren a algo en el aire (o a la nube en mi caso), pude encontrar semejanzas en ambas siglas:
  1. Civil Air Patrol – estoy tratando de construer y aprender CAP en el modelo de programación de la nube CAP
  2. Combat Air Patrol – Estoy construyendo aplicaciones CAP applications and y asegurandome de defender un target (destino).

Y solo por pilon, un shockwave se refiere al fenomeno que sucede cuando la barrera del sonido se rompe cuando los jets vuelan muy rapido / quiero que mi aplicación sea así de rápida en la nube

Empezemos a aprender acerca del #BTP – Business Technology Platform. Para mejor entender el BTP, es importante saber acerca del modelo y la herarquia de Cloud Foundry (CF).

Hay un Org que esta compuesto de 1 o mas spaces. Dentro del space hay 1 o mas apps y services. Aqui esta el enlace a la documentación oficial https://help.sap.com/docs/btp/sap-business-technology-platform/account-model

Y esta imagen es como lo entiendo yo

Que es un org? un Org es la entidad de mero arriba cuando una cuenta es asignada a un cliente. En las cuentas de paga, esto se refiera a la organización que creo la cuenta. En la capa gratis del BTP, BTP te asignara un nombre.

Que es un space? Un Space es un grupo de recursos, aplicaciones, servicios y otros recursos que interactuan dentro del ambiente, por ejemplo, yo puedo tener un espacio para desarrollo, otro para control de calidad QA  y así sucesivamente. 1 o mas espacios pueden existir dentro de un Org.

Que son aplicaciones y servicos?

Aplicaciones son tus custom apps y los APIs que creas en tus proyectos. Estos eventualmente son creados en el BTP como microservicios.

Servicios (o Service Instances) son created y utilizados dentro de tu aplicacion. Por ejemplo, el servicio XSUAA se usa para autenticar usuarios a la aplicacion o al API. 0 o mas aplicaciones pueden usar estos servicios los cuales existen dentro del espacio (space).

Bajo al nivel de servicios y aplicaciones, los usuarios tienen acceso a estos recursos los cuales son asignados por medio de roles o collecion de roles (grupo de roles).

Como se relaciona esto a lo que estoy construyendo en CAP?

Antes de iniciar con la aplicacion de CAP, identifiquemos la informacion que utlizaremos mas delante cuando conectemos y hagamos deployment:

• CF endpoint
• Nombre del org
• Nombre del space

Las primeras tres lineas de informacion se encuentran en la pagina overview del BTP cockpit bajo la sección de Cloud Foundry

• Entitlements – es el derecho a pedir y asignar recursos. Tienes el derecho a usar ciertos servicios como el Business Application Studio (#BAS) or el servicio de SAP HANA Schemas & HDI contenedores. Desde el BTP cockpit, puedes navegar a esta pagina usando el navegador del lado izquierdo (sección después de security en la imagen anterior). Algunos servicios no estan abilitados por default como lo es el servicio de BAS y lo tienes que abilitar para poder usarlo.

• HANA DB – tendras que crear una instancia del servicio de HANA DB que vive en la nube así podrás hacer deployment de tu estructura de DB. Tienes la opcion de usar SAP HANA cloud service y/o el servicio de SAP HANA schemas and HDI container service. La instancia puede ser creada desde el marketplace o usando el cf cli.

• XSUAA – necesitamos crear una instancia del servicio XSUAA para poder autenticar los usuarios de la aplicación. La instancia de este servicio puede ser creada directamente desde el marketplace via the BTP o usando el cf cli desde la terminal una vez que te hayas logeado a tu cuenta de cloud foundry.

Para mejor entender los servicios, lee la siguiente documentación oficial en su sitio

https://docs.cloudfoundry.org/devguide/services/managing-services.html

Hay otros command line interfaces que seran utilizados para crear estos servicios

• cf cli –> https://docs.cloudfoundry.org/cf-cli/install-go-cli.html
• hana-cli –> https://www.npmjs.com/package/hana-cli

este cli se utilza para verificar la instancia de la base de datos HANA en la nube, para hacer query en los tables, views, iniciar/parar las instancias entre otras funcionalidades. Hay otros ejemplos los cuales este cli se puede utilizer, pero para este blog, lo voy a limitar a usarlo dentro de la instancia de mi cuenta del BTP. Para saber mas acerca de los otros ejemplos, puedes leer la documentación en el sitio del npm.

Si no estas familiarizado con los commandos que se pueden utilizar para cualquier cli, puedes usar el comando –help después del nommbvre del cli, por ejemplo:   cf –help

Aqui esta una lista de cadenas para poder entender mas acerca del CAP.

• Crear full stack apps en CAP desde VS code. (Tambien clonar tu app de VS Code al BAS en BTP)

• Desarrollando Front end apps en Cloud Foundry

https://help.sap.com/docs/btp/sap-business-technology-platform/entitlements-and-quotas

• Tutorials de CAP

https://developers.sap.com/tutorial-navigator.html?tag=software-product-function%3Asap-cloud-application-programming-model

• La pagina oficial de CAP https://cap.cloud.sap/docs/about/

Despues de leer estos tutorials y la documentation, empezemos nuestra implementacion de CAP. Para hacer las cosas mas simples, asegurate de instalar los siguientes clis antes de empezar el ejercicio nodejs, npm, hana-cli, cf cli y cds cli.

Problema:

Utilizando #CAP, me gustaria construir una aplicacion donde desarrollemos un modelo de datos usando CDS entities (tables), también me gustaría utilizar un servicio OData v4 para exponer estas entidades y tmb un app SAPUI5 para mostrar los datos.

Pasos para la solucion:

• Usando el cds cli, construyamos un Proyecto en el BAS (Business App Studio) o usa el template de CAP desde el BAS

** Actualmente puedes clonar un repo / sincronizar tu proyecto de github o puedes esperarte mas tarde despues del paso 3 para asegurarte que tengas la estructura correcta – comentare mas abajo el final del cuarto paso **

• Verifica que el archive mta yaml tenga una sección de la base de datos.
• Al momento de escribir esto (April 2023) hay un bug en el template generator y require que hagamos un quick fix : cds add hana   de la terminal para incluir la sección de db en el archivo mta yaml (archivo de deployment)
• Verifica que la seccion que se anadio despues de ejecutar ese comando
• Cambia el path del modulo de la base de datos, usa db en lugar de gen/db –> esto es para asegurarte que puedas correr el proyecto desde el VS code, BAS y también poder ejecutar calc views despues.
• Anade las tareas de build tasks para la db de hana
• Verifica el archico package.json que contenga las dependencias correctas
  1. cds version 6
  2. verifica el package.json que contenga dependencias para @sap.cds, express y hdb modules
  3. run npm install al nivel del proyecto
  4. run hana-cli createModule para hacer cambios en el folder de db y puedas preparar tu proyecto para desarrollo de CAP

***  asegura que tu Proyecto este sincronizado al repo de github para guardar tus cambios (commit/push)***

• Nota que el proyecto contiene 3 folder principalmente (db, app, srv)
  1. El folder db contiene los objetos de la database (entities, views, procedures,functions,synonyms)
• Empezemos con 3 entidades que son communes para mostrar una lista y objects de una lista; Material, Vendor, y Part.
• ** Cuando hagas build en el archive de entidades de cds, normalmente se usa un namespaces o context namespaces. Te recomiendo usar el context namespace para que no haya conflictos cuando vayas a crear calculation views.
• Ahora, crea un folder llamado data para incluir archivos de csv. El nombre de cada archive de csv debe seguir el patron incluyendo el namespace del context.

1. El folder srv contiene nuestros objetos del OData (v4) *nota que en CAP el servicio de odata también se crea con un archivo de tipo cds y haciendo referencia al archivo de CDS en el folder de db

• Anade un servicio cds
• Despues de crear la instancia de servicio xsuaa, anotaciones de authorization pueden ser agregadas al servicio. En el siguiente ejemplo, puedes ver como la entidad Parts require que el usuario sea autenticado authenticated y después la entidad de Vendor require que el usuario tenga el role, Admin. En el siguiente ejemplo, la entidad Materials no tiene ninguna restricción (todavía no). Mientras hagas este ejemplo, no pongas ningn anotacion hasta despues de crear la instancia de servicio de tipo xsuaa service, la llave, y como también hayas hecho el binding (en los siguientes pasos).

1. Ejecuta cds build –> para construir el proyecto y asegurarse de que no haya errores en los archivos de cds
2. Tenemos que crear una instancia de a HANA hdi para poder hacer el deploy de nuestro código a la instancia de la nube de HANA.

• cf create-service hana hdi-shared materialDetails-db

** si encuentras errores en este paso, 1) asegurate que el servicio de HANA DB este abilitado en la seccion de entitlements y 2) asegúrate qye el servicio este corriendo – ejecuta el comando command hana-cli start   para correrlo

*** la creacion de servicios toma unos cuantos segundos – checa el status con el comando cf services

Despues de que el servicio sea creado, crea la llave para dicho servicio (para usarlo desde la aplicacion)

cf create-service-key materialDetails-db SharedDevKey

cds build/all –clean –> para reconstruir el proyecto de lo que se ha hecho

cds deploy –> para hacer deploy al HANA HDI

eventualmente este commando regresara esto:

Saving bindings to .cdsrc-private.json in profile hybrid

Lo cual significa que se ha gusrdado la configuracion del servicio y su llave localmente par apoder correr la aplicacion desde localhost sin tener que guardar credentials.

Para correr la aplicacion ahora, ejecuta cds watch –profile hybrid à este commando te permite correr el servicio odata desde localhost pero, desde el punto de vista de la instancia de la base de datos de HANA

A este momento el sistema corre un servidor express y muestra nuestos recursos de cds (Servicio OData) desde localhost, el mio se ve asi:

• al seleccionar el servicio, regresa la definición de OData V4
• al seleccionar $metadata, regresa el documento de $metadata
• al seleccionar cada endpoint, muestra los datos (si los datos fueron populados inciailmente con un archivo csv en las tablas especificadas anteriormente)
• al seleccionar Fiori preview regresara la aplicacion de Fiori elements que hicimos desde servicio OData y la definición de entidades

mientras selecciones cada uno de estos recursos, fijate en la terminal en VS code o en tu terminal de BAS para ver los logs de lo que se ha llamado. Se ve muy bien! De aqui en adelante, ya estamos listos para empezar a trabajar en la aplicación(folder app).

1. El folder app contiene la aplicacion para desplegar los datos de la base de datos

El app es independiente del CDS, sin embargo, si queremos construir una aplicacoin de tipo elementos de Fiori, podemos usar annotations para mejorar la funcionalidad y presentacion de del archivo $metadata OData

Manten el siguiente comando ejecutado cds watch command running – abre una terminal diferente y usando el sig comando de cds cli, ejecuta:

cds app approuter –> este comando ayudara anadir el app router, xs-security.json, the xs-app.json, entre otros archivos en el folder de app y actualizara el archivo mta yaml para el  deployment.

Ve al command palette en la parte de arriba del browser y selecciona select, > Fiori: open application generator, sigue el wizard para darle al app(ui) un nombre, seleccionar el theme, seleccionar el servicio OData, selecciona un template (List Report), y selecciona la configuracion. Una vez que todos esos pasos hayan sido seleccionados, un proeycto se agrega dentro del folder app (deje el nombre de default, project1, y esto es lo que ahora veo en mi proyecto).

Hize una aplicacion Fiori de tipo elements para rapidamente mostrar el consume de un servicio OData desde mi Fiori app, pero puedes seleccionar un app de tipo Freestyle si eso prefieres.

Con lo que ahora tengo, hay una aplicacion Fiori corriendo, consumiendo un servicio, sin embargo, para hacer la aplicacion mas real, tenemos que incluir los settings de seguridad en forma de usar una instancia de tipo xsuaa dentro de la applicacion. Para completar este paso, tenemos que hacer lo siguientes cambios:

• Desde el path del proyecto, ejecuta cds compile srv/ –to xsuaa > xs-security.json

Para poner la estructura correcta de los que el servicio xsuaa necesita en el archivo de xs-security.json

Luego, asegurate que las sig secciones tengan algo: xsappname, tenant-mode, scopes, role-template, oauth2-configuration.

• Necesitamos poner el route authentication dentro del archivo xs-app.json

authenticationMethod: route

• Necesitamos crear una instancia de servicio xsuaa y también su llave

cf create-service xsuaa application materialDetails-auth -c xs-security.json

cf create-service-key materialDetails-auth default

re-inicia el comando cds watch – nota que el servicio xsuaa agrego un archivo cds private json

• En nuestro servicio OData, Tambien mostraremos como las anotaciones requiren que un un role collection sea agregado. Para obtener la autorizacion del role collection, tienes que entar al BTP cockpit, encontrar el role (o crear uno si no ha sido creado – asignar el role collection con el mismo nombre de la aplicacion).
• Abre el BTP cockpit para crear un role collection.
• Dale Click en el simbolo de mas en la esquina superior derecha, asigna un numbre – el mismo de la aplicacion
• Dale Click al final del renglon en el icono >, abre la pagina de object detail y agrega el role, Admin. Agrega el id de usuario (en mi caso el usuario de la cuenta de BTP).

Agrega esto en tu script en el archive package json

“app”: “npm start –prefix app”

** Desde una terminal diferente ejecuta el sig comando ** asegurate que tengas el comando watch corriendo en una terminal y el sig comando que sea ejecutado desde otra segunda terminal – ahorrate varias horas de debugging y lee esta sección varias veces si resulta en errores)

cds bind –exec npm run app

el browser te sugerira correr tu app desde otro puerto 5000 como lo especificaste en el archivo xs-app.json. Ahora tu app esta utilizando el servicio xsuaa con autenticación desde ese servicio para el usuario que esta utilizando la aplicacion. Semejantemente con tu servicio y la aplicacion de Fiori que se ha abierto.

La aplicacion de front end (Fiori / SAPUI5):

Para facilitar la construccion de esta aplicacion, vamos a incluir una extension mas llamada Fiori templates. Cuando creas esta aplicacion, habra otro folder creado dentro del proyecto principal que vamos a usar para que contenga la aplicación ui5. Dejame explicar unas cosas masdentro de este folder y ciertos archivos que se encuentran dentro de el:

index.html –> la pag  de entrada a la aplicación Fiori

Component.js –>carga el component de ui5 y hace referencia al archivo manifest.json

manifest.json –> configuracion del modelo de datos, routes, views, dependencias, npm scripts

xs-app.json –> ruta de autenticacion y navegacion se especifica aqui. Cada ruta tambien especifica el tipo de autenticacion (ie xsuaa) y sus destinos (a donde se hace un re-routing).

xs-security.json –> referencia el appname, los scopes y los role-templates que se utilizaran en la aplicación Fiori. El role collection agregado del BTP cockpit debe coincidir con el nombre de kis roles que existen en la seccion de role-template.

mta.yaml –> configuracion de deployment y dependencias de configuracion. Este archive se utiliza para nombrar las instancias de servicio y los módulos. Este archivo se utiliza para construir y hacer el deploying de la application

cdsrc-private.json file –> este archive muestra las llaves usadas en los services y también para el deployment

webapp/folder –> este folder es conocido tradicionalmente por le desarrolladores de ui5 debido a que ya es común para ellos.

Y como puedes ver los datos del UI coincide con los datos de mi base de datos mostrados en la sig imagen

6. El proyecto final se ha compartido en el sig github repo: https://github.com/ShockwaveConsulting/materialDetails.git

Mis batallas:

1. My primer batalla fue entender la navegacion del BTP Cockpit (account, marketplace, security, HANA DB – normalmente como desarrollador, los devs no tienen acceso a esta herramienta. Yo tengo mi propia cuenta y asi pude tener acceso al cockpit. Les sugiero a cualquier persona que utilize esta herramienta que pase suficiente tiempo para entender la navegación de la misma.
2. Mi siguiente batalla mientras aprendia CAP fue familiarizarme con los varios clis que se utilizan dentro del mismo proyecto, especialmente el de cds cli. Ya sabia un poco acerca del hana-cli de otros videos y de una session que atendi en tech ed pero mientras trabajaba en este ejercicio, pude entender mejor como utilizar la herramienta.
3. Ya habia construido instancias de servicio anteriormente usando el comando cf services, pero esta vez se me hizo mas fácil al utilizar la herramienta de cf cli y ver los servicios creados y mostrados en el BTP cockpit. Pude entender aun mejor como funcionaba el binding y como los servicios interactúan entre ellos y entre las aplicaciones.
4. La mayor batalla que tuve fue el no saber que el comando watch y el cds bind –exec npm run app se necesitaban ejecutar simultáneamente desde dos terminales diferentes. Esto fue lo que me tomo mas tiempo en todo el proyecto.
5. Entender la funcionalidad de un admin de BTP porque generalmente estas acciones se repartes dependiendo del tipo de trabajo que uno hace, desarrollo vs administracion, sin embargo como desarrollador tenemos que entender todas las acciones aunque no tengamos acceso a ciertas partes del BTP cockpit. Agraciadamente tengo yo este acceso pues tengo mi cuenta de BTP pero se que esto no es común en algunas organizaciones.

Para cerrar:

Como ya vemos que todo se esta moviendo a la nube y mas clientes estan empezando a usar el BTP como tambien mucho Desarrollo esta ocurriendo en el area de CAP, yo queria saber como es este modelo en comparacion de XSJS y de NodeJS en el area de HANA XSA. Me da gusto empezar mi viaje en las areas de BTP, BAS, CF, CAP (tanta sigla!)

Gracias una vez mas por leer este blog – haganme saber cualquier duda, pregunta o comentario o sugerencia.