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-pack.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 le même Pack (de sorte que ré-importer le pack actualise également le workflow).
• Vous créez un Pack 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 du pack — ré-uploader le même .scrydon-pack.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 du Pack 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'un Pack, les workflows et les Process Flows sont découplés par un slug local au pack. Le Process Flow référence un workflow par workflowSlug ; l'importateur du pack 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 pack-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.

Si le slug ne se résout pas (le pack 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 un Pack

Un Pack 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 pack.json de niveau supérieur liste chaque workflow comme une entrée contents[] séparée :

import { defineScrydonPack } from '@scrydon/sdk-authoring/packs'

export default defineScrydonPack({
  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: { isSystemPack: false, isDemoPack: 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 du bundle

<bundle>.scrydon-pack.tar.gz
├── pack.json                          # PackBundleManifestSchema (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 — packs may ship many workflows)
└── process-flow/
    ├── manifest.json                  # ProcessFlowManifestSchema
    └── assets/                        # optional — JSON / image assets

L'inspecteur du pack 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 pack 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'intégration, …) é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.

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 pack build src/pack.ts --outDir dist
# → dist/<package.id>-<package.version>.scrydon-pack.tar.gz

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

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

Idempotence

L'identifiant de ligne du workflow matérialisé est dérivé comme pack:<packageId>:<slug>:<workspaceEnvironmentId>. Re-uploader le même Pack 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 le même pack peut être installé 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