Déclencheurs et événements

Les launchers

Un ProcessLauncher possède sa propre key, ses Working Revisions et ses Releases. Son contrat versionné porte le type, la référence process, les inputs exposés, le mapping et, selon le type, l’événement ou la présentation du parcours utilisateur. Le flag active, l’URL publique et les grants restent locaux à l’environnement.

Le launcher est indépendant du Process : modifier son contrat crée une ProcessLauncher Revision, jamais une Process Revision. Réciproquement, enregistrer un nouveau Working du Process ne modifie pas le contrat du launcher ; seule la résolution d’une référence :working peut faire évoluer la Process Revision utilisée par un prochain lancement.

Référence Process versionnée

La ProcessLauncher Revision référence directement le Process cible avec la syntaxe commune des artefacts : customer_onboarding:working, customer_onboarding:latest, une Release ou un digest exact. Il n’existe plus de champ parallèle revision_mode sur le launcher.

resolved_process_definition_revision_id indique la Process Revision actuellement résolue. Une invocation ne reste jamais flottante après son démarrage : Ormuz enregistre la Process Revision et la ProcessLauncher Revision exactes sur la tentative avant tout effet.

Types de launcher

Pour checkout, onboarding, dispute et return, Ormuz connaît le contrat d’entrée système attendu. Si plusieurs définitions actives proposent le même type pour un marchand, le contexte qui crée la ressource doit sélectionner explicitement la définition ; Ormuz ne choisit pas arbitrairement entre plusieurs candidats.

Déclenchement par événement

Un launcher event écoute exactement le event_type configuré pour son marchand. À la réception d’un événement correspondant, Ormuz applique son input_mapping, crée une instance et conserve dans start_source l’identité de l’événement et du launcher à l’origine du démarrage.

Le contrat de chaque événement déclare les valeurs utilisables par le processus : contexte générique de l’événement, objets plateforme résolus, snapshots, projections ou objets d’extension selon le type. Le nom de l’événement ne suffit jamais à inventer une ressource qui n’est pas déclarée par ce contrat.

Cette liste est volontairement illustrative. Consultez le catalogue des événements plateforme et les pages d’événements propres aux extensions pour la référence exhaustive.

Lien d’expérience hébergée

Le launcher journey publie une URL stable destinée à une personne, avec son identité dans le path/launcher/:id. Ouvrir ce lien affiche une page d’entrée : aucune instance de processus n’est créée tant que la personne n’a pas explicitement choisi de commencer. Après cette confirmation, Ormuz crée une nouvelle instance et ouvre l’expérience hébergée pour le participant principal sans recharger le document : la SPA remplace l’URL par l’accès canonique au parcours utilisateur puis continue directement.

Sa présentation publique est distincte du nom d’administration : presentation.title est obligatoire et presentation.description optionnelle sur la ProcessLauncher Revision. Ces textes expliquent à la personne ce qu’elle vient accomplir ; aucun fallback générique ou nom interne n’est exposé.

La présentation et le contrat d’entrée sont versionnés avec le launcher. La référence processdétermine indépendamment si les prochains accès suivent le Working du Process ou restent liés à un snapshot immuable.

Ce mode convient aux démarches self-service, par exemple un onboarding accessible depuis un site vitrine. Aucun onboarding_case ou autre objet métier préalable n’est requis par le launcher : le processus peut commencer sans entrée externe, collecter les informations utiles puis créer les objets métier au moment approprié.

Les query params ne servent pas au routage technique du launcher : ils appartiennent entièrement au contrat externe, par exemple une campagne, une langue ou un canal. Seules les valeurs scalaires non sensibles peuvent être exposées ainsi. Les paramètres inconnus sont refusés et connaître l’identifiant d’un objet métier ne donne jamais, à lui seul, le droit de le résoudre ou de l’exposer dans l’expérience.

Endpoint API dédié

Le launcher api publie une URL POST propre à un processus et à un contrat d’entrée réduit. Utilisez-le lorsqu’un partenaire doit pouvoir déclencher une opération précise sans recevoir le droit généralprocess_instance:run ni la possibilité de choisir une autre définition de processus.

Chaque clé doit disposer de la permission process_launcher:invoke sur le marchand et d’un grant explicite sur ce launcher. Depuis le Process Builder, l’action Créer une clé dédiée fait ces deux opérations atomiquement avec le périmètre minimal : aucune autre permission métier n’est accordée et le grant cible uniquement cet endpoint. Le secret n’est affiché qu’une fois. L’utilisation d’une clé existante reste disponible comme option avancée.

Le corps JSON n’accepte que les champs déclarés par le contrat exposé ; les valeurs fixes du launcher ne peuvent pas être écrasées par l’appelant. La Process Revision est résolue depuis la référence versionnéeprocess du launcher : l’appelant ne choisit jamais la révision.

POST /v1/process-launcher-invocations/pln_123
Authorization: Bearer ormuz_live_…
Idempotency-Key: partner-request-123

{
  "reference": "partner-order-8472",
  "country": "FR"
}

Idempotency-Key est obligatoire. La première création durable répond avec l’identifiant de l’instance et son statut ; rejouer la même demande avec la même clé retrouve cette instance, tandis que réutiliser la clé avec un autre payload est refusé. Une nouvelle clé représente une nouvelle demande, même si les données métier sont identiques.

Cet endpoint ne crée pas d’accès à l’expérience hébergée et ne donne pas de droit de lecture général sur les instances. Si le processus comporte plus tard une interaction humaine, cet accès doit être produit par le mécanisme métier prévu par le processus, indépendamment du launcher API.

Attendre un événement dans une instance existante

Déclencher un nouveau processus et suspendre un processus existant sont deux primitives différentes. wait_for_platform_event attend un événement pour une ressource précise puis reprend la même instance avec les sorties déclarées par ce contrat d’événement.

wait_for_platform_events applique le même principe à une collection typée et ne termine que lorsque chaque cible attendue a produit son événement. Utilisez ces nodes lorsque l’événement appartient à la continuité d’une instance déjà commencée ; utilisez un launcher lorsque l’événement doit créer une exécution indépendante.

Lancer un processus par API

Un système externe peut démarrer explicitement une définition active avec POST /v1/processes/:id/runs. L’input est préparé et validé contre le schéma d’entrée du snapshot Working utilisé pour l’instance.

POST /v1/processes/prd_123/runs

{
  "input": {
    "invoice": "inv_abc123",
    "amount_threshold": 5000
  }
}

Cet endpoint peut également demander une attente synchrone bornée via son paramètre wait. Ce mécanisme ne change pas l’identité de l’instance ni son modèle d’exécution : il change uniquement la façon dont l’appelant attend le résultat de la Run.

Mapping d’entrée d’un launcher

input_mapping transforme le contexte de démarrage en champs de l’input_schema. Pour un événement, chaque source doit être fournie par le contrat canonique de cet événement et être compatible avec le type attendu par le processus. Une source inconnue ou incompatible est refusée lors de la configuration.

Les launchers système ont un mapping canonique pour leur objet principal — checkout_session, onboarding_case, dispute ou return. Le processus peut déclarer d’autres champs uniquement s’ils sont optionnels ou disposent de valeurs par défaut compatibles avec ce déclencheur.

Pour les launchers journey et api, chaque input du processus peut être alimenté par un champ externe déclaré, une valeur fixe du launcher ou le défaut du processus. Un input obligatoire qui n’est satisfait par aucune de ces sources empêche l’activation. Le contrat est fermé : un champ JSON ou query non déclaré n’est pas fusionné implicitement avec les inputs du processus.

Pour journey et api, vous choisissez explicitement pour chaque input s’il est fourni par l’appelant, fixé par le launcher ou laissé au défaut du processus. Le contrat exposé peut donc être volontairement plus petit que l’input_schema complet ; un champ fixé par le launcher ne peut pas être écrasé par l’appelant.

Idempotence et déduplication

Lorsqu’un même événement est livré plus d’une fois, le lancement événementiel utilise une identité de déduplication qui combine l’événement et le launcher. Un même événement ne crée donc pas plusieurs instances pour le même launcher, tout en pouvant légitimement déclencher plusieurs launchers différents.

Un Endpoint API utilise une Idempotency-Key fournie par l’appelant. Le lien d’expérience hébergée utilise de son côté une tentative de démarrage temporaire afin qu’un double clic ou une réponse perdue ne crée pas deux instances. Dans les deux cas, cette garantie protège les répétitions techniques ; elle ne déduit jamais qu’un même email, une même référence métier ou des inputs identiques représentent la même demande métier.

Ne transposez pas ces garanties au lancement direct POST /v1/processes/:id/runs : cet endpoint représente par défaut une demande explicite de nouvelle exécution.