Como empezar a desarrollar con Forge ¿Qué es Forge?

18 Oct

Como empezar a desarrollar con Forge ¿Qué es Forge?

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

¿Cómo puedo empezar a desarrollar con Forge?

Empezar con Forge es relativamente sencillo y desde atlassian tenemos tutoriales y ejemplos que nos pueden ayudar en nuestro viaje.

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.

Mindville

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

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:

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

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: