If you use the Jira software for project management, software development or for tracking bugs, with the commercial editions you can send notifications from Checkmk to Jira and create Issues there. This works for the products Jira Work Management (formerly Jira Core), Jira Software and Jira Service Management (formerly Jira Service Desk).
The following options are supported:
Create issues for host and service problems.
Create issues with a defined Priority.
Create issues with a defined Label.
Set links to host/services in Checkmk from the generated Jira issues.
Set a Resolution in the issue when OK conditions occur.
To set up the connection between Checkmk and Jira, first create some new fields in Jira and define some Jira-IDs.
Next configure the notification method for Jira in Checkmk, entering the Jira IDs that have been created and read. You will gain more flexibility if you also use custom user attributes. Instead of entering the Jira IDs directly in the notification method, you can define some Jira IDs as custom user attributes. This makes it easy for individual users to create issues in a variety of JIRA projects.
 |
This is a machine translation based on the English version of the article. It might or might not have already been subject to text preparation. If you find errors, please file a GitHub issue that states the paragraph that has to be improved. |
Si utilizas el software Jira para la gestión de proyectos, el desarrollo de software o el seguimiento de errores, con las ediciones comerciales puedes enviar notificaciones de Checkmk a Jira y crear incidencias allí. Esto funciona para los productos Jira Work Management (antes Jira Core), Jira Software y Jira Service Management (antes Jira Service Desk).
Se admiten las siguientes opciones:
Crear incidencias para problemas de host y de servicio.
Crear incidencias con una Prioridad definida.
Crear incidencias con un Label definido.
Establecer enlaces a host/servicios en Checkmk desde las incidencias de Jira generadas.
Establecer una Resolución en la incidencia cuando se den las condiciones OK.
Para configurar la conexión entre Checkmk y Jira, primero crea algunos campos nuevos en Jira y define algunos Jira-IDs.
A continuación, configura el método de notificación para Jira en Checkmk, introduciendo los ID de Jira creados y leídos. Ganarás más flexibilidad si también utilizas atributos de usuario personalizados. En lugar de introducir los ID de Jira directamente en el método de notificación, puedes definir algunos ID de Jira como atributos de usuario personalizados. Esto facilita a los usuarios individuales la creación de incidencias en diversos proyectos de JIRA.
1. Configurar Jira
Al interactuar con Jira, Checkmk necesita saber qué notificaciones han creado ya una incidencia y cuáles no. Para que esto sea posible, tienes que crear dos campos personalizados en Jira: uno para notificaciones sobre incidencias de host y otro para incidencias de servicio.
Para poder identificar correctamente las incidencias de host y de servicio, los identificadores de estas incidencias deben ser únicos. Éste es el caso si tu instancia de Jira recibe notificaciones de un único sitio Checkmk, ya que el núcleo de monitorización de un sitio Checkmk garantiza la unicidad. Ahora bien, en la monitorización distribuida, varios sitios Checkmk pueden enviar notificaciones si se han configurado las notificaciones descentralizadas. Si tu instancia de Jira recibe notificaciones de varios sitios Checkmk, lo más probable es que se acabe la unicidad, como muy tarde cuando el ID de una incidencia host ya haya sido utilizado por otro sitio Checkmk. En una configuración así, necesitas otro campo definido por el usuario para el sitio Checkmk con el que vuelva a ser posible una asignación única.
Para la configuración en Checkmk necesitas los ID de Jira de los campos personalizados que has creado, y además los de algunos otros campos, por lo que en total se necesitan los siguientes:
ID del proyecto
ID del tipo de incidencia
ID de prioridad (opcional)
ID del campo personalizado host
ID del campo personalizado de servicio
ID de campo personalizado del site (opcional)
ID de transición (Flujo de trabajo) (opcional)
La gran mayoría de estos ID se pueden leer utilizando el script que aparece a continuación a través de una de las API REST de Jira. Los administradores de Jira también pueden recuperar los ID a través de la GUI de Jira, incluso aquellos ID que no se pueden recuperar a través de la API y, por tanto, del script.
1.1. Configurar los campos personalizados en Jira
Puedes aprender a crear campos personalizados en Jira en la documentación de Jira, incluida la asignación del campo a las llamadas pantallas de incidencia en Jira.
Cuando crees los campos necesarios para Checkmk, ten en cuenta los siguientes puntos relativos al tipo de campo. Eres libre de dar a tus campos el nombre que desees. Sin embargo, los nombres de campo que se muestran en la siguiente tabla coinciden con el script con el que puedes leer los ID de Jira en la siguiente sección Determinar los ID de Jira utilizando un script externo.
| Campo personalizado | Tipo de campo | Nombre |
|---|---|---|
Campo personalizado host |
|
|
Campo personalizado de servicio |
|
|
Campo personalizado site (opcional) |
|
|
Asegúrate también de que el usuario de Jira utilizado por Checkmk para crear incidencias, es decir, introducido en la regla de notificación de Checkmk, tiene acceso de lectura y escritura a estos campos personalizados.
1.2. Determinar los ID de Jira mediante un script externo
Puedes consultar los IDs de forma colectiva con el siguiente script, que utiliza la API-REST de Jira.
Sustituye JIRA_USERNAME, JIRA_PASSWORD, PROJECT_KEY y https://jira.server.your-domain.de por los valores que te correspondan. También puedes determinar el PROJECT_KEY desde la GUI de Jira sin necesidad de derechos de administrador.
|
Si utilizas un producto Jira Cloud, el script no se autentifica con una contraseña, sino con un token de API. En la documentación de Jiraencontrarás información e instrucciones para crear un token de API .En Jira, puedes copiar el token de API generado en el portapapeles y pegarlo en el siguiente script como |
#!/usr/bin/env python3
import requests
import sys
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
user = "JIRA_USERNAME"
password = "JIRA_PASSWORD"
project_key = "PROJECT_KEY"
jira_instance = "https://jira.server.your-domain.de"
custom_field_1 = "CMK_HOST_FIELD"
custom_field_2 = "CMK_SVC_FIELD"
custom_field_3 = "CMK_SITE_FIELD" # don't edit if field is not used
def handle_response(user, password, jira_instance, what):
url = "%s/rest/api/2/%s" % (jira_instance, what)
sess = requests.Session()
sess.auth = (user, password)
response = sess.get(url, verify=False)
return response
sys.stdout.write("=== IDs for project %s ===\n" % project_key)
infotext = ""
for section, id_name in [ ("Project_ID", "project"),
("Issue", "issuetype"),
("Priority", "priority"),
("Field", "field"),
]:
json_response = handle_response(user,password,jira_instance,id_name).json()
if id_name == "project":
infotext = ""
for project in json_response:
if project["key"] == project_key:
infotext += "%s\n\n" % project.get("id", "Project ID not found")
if not infotext:
infotext += "Project ID not found, project name existing?\n\n"
else:
types = ""
for line in json_response:
if id_name == "field":
if line["name"].lower() == custom_field_1.lower() or \
line["name"].lower() == custom_field_2.lower() or \
line["name"].lower() == custom_field_3.lower():
types += "%s: %s\n" % (line["name"], line["id"].split("_")[1])
else:
types += "%s: %s\n" % (line["name"], line["id"])
infotext += "=== %s types\n%s\n" % (section, types)
sys.stdout.write(infotext)El resultado del script será algo parecido a esto:
=== IDs for project MY_PROJECT ===
10401
=== Issue types
Test case: 10600
Epic: 10000
Task: 10003
Sub-task: 10004
Bug: 10006
Story: 10001
Feedback: 10200
New Feature: 10005
Support: 10500
Improvement: 10002
=== Priority types
Blocker: 1
High: 2
Medium: 3
Low: 4
Lowest: 5
Informational: 10000
Critical impact: 10101
Significant impact: 10102
Limited impact: 10103
Minimal impact: 10104
=== Field types
CMK_HOST_FIELD: 11400
CMK_SVC_FIELD: 11401
CMK_SITE_FIELD: 114031.3. Determinar los ID de Jira utilizando la GUI
Como alternativa a la ejecución de scripts, también puedes leer los ID a través de la GUI de Jira, pero para ello necesitas iniciar sesión en Jira con una cuenta de administrador. Atlassian, el fabricante de Jira, ha descrito este procedimiento utilizando el ejemplo del ID del Proyecto en sus propias instrucciones.
Los ID de los demás campos y tipos de incidencias pueden leerse editando el elemento correspondiente en la GUI del Administrador de Jira. El ID suele ser entonces el último valor de la barra de direcciones de tu navegador.
2. Configurar Checkmk
Ya has aprendido a configurar las notificaciones de Checkmk en general en el artículo sobre notificaciones.
Para utilizar las notificaciones de Jira, procede como se indica a continuación en Checkmk:
-
Si quieres utilizar atributos personalizados de usuario, puedes crearlos para los siguientes ID de Jira: ID de proyecto (
jiraproject), ID de tipo de incidencia (jiraissuetype), ID de prioridad (jirapriority) e ID de transición (jiraresolution). Los nombres que introduzcas como Name de un atributo se muestran entre paréntesis. Crea un atributo personalizado de usuario con Setup > Users > Custom user attributes > Add attribute:
Asegúrate de que el checkbox Make this variable available in notifications está activado para todos estos atributos personalizados de usuario creados para Jira.
A continuación, en las propiedades de un usuario, puedes introducir en estos atributos los ID de Jira de los que este usuario es responsable.
Para cada atributo de usuario personalizado, deja vacío el campo del ID de Jira asociado en la regla de notificación que se crea en los pasos siguientes. Estos campos se rellenan entonces con los atributos de usuario personalizados. Crea una nueva regla de notificación con Setup > Events > Notifications > Add rule.
-
Para el Notification Method elige JIRA (Commercial editions only:
En el campo JIRA URL, introduce la URL de tu instancia de Jira, por ejemplo
jira.server.your-domain.com.En User Name y Password almacena los datos de la cuenta de Jira para este acceso.
Para Project ID y Issue type ID necesitas los identificadores previamente identificados en Jira, en el ejemplo "10401" para el identificador del proyecto y "10006" para el tipo de incidencia "Bug".
Para Host custom field ID, Service custom field ID y (opcionalmente) Site custom field ID introduce los ID de los campos personalizados que creaste en Jira.
Para poder enlazar directamente con Checkmk desde cualquier incidencia generada, en Monitoring URL introduce la URL de tu site de Checkmk, por ejemplo:
https://mycmkserver/mysite
Además, también tienes los siguientes ajustes opcionales:
En Priority ID puedes definir con qué prioridad se crean las incidencias en Jira. Aquí puedes introducir uno de los "tipos de prioridad" leídos en el script, de "1" a "5".
Puedes cambiar las descripciones que se crean para los problemas de host y servicio en las incidencias mediante las opciones Summary for host notifications y Summary for service notifications.
Puedes utilizar la opción Label para definir si quieres pasar etiquetas al crear incidencias en Jira. Si activas Label sin introducir un valor, se establecerá
monitoring.
Checkmk escribe el valor de la label en el campolabelsde Jira, que sólo funciona si este campo existe en tu aplicación Jira, que es el caso de Jira Software, pero no de Jira Service Desk, por ejemplo.Si también quieres que se introduzca un Resolution en la incidencia en Jira al notificar un cambio de estado a OK en Checkmk, puedes definirlo en Activate resolution with following resolution transition ID.
Para poder determinar aquí el ID correcto, también necesitas derechos de administrador en Jira. Vuelve al área Issues y haz clic en Workflows. A continuación, haz clic en View en la fila del Flujo de trabajo estándar del proyecto de Jira que estés utilizando. Si ahora ves un diagrama de flujo, cambia la visualización haciendo clic en Text. Podrás leer el ID deseado en la columna Transitions (id).Con Set optional timeout for connections to JIRA puedes configurar el timeout para las conexiones a Jira. Si no introduces nada aquí, se aplicará el valor por defecto de 10 segundos.
Cuando utilices la siguiente caja Contact selection, ten en cuenta los siguientes puntos:
Cuando selecciones contactos, asegúrate de que las notificaciones sólo se envían a un contacto, por ejemplo, seleccionando un único usuario. Con los métodos de notificación para sistemas de tickets, etc., la selección del contacto sólo sirve para especificar que se envíen notificaciones. Sin embargo, las notificaciones no se envían al usuario seleccionado, sino al sistema de tickets. Ten en cuenta que una selección de contactos a través de grupos de contactos, todos los contactos de un objeto o similar suele generar varias notificaciones idénticas para un evento, que luego acaban en el sistema de tickets dos, tres o incluso más veces.
Si se cumple el primer punto, pero el usuario se utiliza en varias reglas de notificación para el mismo método, sólo se aplica la última regla en cada caso, por lo que es aconsejable crear un usuario funcional distinto para cada una de estas reglas de notificación.
El tema de la selección de contactos es algo diferente cuando se utilizan atributos de usuario personalizados, ya que con ello se pretende asignar ID de Jira diferentes a usuarios diferentes. Por tanto, en este caso normalmente querrás informar a varios contactos, concretamente a aquellos usuarios a los que hayas asignado los atributos personalizados. Si estos usuarios utilizan ID de Jira diferentes, no se generarán notificaciones idénticas.
Puedes averiguar cómo probar el nuevo método de notificación en el artículo sobre notificaciones. Con la nueva función Probar notificaciones, puedes comprobar si tu nueva regla de notificación se aplica a determinados host y servicios.
Para enviar realmente notificaciones de prueba a través de este método de notificación, debes seguir utilizando Fake check results en Checkmk 2.3.0.
3. Opciones de diagnóstico
Si no llegan tickets a Jira después de configurar la regla de notificación en Checkmk, comprueba el archivo de registro asociado ~/var/log/notify.log. Jira suele devolver aquí mensajes de error bastante útiles, que pueden ayudarte realmente en el diagnóstico del problema. A continuación enumeramos algunos ejemplos.
Mensaje de error: No se ha podido crear la incidencia, código de respuesta de JIRA 400, No se puede establecer el campo 'labels'.
Es posible que tu producto Jira no tenga etiquetas. Simplemente desactiva el uso de etiquetas en tu regla de notificación en Checkmk desmarcando Label.
Mensaje de error: No se puede crear la incidencia, código de respuesta JIRA 400, b'se requiere proyecto'.
Este mensaje de error indica que el ID que has introducido en la regla de notificación para el campo en cuestión (aquí: ID del proyecto) es incorrecto.
Mensaje de error: No se puede resolver https://jira.server.your-domain.de/browse/ISSUE-123, código de respuesta JIRA 500, b'Error interno del servidor'.
Si recibes este mensaje de error cuando se supone que un ticket en Jira debe ser cerrado automáticamente por Checkmk, o respectivamente debe ser cambiado a otro estado, entonces esto puede ser una pista de que el ID de Transición que has introducido no es correcto. El ID de Transición está en la regla de notificación del campo Activate resolution with following resolution transition ID. Como regla general, debes comparar este ID de nuevo con la interfaz web de Jira.