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.

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

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 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:

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

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 de un archivo README en su repositorio generado por git

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