Lab 2.4 - Livrer des données de référence et un batch avec des deployment actions¶

Niveau : 2 Contributeur avancé

Durée : ~45 min (observé : médiane 45 min, 9 participants, le plus rapide 24 min)

Vous allez : rencontrer la pire espèce d'échec, celle où rien n'échoue, et la corriger avec trois deployment actions de trois types différents.

La situation¶

US-026 - Crew capacity reference data and nightly recalculation

As a planner, I want capacity rules per crew type and a nightly job that recalculates them, so that the planning board is right every morning and I get a summary of it in my inbox.

Critères d'acceptation :

• 12 enregistrements Crew Capacity existent dans chaque org
• Le batch est planifié toutes les nuits
• Le planificateur reçoit l'e-mail de synthèse du matin

Vous le construisez, le déploiement est vert, tout le monde valide, et trois semaines plus tard un planificateur dit que le tableau ne s'est jamais mis à jour. La métadonnée est arrivée. Rien d'autre.

Un déploiement transporte de la métadonnée. Il ne transporte pas d'enregistrements, pas de jobs planifiés, et rien de ce qu'un humain a dû cliquer dans Setup. Chacune de ces choses doit être déclarée, sinon elle arrive une fois dans votre org et nulle part ailleurs, pour toujours.

Avant de commencer¶

• Lab 2.3 terminé et mergé
• helios-dev au niveau d'integration

Les étapes¶

1. Prendre la story et construire la métadonnée¶

New User Story (2), sous Project Contribution Workflow (1) du panneau DevOps Pipeline. Nom US-026-crew-capacity-data, org helios-dev.

Dans helios-dev, créez :

• Un objet personnalisé Crew Capacity (Crew_Capacity__c), avec :
  • External_Id__c, Text 40, External Id, Unique
  • Crew_Type__c, Picklist : Roof, Ground, Electrical
  • Roof_Type__c, Picklist : Tile, Slate, Flat, Metal
  • Panels_Per_Day__c, Number 3,0
• Un onglet pour lui, pour retrouver les enregistrements dans l'application : Setup > Tabs, New sous Custom Object Tabs, objet Crew Capacity, n'importe quel style d'onglet. Gardez la visibilité par profil que propose l'assistant. Sur le dernier écran, Add to Custom Apps, décochez Include Tab en haut de la liste, puis cochez Helios Delivery seule : les autres applications n'en ont pas l'usage
• Une classe Apex CrewCapacityBatch qui recalcule Total_Capacity_kW__c sur les installations planifiées et que Salesforce peut lancer selon une planification, plus sa classe de test CrewCapacityBatchTest. Vous n'avez pas à les écrire, et c'est le seul élément de cette liste que vous ne créez pas dans l'org. Depuis scripts/apex/samples/ du repository, copiez CrewCapacityBatch.cls, CrewCapacityBatchTest.cls et leurs deux fichiers .cls-meta.xml dans force-app/main/default/classes/, dans l'Explorer, par copier-coller, comme au Lab 2.3. Ce qu'elles calculent importe bien moins ici que le fait que quelqu'un doive les planifier dans chaque org, ce qui est tout l'objet du lab
• Les accès, sur Helios Delivery Manager : Read, Create et Edit sur Crew Capacity, Read et Edit sur ses quatre champs, et sous Tab Settings sur la même page, Available et Visible. Les planificateurs entretiennent ces nombres, et c'est aussi le permission set que porte l'utilisateur de la pipeline dans chaque org : sans lui, le chargement de données de l'étape 4 trouverait des champs qu'il n'a pas le droit d'écrire. Le réglage d'onglet est ce qui affiche l'onglet dans les autres orgs, là où la visibilité par profil gardée dans l'assistant ne voyage jamais

Puis les enregistrements. Helios prend en charge 12 combinaisons, trois types d'équipe par quatre types de toiture, et chacune a besoin d'un enregistrement Crew Capacity qui dit combien de panneaux par jour cette équipe pose sur cette toiture. Saisir douze enregistrements n'apprend rien de ce dont parle ce lab, alors le menu Training les crée : Training: Level 2 (1) > Create my lab records (2). Le panneau prend de lui-même Lab 2.4 - the 12 Crew Capacity records et helios-dev, le seul lab et la seule org qu'il propose ici : répondez Yes à Create them?.

Le panneau vérifie d'abord que votre objet et ses quatre champs sont dans l'org, puis crée les enregistrements, les liste, et termine par un lien See them in the org. Ouvrez-le, ou ouvrez l'onglet Crew Capacity de l'application Helios Delivery et choisissez la vue de liste All : elle indique 12 items (1), de CAP-ROOF-TILE à CAP-ELECTRICAL-METAL. Si le panneau dit qu'un champ manque, terminez d'abord l'objet, puis relancez-le : il met à jour les mêmes douze enregistrements au lieu d'en créer d'autres.

node scripts/training.mjs records

2. Publier et regarder rien échouer¶

Récupérez l'objet, ses champs, son onglet, sa vue de liste All (la ligne ListView nommée Crew_Capacity__c.All), l'application Helios_Delivery et Helios_Delivery_Manager avec Commit changes. Sans la vue de liste, l'onglet s'ouvrirait dans les autres orgs sur Recently Viewed, qui ne montre à chacun que les enregistrements qu'il a lui-même ouverts. Les deux classes Apex ne se récupèrent pas : ce sont déjà des fichiers du projet, et Source Control liste les quatre que vous avez copiés à côté de ce que vous avez récupéré. Commitez le tout, puis Save / Publish, poussez, Pull Request. Le contrôle est vert. Mergez. Le déploiement est vert.

Ouvrez maintenant helios-integration et regardez :

• L'onglet Crew Capacity est dans l'application Helios Delivery et sa vue de liste All est là, avec zéro enregistrement
• CrewCapacityBatch existe, planifié nulle part
• Personne n'a vérifié que l'org a le droit d'envoyer l'e-mail de synthèse du batch

La fonctionnalité est dans l'org et complètement inerte. C'est pire qu'un échec, parce qu'un échec, lui, vous prévient.

3. Construire un data workspace pour les enregistrements de référence¶

La story est mergée, donc ce qui manque part dans une deuxième Pull Request pour la même story. New User Story, nom US-026-crew-capacity-actions, org helios-dev : une branche de suite est la façon dont une équipe termine une story, et sfdx-hardis le dit lui-même à la fin de chaque Save / Publish, ne réutilisez pas la même branche.

Sur la Welcome page, cliquez sur Data Workbench. Le panneau qui s'ouvre s'intitule Data Import/Export Workbench. Create Workspace (1) est en haut à droite, et les workspaces que le projet porte déjà sont listés à gauche (2) : HeliosBaseline est celui dont se sert le menu Training pour alimenter votre org.

Un workspace est un dossier de fichiers CSV plus la recette qui dit quel objet chacun remplit et comment. Il est exécuté par SFDMU, le chargeur de données qu'utilise sfdx-hardis, et rien dedans n'est propre à une org.

La capture a été prise à la fin de cette étape : elle montre déjà HeliosCrewRefData sous HeliosBaseline. La vôtre ne montre que HeliosBaseline tant que vous ne l'avez pas créé.

Créez un nouveau workspace :

1. Create Workspace (1), et remplissez ses trois champs :
   • Workspace Name : HeliosCrewRefData, le nom de son dossier sous scripts/data/
   • Display Label : Crew capacity reference data, le nom qu'affichent les panneaux, par exemple quand vous choisissez ce workspace dans une action de déploiement à l'étape 4
   • Description : The 12 Crew Capacity records every org needs: panels a day per crew type and roof type.

2. Add Object, et collez ceci dans SOQL Query. Elle nomme l'objet et les quatre champs que vous avez créés :

   SELECT External_Id__c, Crew_Type__c, Roof_Type__c, Panels_Per_Day__c FROM Crew_Capacity__c
   

3. Operation : Upsert

4. External Id (for Upsert) : External_Id__c

Puis Export data. Il pose deux questions : s'il faut utiliser votre org par défaut, helios-dev, et si vous confirmez l'export. Oui aux deux. Le panneau tire vos 12 enregistrements dans scripts/data/HeliosCrewRefData/Crew_Capacity__c.csv.

Ouvrez ce fichier (1) et lisez-le. Douze lignes, une colonne par champ, chacune avec un identifiant externe stable (3), et une colonne Id en premier (2) : les identifiants d'enregistrement de helios-dev, qui ne veulent rien dire ailleurs et que l'import ignore, parce qu'il fait correspondre sur l'identifiant externe. Ce fichier est désormais versionné, relu et déployé comme n'importe quelle autre source. Les dossiers logs, reports et target que l'export a aussi écrits à côté sont ignorés par git : rien à commiter de ce côté.

4. Déclarer les trois actions¶

Les actions appartiennent à une Pull Request, elle doit donc exister d'abord : commitez le workspace, son export.json et le fichier CSV, Save / Publish, et ouvrez la Pull Request. Ouvrez-la ensuite dans le panneau DevOps Pipeline, onglet Deployment Actions, et ajoutez-en trois.

Un : charger les données de référence.

Deployment job only, pas les deux jobs, parce qu'un job de validation est une répétition : il contrôle la métadonnée et ne change rien. Un import écrit des enregistrements pour de vrai, il n'a donc rien à faire pendant un contrôle.

Type (1) décide des champs que montre le reste de la boîte. SFDMU Project Path (2) est une liste déroulante des workspaces sous scripts/data/, il nomme donc HeliosCrewRefData plutôt que son chemin. Target orgs (3) sur All target orgs veut dire toutes les orgs dans lesquelles la pipeline déploie.

Deux : planifier le batch.

Schedule Batch (1) remplace le champ de script par deux champs à lui : Apex Class Name (2), une liste déroulante des classes que Salesforce peut lancer selon une planification, lues dans votre org par défaut et dans le projet, et Cron Expression (3), que la boîte explique avec des exemples sous le champ.

Dans votre liste, la classe s'affiche CrewCapacityBatch (in the project, not in the default org yet). C'est normal, et c'est bien celle à choisir : la classe est allée du repository à helios-integration par la pipeline et jamais dans helios-dev, où vous n'en aviez pas besoin. L'action s'exécute dans les orgs où la pipeline déploie, et la classe y est avant qu'elle ne tourne.

Trois : celle que personne ne peut automatiser.

Certaines choses n'ont pas d'API. La délivrabilité des e-mails est la plus connue : le droit pour une org d'envoyer des e-mails tout court est un réglage de Setup qu'aucun déploiement ne peut changer. Le batch envoie au planificateur une synthèse quand il a fini, et dans une org où la délivrabilité n'est pas sur All email, cet e-mail est jeté sans un mot.

1. Open **Setup**, type `Deliverability` in the Quick Find box, and open it.
2. Under **Access to Send Email**, set **Access level** to **All email**.
3. Click **Save**.
4. Check: the page reads **All email**. If it already did, there is nothing to do.

Sur vos scratch orgs, c'est déjà sur All email, l'étape prend donc dix secondes. Sur un vrai projet, c'est l'étape que les gens oublient : chaque rafraîchissement de sandbox remet une sandbox sur System email only, et le premier signe est un planificateur qui demande pourquoi la synthèse n'arrive plus.

Manual (1) ne laisse qu'un champ qui compte, Instructions (2), une zone multiligne qui accepte le Markdown : numérotez les clics, et terminez par ce que la personne doit voir après. Target orgs (3) reste sur All target orgs, parce que ce clic est nécessaire dans chaque org.

When est sur Before Metadata Deployment, contrairement aux deux autres. L'org doit avoir le droit d'envoyer des e-mails avant que quoi que ce soit qui en envoie y arrive : la personne qui merge fait donc ce clic d'abord, puis merge. Une étape manuelle déclarée avant le déploiement est listée en premier dans le commentaire de la Pull Request, c'est là qu'elle la lit.

Execution Contexts est sur Validation and Deployment jobs, contrairement aux deux autres là aussi : le check de la Pull Request doit voir l'étape pour la réclamer avant le merge. Dès que When indique Before Metadata Deployment, une étape manuelle ne propose rien d'autre. Si votre fenêtre liste encore trois contextes, votre extension est plus ancienne : choisissez celui-ci.

Une étape manuelle ne fait rien. Elle apparaît dans le commentaire de la Pull Request et dans le rapport de déploiement, de sorte que la personne qui livre en production est prévenue, dans la livraison elle-même, qu'il y a un clic à faire. C'est la différence entre une étape manuelle qui est faite et une qui vit dans une page Confluence que personne n'ouvre.

Écrivez-la donc pour quelqu'un qui n'a jamais vu votre story : chaque clic, dans l'ordre, avec les noms exacts à l'écran, et ce que la page montre une fois que c'est fait, comme les quatre lignes ci-dessus. Le release manager la fait dans une org que vous n'avez jamais ouverte, souvent le jour de la livraison. S'il doit deviner ce que vous vouliez, il devinera, et une mauvaise supposition en production est pire que pas d'étape du tout.

Mettez ensuite la Pull Request à jour, sinon aucune des trois n'existe pour le pipeline.

Pour l'instant, les actions ne sont que sur votre poste. Chaque Save a écrit l'action dans un fichier sous scripts/actions/, nommé d'après le numéro de votre Pull Request : .sfdx-hardis.12.yml pour la Pull Request 12. VS Code l'a dit à chaque fois, dans une notification en bas à droite : Deployment action saved for Pull Request #12. Don't forget to commit and push, suivi du chemin du fichier. Son bouton Open Git ouvre Source Control, où le fichier attend.

Commitez-le, puis Save / Publish. Le contrôle de la Pull Request et le déploiement lisent les actions dans ce fichier, sur la branche de la Pull Request, et non dans le panneau : une action jamais poussée ne tourne pas, et rien n'échoue pour vous le dire.

5. Lire le commentaire de la Pull Request¶

Le contrôle repart sur le commit que vous venez de publier. Cette fois, il passe au rouge, et c'est voulu. L'étape de délivrabilité tourne avant le déploiement : elle doit donc être faite avant le merge, et sfdx-hardis arrête le contrôle tant que personne ne dit qu'elle l'est. Son log nomme l'étape et les trois façons de la marquer, et sfdx-hardis publie un commentaire Deployment Actions sur la Pull Request :

Sous sa bannière, un verdict indique In integration: 👋 1 to do by hand, puis :

• Needs you (1) : votre étape de délivrabilité, avec une case à cocher, marquée 👋 et suivie de (org branch: integration)
• Status by org (2) : une ligne par action, avec son moment. L'étape de délivrabilité, pre-deploy, est to do by hand ; l'import et la planification, post-deploy, indiquent not run in this org branch yet, parce que le contrôle s'est arrêté avant eux, et qu'un contrôle ne lance ni l'un ni l'autre de toute façon

Le commentaire du contrôle liste aussi l'étape, sous 👋 To do by hand in integration before the deployment, avec sa propre case à cocher.

Faites le clic dans helios-integration (elle affiche déjà All email sur vos scratch orgs, c'est donc une vérification de dix secondes), puis cochez la case (1). Dans VS Code, Mark as done in integration sur l'étape, dans l'onglet Deployment Actions de votre Pull Request, fait la même chose.

Relancez ensuite le contrôle : sur la Pull Request, ouvrez Checks et cliquez sur Re-run all jobs. Il lit votre case, enregistre l'étape comme faite dans integration, la saute, et passe au vert.

Mergez, et regardez le job de déploiement : l'import de données tourne, le batch est planifié, et l'étape manuelle est sautée, parce qu'elle est déjà faite dans integration.

6. Vérifier dans l'org d'intégration¶

Ne vous contentez pas de la coche verte. Ouvrez l'org et regardez :

• La vue de liste All de l'onglet Crew Capacity, dans l'application Helios Delivery, a 12 enregistrements
• Setup > Scheduled Jobs liste Helios crew capacity nightly
• L'étape manuelle est done pour integration sous Status by org, avec la date de votre case

Vous avez fait le clic avant le merge, ce qu'exige une vraie release : la personne qui merge le fait et coche la case, et la pipeline ne laisse pas passer le merge tant que ce n'est pas fait. C'est tout l'intérêt : vous l'avez faite parce que la pipeline vous l'a dit, pas parce que vous vous en êtes souvenu.

[WARNING] Describe failed for {Crew_Capacity__c}: The requested resource does not exist
[WARNING] {Crew_Capacity__c} is missing in the Target.
[WARNING] {Crew_Capacity__c} Object will be excluded from the process.
[WARNING] Object set 1 has no objects to process after validation. Skipping.
===== MIGRATION JOB ENDED =====
Command succeeded.
Exit code 0 (SUCCESS).

L'habitude derrière tout cela : un déploiement vert prouve que la métadonnée est entrée, et ne prouve rien d'autre. L'org est la seule chose qui vous dise qu'une action a tourné.

commandsPreDeploy:
  - id: 5b2e8c71-0a3d-4f6e-9c1b-026000000003
    label: Set Email Deliverability to All Email
    type: manual
    parameters:
      instructions: |
        1. Open **Setup**, type `Deliverability` in the Quick Find box, and open it.
        ...
commandsPostDeploy:
  - id: 5b2e8c71-0a3d-4f6e-9c1b-026000000001
    label: Load crew capacity reference data
    type: data
    parameters:
      sfdmuProject: HeliosCrewRefData
    context: process-deployment-only
    runOnlyOnceByOrg: true
  - id: 5b2e8c71-0a3d-4f6e-9c1b-026000000002
    label: Schedule the nightly crew capacity recalculation
    type: schedule-batch
    parameters:
      className: CrewCapacityBatch
      cronExpression: "0 0 2 * * ?"
      jobName: Helios crew capacity nightly
    context: process-deployment-only
    runOnlyOnceByOrg: true

Ce que vous devez voir¶

• Douze enregistrements Crew Capacity dans helios-integration
• Helios crew capacity nightly dans Setup > Scheduled Jobs
• L'étape manuelle listée dans le rapport de déploiement, cochée par vous

Vérifiez votre travail¶

Welcome page > Training: Level 2 > Check my work, puis choisissez le Lab 2.4.

Pour aller plus loin¶

• Data workspaces avec SFDMU
• Deployment actions

Suite : Lab 2.5 - Passer la barrière de qualité de code et la couverture de tests Apex

Questions and comments