Le submit

Le submit : ce que fait l'exécution

Le submit d'une skill à kinds est une liste d'appels nommés. Un kind peut avoir les siens, dans kinds.<kind>.submit.

    submit:
      - name: dispatch
        mode: request               # request (défaut) | handover | self
        tool: createDelivery
        args:
          body.address: "$item.fields.address"
          body.items: "$selection[kind=dish]"
          body.fee: "$item.price"
          body.idempotency_key: "$action.key"
        line_fields: {ref: slug, quantity: quantity}

clé	sens
name	le nom de l'appel : lettres, chiffres, _, -. Unique parmi les appels d'une skill (les siens et ceux de ses kinds). Obligatoire
mode	request par défaut ; voir le tableau ci-dessous
tool	l'opération appelée. Obligatoire pour un request : sans elle, la station est refusée
url	le lien du tenant, pour un handover
args	les entrées de l'opération (body.x, query.y) et leurs sources
output	ce que l'appel garde de la réponse du tenant, pour un appel suivant
line_fields, line_shape	la forme d'une ligne envoyée au tenant

mode	sens	ce qui part
request	Convoy appelle une opération du tenant	tool avec args
handover	la personne termine sur le site du tenant	rien ; elle reçoit le lien url déclaré
self	la personne s'en charge elle-même (retrait au comptoir)	rien ; c'est enregistré

Un appel par skill ou par kind, aujourd'hui. Une liste de deux appels est refusée au chargement. Pour enchaîner deux écritures, utilisez deux skills, chacune avec son appel et chacune la tâche d'un playbook, et faites lire la première par la seconde avec $submitted[…]. Voir Limites actuelles.

Les sources de args.

écrire	donne
$selection	les lignes de cette skill, une par item
$selection[kind=X]	les lignes du kind X, dans toute la sélection — déposées seulement si cette opération réussit ; sinon elles restent dans la sélection
$item.fields.<champ>	un champ rempli de l'item
$item.price	le montant calculé par la garde update: {price: …}
$item.ref	la référence de l'item chez le tenant
$submitted[<tâche>.<appel>].<sortie>	une sortie d'un autre appel du même submit — voir ci-dessous
$params.<nom>	un paramètre de la skill : la liaison d'une tâche du playbook actif, sinon son default — voir ci-dessous
$action.key	la clé d'idempotence de l'action que dépose cet appel
$submit.<champ>	ce que la personne a répondu dans le formulaire du submit guard, ou ce que la room savait déjà pour un champ identifies (Auth)

Lire un autre appel : $submitted et output

skills:
  - name: formation
    invoke: {method: recommendLegalStructure}
    kinds: {company_formation: {}}
    submit:
      - name: open
        tool: openFormationDossier
        args: {body.idempotency_key: "$action.key"}
        output: {company_id: "$output.company_id"}
  - name: accounting
    invoke: {method: getAccountingPlans}
    kinds: {accounting_subscription: {}}
    submit:
      - name: subscribe
        tool: subscribeAccounting
        args: {body.company_id: "$submitted[societe.open].company_id"}

playbooks:
  - name: open-company
    tasks:
      societe: {skill: formation}
      compta:  {skill: accounting, required: false, after: [societe]}

• La tâche est celle d'un playbook : $submitted[societe.open] cite l'appel open de la skill formation, dont societe est la tâche. Écrite sur l'appel d'une skill, la référence vaut pour toute la station (une skill n'appartient à aucun playbook) : deux playbooks peuvent partager un nom de tâche s'il désigne le même appel ; un nom que deux playbooks donnent à deux appels différents est refusé à la lecture. Elle ne place pas la tâche lue avant : écrivez l'after.
• Un choix est une seule référence. Deux méthodes d'un même one_of peuvent avoir chacune un appel du même nom (pay pour le remboursement et pour l'avoir) : $submitted[geste.pay] lit la méthode qui a été déposée.
• Seul ce qui est déclaré dans output se lit. Une sortie vaut $output (toute la réponse) ou $output.<chemin> (un chemin dans la réponse). Le reste de la réponse n'est gardé pour personne.
• Seul un request a une réponse. output sur un appel handover ou self refuse la station, comme une référence à un tel appel.
• Vérifié au chargement. Citer un appel qu'aucune tâche ne fait (le nom d'une skill à la place de celui d'une tâche, une skill qui n'est la tâche d'aucun playbook), un appel non déclaré, une sortie non déclarée, la réponse de l'appel lui-même, ou une autre forme que $submitted[<tâche>.<appel>].<sortie> refuse la station. Une sortie que personne ne lit donne une note.
• À l'exécution, l'appel qui en lit un autre passe après lui. Si l'appel cité a échoué, si la référence ne peut pas recevoir de réponse, ou si deux méthodes d'un même choix y répondent, l'appel qui en dépend est mis en attente (reçu held, avec waits_for) : il n'est jamais déposé avec une valeur vide. De même pour une ligne dont l'appel enregistré lit une source que Core ne connaît pas : elle est mise en attente, jamais envoyée avec cette source écrite telle quelle ; il faut la choisir à nouveau.
• Si la tâche citée n'a rien dans la sélection, la référence est vide : le tenant applique sa propre valeur par défaut (le SIREN, par exemple).
• Une nouvelle tentative dans un parcours lit ce que ce parcours a déjà déposé, dans l'enregistrement de la room : après un submit partiel (la société ouverte, la comptabilité refusée), la comptabilité est rattachée à la société que le premier submit a ouverte. Ce qu'un parcours précédent a déposé n'est jamais lu. Si cet enregistrement ne peut pas être lu, l'appel qui en dépend est retenu (« … cannot be read right now — try again in a moment »), jamais envoyé à blanc ; si le parcours lui-même ne peut pas être lu, le submit est refusé. Hors parcours, seul ce dont des lignes déposées sont encore dans la sélection est relu.

$params au submit

Un appel du submit lit un paramètre de sa skill par $params.<nom> dans ses args. Sa valeur est la liaison que lui donne une tâche du playbook actif, pour la méthode de la ligne (Les params d'une tâche), sinon le default du paramètre.

• Une liaison part avec la réponse de l'appel qu'elle lit, dans le même submit, après lui.
• Une liaison n'a pas de valeur de repli. Si rien, dans ce submit ou plus tôt dans ce parcours, n'a répondu (la ligne du geste a quitté la sélection), ou si l'appel lu a échoué, l'appel est mis en attente.
• Ni liaison ni default : l'appel est mis en attente, avec la raison (en anglais) — « … reads $params.refund_id, which nothing sets here — no task of the active playbook binds it, and it has no default ». C'est le cas d'une skill lancée hors du playbook qui lie son paramètre.

Idempotence : $action.key, jamais $item.id

$item.id est la référence catalogue, la même pour tous les clients qui choisissent cet item. Un tenant qui dédoublonne dessus donne au deuxième client la commande du premier, avec ok: true. $action.key vient de la room et des lignes que dépose l'appel ; elle reste stable pour une nouvelle tentative. Deux lignes déposées par deux appels ont deux clés. Plusieurs lignes déposées par un seul appel (trois plats commandés ensemble) sont une seule action et partagent une clé.

line_fields — comment le tenant appelle la référence et la quantité d'une ligne. Par défaut, Convoy envoie {slug, qty}. Si le schéma du tenant attend quantity, une clé inconnue est ignorée par son API : il commande 1 pour un client qui en voulait 2, sans erreur. Vérifiez son schéma.

line_shape: ref — pour un tenant qui attend une liste d'identifiants (timesheet_ids: [..]). Refusé sur une part qui a des quantités.

handover — l'URL est celle du tenant, avec des emplacements fermés : {tenant_url}, {items}, {room}. Un emplacement inconnu refuse la station.

Les conditions à remplir avant d'exécuter — le submit guard — sont dans Politiques.