Table of Contents

Initialise Enrolment Register

Important

This operation is gated. An apply needs --AllowHost <host> naming the destination, and --Confirm <token> carrying the token a --PreviewMode run of this exact command printed. A command with --Apply alone is refused with exit code 2 and writes nothing. See the apply gate for the workflow.

Run this once on every existing environment after importing the release that brings enrolment quick complete, and before anyone turns on Referral - Use Modern Enrolment Activities.

Why it is needed

The release adds two Yes/No columns to the Activity Register:

  • Allow quick complete (mag_allowquickcomplete) lets an administrator stop a type from being completed from the referral's Enrolment activities list.
  • Enrolment Activity at Accepted (mag_enrolmentactivityataccepted) decides which types the list's Add activity menu offers once a referral is Accepted. It replaces the Enable_Enrolement_Activity_Button system configuration entry.

Both default to Yes, but a Dataverse default only applies to rows created after the column exists. Register rows that were already there hold no value, and both the list and the completion check read no value as No. Without this step, turning the list on would hide every type from the Add menu and block every activity from being completed from the list.

What it does

For each Activity Register row, active or not, and only for a column that is empty:

Column Value written
Allow quick complete Yes, except No for consent, dynamic assessment and email. These three are completed on their own form in this release, which is what the seed data ships.
Enrolment Activity at Accepted Yes, except No for a type the Enable_Enrolement_Activity_Button entry turns off, so the new Add menu offers what the current grid offers. Every row of that type is set, not just one.

A value that is already set is never changed. Running the operation again finds nothing to do, so it is safe to include in every upgrade.

Each row is written only if nobody has changed it since the run read it. If an administrator edits a row while the operation is running, Dataverse refuses the write, their change stands, and the log says NOT WRITTEN for that row. The run then ends with exit code 1. Preview again to see what the row still needs.

The Enable_Enrolement_Activity_Button entry is read exactly as the current grid reads it: nine values separated by *, for case note, consent, assessment, appointment, booking request, email, TXT message, alert and dynamic assessment, in that order. A value of false in any case turns that type's button off. An entry that is missing, empty, or does not have exactly nine values turns nothing off, because the grid then shows every button. If there is more than one entry and they disagree, the operation stops and writes nothing, because it cannot tell which one the grid used.

Each table is read in pages of 5,000 rows, up to 10 pages. If the register or the legacy entries still have more rows after that, the operation stops with exit code 1 and writes nothing, rather than work from part of a list.

Usage

# 1. Rehearse. Writes nothing; lists each row it would change and prints the token.
WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation --InitialiseEnrolmentRegister `
  -e "https://yourorg.crm6.dynamics.com" --PreviewMode

# 2. Apply exactly what was rehearsed.
WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation --InitialiseEnrolmentRegister `
  -e "https://yourorg.crm6.dynamics.com" --Apply `
  --AllowHost yourorg.crm6.dynamics.com --Confirm <token from step 1>

run-migrationtasks.ps1 includes this step, so a release window that already rehearses and applies the relationship repairs picks it up with its own token.

What to check afterwards

Open the Activity Register (Whānau Tahi Back Office > Configuration > Activity Buttons) and compare the Enrolment Activity at Accepted column with the Enable_Enrolement_Activity_Button entry before turning the list on. The All Activity Buttons view shows both new columns, and each row's form has them next to the other Enrolment Activity at settings. The preview prints the entry's value and which types it turns off, so the two can be checked side by side.