ProcessMaker Companion

Extension de VS Code para trabajar ProcessMaker 4.x con flujo local:

• Extraer recursos desde ProcessMaker (PULL)
• Editar localmente en archivos
• Detectar cambios automaticamente
• Sincronizar de vuelta al servidor (PUSH)
• Visualizar BPMN y analizar uso de scripts/screens

Version actual del proyecto: 5.2.0

Funcionalidades principales

• Autenticacion OAuth usando processmaker.key
• Extraccion de:
  • scripts
  • screens
  • collections + records
  • procesos (data + BPMN)
• Sincronizacion al servidor de:
  • scripts editados
  • screens editadas (incluye style.css y computed/*.js)
  • records de collections (create/update/delete)
• Deteccion de cambios al guardar archivos (tracking en SQLite local)
• Boton en status bar con contador de cambios pendientes
• Preview de screens:
  • editor server por screen_id
  • preview server por screen_id
  • preview server por task_id
  • preview local (webview, con entrada de datos)
• Test de script actual contra ProcessMaker (endpoint execute)
• Visor BPMN con resaltado y exportacion SVG/PNG
• Analisis de uso:
  • mapa de proceso
  • uso de script en procesos
  • uso de screen (directo e indirecto por anidacion)
• Snippets incluidos:
  • JavaScript: 87
  • PHP: 83
• Integracion opcional con git (github_url en processmaker.key)

Requisitos

• VS Code ^1.97.0
• Node.js 20.x (recomendado para desarrollo local)
• Instancia ProcessMaker 4.x accesible por red
• Credenciales OAuth tipo password grant en ProcessMaker

Instalacion y ejecucion local (desarrollo)

npm install
npm run compile

Luego abre el proyecto en VS Code y ejecuta la extension con F5 (Extension Development Host).

Configuracion inicial

1. Ejecuta el comando PM4: Generar key de example.
2. Completa el archivo processmaker.key en la raiz del workspace.
3. Ejecuta PM: PULL - Extraer todo.

Ejemplo de processmaker.key:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "base_url": "https://your-processmaker-url",
  "username": "your-username",
  "password": "your-password",
  "github_url": "https://github.com/your-org/your-repo"
}

Notas:

• github_url es opcional.
• Si existe github_url, la extension puede crear/actualizar .gitignore y .gitattributes, e inicializar git si no existe .git/.

Estructura de carpetas generada

Despues de una extraccion, el workspace queda similar a:

processmaker-companion/
  processmaker.key
  data/
    companion.db
  scripts/
    javascript/
    php/
    python/
    csharp/
  screens/
    <ScreenTitle>/
      data.json
      style.css
      vars.json
      computed/
        <id> - <property>.js
  collections/
    <CollectionName>/
      records.json
  processes/
    <ProcessName> - <id>/
      data.json
      bpmn.xml

Flujo recomendado de trabajo

1. PM: PULL - Extraer todo
2. Editar archivos locales (scripts/, screens/, collections/)
3. Guardar archivos para marcar cambios pendientes
4. Revisar contador en status bar (Sync PM)
5. PM: PUSH - Sincronizar todo
6. Validar con:
   • PM: TEST - Probar script actual
   • PM: USO - Mostrar uso de script/screen
   • PM: PROCESS - Ver mapa BPMN

Comandos disponibles

Comandos por menu contextual

• En archivos de scripts/*: test script y ver uso de script.
• En screens/*/data.json: abrir editor, preview, sync desde server y ver uso de screen.
• En carpeta screens/*/computed: crear computed.
• En carpeta processes/<Proceso - id> o bpmn.xml: abrir editor de proceso y ver mapa BPMN.

Tracking de cambios (como funciona)

• Se activa al guardar (onDidSaveTextDocument).
• Marca flags en SQLite data/companion.db:
  • scripts.is_edited
  • screens.is_edited
  • collection_records.is_edited | is_new | is_deleted
• El status bar muestra cantidad de pendientes y permite lanzar syncAll.

Analisis BPMN y visor de uso

El analizador revisa procesos locales (/processes) y cruza referencias BPMN como:

• pm:scriptRef
• pm:screenRef
• pm:interstitialScreenRef
• pm:config (por ejemplo screenRef, screen_id, completed_screen_id)

Para visualizacion, intenta cargar BPMN actualizado desde API por process_id, con cache en memoria y fallback.

El visor permite:

• Cambiar proceso impactado
• Ver tablas de referencias
• Ver resumen de impacto
• Exportar SVG y PNG
• Render con pm-modeler o bpmn-js (fallback automatico)

Preview y edicion de screens

screenPreview soporta:

• Editor server (/designer/screen-builder/{screen_id}/edit)
• Preview server por screen_id (/designer/screens/preview)
• Preview server por task_id (/tasks/{task}/edit/preview)
• Preview local en webview con:
  • datos de entrada editables
  • datos de vista previa editables
  • guardado directo en data.json
  • recarga de cambios

syncScreenFromServer actualiza en local:

• data.json
• style.css
• computed/*.js
• vars.json
• registro en tabla screens de SQLite

Snippets incluidos

• JavaScript (snippets_javascript.json): 87 snippets, prefijos pm4.*
• PHP (snippets_php.json): 83 snippets, prefijos pm4php.*

Enfocados en operaciones del SDK/API de ProcessMaker (files, environment variables, etc).

Configuracion de la extension

Propiedades disponibles en settings.json:

Scripts npm del proyecto

Endpoints usados por la extension

• POST /oauth/token
• GET /api/1.0/scripts?per_page=500
• GET /api/1.0/screens?per_page=500
• GET /api/1.0/collections?per_page=500
• GET /api/1.0/collections/{id}/records?per_page=500
• PUT /api/1.0/scripts/{id}
• PUT /api/1.0/screens/{id}
• POST|PUT|DELETE /api/1.0/collections/{collectionId}/records
• POST /api/1.0/scripts/execute/{scriptId}
• GET /api/1.0/processes?per_page=500
• GET /api/1.0/processes/{id}
• GET /api/1.0/processes/{id}/bpmn

Y vistas server:

• /designer/screen-builder/{screen_id}/edit
• /designer/screens/preview?node=...
• /tasks/{task_id}/edit/preview
• /modeler/{process_id}

Consideraciones importantes

• El workspace usado es la primera carpeta abierta en VS Code.
• El test de script ejecuta la version guardada en ProcessMaker, no cambios locales sin sync.
• Para uso/mapa BPMN se recomienda mantener /processes actualizado con extractProcesses.
• extractAllTogether no elimina collections/ antes de descargar; refresca contenido usando API/DB local.
• La suite de tests incluida actualmente es basica (sample test).