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 (SQLite local)
  • procesos (data + BPMN)
• Sincronizacion al servidor de:
  • scripts editados
  • screens editadas (incluye style.css y computed/*.js)
  • records de collections (create/update/delete) desde editor tabular
• 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)
• Autocompletado del SDK/API de ProcessMaker en scripts php, javascript y python
• Snippets de andamiaje de script: 10 por lenguaje (15 en Python)
• Generacion de pm4-context/: contexto destilado de ProcessMaker para asistentes de IA
• 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
  pm4-context/
  data/
    companion.db
  scripts/
    javascript/
    php/
    python/
    csharp/
  screens/
    <ScreenTitle>/
      data.json
      style.css
      vars.json
      computed/
        <id> - <property>.js
  processes/
    <ProcessName> - <id>/
      data.json
      bpmn.xml

Flujo recomendado de trabajo

1. PM: PULL - Extraer todo
2. Editar scripts/screens en archivos y collections desde PM4: COLLECTION - Abrir editor tabular
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.pending_op (none|create|update|delete) desde el editor tabular
• 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

Autocompletado del SDK

La extension registra providers de autocompletado para php, javascript y python alimentados por un catalogo generado desde el OpenAPI de ProcessMaker (assets/pm4-api-catalog.json: 33 grupos, 16 de ellos cubiertos por el SDK, 206 operaciones con sus parametros).

La idea es que no haya que recordar nombres: se escribe el acceso y salen las opciones reales, con sus parametros y su documentacion.

PHP

Incluye ademas signature help: al abrir el parentesis de un metodo se muestra la firma posicional completa con el parametro activo resaltado. En PHP los parametros opcionales del SDK son posicionales, asi que esto evita el fallo clasico de desplazarlos y acabar filtrando por el campo equivocado.

JavaScript

La llamada se inserta ya con la firma callback correcta y el manejo de error:

getUserById(userId, (error, result) => {
    if (error) { reject(error); return; }

});

Python

En Python el autocompletado ofrece rutas REST, no metodos de SDK, porque el SDK de Python de ProcessMaker no esta publicado (ver pm4-context/04-python.md). Al insertar una ruta con parametros, el literal se convierte en f-string automaticamente.

Regenerar el catalogo

npm run generate:api-catalog

Lee el OpenAPI (docs (3).json por defecto, o la ruta que se le pase como argumento) y reescribe assets/pm4-api-catalog.json. Util al actualizar de version de ProcessMaker.

Snippets incluidos

Los snippets cubren solo el andamiaje del script, que es lo que el autocompletado no puede dar. Las operaciones concretas se resuelven con el autocompletado de arriba.

Los 10 comunes: boilerplate, data, config, env, magicRequest, magicUser, tryCatch, rest, collectionRecords, updateRequestData.

Python anade 5 pm4py.sdk.*, entre ellos pm4py.sdk.probe: una sonda que se ejecuta una vez contra la instancia para descubrir que expone realmente su Python Executor.

Detalles que los snippets resuelven bien y que es facil equivocar a mano:

• JavaScript: todo lo que use el SDK va dentro de return new Promise((resolve, reject) => {...}). El Node Executor no expone resolve como global. Ademas la imagen es Node 14: sin ?., sin ??, sin fetch.
• PHP: return con array asociativo (['x' => $y], no ['x', $y]).
• Python: patron session con timeout=30 y raise_for_status(), resultado en output.

Contexto para IA (pm4-context/)

La extension genera una carpeta pm4-context/ en la raiz del workspace con el contrato verificado de ProcessMaker 4 destilado en Markdown, pensado para que un asistente de IA (Claude Code, Copilot, Cursor) escriba codigo correcto en lugar de inventarse nombres de metodos y rutas.

Se genera en dos momentos:

• Al activarse la extension sobre un workspace que ya tiene processmaker.key, y al crear la key con PM4: Generar key de example. En este caso solo crea los ficheros que falten: nunca pisa ediciones propias.
• Con el comando PM4: IA - Generar contexto, que regenera todos los documentos y abre el indice.

Contenido:

Cada afirmacion esta marcada como [verificado], [inferido] o [sin verificar], con la fuente citada, para que el modelo sepa de que se puede fiar.

Los documentos de origen viven en assets/pm4-context/ dentro de la extension; para ampliar el contexto basta con anadir o editar ficheros .md en esa carpeta.

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.
• Collections ya no se persisten como archivos en /collections; el almacenamiento oficial es SQLite (data/companion.db).
• La suite de tests incluida actualmente es basica (sample test).