Le graphe

Les étapes d'un flux, les liens qui les relient, les aiguillages et les déclencheurs — la forme exacte du graphe que l'API accepte.

7 min de lecture Mise à jour le 10 novembre 2026

Le graphe d'un flux est un objet JSON :

JSON

{
  "Nodes": [ { "kind": "start", "Id": "…", "Name": "Accueil des nouveaux contacts" } ],
  "Links": [ { "Id": "…", "FromFlowNodeId": "…", "ToFlowNodeId": "…", "Order": 1, "Condition": null, "IsDefault": false } ],
  "Variables": [ { "Name": "Total", "Type": 1, "DefaultValue": "0" } ],
  "Triggers": [ { "Id": "…", "Kind": 0, "Event": 1, "EntityTypeName": "Contact", "Scope": 0 } ],
  "Canvas": { "Zoom": 1, "PanX": 0, "PanY": 0, "Annotations": [] }
}

Le dernier numéro d'étape, la fiche du flux et les noms des identifiants cités sont rendus par le serveur, et ignorés à l'envoi.

Les étapes

Chaque étape porte kind, en premier dans l'objet : c'est lui qui dit sa sorte.

`kind`	Rôle	Ce qu'elle porte
`start`	La carte du flux, unique et obligatoire : tous les déclencheurs y mènent, la première étape en part.	—
`trigger`	La carte d'un déclencheur : une par déclencheur de `Triggers`, avec un seul lien sortant, vers `start`.	`FlowTriggerId` (l'`Id` du déclencheur)
`action`	La seule sorte qui agit : voir Les actions et les champs.	`ActionCode`, `Configuration`, `RetryCount` (0 à 10), `RetryBackoffSeconds`, `TimeoutSeconds`, `OnErrorBehavior`, `OutputVariableName`
`delay`	Une attente.	`DelayKind` : `0` une durée (`DurationSeconds`, une seconde au moins), `1` jusqu'à une date d'un champ (`UntilFieldName`, `OffsetDays`), `2` jusqu'à une condition (`UntilCondition`, `TimeoutSeconds`, `UntilConditionTarget`)
`approval`	Une attente humaine : les approbateurs sont prévenus. Ses sorties se distinguent par `BranchKey` : `approved`, `rejected`.	`ApproverDocageUserId` ou `ApproverCircleId`, `Message`, `TimeoutSeconds`, `OnTimeoutBehavior` (`0` échouer, `1` continuer, `2` approuver, `3` refuser)
`forEach`	Une boucle : une exécution par fiche que retient son filtre, qui joue le corps — l'étape reliée par un lien `IsLoopBody`.	`EntityTypeName`, `Filter`, `MaxIterations` (1 à 10 000, d'office 1 000), `WaitForCompletion`
`call`	L'appel d'un autre flux, qui doit avoir un déclencheur « Appel de flux ».	`CalledFlowId`, `WaitForCompletion`
`condition`	La décision : ses cas se lisent dans l'ordre, le premier vrai donne sa sortie ; aucun, la sortie `otherwise`.	`Cases`, `OtherwiseLabel` — voir ci-dessous
`termination`	Une fin explicite.	`FinalStatus` (`4` réussie, `5` en échec, `6` annulée), `Message`

Toutes portent Id, Name, Description, PositionX, PositionY, EntryMode et ExitMode. Un état d'exécution envoyé (Status, Output, StartedOn…) est effacé à l'enregistrement.

Les liens et les aiguillages

Le routage se règle sur l'étape, la condition sur le lien.

Sur l'étape	Valeurs
`ExitMode`	`0` une seule sortie, dont la condition est lue : fausse, la suite n'est pas suivie (« continuer seulement si ») ; `1` plusieurs sorties, chacune avec son `Order`, la première vraie l'emporte, une seule `IsDefault` au plus ; `2` toutes les sorties en parallèle, sans condition.
`EntryMode`	`0` une seule entrée ; `1` repartir à chaque arrivée ; `2` repartir à la première arrivée et annuler les autres branches ; `3` attendre chaque branche (une branche non retenue compte pour arrivée).

Sur le lien	Rôle
`Order`	L'ordre d'évaluation, en `ExitMode` `1`.
`Condition`	Un filtre en JSON, écrit dans une chaîne — voir Les conditions et les filtres ; vide, toujours vrai.
`ConditionTarget`	Sur quoi porte la condition : absent, la fiche de l'exécution ; `PreviousStep`, la fiche produite par l'étape d'où part le lien ; l'`Id` d'une étape en amont, la fiche qu'elle a produite ; `Variables`, les variables de l'exécution — la seule forme qui ait un sens dans un flux sans fiche (courrier ou webhook entrant).
`IsDefault`	La branche « sinon », évaluée en dernier.
`BranchKey`	Après une approbation, `approved` ou `rejected` ; `error`, la branche suivie quand l'étape échoue (avec la politique « branche d'erreur ») ; après une `condition`, la clé d'un de ses cas, `otherwise` ou `error`, et rien d'autre.
`IsLoopBody`	Le lien qui accroche le corps d'une boucle : un seul par boucle, sans condition, vers une étape sans autre entrée ni sortie.
`ExecutionMode`	`0` après l'enregistrement de la fiche, par la file (d'office) ; `1` pendant l'enregistrement de la fiche qui déclenche, réservé à « Modifier l'entité » sur cette fiche.

Une sortie error compte pour une sortie : une étape qui a une suite normale et une branche d'erreur a deux sorties, donc "ExitMode": 1 et un Order sur chaque lien.

La décision : l'étape `condition`

Pour suivre une branche parmi plusieurs, posez une étape condition. Chaque cas a sa clé (Key), se juge en entier (Match : 0 tous ses blocs, 1 l'un d'eux), et chacun de ses blocs a son propre sujet : « carte prioritaire et sujet du courrier contenant urgent » s'écrit en un cas à deux blocs.

JSON

{ "kind": "condition", "Id": "…", "Name": "Prioritaire et urgent ?", "Cases": [ { "Key": "yes", "Match": 0, "Blocks": [
    { "ConditionTarget": "PreviousStep", "Test": 0, "Condition": "{\"OperatorType\":\"and\",\"Operands\":[{\"PropertyName\":\"Priority\",\"Comparison\":\"=\",\"Value\":2}]}" },
    { "ConditionTarget": "Variables", "Test": 0, "Condition": "{\"OperatorType\":\"and\",\"Operands\":[{\"PropertyName\":\"CourrierSujet\",\"Comparison\":\"contains\",\"Value\":\"urgent\"}]}" } ] } ] }

puis un lien par sortie : "BranchKey": "yes" vers l'étape du cas, "BranchKey": "otherwise" vers celle du « sinon ». Test vaut 0 pour des critères, 1 « la fiche existe », 2 « la fiche manque ». Vingt cas et dix blocs par cas au plus. Un test qui ne peut pas être jugé (fiche introuvable ou illisible, variable inconnue) met l'étape en échec — elle suit alors son lien error s'il existe —, jamais dans la sortie « sinon ». Un lien qui part d'une condition ne porte pas de Condition.

La Condition d'un lien reste admise comme garde-fou, sur une sortie unique (« continuer seulement si »). Ne composez pas d'aiguillage par ExitMode 1 : la décision s'écrit avec une étape condition.

Les déclencheurs

Chaque élément de Triggers a son Id, sa sorte (Kind) et sa carte trigger dans les étapes.

`Kind`	Déclencheur	Ce qu'il porte
`0`	Un événement sur une fiche	`EntityTypeName` (la clé du type, ou le code d'une famille de cartes : `DEAL`, `TICKET`…), `Event` (`1` création, `2` modification, `3` changement d'état, `11` rangée dans un classeur, `10` retirée d'un classeur, `20` changement de statut d'un parcours, `30` changement de statut d'un email), `Scope` (`0` toutes les fiches du type, `1` celles tirées d'un modèle, `2` une seule fiche ; `ScopeEntityId` désigne le modèle ou la fiche), `Condition`
`1`	Un champ qui change	La même chose, plus `WatchedFieldName`, et au besoin `FromValue`, `ToValue`. Un champ personnalisé s'écrit `CustomFields.` suivi de son nom technique.
`2`	Une date	`EntityTypeName`, `RelativeToFieldName` et `OffsetDays` : « sept jours avant l'échéance ».
`3`	Manuel	`EntityTypeName`, pour lancer le flux sur une fiche de ce type (`POST https://staging-api.docage.com/Flows/{id}/Launch/{entityId}`).
`4`	Un formulaire envoyé	`FormId`, `"EntityTypeName": "Form"`, `"Event": 1`.
`5`	Un appel entrant (webhook)	`Condition`. L'adresse à appeler est rendue avec le graphe ; voir ci-dessous.
`6`	Un email reçu	`Condition` ; `Scope` autre que `0` et `ScopeEntityId` désignent le compte email écouté, `0` tous ceux de l'organisation.
`7`	Un appel de flux	Le flux s'appelle depuis l'étape `call` d'un autre flux de la même organisation.
`8`, `9`	Un appel téléphonique reçu, manqué	Le numéro, la file ou le poste écouté.
`10`, `11`	Une réunion terminée, un enregistrement disponible	La réunion, ou toutes.
`12`	Un lien posé ou retiré entre deux fiches	`EntityTypeName`, `WatchedFieldName` = la relation et le côté de la fiche écoutée (`<code>\\|A` ou `<code>\\|B`), `"Event"` `1` (posé) ou `0` (retiré). L'autre fiche est dans les variables `LienAutreFicheId` et `LienAutreFicheType`.
`13`, `14`	Une page web visitée, un composant d'une page activé	Un visiteur identifié (un contact) ; la portée est une page, un modèle de page ou un site.

Un déclencheur sans fiche — courrier, appel entrant — remplit des variables, que ses conditions et les étapes lisent : CourrierSujet, CourrierExpediteur, CourrierExpediteurNom, CourrierCorps, CourrierCorpsHtml, CourrierEmailId pour un email reçu ; AppelCorps et Appel_<propriété> (une par propriété de premier niveau d'un corps JSON) pour un appel entrant. Sa Condition porte sur ces variables : fausse, aucune exécution n'est ouverte.
Appeler un flux depuis un autre système : POST https://staging-api.docage.com/Flows/Inbound/{triggerId}, sans authentification — l'adresse est le secret —, avec un corps de 256 Ko au plus. L'appel répond 202, que le flux parte ou que sa condition l'écarte.
Un flux mis à la corbeille ne part plus par aucun chemin (son adresse d'appel entrant répond 404) ; restauré, il repart.

Règles : chaque déclencheur a sa carte, chaque carte désigne un déclencheur du graphe et ne mène qu'à start, start a une première étape, et il n'y a qu'une carte start.

Les positions

PositionX et PositionY placent les étapes sur le canevas, en pixels (une carte mesure 200 × 64). Si toutes les étapes sont à (0, 0), le serveur les range lui-même, de gauche à droite ; POST https://staging-api.docage.com/Flows/{id}/Arrange les range de nouveau à la demande.