Workflows

Un Workflow est un graphe de blocs exécutable qui s'exécute aux côtés des Process Flows — une porte human-in-the-loop, un routage d'approbation, une automatisation multi-étapes. Le SDK d'authoring de Workflows vous permet de distribuer des workflows dans la même archive .scrydon-extension.tar.gz que votre Process Flow, de sorte qu'un seul téléversement installe l'ontologie, tous les workflows dont le flow a besoin, et le flow lui-même en une seule transaction atomique.

Quand utiliser ce SDK

Utilisez le SDK d'authoring de Workflows quand :

• Un Process Flow que vous distribuez a une action de actionType: "workflow" et vous voulez que le workflow réside dans la même extension (de sorte que ré-importer l'extension actualise également le workflow).
• Vous créez une extension de démo / de démarrage et ne voulez pas demander aux opérateurs de configurer manuellement les workflows après l'installation.
• Vous voulez l'idempotence au niveau de l'extension — ré-uploader le même .scrydon-extension.tar.gz met à jour les lignes de workflow sur place.

Si le workflow existe déjà dans votre tenant (workflow système ou créé manuellement), continuez d'utiliser actionType: "workflow" + workflowId sur le modèle d'action — aucune modification de l'extension n'est nécessaire.

Installation

bun add -d @scrydon/sdk-authoring zod

npm install --save-dev @scrydon/sdk-authoring zod

import {
  defineWorkflow,
  defineBlock,
  defineEdge,
} from '@scrydon/sdk-authoring/workflows'

Anatomie d'un workflow

Un exemple complet — porte HITL

Cet exemple reflète la porte HITL démontrée par la PR #1208 : un seul bloc human-in-the-loop qui bloque la transition de Realize → Deploy. Le Process Flow (section suivante) y fait référence par slug.

import { defineWorkflow } from '@scrydon/sdk-authoring/workflows'

export const realizeGate = defineWorkflow({
  slug: 'hitl-realize-gate',
  name: 'HITL — Realize → Deploy Gate',
  description: 'Approval gate before transitioning from Realize to Deploy.',
  version: '1.0.0',
  definition: {
    blocks: {
      'block-start': {
        id: 'block-start',
        type: 'starter',
        name: 'Start',
        position: { x: 0, y: 0 },
        subBlocks: {},
        outputs: {},
        enabled: true,
      },
      'block-hitl': {
        id: 'block-hitl',
        type: 'human_in_the_loop',
        name: 'Realize → Deploy Gate',
        position: { x: 240, y: 0 },
        subBlocks: {
          reviewerRole: {
            id: 'reviewerRole',
            type: 'short-input',
            value: 'admin',
          },
          resolutionMode: {
            id: 'resolutionMode',
            type: 'dropdown',
            value: 'first_claim',
          },
        },
        outputs: {
          approved: 'boolean',
          notes: 'string',
        },
        enabled: true,
      },
    },
    edges: [
      { id: 'edge-start-hitl', source: 'block-start', target: 'block-hitl' },
    ],
    loops: {},
    parallels: {},
  },
})

defineWorkflow, defineBlock et defineEdge sont des fonctions d'identité à l'exécution — ils affinent les types pour que votre IDE détecte un champ manquant ou une faute de frappe avant que le build ne s'exécute.

Le contrat de rebind de slug

Au sein d'une extension, les workflows et les Process Flows sont découplés par un slug local à l'extension. Le Process Flow référence un workflow par workflowSlug ; l'importateur de l'extension matérialise le workflow dans le tenant, récupère un vrai identifiant de workflow et rebind le modèle d'action :

// In the Process Flow:
defineAction({
  name: 'Realize → Deploy gate',
  actionType: 'workflow',
  isRequired: true,
  workflowSlug: 'hitl-realize-gate',   // ← references the workflow by extension-local slug
})

L'importateur parcourt le manifeste, cherche hitl-realize-gate dans la correspondance slug → id résolue produite par la phase d'installation du workflow, et mute le modèle d'action sur place : workflowId est défini à l'identifiant matérialisé et workflowSlug est effacé. À partir de ce moment, l'action se comporte comme toute autre action workflow.

Un slug que le modèle de Process Flow déclare en ligne dans sa propre liste workflows[] n'est pas re-lié : l'action conserve son workflowSlug, et chaque exécution matérialise sa propre copie de ce workflow. Une déclaration en ligne a priorité sur un sous-répertoire workflow-<slug>/ portant le même slug. Les deux chemins d'import (Paramètres → Extensions et POST /api/extensions/import) acceptent les mêmes archives.

Si le slug ne se résout pas (le modèle ne le déclare pas en ligne, l'extension n'a pas distribué un sous-répertoire workflow-<slug>/ pour lui, ou le manifeste à l'intérieur l'a nommé différemment), l'installation échoue immédiatement avec UNKNOWN_WORKFLOW_SLUG. De même, deux sous-répertoires de workflow revendiquant le même slug échouent avec DUPLICATE_WORKFLOW_SLUG.

Packaging dans une extension

Une extension peut contenir une ontologie, un Process Flow, et zéro ou plusieurs workflows. Chaque workflow réside dans son propre sous-répertoire workflow-<slug>/ avec un manifest.json produit depuis defineWorkflow. Le fichier extension.json de niveau supérieur liste chaque workflow comme une entrée contents[] séparée :

import { defineExtension } from '@scrydon/sdk-authoring/extensions'

export default defineExtension({
  manifestVersion: 1,
  package: {
    id: 'sap-activate-brabant',
    name: 'SAP Activate (Brabant)',
    version: '1.0.0',
  },
  contents: [
    { kind: 'ontology',     path: 'ontology',             version: '1.0.0', required: true },
    { kind: 'workflow',     path: 'workflow-hitl-gate',   version: '1.0.0', required: true },
    { kind: 'process-flow', path: 'process-flow',         version: '1.0.0', required: true },
  ],
  installOrder: ['ontology', 'workflow', 'process-flow'],
  metadata: { isSystemExtension: false, isDemoExtension: true, tags: ['sap-activate'] },
})

Quelques règles appliquées par le bundler :

• ontology et process-flow sont des singletons — chacun ne peut apparaître qu'une fois au maximum. workflow peut se répéter.
• contents[].path doit être unique pour toutes les entrées.
• installOrder est une permutation des types distincts dans contents[] — une seule entrée "workflow" couvre tous les sous-répertoires de workflow ; ils s'exécutent tous dans la phase workflow, avant process-flow pour que la correspondance de slugs soit peuplée quand le rebind du process-flow s'exécute.

Structure de l'extension

<extension>.scrydon-extension.tar.gz
├── extension.json                          # ExtensionArchiveManifestSchema (lists every subdir)
├── ontology/
│   └── manifest.json                  # OntologyManifestSchema — may be empty
├── workflow-hitl-gate/
│   └── manifest.json                  # WorkflowManifestSchema (one per workflow)
├── workflow-cutover-gate/
│   └── manifest.json                  # (optional — extensions may ship many workflows)
└── process-flow/
    ├── manifest.json                  # ProcessFlowManifestSchema
    └── assets/                        # optional — JSON / image assets

L'inspecteur de l'extension valide le manifeste de chaque sous-répertoire contre son propre schéma Zod. Les manifestes de workflow font l'aller-retour comme du JSON autonome — vous pouvez en valider un de façon isolée avec bunx @scrydon/sdk-authoring extension validate contre un manifest.json de workflow.

Règles de validation des blocs

WorkflowDefinitionSchema applique deux invariants structurels au-delà des types par champ :

Le type de bloc est intentionnellement une chaîne ouverte — le catalogue de blocs runtime (starter, human_in_the_loop, chaque bloc d'extension, …) évolue indépendamment du SDK et le schéma ne se verrouille pas sur un instantané. Pareil pour le type de sous-bloc : la valeur est préservée verbatim et exposée à l'éditeur.

Les références entre blocs sont vérifiées

Ces deux règles couvrent le graphe d'arêtes — la circulation du contrôle. L'autre moitié, ce sont les références <nomDuBloc.champ> dans les valeurs des sous-blocs — et dans forEachItems, whileCondition et doWhileCondition d'une boucle —, par lesquelles circulent les données. Elles sont vérifiées dans chaque workflow livré par votre extension : les workflows d'un manifeste workflow et les template.workflows inline d'un process flow. Chaque commande qui produit une extension livrable les résout toutes : extension validate, extension build, build-dist et build-source. Les erreurs font échouer la commande et sont signalées toutes à la fois : un workflow comportant plusieurs mauvaises références se corrige en une seule exécution, pas en une par référence. Les avertissements s'affichent sur stderr et ne modifient jamais le code de sortie.

Une référence désigne un bloc par son name, en minuscules et sans espaces — jamais par son id :

defineBlock({ id: 'block-intake-webhook', name: 'Report', /* … */ })
// reads as <report.body.subject>   ✅  the name, normalized
// NOT      <block-intake-webhook.body.subject>   ❌  the id never resolves

Les noms ne sont pas limités à l'ASCII : un bloc nommé Résumé se lit <résumé.content> et est vérifié comme les autres. Un segment de champ peut contenir un tiret — <api.headers.content-type> lit la clé content-type. Un élément de tableau se lit par sa position, écrite [0] ou .0 : <api.data.users[0].name> et <api.data.users.0.name> sont la même référence, et les deux sont vérifiées. Seul un nombre va entre crochets — <api.data[key]> n'est pas une référence.

Les trois racines runtime sont circonscrites, pas acceptées en bloc

start, loop et variable ne désignent aucun bloc : elles sont donc résolues d'après ce que le runtime fournit réellement, et non d'après blocks :

Deux formes ne sont délibérément pas vérifiées, car ce sont du texte ordinaire que le runtime laisse lui aussi intact : une référence sans segment .champ (<announcement> — impossible à distinguer de la balise HTML <div>), et tout ce qui commence par une espace, est un nombre ou contient un opérateur, @, : ou / (a < b && c > d, <0.5>, <someone@example.com>). Un nom peut commencer par des chiffres pourvu qu'une lettre les suive directement : un bloc nommé 2FA check, lu <2facheck.result>, est vérifié comme les autres, tandis que <0.5> et <1.2.3> restent du texte.

Note de migration — nouvelles erreurs de build

Une extension qui compilait sans erreur avant cette vérification peut désormais échouer à extension build / extension validate avec workflow_reference_unresolvable. Chacune de ces références produisait déjà une valeur fausse à l'exécution — le texte littéral de la référence —, le build signale donc un défaut existant, il n'en introduit pas. Pour la même raison, la vérification est livrée dans une version mineure de @scrydon/sdk-authoring, et non majeure ; épinglez la version précédente si un build doit rester vert le temps de corriger les références signalées.

Les mêmes vérifications couvrent désormais les forEachItems / conditions d'une boucle et les template.workflows inline d'un process flow : une extension dont les sous-répertoires workflow étaient déjà propres peut donc y trouver de nouvelles erreurs.

Les extensions déjà publiées continuent de s'installer. L'import d'une archive (l'aperçu de téléversement dans Settings → Platform → Extensions → Sources → Upload an extension, l'API /api/extensions/import et extension inspect) exécute les mêmes vérifications mais signale chaque constat comme un avertissement — une racine non résolue garde le code workflow_reference_unresolvable, les constats consultatifs utilisent workflow_reference_advisory — et ne bloque jamais l'installation. Reconstruisez l'extension pour les voir comme des erreurs et les corriger.

Portes Human-in-the-Loop

Chaque bloc human_in_the_loop est inspecté au build de l'extension, à son import, et au déploiement du workflow — depuis le canevas, Monitor, une automatisation, une promotion, ou POST /api/v1/workflows/{id}/deploy. Trois constats bloquent, trois avertissent. Chaque constat bloquant bloque au build, à l'import et au déploiement : une extension construite avant ces contrôles est refusée tant que sa porte n'est pas corrigée et l'extension reconstruite. Chaque avertissement est renvoyé dans hitlWarnings au déploiement et affiché à côté du message de réussite. Un retour arrière vers une version antérieure signale ses constats comme avertissements au lieu de refuser, car cette version s'est déjà exécutée.

Les noms réservés sont approved, decision, reason, verdict, responses, aggregate, submission, response, url et option. Vous n'avez pas besoin d'un champ pour la décision elle-même — approuver ou rejeter est la décision, lisible en aval via <gate.verdict> (et <gate.approved>). Le formulaire sert à ce que l'enveloppe ne porte pas déjà.

Options de décision

Une porte qui a besoin de plus qu'approuver / rejeter déclare son bulletin dans le sous-bloc decisionOptions. Chaque option correspond à une classe d'issue — approve compte pour les approbations requises, reject est un refus, other n'est ni l'un ni l'autre — et il n'y a pas de pondération. Les lignes du tableau de l'éditeur comme les objets simples sont acceptés :

decisionOptions: {
  id: 'decisionOptions',
  type: 'table',
  value: [
    { value: 'go', label: 'Go', outcome: 'approve' },
    { value: 'no_go', label: 'No go', outcome: 'reject' },
    { value: 'defer', label: 'Reporter', outcome: 'other' },
  ],
},

Les blocs en aval lisent <gate.verdict> (approve · reject · undecided), <gate.aggregate.byOption.go> (un décompte par option, 0 compris) et — sur une porte à approbation unique — <gate.option>. L'API de reprise et A2A n'acceptent qu'une valeur déclarée, envoyée comme option ; toute autre est refusée en HTTP 400 et n'est pas enregistrée. Voir Human in the Loop → Options de décision pour la façon dont chaque règle libère la porte.

Blocs IA et le champ model

Les blocs IA de base (agent, router, evaluator, translate) ont un champ model requis, mais les workflows fournis par une extension doivent le laisser vide. Coder un modèle en dur lierait votre extension à un fournisseur que l'organisation qui l'installe n'a peut-être pas activé. Lorsque le sous-bloc model est vide au moment de l'exécution, la plateforme résout l'extension LLM par défaut de l'organisation (celle configurée dans Settings → Agentic → Default LLM Extension) et utilise son modèle. Si l'organisation n'a pas de LLM par défaut configuré, l'exécution échoue avec <nom du bloc> is missing required fields: Model — configurer une extension LLM par défaut résout le problème.

Version du manifeste

Les manifestes de workflow portent manifestVersion: 1. L'extracteur au moment du build l'injecte de sorte que les auteurs n'ont pas à le faire.

Le schéma rejette :

Construire, inspecter, téléverser

bunx @scrydon/sdk-authoring extension build src/extension.ts --outDir dist
# → dist/<package.id>-<package.version>.scrydon-extension.tar.gz

bunx @scrydon/sdk-authoring extension inspect dist/sap-activate-brabant-1.0.0.scrydon-extension.tar.gz

curl -X POST "$AGENTIC_URL/api/extensions/import?organizationId=$ORG_ID&workspaceEnvironmentId=$ENV_ID" \
  -H "Cookie: $SESSION_COOKIE" \
  -F "file=@dist/sap-activate-brabant-1.0.0.scrydon-extension.tar.gz"

Idempotence

L'identifiant de ligne du workflow matérialisé est dérivé comme extension:<packageId>:<slug>:<workspaceEnvironmentId>. Re-uploader la même extension dans le même environnement d'espace de travail trouve la ligne existante et (quand replacePublished: true est passé) la supprime + la réinsère — workflow_blocks, workflow_edges et workflow_subflows en cascade. Des identifiants d'environnement différents produisent des lignes différentes, de sorte que la même extension peut être installée côte à côte dans des environnements dev / staging / prod.

workflow.variables est stocké comme Record<string, Variable> indexé par identifiant de variable. Le matérialiseur attache le workflowId résolu à chaque variable à l'insertion ; les entrées créées l'omettent.

Où aller ensuite