• Inicio
  • Novedades
  • Academia SAP
  • FAQ
  • Blog
  • Contacto
S4PCADEMY_Logo
  • Inicio
  • Novedades
  • Academia SAP
  • FAQ
  • Blog
  • Contacto
Twitter Linkedin Instagram

S4PCADEMY_Logo
  • Inicio
  • Novedades
  • Academia SAP
  • FAQ
  • Blog
  • Contacto
Twitter Linkedin Instagram
Technical Articles

SAP CPI: CI/CD de cero a héroe – Documentación

By s4pcademy 


Este blog es parte de una serie de blogs, por lo que puede encontrar la primera página aquí (https://blogs.sap.com/2023/02/02/sap-cpi-ci-cd-from-from-zero-to-hero/). Esta es la agenda que estamos siguiendo:

La documentación es una tarea crucial requerida para la mayoría de las personas que trabajan en TI. Ya sea que trabaje con manuales de usuario, especificaciones funcionales, especificaciones técnicas, diagramas de arquitectura, comentarios de código, etc., debe poder transmitir su conocimiento de una manera lo suficientemente concisa y simple para que su audiencia pueda absorberlo (este blog probablemente no sea lo suficientemente conciso). )

Una vez más, mi opinión es muy discutible, pero a mi modo de ver, la documentación de su interfaz debería responder a las siguientes preguntas: ¿Quién, qué, cómo y también por qué? En el contexto de la integración, mientras que las primeras tres preguntas tienen cierto potencial para la automatización, creo que la última debería ser entrada manual.

¿OMS?

¿Quién te pidió que hicieras la interfaz? Siempre es bueno tener los contactos identificados tanto para el solicitante de la interfaz como para el desarrollador de la integración y sus contrapartes de origen y destino. Básicamente, toda la persona está involucrada en ello.

Si usted u otra persona nueva en la interfaz tiene que volver a visitar la interfaz más adelante, al menos hay personas identificadas a las que se puede contactar para obtener información adicional. Dado que tenemos el enlace del paquete CPI a la historia de usuario de Jira y documentamos la persona de contacto allí, hay formas de automatizar la generación de esta parte del documento.

¿Qué?

Con respecto a las interfaces, lo que veo, el alcance de su interfaz, cuáles son los límites de lo que está implementando, qué casos de uso cubrirá. Sería bueno si AI puede leer su flujo de flujo e interpretar lo que está haciendo y describirlo a personas no técnicas. Intenté proporcionar la fuente de iflow a Chat GPT y pregunté qué estaba haciendo. Ejemplo a continuación, no es incorrecto pero es demasiado técnico. Definitivamente hay margen de mejora.

BPMN%20explicación%20por%20chat%20gpt

Explicación de BPMN por chat gpt

¿Cómo?

¿Cómo implementó el alcance con el que se comprometió? Tener su captura de pantalla de iflow, la lista de parámetros externos, las conexiones entre los componentes en su iflow, le permitiría a un desarrollador de integración comprender cómo logró el alcance que prometió lograr.

¿Por qué?

Esta es para mí la pregunta más importante (cuando corresponda), la mayoría de los desarrolladores pueden abrir un iflow y leer qué hay allí y cómo se construyó, pero por qué se construyó de esa manera generalmente no se expresa en ninguna parte. Incluso cuando documento el código, tiendo a ver que se repite el mismo patrón, donde el desarrollador explica línea por línea lo que hace el código con palabras que las personas sin conocimientos técnicos pueden leer y comprender. No veo mucho valor en ello. Quiero decir, veo valor en documentar un fragmento complejo de código en palabras simples, así como el por qué lo estás haciendo de esa manera, o por qué lo necesitas.

Comprender por qué usó un adaptador en lugar del otro, por qué eligió un patrón de integración sobre el otro, por qué está considerando solo deltas o solo instantáneas completas de datos, por qué tiene una capa de fachada adicional, etc. la brecha de conocimiento faltante que permitiría a un nuevo desarrollador comprender la historia y el contexto para tomar posesión de una interfaz con éxito.

Incluso para su arquitectura, si hace el ejercicio de preguntarse por qué tiene cada capa/componente/conexión y no puede explicarlo de manera convincente para usted y para los demás, tal vez debería preguntarse si realmente necesita esa parte. .

Desafortunadamente, en Cloud Integration, AFAIK, no hay muchos lugares donde pueda agregar esta información. Puede comentar el código maravilloso, la descripción del paquete, la descripción del flujo, pero no a nivel de componente.

Documentación técnica

Todas nuestras interfaces se basan en una plantilla de documento que debemos completar. Lo vinculamos en la pestaña de documentación del paquete siempre con el mismo nombre para que podamos verificar en nuestras automatizaciones si falta documentación y reportarlo si es así. Algunos de los capítulos de esta documentación son qué y cómo (captura de pantalla de iflow, parámetros externos), mientras que otros son por qué (motivación empresarial, contexto del proceso). Odio hacer trabajo repetitivo, así que cuando me di cuenta de que tendría que revisar todos los iflows desarrollados y tomar una captura de pantalla de ellos, además de crear una tabla con todos los parámetros externos, perdí la motivación para hacerlo manualmente, así que tuve la idea de automatizarlo tanto como sea posible

Documentación%20tareas%20diagrama

Diagrama de tareas de documentación

Captura de pantalla de flujo de flujo

Que yo sepa, no hay una API oficial para descargar su captura de pantalla de iflow, leí un blog interesante de @ r_herrmann2 https://blogs.sap.com/2021/04/23/from-cpi-iflow-to-diagram-with-iflow-plotter/ sobre el uso de una biblioteca nodejs para generar una captura de pantalla de la representación bpmn del iflow. Lo implementé en nuestra plataforma jenkins como una nueva tubería que extraería diariamente todas las capturas de pantalla para todos los flujos de flujo. El siguiente ejemplo fue tomado de https://blogs.sap.com/2021/04/09/how-to-create-vector-graphics-from-iflows/

Ejemplo%20de%20a%20generación%20de%20bpmn%20io%20sitio

Ejemplo de una generación del sitio bpmn io

Desafortunadamente, la captura de pantalla final es, en mi opinión, una imagen fea en blanco y negro que parece un iflow obsoleto muy antiguo con una apariencia terrible.

Trabajé con webdriver en el pasado, y dado que no había una API oficial para tomar las capturas de pantalla de los flujos de flujo, creé un script que iría a diario abriendo CPI DEV con un usuario técnico y navegando a través de todos los paquetes y all iflows y tome una captura de pantalla y guárdela en un directorio. Un detalle que podría pasar por alto es que su secuencia de comandos hará clic en el ícono de zoom una vez que su ventana sin cabeza de Chrome esté ejecutando su automatización y esté ubicado en el diseñador de iflow, para que su zoom de iflow se ajuste a la ventana y con eso asegurar que todo Los componentes de iflow son parte de la captura de pantalla. Ejemplo de tal imagen a continuación:

Automáticamente%20imagen%20capturada%20de%20un%20iflow%20de%20Iflow%20designer

Imagen capturada automáticamente de un iflow del diseñador Iflow

Luego creó un directorio de servidor http simple y lo publicó como un servicio de ventana para que sus capturas de pantalla estuvieran disponibles como URL teniendo en cuenta incluirlas en git markdown más adelante.

Valor añadido

Tienes un servidor http actualizado diariamente donde puedes navegar fácilmente a través de la captura de pantalla de cada iflow. Puede usar estas imágenes para permitir la generación de documentación.

Parámetros externos

Mientras tanto, un colega mejoró nuestra canalización para generar ahora el documento técnico (docx) utilizando la captura de pantalla descargada anteriormente, además de crear la lista de parámetros externos para cada uno de ellos. Creo que usó java apache poi (que es una biblioteca muy buena), pero también hay formas de hacerlo con nodejs. Buen trabajo Flavio 🙂

Valor añadido

Genere partes de la documentación oficial de forma automática/siempre sincronizada

Documentación de asignación de mensajes

Una de las partes de su documento técnico es probablemente la documentación de mapeo. Hay una opción en la interfaz de usuario para exportarlo como Excel, sin embargo, es algo limitado, ya que:

  • no identifica los tipos de datos de origen y destino involucrados en cada línea de mapeo
  • No tiene resaltado de palabras clave, por lo que es un poco difícil para usted leer una lógica de secuencias de comandos compleja
  • Si lo copia directamente a su documento de Word, aún necesita formatearlo de acuerdo con su plantilla

Por lo tanto, creó una aplicación java que analiza el archivo de mapeo xml y genera una página html con resaltado de sintaxis y sangría para funciones para que sea más fácil de leer. Lee los tipos de datos de la información xsds asociada, por lo tanto, solo admite asignaciones xml en este momento. También admite diferentes «contextos» dentro de cada línea de mapeo. Al final, también lo hace disponible para ser consumido a través del servidor http. Ejemplo a continuación

Mensaje%20asignación%20documentación%20en%20html%20formato%20con%20sintaxis%20resaltado

Documentación de asignación de mensajes en formato html con resaltado de sintaxis

Valor añadido

Sin la intervención del desarrollador, la automatización crea una documentación html para cada asignación dentro de cada iflow cada vez que se ejecuta el paquete de canalización de jenkins para su paquete.

Generación de rebajas

Como ahora tenemos un repositorio git generado automáticamente para cada fuente de paquete CPI, el archivo README generado automáticamente estaba algo vacío, por lo que tenía en mente generarlo con la información que ya teníamos al ejecutar la canalización. Entonces pude generar un descuento para cada paquete que contenía las descripciones del paquete, las etiquetas, la lista de todos sus flujos de flujo flotante, la descripción de cada flujo de flujo flotante, la captura de pantalla del flujo de flujo flotante y la documentación de asignación de mensajes (arriba) si el flujo de flujo flotante tiene cualquier. Esto se actualiza automáticamente a diario cuando el código se sincroniza para ese paquete. Entonces, al final, es una forma de tener siempre la documentación actualizada para sus interfaces. Ejemplo a continuación:

Ejemplo%20of%20a%20README%20file%20on%20your%20git%20generated%20repo

Ejemplo de un archivo README en su repositorio generado por git

Ejemplo%20de%20el%20contenido%20de%20un%20README%20archivo

Ejemplo del contenido de un archivo README (continuación)

Valor añadido

Sin la intervención del desarrollador, hay un repositorio de git creado para su paquete, si accede a ese repositorio de git, verá un archivo Léame actualizado que contiene una descripción general de la lista de flujos de datos, capturas de pantalla e información adicional, totalmente autónomo.

Próximos pasos

Pensando en una manera de incluir los «por qué» requeridos por nuestra plantilla dentro del paquete de la interfaz, ya sea siguiendo alguna convención de plantilla en la descripción del paquete o cualquier otro medio, para que podamos generar la documentación completamente y para que la documentación sea lo más estrechamente posible con el paquete IPC. La motivación es que si transportas el paquete, o lo descargas, sería bueno tener toda esa documentación como parte de la unidad que transportaste.

En este tema, introduje el tema de las pruebas automatizadas, presentando algunas de las herramientas que hemos investigado, así como la solución elegida para realizar pruebas unitarias automatizadas a través de jenkins.

También te invito a compartir algunos comentarios o pensamientos en las secciones de comentarios. Estoy seguro de que todavía hay mejoras o ideas para nuevas reglas que beneficiarían a toda la comunidad. Siempre puede obtener más información sobre la integración de la nube en el página de tema para el producto



Source link


ceroCICDCPIdocumentaciónhéroeSAP

Artículos relacionados


#Artificial Intelligence  ·  ChatGPT  ·  Generative AI  ·  Personal Insights
ChatGPT + SAP Service Cloud – Casos de uso
Technical Articles
SAP ALM Analytics: SAP Cloud ALM Real User Monitoring Dashboards
#Azure  ·  #EVENT  ·  #Event-driven-architecture  ·  #industry40  ·  #microsoftazure  ·  #referenceArchitecture  ·  #sapcap  ·  Technical Articles
[Part-4] Aprovechamiento de ‘Events-to-Business Actions Framework’ para SAP Service Cloud Scenario

Deja tu comentario Cancelar la respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

*

*

Herramientas SAP Fiori: evolución de los iconos
Previo
Protección de datos de la interfaz de usuario: cómo proteger los datos confidenciales que se muestran en las consultas analíticas mediante el monitor de consultas (RSRT TCode) en el modo de visualización de consultas WD Grid
Siguiente

Madrid

Calle Eloy Gonzalo, 27
Madrid, Madrid.
Código Postal 28010

México

Paseo de la Reforma 26
Colonia Juárez,  Cuauhtémoc
Ciudad de México 06600

Costa Rica

Real Cariari
Autopista General Cañas, 
San José, SJ 40104

Perú

Av. Jorge Basadre 349
San Isidro
Lima, LIM 15073

Twitter Linkedin Instagram
Copyright 2022 | All Right Reserved.
Cookies Para que este sitio funcione adecuadamente, a veces instalamos en los dispositivos de los usuarios pequeños ficheros de datos, conocidos como cookies. La mayoría de los grandes sitios web también lo hacen.
Aceptar
Cambiar ajustes
Configuración de Cookie Box
Configuración de Cookie Box

Ajustes de privacidad

Decida qué cookies quiere permitir. Puede cambiar estos ajustes en cualquier momento. Sin embargo, esto puede hacer que algunas funciones dejen de estar disponibles. Para obtener información sobre eliminar las cookies, por favor consulte la función de ayuda de su navegador. Aprenda más sobre las cookies que usamos.

Con el deslizador, puede habilitar o deshabilitar los diferentes tipos de cookies:

  • Bloquear todas
  • Essentials
  • Funcionalidad
  • Análisis
  • Publicidad

Este sitio web hará:

Este sitio web no:

  • Esencial: recuerde su configuración de permiso de cookie
  • Esencial: Permitir cookies de sesión
  • Esencial: Reúna la información que ingresa en un formulario de contacto, boletín informativo y otros formularios en todas las páginas
  • Esencial: haga un seguimiento de lo que ingresa en un carrito de compras
  • Esencial: autentica que has iniciado sesión en tu cuenta de usuario
  • Esencial: recuerda la versión de idioma que seleccionaste
  • Functionality: Remember social media settings
  • Functionality: Remember selected region and country
  • Analytics: Keep track of your visited pages and interaction taken
  • Analytics: Keep track about your location and region based on your IP number
  • Analytics: Keep track of the time spent on each page
  • Analytics: Increase the data quality of the statistics functions
  • Advertising: Tailor information and advertising to your interests based on e.g. the content you have visited before. (Currently we do not use targeting or targeting cookies.
  • Advertising: Gather personally identifiable information such as name and location
  • Recuerde sus detalles de inicio de sesión
  • Esencial: recuerde su configuración de permiso de cookie
  • Esencial: Permitir cookies de sesión
  • Esencial: Reúna la información que ingresa en un formulario de contacto, boletín informativo y otros formularios en todas las páginas
  • Esencial: haga un seguimiento de lo que ingresa en un carrito de compras
  • Esencial: autentica que has iniciado sesión en tu cuenta de usuario
  • Esencial: recuerda la versión de idioma que seleccionaste
  • Functionality: Remember social media settings
  • Functionality: Remember selected region and country
  • Analytics: Keep track of your visited pages and interaction taken
  • Analytics: Keep track about your location and region based on your IP number
  • Analytics: Keep track of the time spent on each page
  • Analytics: Increase the data quality of the statistics functions
  • Advertising: Tailor information and advertising to your interests based on e.g. the content you have visited before. (Currently we do not use targeting or targeting cookies.
  • Advertising: Gather personally identifiable information such as name and location
Guardar y cerrar