Forge es una plataforma de desarrollo diseñada para revolucionar la forma en la que se customizan, extienden y se integran los productos Cloud.
Forge nace para ayudar a los desarrolladores a hacer extensiones o plugins de manera mucho más sencilla y con un coste económico menor para el desarrollador, debido a la alta complejidad que tenía desarrollar con Connect, Atlassian tomo el objetivo de facilitar esta necesidad y de ahí el nacimiento de Forge.
Forges cooperación desarrollo
Empezar con Forge es relativamente sencillo y desde atlassian tenemos tutoriales y ejemplos que nos pueden ayudar en nuestro viaje.
Antes de comenzar la configuración del entorno de desarrollo, será necesario:
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.
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 qué 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.
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:
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.- Una 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:
Al tratarse de la primera instalación, se ejecutará el comando forge install y se completará la siguiente información solicitada:
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.
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:
https://developer.atlassian.com/platform/forge/getting-started/
https://developer.atlassian.com/platform/forge/example-apps/
https://developer.atlassian.com/platform/forge/debugging/
https://developer.atlassian.com/platform/forge/manifest-reference/modules/
Recent Comments
QA: valor crítico de éxito
Inlogiq especialista en calidad del software, metodologías y tecnologías para garantizarla - Plaza MayorQA: valor crítico de éxito
Inlogiq se especializa en calidad del software, metodologías y tecnologías para garantizarla - corporate.es