ProcessMaker 3 Companion (PMKR3)

Manual de usuario completo para trabajar con recursos de ProcessMaker 3 desde VS Code.

PMKR3 permite:

• sincronizar recursos entre tu workspace y ProcessMaker (pull, push, sync);
• editar recursos localmente con seguimiento de cambios;
• visualizar uso de triggers y dynaforms dentro del proceso;
• previsualizar output documents como PDF;
• exportar variables de casos a JSON;
• lint de triggers PHP con soporte para variables ProcessMaker (@@, @%, @#, @=).

1. Requisitos

• VS Code 1.97 o superior.
• Node.js 20 o superior.
• PHP CLI en PATH si usaras:
  • previsualizacion PDF (pmkr3.showOutputPdf);
  • lint PHP (pmkr3.lintPhp).
• OpenSSH en PATH si usaras funciones SSH/Docker.
• Un workspace abierto en VS Code.

2. Inicio rapido

1. Abre la carpeta de tu proyecto en VS Code.
2. Ejecuta PMKR3: Generar PM3.key desde ejemplo.
3. Completa credenciales en PM3.key.
4. Ejecuta PMKR3: Pull from ProcessMaker.
5. Edita archivos en processes/....
6. Ejecuta PMKR3: Sync para enviar o traer cambios segun estado local.

3. Visibilidad de comandos

• Si PM3.key no existe en la raiz del workspace:
  • solo se muestra PMKR3: Generar PM3.key desde ejemplo.
• Cuando PM3.key existe:
  • se habilitan y muestran el resto de comandos PMKR3.

4. PM3.key (configuracion)

Usa PM3.key.example como base.

Campos obligatorios:

• base_url
• workspace
• api_path
• oauth_path
• client_id
• client_secret
• username
• password

Campos opcionales:

• request_timeout_ms (default: 20000)
• retry_count (default: 1)
• github
• ssh

Ejemplo minimo

{
  "base_url": "https://tu-servidor.example.com",
  "workspace": "workflow",
  "api_path": "/api/1.0",
  "oauth_path": "/oauth2/token",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "username": "admin",
  "password": "secret"
}

5. Comandos disponibles

6. Menus contextuales en Explorer

• processes/*/output-documents/*.html:
  • PMKR3: Mostrar PDF
• processes/*/triggers/*.php:
  • PMKR3: Ver uso de Trigger
  • PMKR3: Lint PHP (ProcessMaker)
• processes/*/dynaforms/*.js:
  • PMKR3: Ver uso de Form

7. Flujo de sincronizacion

Pull (pmkr3.pull)

1. Obtiene lista de proyectos.
2. Si existe github.remote_url en PM3.key y aun no hay .git, inicializa Git automaticamente.
3. Trae siempre todos los proyectos disponibles.
4. Pregunta si quieres backup PMX.
5. Descarga:

• process.json
• triggers
• dynaforms
• output documents
• mail templates

6. Genera/actualiza variables.json por proceso con variables y labels detectados en dynaforms.
7. Actualiza base local SQLite y estado de cambios.

Push (pmkr3.push)

Sube solamente recursos marcados como editados localmente:

• triggers;
• dynaforms;
• output documents;
• mails.

Sync (pmkr3.sync)

• Si hay pendientes locales: ejecuta push.
• Si no hay pendientes: ejecuta pull.

Re-sync (pmkr3.reSync)

• Muestra lista de pendientes.
• Si confirmas, los descarta y hace pull de nuevo.

8. Seguimiento de cambios locales

• PMKR3 detecta cambios al guardar archivos de recursos gestionados.
• El Status Bar muestra pendientes por tipo:
  • T triggers
  • D dynaforms
  • O output documents
  • M mails
• Click en el Status Bar ejecuta pmkr3.sync.

9. Funcionalidades avanzadas

9.1 Crear trigger

• pmkr3.createTrigger:
  • seleccionas proyecto;
  • indicas nombre;
  • crea trigger en servidor;
  • crea archivo local en triggers/.

9.2 Preview PDF de output documents

• Usa HTML de output-documents/*.html.
• Renderiza PDF via TCPDF + PHP CLI.
• Auto refresca cuando cambias/guardas el HTML.

9.3 Uso de trigger

• Analiza donde se usa un trigger en el proceso.
• Presenta:
  • tabla de tareas/puntos de ejecucion;
  • mapa BPMN resaltando actividades involucradas.

9.4 Uso de form (dynaform)

• Analiza:
  • tareas donde un form esta asignado en steps;
  • formularios padre donde aparece como subform;
  • variables del form seleccionado y de sus subforms internos (con labels y origen).
• Presenta mapa BPMN + tablas.
• Conserva todos los labels detectados para cada variable.

9.5 Exportar variables de caso

• Pide numero o parte del numero del caso.
• Busca casos via API (home/search).
• Permite seleccionar el caso en QuickPick.
• Exporta variables a:
  • cases-data/case-<APP_NUMBER>-<APP_UID>.json

9.6 Lint PHP con soporte ProcessMaker

• Ejecuta php -l sobre una copia temporal preprocesada.
• Convierte tokens ProcessMaker antes del lint:
  • @@VAR
  • @%VAR
  • @#VAR
  • @=VAR
• Publica errores en Problems.
• No modifica el archivo original.

10. GitHub init

• pmkr3.initGithub:
  • inicializa repositorio local;
  • asegura .gitignore con PM3.key;
  • asegura .gitattributes con LF;
  • configura/actualiza remoto desde PM3.key.github;
  • valida acceso al remoto con git ls-remote;
  • si no hay acceso, muestra advertencia y ofrece abrir el repositorio en navegador para solicitar permisos.

11. SSH y Docker

• PMKR3 puede montar un root remoto como carpeta secundaria.
• Si existe bloque ssh.docker, puede operar sobre filesystem del contenedor.
• Soporta:
  • auto-conexion (pmkr3.sshAutoConnect);
  • abrir terminal SSH;
  • abrir terminal dentro de contenedor.

12. Configuraciones de extension

• pmkr3.phpPath:
  • path de php para PDF/lint.
  • vacio = usa php de PATH.
• pmkr3.sshAutoConnect:
  • manual
  • prompt
  • always
• pmkr3.sshOpenTerminalOnMount:
  • true o false

13. Estructura local generada

processes/
  <ProcessName - prj_uid>/
    process.json
    variables.json
    triggers/
    dynaforms/
    output-documents/
    mails/
    backup/
data/
  pmkr3-companion.db
  pdf-cache/
cases-data/
  case-<APP_NUMBER>-<APP_UID>.json
PM3.key

14. Troubleshooting

No veo comandos PMKR3

• Verifica que PM3.key exista en la raiz del workspace.
• Si no existe, usa PMKR3: Generar PM3.key desde ejemplo.

Falla autenticacion API

• Revisa base_url, workspace, api_path, oauth_path, usuario/clave.
• Verifica que el cliente OAuth y credenciales sean validos en tu servidor PM3.

Error de PHP en preview o lint

• Instala PHP CLI o configura pmkr3.phpPath.
• Verifica ejecutando php -v en terminal.

Linter externo marca error por @@VAR

• Usa pmkr3.lintPhp para triggers PM3.
• Si Intelephense sigue mostrando falsos positivos, excluye processes/*/triggers/*.php en settings de VS Code.

SSH no monta

• Revisa alias en ~/.ssh/config.
• Verifica ssh.host_alias, ssh.remote_root y credenciales.
• Prueba conectividad con ssh <host_alias> en terminal.

15. Desarrollo (para contribuidores)

npm install
npm run compile
npm run lint