Modifier un enregistrement

La syntaxe permettant de modifier un enregistrement avec un identifiant unique est la suivante (méthode PATCH):

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"field":"value"}'
     -X PATCH
     'https://<host>/api/v1/<taskId>/<recordId>'

Les champs non définis reprennent la valeur actuelle. Il est donc possible de ne spécifier que les champs devant être modifiés.

Info:

Les champs de type enum peuvent être spécifiés soit de manière complète ("FIELD":{"key":"KEY","value":"VALUE"}) ou simplifiée ("FIELD":"KEY"). Lors de la récupération d’un enregistrement, ces champs sont toujours spécifiés de manière complète.

Si le code de retour HTTP est 200, la réponse sera structurée comme ceci (comme le retour de récupération):

{
  "metadata": {
    "apiVersion": "1.0",
    "taskId": "<taskId>",
    "taskType": "<type>",
    "domainId": "<domain>"
  },
  "data": { ... }
}

Attention:

La modification est supportée dans les tâches simples, dossier et à double niveau (types B, R et F).

Paramètres

Paramètres	Type	Description
`autoAcknowledge`	Boolean	Voir la description générale. Vaut aussi bien pour la modification d’un enregistrement que pour la modification d’une page.

Modifier une page

La modification d’une page s’effectue avec la commande suivante:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"field":"value"}'
     -X PATCH
     'https://<host>/api/v1/<taskId>/<recordId>/pages/<pageId>/<occurrence>'

Si le code de retour HTTP est 200, la réponse sera structurée comme ceci:

{
  "metadata": {
    "apiVersion": "1.0",
    "taskId": "<taskId>",
    "taskType": "<type>",
    "domainId": "<domain>"
  },
  "data": { ... }
}

Certaines vérifications sont faites automatiquement par le système:

Si la clé $occurrence est précisée dans les données, elle doit être identique à l’occurrence précisée dans l’URL.
Si la clé FM_PAGE_VERSION est précisée, elle doit être identique à la version en base de données (permet d’éviter les modifications concurrentes).

Modifier un enregistrement à double niveau

Pour une tâche à double niveau (taskType = F), le corps de la requête décrit l’état cible complet: la clé header (optionnelle) contient les champs de l’en-tête à modifier, la clé lines (optionnelle) contient l’ensemble des lignes souhaitées après modification.

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{
       "lines": [
         { "$recordId": "$k$D1000$20200001$1", "SUB_MONTANT": 1200.0 },
         { "SUB_NO_ARTICLE": "TRANSPORT", "SUB_QUANTITE": 1, "SUB_MONTANT": 50.0 }
       ]
     }'
     -X PATCH
     'https://<host>/api/v1/STO30/$k$D1000$20200001$0'

Si la clé header est absente, l’en-tête n’est pas touché.
Si la clé lines est absente, les lignes ne sont pas touchées.
Si la clé lines est présente (y compris un tableau vide []), chaque ligne existante en base est comparée aux lignes du payload:
- une ligne du payload portant un $recordId existant est modifiée (mêmes règles que pour l’en-tête: les champs non spécifiés conservent leur valeur actuelle) ;
- une ligne du payload sans $recordId est créée ;
- une ligne existante en base qui n’apparaît pas dans le payload est supprimée.
Les suppressions sont effectuées en premier, puis les modifications, puis les créations.
La validation (terminate) de l’enregistrement complet est effectuée automatiquement en fin de traitement.

Attention:

Comme pour la création, une ligne du payload sans $recordId (donc créée par cet appel) doit fournir explicitement tous les champs que la cascade de remplissage automatique de l’écran (onFieldChange) aurait renseignés à la sélection d’un article: voir la remarque équivalente pour la création.

Attention:

Un $recordId de ligne qui n’appartient pas à l’enregistrement visé par l’URL est refusé (erreur 400): il n’est pas possible de « déplacer » une ligne d’un enregistrement à un autre par ce biais.

Note:

Un tableau lines vide ([]) demande donc la suppression de toutes les lignes existantes, sans toucher à l’en-tête.

Attention:

Cette suppression complète des lignes reste soumise à la validation finale (terminate) de la tâche visée, qui peut la refuser si l’enregistrement résultant sans ligne n’est pas admissible (voir la remarque équivalente pour la création). Dans ce cas, la modification échoue entièrement: ni l’en-tête ni les lignes ne sont modifiés.

Cette sémantique permet notamment de modifier une tâche dont l’en-tête est en lecture seule (par exemple SAL21, voir ici): il suffit de ne pas spécifier la clé header dans le corps de la requête.