Saltar a contenido

Adoption playbook — primeros 90 días

Plan ejecutivo para un equipo nuevo adoptando el workflow engine. Desde "hello world local" en día 1 hasta "production rollout" en día 90. Hitos verificables, anti-patterns, escalations.

Audiencia

Equipo técnico (3-10 personas) adoptando el engine para automatizar procesos de negocio. Asumimos: - Conocen Postgres básico. - Conocen REST APIs. - Posiblemente vienen de cron jobs / Airflow / state machines en código. - NO necesariamente conocen BPMN.

Fase 1: Discovery & decision (semanas 0-2)

Goals

  • Validar fit técnico.
  • Convencer stakeholders.
  • Setup local dev environment.
  • Primer proceso "hello world".

Hitos verificables

Día 1: wf CLI instalado, engine local corriendo, hello-world proceso completa.

# Quick start
curl -sSL https://get.example.com | sh  # instala wf CLI
wf engine start-local                    # docker-compose up
wf process deploy hello-world.bpmn
wf instance start hello-world --await

Si esto no funciona en < 30 minutos, no continúes — escalate a soporte / docs.

Día 3: Equipo ha leído: - README.md (overview). - analysis/blueprint-plataforma-simplificada (arquitectura). - analysis/bpmn-coverage-matrix (qué soportamos). - Quickstart tutorial (40 min hands-on).

Día 7: PoC con un proceso real del equipo. Reflexiones documentadas: - ¿Modela bien tu use case? - ¿Falta algo crítico? - ¿DX es aceptable?

Día 14: Decisión go/no-go documentada. Si go: - Sponsor identificado. - Equipo de 2-3 ingenieros asignados. - Budget para infra aprobado. - Timeline a producción (recomendado: 60-75 días desde día 14).

Anti-patterns Fase 1

  • ❌ "Vamos a evaluar 5 workflow engines en paralelo" → análisis-parálisis. Pick 2, deep-dive.
  • ❌ "Probemos con un proceso super complejo" → frustración. Empezar simple.
  • ❌ Sin sponsor ejecutivo → muere a los 60 días por prioridad shift.

Fase 2: Foundations (días 15-30)

Goals

  • Staging environment funcional.
  • 3-5 procesos modelados (no necesariamente en producción).
  • Workers implementados.
  • CI/CD pipeline para deployments.
  • Observability básica.

Setup técnico

Día 15: Provisioning staging.

# Helm
helm install wf-staging oci://ghcr.io/example/charts/wf-engine \
    -f staging-values.yaml \
    --namespace wf-staging --create-namespace

# Verify
kubectl get pods -n wf-staging
wf cluster status --context staging

Staging incluye: - Engine cluster 2 nodes (HA). - Postgres 1 primary + 1 replica. - Operate + Tasklist accesible vía VPN/internal. - Prometheus + Grafana dashboards. - Audit log retention 30 días.

Día 17: First worker en Go.

client.RegisterWorker(wfclient.WorkerOptions{Type: "send-email"}, sendEmailHandler)
client.Run(ctx)

Deploy worker como container, monitor en Grafana.

Día 20: Modelar 3 procesos.

Sugerencia: empezar con procesos pequeños bien definidos.

proceso-1.bpmn — "onboarding cliente" (5 elementos, 0 gateways)
proceso-2.bpmn — "approve invoice" (8 elementos, 1 boundary timer)
proceso-3.bpmn — "ship order" (10 elementos, 1 XOR gateway, 1 boundary error)

NO empezar con procesos > 20 elementos o con compensation hasta haber modelado 5+ simples.

Día 25: CI/CD para deployments.

# .github/workflows/deploy.yml
on:
  push:
    branches: [main]
    paths: [processes/**]
jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - run: wf process validate processes/*.bpmn
      - run: |
          for f in processes/*.bpmn; do
              wf process deploy "$f" --context staging
          done
      - run: ./tests/run-integration-tests.sh

Día 30: Observability dashboards.

Dashboards en Grafana: - Process throughput (instances/min). - Job latency (p50, p95, p99). - Error rate. - Incident count. - Engine resource usage.

Anti-patterns Fase 2

  • ❌ "Vamos a modelar todos los 50 procesos del equipo en 2 semanas" → spaghetti BPMN.
  • ❌ Workers en mismo deployment que el engine → tightly coupled, no scale.
  • ❌ Skip observability "lo agregamos después" → ciegos cuando algo falle.

Fase 3: First production process (días 31-60)

Goals

  • 1 proceso crítico en producción.
  • Runbook operacional.
  • Equipo on-call trained.
  • Production-grade monitoring.

Selection criteria del primer proceso prod

Bueno: - Volumen medio (100-10K instances/day; ni demasiado bajo ni catastrophic load). - Owners claros. - Bien entendido (no descubriendo edge cases). - Reversible si va mal (e.g., con fallback al método legacy).

Mal: - Proceso de regulación cumplimiento crítico (audit pressure). - Tráfico billions/day (overkill para primer rollout). - Sin owner técnico claro.

Production rollout strategy

Día 31-35: Deployment a prod environment.

helm install wf-prod oci://ghcr.io/example/charts/wf-engine \
    -f prod-values.yaml \
    --namespace wf-prod

Prod difiere de staging: - 3+ nodes engine. - Postgres Patroni con 3 nodes + observer. - Backup automático. - TLS con cert real. - OIDC integration con corp SSO. - Alerts → PagerDuty / Opsgenie.

Día 36-40: Canary deployment del primer proceso.

Day 36: 1% del traffic real va al new engine, 99% sigue al legacy
Day 37: 5%
Day 38: 25%
Day 39: 50%
Day 40: 100% (legacy en standby para rollback)

Métricas monitoreadas: - Error rate engine vs legacy (debe ser ≤). - Latency p99 (debe ser ≤ +20% legacy). - Throughput. - Customer-facing errors.

Día 41-50: Soak.

Sin cambios. Solo observación. Bug bash session. Documentar issues encontrados.

Día 51-55: Legacy decommission.

  • Comunicar a stakeholders.
  • Apagar legacy graceful.
  • Mantener data legacy por 90 días para audit.

Día 56-60: Postmortem retrospectiva.

  • ¿Qué funcionó?
  • ¿Qué falló?
  • ¿Cuántos incidents?
  • ¿Customer impact?
  • Action items para Phase 4.

Runbook obligatorio antes de prod

# Runbook: Workflow Engine Prod

## Healthchecks
- API: curl https://wf.example.com/healthz
- DB: patronictl list
- Workers: kubectl get pods -n wf-workers

## Incidents
- High error rate: investigate worker logs
- DB primary down: check Patroni; manual failover if needed
- Disk full: see DR runbook section 4

## Escalation
- L1: on-call engineer (PagerDuty)
- L2: senior engineer
- L3: principal engineer / vendor

## Common operations
- Resolve incident: wf incident resolve <key>
- Cancel instance: wf instance cancel <key>
- Drain node: wf cluster drain <node>

Ver analysis/disaster-recovery-runbook para DR-specific.

Anti-patterns Fase 3

  • ❌ Big-bang cutover (legacy off, engine on, mismo día) → catastrophic rollback.
  • ❌ Sin canary period → bugs pegan a 100% users.
  • ❌ Equipo no entrenado en on-call → first incident is disaster.

Fase 4: Expansion (días 61-90)

Goals

  • 5-10 procesos en producción.
  • Multiple teams onboarded.
  • Best practices documentados internamente.
  • Métricas de adoption tracked.

Pattern: "Champion + Coach" model

Equipo central (3-5 ingenieros) actúa como: - Champion: evangelize el engine, train new teams. - Coach: code review BPMN, debug, optimize.

NO como gatekeeper (anti-pattern). Su rol es habilitar, no aprobar.

Onboarding cadence

Week 1: Coach pair-programs con nuevo team en su primer proceso.
Week 2: Team modela proceso 2 solo; coach reviews.
Week 3: Team deploys to staging; coach observes.
Week 4: Team deploys to prod; coach standby.

5-7 teams onboarded en 90 días = realistic.

Internal docs to maintain

  • Cookbook con patterns:
  • "How to retry with backoff"
  • "How to handle BPMN errors"
  • "How to migrate processes versions"
  • "How to write idempotent workers"
  • FAQ
  • Slack channel con search
  • Office hours weekly

Metrics dashboard for adoption

adoption.processes_in_prod
adoption.teams_using_engine
adoption.instances_per_day
adoption.workers_deployed
adoption.incidents_per_week  ← debería bajar over time

Anti-patterns Fase 4

  • ❌ Champion team se vuelve cuello de botella ("solo ellos pueden deploy").
  • ❌ Cada team inventa convención propia (variable naming, error codes) → caos.
  • ❌ Sin docs → tribal knowledge → bus factor low.

Day 90 retrospective

Cosas que medir

Métrica Target Day 90 Status
Processes in production 5-10
Teams using engine 3-5
Instances per day 5K-50K
Avg latency p99 < 1s
Error rate < 0.1%
Incidents this month < 5
Postmortems completed All major
Docs coverage 90% topics
Team confidence (survey 1-10) ≥ 7

Decision points Day 90

  1. Continue expansion: si métricas verdes, plan para 90-180 días siguientes.
  2. Pause and stabilize: si demasiado fragile, no agregar processes nuevos hasta consolidar.
  3. Roll back: si fundamentally broken, planning para sunset (raro pero posible).

Common pitfalls 90 days

"BPMN as code" anti-pattern

Equipos viendo BPMN como otra forma de escribir código procedural:

<!-- ANTI: lógica granular en BPMN -->
<bpmn:serviceTask id="t1" type="add-one"/>
<bpmn:serviceTask id="t2" type="multiply-two"/>
<bpmn:serviceTask id="t3" type="check-positive"/>

Mejor: agruparán lógica primitiva en UN service task que llama código.

<bpmn:serviceTask id="calculate" type="calculate-final-amount"/>

"Workflow knows too much"

Workers que solo hacen "DB INSERT + return" → workflow es just business logic.

<bpmn:serviceTask id="save-order" type="db-insert-order"/>

Mejor: el workflow modela el proceso, el worker hace un paso significativo.

"Workflow knows too little"

Workers con lógica grande monolítica que tiene branching, retries, transactions → mismas razones por las que tenés workflow engine, pero ahora dentro del worker.

// MAL en worker
if customer.tier == "premium" {
    if order.amount > 1000 {
        approval := requestApproval()
        // ... 200 lines más
    }
}

Mejor: modelar los branches en BPMN.

Variables explosion

Variables creciendo a 100KB+ por instancia por accumular toda la data.

Mejor: - Solo guardar IDs, no payloads. - Fetch data fresh en workers cuando se necesite. - Pruning de variables al complete activities.

Tooling para coach team

  • wf process validate --strict → catches anti-patterns.
  • wf process lint → suggestions.
  • Code review checklist BPMN PR.
  • BPMN coverage matrix accessible.

Comunicación con stakeholders

Weekly status (semanas 1-12)

This week:
- Processes deployed: <list>
- Instances run: <number>
- Incidents: <count, brief>
- Coming next week: <plan>

Blockers: <if any>

Metrics dashboard: <link>

Monthly business review

  • ROI vs legacy stack.
  • Customer impact (faster onboarding? fewer support tickets?).
  • Team productivity metrics.

Off-boarding (si decide rollback)

Si en Day 90 la decisión es "abandonar":

  1. Document why (postmortem).
  2. Migrate active instances back to legacy.
  3. Export historical data for retention.
  4. Sunset engine prod environment.
  5. Lessons learned doc → public if appropriate.

Mejor que pretender que funciona y morir lento.

Referencias