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

Niveau : 2 Contributeur avancé

Durée : ~30 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
• 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. Copiez-les depuis scripts/apex/samples/ du repository : 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, et Read et Edit sur ses quatre champs. 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

Créez ensuite 12 enregistrements Crew Capacity dans votre org, un par combinaison de type d'équipe et de type de toiture qu'Helios prend en charge.

2. Publier et regarder rien échouer¶

Récupérez l'objet, ses champs, les deux classes Apex et Helios_Delivery_Manager avec Commit changes, commitez-les, puis Save / Publish, poussez, Pull Request. Le contrôle est vert. Mergez. Le déploiement est vert.

Ouvrez maintenant helios-integration et regardez :

• Crew_Capacity__c existe, 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.

Créez un nouveau workspace nommé HeliosCrewRefData :

1. Create Workspace, et nommez-le HeliosCrewRefData
2. Ajoutez l'objet Crew_Capacity__c
3. Opération : Upsert
4. Identifiant externe : External_Id__c
5. Champs : les quatre que vous avez créés

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 et lisez-le. Douze lignes, une colonne par champ, chacune avec un identifiant externe stable, et une colonne Id en premier : 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 planifiables du projet, et Cron Expression (3), que la boîte explique avec des exemples sous le champ.

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.

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.

5. Lire le commentaire de la Pull Request¶

L'éditeur a écrit les trois actions dans scripts/actions/, dans un fichier nommé d'après votre Pull Request. Commitez-le, Save / Publish.

Quand le contrôle se termine, sfdx-hardis publie un commentaire Deployment Actions sur la Pull Request :

• Pending manual actions (1) : votre étape de délivrabilité, avec une case à cocher, pour integration. Faites le clic dans l'org, puis cochez la case : le job suivant l'enregistre comme faite
• Status by org branch (2) : une ligne par action, avec son moment. L'étape de délivrabilité, pre-deploy, attend quelqu'un ; l'import et la planification, post-deploy, sont marqués skipped, parce qu'un contrôle ne change rien

Mergez, et regardez le job de déploiement : l'import de données tourne, le batch est planifié, et l'étape manuelle reste en attente jusqu'à ce qu'une personne dise qu'elle est faite.

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

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

• Crew Capacity a 12 enregistrements
• Setup > Scheduled Jobs liste Helios crew capacity nightly
• L'étape manuelle est listée comme restant à faire, parce que vous ne l'avez pas faite

Faites l'étape manuelle à la main dans helios-integration, puis cochez sa case sous Pending manual actions dans le commentaire de votre Pull Request : le job sfdx-hardis suivant l'enregistrera comme faite. 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: email-deliverability
    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: load-crew-capacity
    label: Load crew capacity reference data
    type: data
    parameters:
      sfdmuProject: HeliosCrewRefData
    context: process-deployment-only
  - id: schedule-crew-capacity
    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