Primeros pasos en Forge: Cómo desarrollar Apps en Atlassian Cloud (Parte 1: App para Jira)

Publicado por Juan José García Merino el

ALMAtlassianAtlassian CloudForge

El objetivo de este post es introducir Forge, la nueva plataforma que proporciona Atlassian para desarrollar apps en su entorno Cloud sin necesidad de infraestructura adicional. Únicamente será necesario disponer de una instancia Cloud de Atlassian donde desplegar y probar las apps desarrolladas.

Requisitos Previos

Antes de comenzar la configuración del entorno de desarrollo, será necesario:

  • Node.js: se puede descargar desde: https://nodejs.org/es/.
  • Instancia Cloud Atlassian: donde instalar y probar las apps que se desarrollarán con Forge. Para ello se puede crear una instancia nueva desde este enlace: http://go.atlassian.com/cloud-dev y crear un site nuevo utilizando el email asociado a tu cuenta de Atlassian. Si no se dispone de una cuenta, desde ese mismo enlace se podrá crear una cuenta.

Paso 1 - Configuración del API Token

Para poder instalar apps desde un pc local sobre una instancia Cloud, será necesario que el CLI de Forge disponga de conectividad con la instancia Cloud y, además, poder logearse. Para el logeo se utiliza un API Token que se debe generar desde el perfil de la cuenta de Atlassian del usuario que se utilizará para instalar las apps desarrolladas en Forge. Para generar un API Token, será necesario realizar los siguientes pasos:

1.- Acceder al siguiente enlace: https://id.atlassian.com/manage-profile/security/api-tokens (es necesario estar logeado con la cuenta de Atlassian del usuario que se utilizará para instalar las apps)

2.- En esa página se pulsará sobre el botón Create API Token.

3.- Se introducirá un label y se guardará el token generado, ya que este token se utilizará para autenticar Forge con la instancia Cloud.

Una vez configurado el API Token, como se muestra en la siguiente imagen, se procederá a configurar el entorno de desarrollo.

Paso 2 - Configuración del entorno de desarrollo

Para poder configurar el entorno de desarrollo se realizarán los siguientes pasos:

1.- Se instalará Node.js (se puede descargar desde el enlace arriba indicado).

2.- Un vez instalado Node.js, se procederá a instalar CLI de Forge que no es más que un paquete npm. Para ello se abrirá una consola o terminal y se ejecutará el siguiente comando:

npm install -g @forge/cli

3.- Para verificar que CLI de Forge se ha instalado correctamente, se ejecutará el siguiente comando:

forge --version

Este comando debe proporcionar la versión de Forge instalada, mostrando un valor similar o superior al que se muestra a continuación:

A modo de ayuda, para conocer todos los comandos posibles que se pueden ejecutar en Forge, se puede utilizar el siguiente comando:

forge --help

Este comando muestra un listado de ayuda de la sintaxis de comandos que se pueden ejecutar en Forge y para que sirve cada uno:

4.- Lo último que falta por configurar es el login entre CLI de Forge y la instancia Cloud. Para ello se utilizará el API Token generado en el paso 1 cuando se ejecute el siguiente comando:

forge login

Se introducirá el email asociado a la cuenta de usuario de Atlassian que se utilizará para instalar las apps de Forge y el API token generado sobre esa cuenta, obteniendo como resultado el siguiente mensaje de confirmación de logeo.

Paso 3 - Mi primera App en Forge (Validador para Jira)

En este paso vamos a crear nuestra primera app con Forge, que será un validador para Jira. Este validador permitirá controlar que una subtarea no avance a un determinado estado si la tarea padre no se encuentra en una categoría de estado IN PROGRESS, es decir, no se podrá empezar a trabajar en una subtarea si la tarea padre no ha sido iniciada.

Para crear un validador en Jira, se ejecutarán los siguientes pasos:

1.- Se ejecutará el siguiente comando que permitirá crear la app:

forge create

2.- Se introducirá el nombre de la app. En este ejemplo el nombre de la app será: parent-status-validator.

3.- Una vez introducido el nombre, Forge permite seleccionar de un listado de arquetipos el tipo de app que se va a crear. En este caso se seleccionará la opción "Triggers and Validators" > "jira-workflow-validator", como se puede ver en la imagen:

Todos los módulos que se pueden desarrollar con Forge utilizando el listado de arquetipos se encuentran documentados en esta página: https://developer.atlassian.com/platform/forge/manifest-reference/modules/

4.- Una vez ejecutados los puntos anteriores se obtendrá un esqueleto de app de tipo validador. Si se accede a la carpeta creada con el nombre de la app parent-status-validator se pueden ver los ficheros que se han creado. Concretamente hay 2 ficheros que será necesario modificar para este ejemplo:

  • manifest.yml: es el fichero de configuración de la app donde se añade: nombre de la app, permisos, módulos que se incluirán en la app (validadores, panels,..), etc. Se puede considerar este fichero en Forge como el homólogo del fichero atlassian-plugin.xml en los desarrollos de modalidad On-premise.
  • src/index.js: es el fichero donde se programará toda la funcionalidad del validador de la app.

5.- Se editará el fichero manifest.yml:

Se añadirá al final del fichero manifest.yml las siguientes líneas de código, que representan los permisos necesarios que requiere la app:

permissions: scopes: - 'read:jira-work'

El resultado final del fichero manifest.yml será el siguiente:

modules: jira:workflowValidator: - key: parent-status-validator-example-workflow-validator function: main name: parent-status-validator description: A Jira workflow validator example. function: - key: main handler: index.run app: id: ari:cloud:ecosystem::app/4cbbcd9f-908e-4eaa-ad0b-23223fdfd51d name: parent-status-validator permissions: scopes: - 'read:jira-work''

Si se deseas ampliar la información sobre los permisos en Forge, se puede consultar esta página: https://developer.atlassian.com/platform/forge/manifest-reference/permissions

6.- Una vez se haya modificado el fichero manifest.yml, se editará el fichero src/index.js y se añadirán las siguientes líneas de código:

import api from "@forge/api"; export const run = async ({ issue }) => { const { key: issueKey } = issue; const res = await api const response = await api.asApp().requestJira(`/rest/api/3/issue/${issueKey}`); const issueJson = await response.json(); return { //parent status category IN PROGRESS = 4 result: issueJson.fields.parent.fields.status.statusCategory.id===4 ? true : false, errorMessage: `Issue ${issue.key} is not ready for transition because the parent status is not a IN PROGRESS status`, }; };

En esta imagen se explica el código fuente introducido:

Toda la información referente a llamadas al API Rest de JIRA se puede consultar en esta página: https://developer.atlassian.com/platform/forge/call-a-jira-api/

7.- Un vez modificados los dos ficheros se procederá a compilar y desplegar la app. Para poder compilar la app es necesario instalar todos los paquetes que se hayan importado en el código. En este caso, sólo se ha importado el paquete @forge/api. Para instalar el paquete se ejecutará el siguiente comando:

npm install @forge/api

8.- Ahora se procederá a compilar la app, ejecutando el siguiente comando:

forge deploy

El resultado obtenido deberá ser el que se muestra en la imagen:

9.- Después de compilar la app se procederá a instalar la app en la instancia Cloud, para lo cual se pueden ejecutar los siguientes comandos:

  • forge install: por defecto instala la app con un literal, indicando que se trata del entorno (DEVELOPMENT).
  • forge install -e production: instala la app sin literal debido a que se trata del entorno de producción.
  • forge install --upgrade: si la app ya ha sido instalada y lo que se desea es volver a instalarla con algún cambio, será necesario ejecutar este comando.

Al tratarse de la primera instalación, se ejecutará el comando forge install y se completará la siguiente información solicitada:

  • Seleccionar el producto donde instalar la app: Jira o Confluence; en este caso se seleccionará Jira.
  • Introducir la url de la instancia Cloud: mi-instancia-cloud.atlassian.net
  • Por último, añadir "y" para indicar si todo esta correcto y proceder a la instalación.

Una vez introducidos todos los valores se deberá obtener el resultado mostrado en la imagen:

Toda la información necesaria sobre deploy e install de apps se puede consultar en está página: https://developer.atlassian.com/platform/forge/staging-and-production-apps/#environments.

  • Si se desea desinstalar una app de una instancia Cloud se debe utilizar el siguiente comando: forge uninstall*

10.- Una vez instalada la app se accederá a la instancia Cloud y se editará el workflow diseñado exclusivamente para las Subtareas. Se seleccionará la transición donde se desea añadir la validación y se selecciona el validador que se acaba de instalar como se muestra en la imagen:

11.- Por último, lo único que quedará por hacer es probar a ejecutar la transición de la Subtarea donde se ha añadido el validador. Si la tarea padre se encuentra en una categoría de estado In Progress, la transición debería realizarse y no mostrarse ningún mensaje. Si la tarea padre se encuentra en una categoría de estado To Do o Done, el mensaje del validador debería mostrarse e impedir la transición, como se muestra en la imagen:

Espero que este post te haya servido de ayuda para crear tu primera app en Jira Cloud.

Conclusiones

Tras un análisis de la plataforma Forge, la creación de varias apps y algunos intentos de crear otras, puedo dar mi opinión personal.

Me ha sorprendido gratamente la facilidad para crear e instalar apps, sobre todo por su rapidez en la instalación y por no requerir de infraestructura adicional como pasa con Atlassian Connect. Aunque no me cabe duda de que en los próximos meses nos sorprenderá el crecimiento de esta plataforma, actualmente, dispone de algunas limitaciones. En mi opinión, las más destacables son:

  • Actualmente dispone de un listado de Módulos a implementar muy limitado. Desgraciadamente no se pueden crear Condiciones ni Post-funciones para los workflows que son tan útiles y necesarias.
  • En cuanto a los validadores, como hemos visto en este post, el criterio que se utiliza para la validación debe ser fijado con anterioridad, es decir, no se puede crear una pantalla de configuración para personalizar ese mismo validador en cada workflow modificando el criterio de validación.
  • En Forge no es posible almacenar información en base de datos como se hacía con los Active Objects en la modalidad On-premise. Si se desea guardar valores para luego utilizarlos en la app creada, se puede crear una pantalla de administración para almacenar esos valores en Propiedades, en lugar de utilizar Active Objects como se hacia en la modalidad On-premise. Posteriormente, los valores almacenados en Propiedades se pueden recuperar utilizando este API Rest: https://developer.atlassian.com/platform/forge/runtime-reference/storage-api/
  • La mayor limitación con la que me he encontrado en Forge es que, como en cualquier tecnología nueva, la documentación, ayuda y ejemplos para desarrollar nuevas apps son prácticamente inexistentes, por lo que hacer cualquier desarrollo, por simple que sea, se hace más complicado, pero con el tiempo y uso de la plataforma por la comunidad de desarrolladores, esto irá cambiando.

Continuará...

El código actual de la app lo puedes clonar desde esta url de Bitbucket:

Si quieres aprender más sobre Forge puedes consultar estas páginas de referencia que te sirvan de ayuda:

Si te ha gustado, ¡síguenos en Twitter para estar al día de próximos posts, y de la segunda parte sobre Atlassian Forge!