Dans cette section, nous verrons comment mettre à jour les attributs de la ressource. Les mises à jour sont effectuées avec une commande PATCH, et la documentation de l’API REST explique comment les gérer.

Nous allons chercher à modifier les données d’une ressource particulière.

Lecture de la documentation

La lecture de la documentation nous informe sur la méthode à utiliser (PATCH), comment construire l’URL et un paramètre supplémentaire, à savoir les Headers.

URL

L’URL à utiliser ressemble à celle utilisée pour afficher les ressources, mais comme nous voulons changer une ressource spécifique, nous devons l’identifier par son identifiant interne.

L’ID interne est facilement récupéré à partir du client HTML.

L’URL sera donc {{rest_url}}/resources/91092682

Headers

La section headers spécifie la valeur : application/vnd.sciforma.v1+merge-patch+json

Dans Postman, cela sera renseigné dans la section Headers de notre nouvelle demande.

Ce paramètre est crucial ; la requête ne fonctionnera pas correctement si vous l’omettez.

Utilisation de Postman

Construire la requête

Mettons tout ce que nous avons vu ensemble et créons une nouvelle requête pour notre collection et la nommer Patch Resource

Assurons-nous que la méthode choisie est PATCH et écrivons l’URL que nous avons définie plus tôt.

L’onglet Authorization doit être défini sur ‘Inherit auth from parent’, car la récupération de jeton a été définie au niveau de la collection.

Dans l’onglet En-têtes, ajoutez un nouveau paramètre en tapant ‘Content-Type’ et en utilisant la saisie assistée pour sélectionner cette valeur.

Une fois le paramètre créé, copiez et collez la valeur de la documentation REST API.

application/vnd.sciforma.v1+merge-patch+json

À ce stade, vous devriez avoir quelque chose comme ça.

Nous sommes presque prêts, mais nous devons encore dire quel changement nous voulons faire. Cela aura lieu dans la région du body. Ouvrez-le et réglez le mode sur ‘raw’. Les paramètres de changement sont passés au format JSON et se composent de paires de nom et de valeur d’attribut.

Trouver le nom exact des attributs peut être un peu délicat. Pour les UDF, c’est le nom que vous avez donné à l’attribut. Pour le build-in, vous devriez rapidement le trouver au bout de quelques essais (le nom visible dans le Designer est en général un très bon indice).

Certains attributs, comme l’ID interne, ne peuvent pas être modifiés. Pour d’autres, le changement peut échouer si vous passez des valeurs cibles inadéquates. La valeur inadéquate peut-être (liste non exhaustive) :

• Valeurs qui ne figurent pas dans la liste de valeurs définie
• Valeurs conduisant à une erreur de validation (exemple : un ID déjà utilisé)
• Valeurs avec un mauvais format (dates, par exemple). Je ne sais pas vous, mais pour ma part, l’utilisation des dates a toujours été un enfer dans un contexte technique.

Dans notre cas, disons que nous voulons changer l’organisation. C’est assez intéressant : même si l’Organisation est une catégorie intégrée dans Sciforma, nous pouvons la changer en passant simplement le nom de la cible comme une chaîne de caractères, pas un objet.

Disons que nous voulons également actualiser la date de début. J’ai passé beaucoup de temps à comprendre le format exact à utiliser (ce n’était pas celui mentionné dans la documentation), et je vais vous aider à gagner du temps.

Retour à l’onglet Corps, insérez les données suivantes.

<!> Il faut, bien entendu, que les données que vous allez placer soient licites :

• l’organisation doit exister (créez-en une pour l’occasion, si besoin)
• la date de début doit absolument, par exemple, précéder une date de fin existante.

Lancer la requête

Vous devez cliquer sur le bouton Envoyer pour envoyer votre demande à Sciforma.

Voici ce que nous avions, dans Sciforma, avant :

Voici ce que nous obtenons, dans Postman, après avoir exécuté la requête

Notez que le code de réussite est 204, sans autre message. Cela signifier que tout s’est bien passé.

Après avoir rafraîchi votre environnement Sciforma, nous avons ceci.

La date de début a été mise à jour et l’organisation a été changée.

Possibles petits désagréments

Qu’est-ce qui pourrait mal se passer ? Beaucoup de choses.

Si vous avez ceci,

Le token d’autorisation a expiré : il faut le régénérer. Retournez à la section Autorisation de votre collection pour renouveler votre jeton et suivre le processus

Si vous avez mal saisi l’ID interne de la ressource, vous obtiendrez ce message

Si vous avez mal orthographié un nom d’attribut, vous obtiendrez un tel message

Et oui, Organization ça s’écrit avec un Z.

Conclusion

C’est tout. Vous avez tout ce qu’il faut pour modifier les données dans Sciforma. Changer une ou deux ressources est relativement simple, mais faire des changements massifs pour des centaines de personnes peut être un poil plus fastidieux. C’est pourquoi nous allons introduire l’utilisation d’un script dans la prochaine section pour automatiser cela autant que possible. On se retrouve là-bas..