Skip to content
Guida del Centro assistenza · Workflow e automazione
3 min di letturaVerificato 2026-11-16

Configurazione dei workflow

Imposta regole di automazione e cambi modello all'interno delle tue Wallet Experiences nel workspace.

In questa guida

Panoramica

Passinstance offre due motori di automazione complementari all'interno della Dashboard (/workflows, /automations e /settings/workspace/integrations):

  1. 1
    Workflow Engine (Workflow Engine API su /api/v1/workflows): Macchine a stati DAG guidate dagli eventi, supportate da workflow trigger type (29 tipi di trigger), workflow action type (25 tipi di azione), IF_CONDITION e DELAY.
  2. 2
    Automazioni Universali (Automations API su /api/v1/automations): Regole basate su policy per e-commerce e PassFlow con supporto a ExistingCardPolicy (REUSE_AND_UPDATE, ISSUE_ADDITIONAL, REPLACE, NO_OP, ecc.) e ConflictResolutionPolicy (ALLOW_ALL, RUN_ALL, HIGHEST_PRIORITY, BEST_OFFER, FIRST_MATCH, EXCLUSIVE, EXCLUSIVE_BY_SCOPE).

Prerequisiti: La creazione o modifica di workflow tramite POST /api/v1/workflows richiede i permessi di modifica modello (templates:manage) e almeno un Modello di pass pubblicato. I workflow appena creati iniziano in stato DRAFT o INACTIVE finché non vengono attivati tramite POST /api/v1/workflows/:workflowId/activate.

Pipeline di esecuzione dei workflow

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
MOTORE WORKFLOW EVENT-DRIVEN E PROCESSOR
ATTORI DI SISTEMA COINVOLTI
P1 Event Bus di dominio / Cron
P2 Workflow Engine API e Matcher
P3 Workflow Execution Engine (Coda Bull)
FASE 1 RICHIESTA / AZIONE Emette evento trigger
FASE 2 RICHIESTA / AZIONE Abbina i workflow attivi
›
TIER_CHANGED, PASS_SCANNED)
›
(status: ACTIVE, filters)
FASE 3 RICHIESTA / AZIONE Accoda job di esecuzione
FASE 4 RICHIESTA / AZIONE Valuta condizioni
›
e azioni IF_CONDITION
FASE 5 RICHIESTA / AZIONE Esegue actions[] ordinate
›
(DELAY, SEND_PUSH_NOTIFICATION,
›
SWITCH_WALLET_EXPERIENCE)

Gestione dei workflow tramite REST (Workflow Engine API)

MetodoEndpointDescrizione
GET/api/v1/workflowsElenca i workflow del workspace (filtrabili per status in workflow status: DRAFT, ACTIVE, PAUSED, INACTIVE, ARCHIVED, ERROR).
POST/api/v1/workflowsCrea un nuovo workflow utilizzando request payload (name, trigger, actions, conditions, tags).
GET/api/v1/workflows/:workflowIdRecupera la definizione del workflow, lo storico delle esecuzioni (/:workflowId/executions) e i log (/:workflowId/logs).
PUT/api/v1/workflows/:workflowIdAggiorna trigger, condizioni, azioni o status del workflow (request payload).
POST/api/v1/workflows/:workflowId/activateAttiva immediatamente un workflow (deactivate mette in pausa l'esecuzione; trigger lo esegue manualmente).
DELETE/api/v1/workflows/:workflowIdElimina un workflow e annulla gli eventuali job differiti in sospeso.

Trigger supportati (workflow trigger type)

L'enum Passinstance database workflow trigger type definisce tutti i 29 tipi canonici di trigger di workflow:

Categoria di triggerValori workflow trigger typeQuando si attiva
Ciclo di vita pass e modelliPASS_CREATED, PASS_UPDATED, PASS_SCANNED, PASS_VOIDED, PASS_DELETED, PASS_DOWNLOADED, TEMPLATE_CREATED, TEMPLATE_UPDATEDImmediatamente quando un pass o modello viene creato, modificato, scansionato, annullato, eliminato o scaricato.
Wallet, meccaniche e opt-inPASS_INSTALLED, PASS_REMOVED, USER_OPT_IN, USER_OPT_OUT, POINTS_UPDATED, TIER_CHANGED, BALANCE_CHANGED, EVENT_EXPIRED, PASS_INACTIVE, SCAN_PERFORMEDQuando cambia la registrazione del dispositivo Apple/Google Wallet, varia il consenso marketing o viene superata una soglia di punti/livello/saldo.
Utente, fatturazione e pianificazioneUSER_REGISTERED, USER_LOGIN, USER_PROFILE_UPDATED, SUBSCRIPTION_CHANGED, PAYMENT_RECEIVED, PAYMENT_FAILED, WEBHOOK_RECEIVED, API_CALL, SCHEDULED, MANUAL, CUSTOM_API_EVENTSu eventi utente/pagamento, ricezione webhook in ingresso (POST /api/v1/workflows/webhook/:customerId/:workflowId), pianificazioni cron (normalizzate sul fuso orario del workspace) oppure esecuzioni manuali/API.

Esempio: creazione di un workflow di follow-up per cambio livello (POST /api/v1/workflows)

request payload accetta un oggetto trigger di primo livello e un array ordinato actions (IWorkflowActionConfig[]), insieme ai campi opzionali conditions, dataMapping, maxRetries (predefinito 3) e timeout (predefinito 300 secondi):

JSON
{
  "name": "Gold Tier Upgrade Celebration & Companion Voucher",
  "description": "Sends congratulatory push and waits 1 hour before issuing bonus drink voucher",
  "trigger": {
    "type": "TIER_CHANGED",
    "filters": {
      "templateId": "tmpl_loyalty_01"
    }
  },
  "conditions": {
    "field": "pass.tier",
    "operator": "EQUALS",
    "value": "GOLD"
  },
  "actions": [
    {
      "type": "SEND_PUSH_NOTIFICATION",
      "name": "Gold Upgrade Alert",
      "config": {
        "message": "Welcome to Gold Tier! Enjoy 2x points on every visit."
      }
    },
    {
      "type": "DELAY",
      "name": "Wait 60 Minutes",
      "config": {
        "durationMinutes": 60
      }
    },
    {
      "type": "GENERATE_ADDITIONAL_PASS",
      "name": "Issue Companion Voucher",
      "config": {
        "targetTemplateId": "tmpl_gold_welcome_drink",
        "linkToParentPass": true
      }
    }
  ],
  "tags": ["loyalty", "gold-tier"]
}

Esplori tutti i tipi di azione in Operazioni automatizzate sui pass e l'orchestrazione visuale su /workflow-engine.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.