Bizagi CLI

Para desarrollar conectores de Bizagi Studio de forma más eficiente, se puede usar una API llamada bz-cli (pronunciada cómo "Bizagi CLI"). Es una API en tiempo de compilación que permite construir conectores de Bizagi Studio sin la necesidad del editor de conectores.

Esta herramienta que soluciona los problemas mencionados a lo último de la sección anterior y provee algunas utilidades cómo generación automática de documentación, mapeo automático de entradas y salidas, entre otros.

Instalación

npm install bz-cli -g

Crear un nuevo proyecto

bz new <appName>

También se puede usar yarn para crear el proyecto (yarn es más rápido que npm), de manera:

bz new <appName> --yarn

Esto generará un nuevo proyecto con la siguiente configuración:

• Babel para transpilación de ES2015+ a ES5.
• Jest para pruebas.
• bz-define para crear la definición del conector.
• bz-zip para comprimir el conector en un archivo .bizc.

Estructura del proyecto

.
|-- .babelrc_____________________________# Archivo de configuración de babel
|-- .editorconfig________________________# Configuración de espacios.
|-- README.md____________________________# README.
|-- bz.config.js_________________________# Archivo de configuración principal.
|-- logo.js______________________________# Módulo que exporta un string en base64.
|-- map-contract.js______________________# Generador de entradas y salidas.
|-- package.json_________________________# Archivo de configuración de npm.
|-- __tests__ ___________________________# Archivo de test.
|   |-- common.js _______________________# Common functions used by all the test files.
|   |-- upload-file.test.js______________# Ejemplo de prueba.
|-- build________________________________# Verdadero contenido del conector.
|   |-- bizagiRouter.js
|   |-- actions
|   |-- auth
|   |   |-- auth.js
|   |-- etc
|       |-- config.js
|       |-- errors.js
|-- docs_________________________________# Archivos relacionados a la generación de la documentación
|   |-- doc-styles.js____________________# Estilos del documento.
|   |-- generate-english-docs.js_________# Script para generar la versión inglés de la documentación.
|   |-- generate-spanish-docs.js_________# Script para generar la versión español de la documentación.
|   |-- index.js
|   |-- inputs.d.js______________________# Diccionario inglés-español de los inputs de las acciones..
|-- etc__________________________________# Archivo necesario para usar bz-util.
|   |-- config.js
|-- inputs_______________________________# Mapeo de entradas para bz-define. Se generan ejecutando los test.
|   |-- index.js_________________________# Archivo mapa para exportar las entradas.
|   |-- upload-file.inputs.js
|-- outputs______________________________# Mapeo de entradas para bz-define. Se generan ejecutando los test.
|   |-- index.js_________________________# Archivo mapa para exportar las entradas.
|   |-- upload-file.outputs.js
|-- src__________________________________# Tu código va acá.
    |-- upload-file.js

Instrucciones

• Escriba todo su código en la carpeta src. Puede tener cualquier clase de jerarquía dentro de esta, pero recuerde:

  • Las acciones deben estar ubicadas en la raíz del directorio src.

  • Para que sea reconocida por Bizagi Studio, las acciones deben estar escritas en el archivo bz.config.js.

  • Los nombres de los archivos de las acciones deben ser iguales a los nombres de las acciones en el archivobz.config.js.

• Para generar el código que Bizagi Studio usará, use npm run dev. Este comando ejecutará a Babel que transpilará todo el código de src al directorio build/actions por ti.

• Por defecto, las pruebas se encuentran en el directorio __tests__.

  • El archivo de prueba generará las entradas y salidas de las acciones adicionalmente y las ubicará en las carpetas respectivas.

  • Los mapeos de las entradas serán ubicados en la carpeta inputs y exportados en su archivo index.js.

  • Los mapeos de las salidas serán ubicados en la carpeta outputs y exportados en su archivo index.js.

  • Recuerde siempre ejecutar las pruebas desde lar raíz del proyecto.

• Ejecute npm run build para compilar el conector.

  • Un archivo llamado Connector.bizc será generado cómo resultado.

  • Recuerde incrementar la versión del package.json.

• Ejecute npm run clear para borrar archivos temporales (En caso tal que el proceso de compilación fue interrumpido).

• No modifique los contenidos de la carpeta build.

• No modifique los contenidos de la carpeta etc.

Comandos útiles

• bz generate-action <actionName>: Genera una acción y su prueba. Recuerde registrar la acción en el archivo bz.config.js.

• bz generate-service <serviceName>: Genera una nueva clase de servicio.

• bz generate-repository <repositoryName>: Genera una nueva clase repositorio.

• bz generate-http: Genera un nuevo módulo http.

Configuración

Este proyecto utiliza bz-define para crear la definición del connector, es decir, utiliza un archivo llamado bz.config.js, ubicado en la raíz del proyecto. bz.config.js contiene toda la información que Bizagi Studio requiere para interpretar el conector.

Este es un breve resumen de las propiedades del JSON bz.config. Véase la interfaz para mayor detalle.

Acciones

Propiedades de autenticación

Usando Typescript, podemos definir el contrato como el siguiente (Tomada directamente del repositorio):

interface BzConfig {
  /**
   * Name of the connector.
   * The standard is to use a name such as 'bz-something', like 'bz-docker' for example.
   */
  name: string;

  /*
   * Name to display in the documentation.
   * if the name is 'bz-docker' then the serviceName should be something like 'Docker Remote API'.
   */
  serviceName: string;

  /**
   * What does this connector is supposed to accomplish.
   */
  description: string;

  /**
   * A short summary of what the service you are connecting to is about.
   * This is used in the english docs.
   */
  'explanation-en': string;

  /**
   * A short summary of what the service you are connecting to is about.
   * This is used in the spanish docs.
   */
  'explanation-es': string;

  /**
   * URL of the service docs.
   */
  url: string;

  /**
   * A base64 image string.
   */
  icon: string;

  /**
   * Who is creating this project.
   */
  author: string;

  /**
   * Semantic versioning. Current version of the project.
   * ALWAYS REMEMBER TO INCREASE THIS VALUE BY 1 EVERYTIME YO UWANT TO IMPORT IT TO BIZAGI STUDIO.
   */
  version: string;

  /**
   * An array of the actions the connector provides.
   */
  actions:
    {
      /**
       * The name should be dashcased and should be the same as the filename that contains the action (this is the only way Bizagi Studio finds it).
       */
      name: string;

      /**
       * Every action needs a description in english.
       * This is used in the english docs.
       */
      'description-en': string;

      /**
       * Every action needs a description in spanish.
       * This is used in the spanish docs.
       */
      'description-es': string;

      /**
       * Every action has inputs. See the ActionIO interface to understand how to structure them.
       * If the action doesn't have inputs, place and empty array [].
       */
      inputs: ActionIO[];

      /**
       * Every action has outputs. See the ActionIO interface to understand how to structure them.
       */
      outputs: ActionIO[];
  }[];

  /**
   * An array of auth properties that repensents what you need to configure in Bizagi Studio.
   */
  auth: {
    /**
     * Name of the authentication property.
     */
    name: string;

    /**
     * If this value required.
     */
    required: boolean;

    /**
     * Should the value be encrypted by Bizagi.
     */
    hide: boolean;

    /**
     * What this property means.
     * This is used in the english docs.
     */
    'description-en': string;

    /**
     * What this property means.
     * This is used in the spanish docs.
     */
    'description-es': string;
  }[];
}

interface ActionIO {
  /**
   * The name of the action and also the name of the file that executes such actions.
   * It should not contain special characters.
   */
  name: string;

  /**
   * The type of input this represents
   */
  type: 'integer' | 'decimal' | 'string' | 'boolean' | 'date' | 'time' | 'byte' | 'object';

  /**
   * boolean to indicate if Is this an unique input or an array.
   */
  qty: 'single' | 'list';

  /**
   * If you have 'object' as type then you will need to provide the properties as a nested ActionIO with the same structure.
   * This is ignored type has any other value.
   * You cannot have this array empty if the type is 'object'. It must have a key at least.
   */
  props?: ActionIO[];
}

Documentación Automática

bz-cli también permite generar la mayor parte de la documentación en inglés y español. Para hacer eso, se necesita llenar un diccionario en el archivo inputs.d.js ubicado en el directorio docs de tu nuevo proyecto.

El diccionario es usado para leer la descripción de cada entrada de cada acción descrita en el archivo bz.config.js y debe seguir la siguiente estructura:

module.exports = {
  /**
   * Each key is an action name.
   */
  'upload-file': {
    /*
     * Each input is an object with both the descriptions as its keys.
     */
    Image: {
      en: 'Input description in english',
      es: 'Input description in spanish'
    }
  },
  /* Other actions */

Una vez el diccionario esté listo, puede ejecutar npm run docs-en para generar la versión en inglés y npm run docs-es para generar la versión en español de la documentación. Un nuevo archivo en word estará en la raíz de su proyecto y solo harán falta unas cuantas cosas por escribir.