En Alfastrakhovanie utilizamos activamente el "Wiki", cuyo motor es Atlassian Confluence. La primera vez que lo encontré seriamente (en un intento de crear contenido), carecía de "dinamismo": quería formar parte de páginas mediante programación, interactuar con otros sistemas, etc.
Durante un tiempo se golpeó la cabeza contra diferentes paredes, pero luego vio que "no había una sola pared en la casa". Quiero compartir mi experiencia: ¿cómo puedo agregar altavoces a Confluence? Espero que esto sea útil para quienes lo usan. Y, como siempre, a todos los curiosos.
Wiki dinámico
Inicialmente, Confluence sugiere una forma universal de expandir su funcionalidad: los complementos. Probablemente, él es bueno, solo hay un inconveniente: un umbral de entrada alto (necesita aprender mucho).
Después de una breve reflexión (según los estándares espaciales), había dos formas más simples de expandir su funcionalidad: la macro estándar "HTML" y "HTML Incluir", en este artículo me centraré en la última con más detalle.
Hay un principio de funcionamiento para estos métodos: el código HTML está incrustado en la página Confluence, puede ser estático (que también puede ser interesante, por ejemplo, para el formato de página no estándar) y puede ser dinámico (incluidos los componentes del servidor).
Ejemplo: solicitud de reconciliación
Veamos la forma propuesta de expandir las capacidades de Confluence con un ejemplo simple: una lista de aprobación de documentos.
Lo que queremos hacer: agregar una lista de aprobación a la página para que todos puedan ver quién debe estar de acuerdo con el documento, si se acordó y, de ser así, cuándo.
Por conveniencia, haremos que el elemento de la lista sea un botón y escribiremos en él el nombre del coordinador. El botón estará activo si la página es vista por el coordinador, y no estará activo en todos los demás casos.
Después de la aprobación, el botón "dejará de ser un botón": en lugar del botón después de la aprobación, dibujaremos en la página el hecho de la aprobación en forma de texto (el nombre del aprobador y la fecha de aprobación). En la versión más borrador (sin diseño) puede verse así:
Esquema de interacción
Comentarios - cómo funciona:
- la página en Confluence contiene varias macro "html include", en realidad solicitudes HTTP GET con parámetros (lo consideraremos con más detalle a continuación)
- Al representar una página, estas solicitudes (scripts de Python) se ejecutan en el servidor de aplicaciones, el resultado (HTML generado) se dibuja en la página
- En el curso de su trabajo, el script, por ejemplo, contacta la base de datos con el historial de firma de la página, si la página aún no ha sido "firmada" por el firmante - HTML contendrá un botón (todo como se describió anteriormente)
- cuando hace clic en el botón, se produce el envío; se llama a otro script de Python (un script para procesar el hecho de la reconciliación)
- Este script guarda información sobre el hecho de iniciar sesión en la base de datos y redirige al usuario a la página original (al representar el hecho de que se tendrá en cuenta el hecho de firmar, haga clic en el botón "Firmar")
Un poco complicado en palabras, intentemos aclarar el código.
Entonces necesitamos crear dos scripts
- el guión para la formación del botón "signo" (lo llamaré el "botón" guión)
- un script para resolver el hecho de firmar (reacción a un clic en el botón - llamaré a su script "controlador")
Vamos a crearlos, comience con el botón.
Botón de script
Esquemáticamente, cómo funciona la secuencia de comandos del botón:
date = getSignDate() if date:
El script debe ser un documento HTML válido, cuyo cuerpo en la forma más mínima es un formulario
- La acción del formulario contiene la URL del script "controlador"
- el botón activo es enviar
- los campos de formulario ocultos contienen parámetros adicionales para el controlador (en nuestro caso, el nombre de la página y el inicio de sesión signatario)
Una vista aproximada de la secuencia de comandos (por brevedad, descarté todo lo innecesario; vea el código de trabajo completo en github )
form = cgi.FieldStorage() signee = form["signee"].value
Script "manejador"
La tarea del controlador es muy simple: solucionar el hecho de presionar el botón "aceptar". Luego, redirija de nuevo a la página de donde provino la solicitud: al representar la página, el hecho de la coordinación ya se tendrá en cuenta (consulte la descripción anterior).
Un ejemplo (abreviado) script "handler" (la versión completa - ver github)
form = cgi.FieldStorage() signee = form["signee"].value
Página en confluencia
La página en Confluence contiene tres macro HTML incluidas con diferentes parámetros (vea el código a continuación) y en la versión más simple se ve así:
Código de página en formato de marcado wiki: aquí puede ver los parámetros
<h1> </h1> <p> , </p> <h1> </h1> <ul> <li> <ac:structured-macro ac:macro-id="..." ac:name="html-include" ac:schema-version="1"> <ac:parameter ac:name="url"> <ri:url ri:value="http://z14-0510-wiksap.vesta.ru/misc/sign_btn.py?signee=boss&actual=korolevmv&id=wikitools_sign"/> </ac:parameter> </ac:structured-macro> </li> <li> <ac:structured-macro ac:macro-id="..." ac:name="html-include" ac:schema-version="1"> <ac:parameter ac:name="url"> <ri:url ri:value="http://z14-0510-wiksap.vesta.ru/misc/sign_btn.py?signee=korolevmv&actual=korolevmv&id=wikitools_sign"/> </ac:parameter> </ac:structured-macro> </li> <li> <ac:structured-macro ac:macro-id="..." ac:name="html-include" ac:schema-version="1"> <ac:parameter ac:name="url"> <ri:url ri:value="http://z14-0510-wiksap.vesta.ru/misc/sign_btn.py?signee=maxvar&actual=korolevmv&id=wikitools_sign"/> </ac:parameter> </ac:structured-macro> </li> </ul>
Un poco sobre la configuración
Para que el esquema descrito funcione, es necesario tener en cuenta lo siguiente
Disponibilidad de HTML Incluir macro
A veces, los administradores lo "ocultan": hay muchos problemas adicionales (el otro lado de las posibilidades).
Esta macro es gratuita y es parte de Confluence: si no tiene una, comuníquese con los administradores, déjelos mirar ...
Listas blancas de confluencia
Confluence no ejecutará scripts alojados en fuentes desconocidas, el host en el que está alojado el script debe estar en las llamadas "listas blancas" (póngase en contacto con los administradores). Esto solo se aplica a la secuencia de comandos de "botón": la secuencia de comandos del controlador ya se llama mediante el botón, las restricciones de Confluencia no se aplican a ella.
Ejecución de script
Las secuencias de comandos (botones y un controlador) deben ser ejecutables: copie la URL en el navegador, debería funcionar y generar HTML; si esto no sucediera, depúrelo.
Errores de guion
Si alguno de los scripts falla con un error, no verá nada bueno, depure correctamente antes de publicar en Confluence.
Opciones de guion
Una mente inquisitiva podría prestar atención a los parámetros del script; por un lado, son redundantes (por ejemplo, el nombre de la página en la que se coloca el botón de aprobación; se sabe, ¿por qué completarlo?). Por otro lado, no son seguros (el "atacante" en nuestro ejemplo puede cambiar el nombre del aprobador por su cuenta o eliminar el botón de reconciliación).
La redundancia puede ser "superada" por las macros de los usuarios (me he estado preguntando durante mucho tiempo, ¿cómo pueden ser prácticamente útiles? Escribiré brevemente en un artículo separado). La seguridad en Confluence está garantizada por el historial de la página: todos los "movimientos" se registran, puede cambiar cualquier cosa, en Confluence sigue habiendo un maravilloso "rastro de auditoría" que le permite comprender en detalle quién cambió qué y cuándo.
Interacción de página
En nuestra práctica, ha habido casos en los que tuvimos que analizar el código de la página para recopilar datos (por ejemplo, así es como gestionamos la cartera de proyectos). Es posible y ni siquiera demasiado difícil. Evolutivamente, hemos llegado a la conclusión de que si se necesita cierta información en una página solo para el código que interpreta esta información, entonces esta información es más fácil de formular inmediatamente en el propio código (en forma de JSON, por ejemplo): editarlo en el modo de edición de página es bastante simple , está dibujado por el programa, pero los ahorros en análisis y mayor confiabilidad son significativos.
Más ejemplos
¿Por qué más usamos estas macros (como ideas, de repente algo resulta útil), muy brevemente
Diseño de página : si desea diseñar la página de una manera no estándar, marque con CSS, que está contenido en el bloque HTML
Calendario de vacaciones : utilizamos un calendario JS simple, lo llenamos con datos de JSON, que editamos directamente en el código de la página, obtenemos un hermoso plato con vacaciones desglosadas (año, mes, semana).
Impresión de tarjetas de tareas para un tablero de scrum : configuramos los parámetros (números de tarea en Jira y atributos adicionales) en el formulario directamente en la página wiki (en el bloque HTML), el lado del servidor genera tarjetas en un formulario adecuado para enviar a una impresora.
Gestión de cartera de proyectos : tuvimos una idea. Los mapas se puntuaron directamente en la wiki (el mapa scor es una página especialmente marcada), se compiló un plan de bloques grandes a partir de estos mapas scor, que se dibujó maravillosamente en forma de un diagrama de Gantt.
Glosario : la capacidad de visualizar términos (explicaciones para palabras individuales de una página) de un diccionario común y emitir entradas de diccionario en forma de "ventanas emergentes". El diccionario en sí se recopila automáticamente en la parte inferior de la página.
Gráficos : si necesita dibujar un gráfico simple, es muy simple hacerlo incrustando el bloque HTML con cualquiera de los paquetes estándar (Google Charts, HighCharts, etc.)
Tablas : en la parte superior de cualquier tabla en Confluence puedes "colgar" Datatable: obtenemos una tabla filtrada con "paginación", muy agradable y conveniente.
La lista se puede continuar el tiempo suficiente, durante la operación, se notó un inconveniente significativo: los errores en el código del servidor se detectan deficientemente, los 500 errores se visualizan de manera deficiente y prácticamente no contienen información. De lo contrario, experimente, es lo suficientemente seguro.
Para resumir
La forma simple descrita anteriormente para aumentar el dinamismo de Confluence le permite resolver muchos problemas diferentes. Para usarlo no se requieren herramientas y habilidades especiales. El uso es lo suficientemente seguro. Lo recomiendo
En el próximo artículo hablaré sobre la experiencia de usar macros personalizadas en Confluence, que, en mi opinión, realmente se pueden mejorar con su ayuda.
Todo es posible en la programación, solo es cuestión de tiempo y motivación.