print Command Reference

The print command generates PDF documents from Dataverse records. It supports these modes:

Single Record Mode - Export a single record using its entity type, record ID, and form configuration
Plan Mode - Export comprehensive plans that aggregate data across a family group, including individuals, referrals, and activities within a date range
Query Mode - List the plans in the environment, to find the record IDs the other modes need
Bulk Mode - Export a PDF per plan, for all plans or a page of them
Test Mode - Connect to the environment and stop, to prove the credentials and URL are right

Every mode connects to Dataverse first. There is no offline mode.

Authentication

The print command uses Service Principal (SPN) authentication to connect to Dataverse environments.

Parameter	Alias	Required	Description
`--ClientId`		Yes	Application (client) ID of a service principal that is an application user in the target environment.
`--Secret`		Yes	Client secret for that application.
`--EnvironmentUrl`	`-e`	Yes	The Dataverse environment URL (e.g., `https://org.crm6.dynamics.com`).

The tool holds no application registration and no secret of its own. Both belong to the tenant being worked on and have to be supplied on every run: a run started without them is refused with exit code 3 before any environment is contacted. In a pipeline, supply them from pipeline variables backed by Key Vault.

Operation Modes

The command supports five mutually exclusive operation modes:

Parameter	Alias	Description
`--single`	`-s`	Generate a PDF for a single record.
`--plan`	`-p`	Generate a comprehensive plan PDF aggregating related data.
`--query`	`-q`	List plans in the environment. Use `--top` and `--skip` to page through them. Generates no PDF.
`--bulk`	`-b`	Export a PDF per plan into `--outputdir`. Use `--top`, `--skip` and `--parallelism` to control the run.
`--test`	`-t`	Connect to the environment, report success, and stop. It is a connection test, not an offline validation: the connection is made before the mode is looked at, so `--test` fails wherever a real run would fail to connect.

Single Record Parameters

When using --single mode, specify the record to export:

Parameter	Alias	Required	Description
`--entity`	`-n`	Yes	The logical name of the entity (e.g., `mag_referral`, `contact`).
`--recordid`	`-r`	Yes	The GUID of the record to export.
`--formid`	`-f`	No	The GUID of the form configuration to use for rendering. If not specified, uses the default main form.

Plan Mode Parameters

When using --plan mode, specify the family group and filtering options:

Parameter	Alias	Required	Description
`--recordid`	`-r`	Yes	The GUID of the family group (mag_familygroup) record.
`--startdate`		No	Start date for filtering activities (format: `yyyy-MM-dd`).
`--enddate`		No	End date for filtering activities (format: `yyyy-MM-dd`).
`--individuals`		No	Comma-separated list of individual (contact) GUIDs to include.
`--referrals`		No	Comma-separated list of referral GUIDs to include.
`--activitytypes`		No	Comma-separated list of activity type codes to include.
`--completedonly`		No	When set, only include completed activities.

Query Mode Parameters

--query reports how many plans (mag_plan) the environment holds and lists the newest ones, so you can find the record IDs the other modes need. It writes to the console only and generates no PDF.

Parameter	Alias	Required	Description
`--top`		No	Number of plans to list. Default `20`. `--skip` is not used in this mode.

Bulk Mode Parameters

--bulk exports one plan PDF per plan record, oldest first, into a folder. Each file is named for its plan and plan owner, and a _logs subfolder records what happened per plan.

Parameter	Required	Description
`--outputdir`	No	Folder to write the PDFs into. Created if it does not exist. Defaults to `pdf_export` under the current directory.
`--top`	No	Number of plans to process. Default `20`.
`--skip`	No	Number of plans to skip, so a large export can be run in pages. Default `0`. Use a multiple of `--top`: paging is by page number, so `--top 100 --skip 200` is the third page.
`--parallelism`	No	Plans processed at once. Default `1`, maximum `16`; 4–8 is a sensible range on a multi-core machine.

The plan-mode filters (--startdate, --enddate, --completedonly and the rest) apply to each plan in a bulk run as well.

Attachment and CCMS Options

Parameter	Alias	Required	Description
`--includeattachments`		No	Include activity attachments: PDFs are embedded, and anything that cannot be converted is zipped alongside the output PDF.
`--ccmsassessmentfolder`		No	Path to an NHI-keyed CCMS assessment cache folder (the `by-nhi` folder produced by the CCMS extractor). When given, the CCMS assessments found there are included in plan PDF output.

--ccmsassessmentfolder reads every *.json file in the folder given; it does not recurse. A folder that does not exist, or that holds no JSON, is reported and the run continues without CCMS content. The cache holds clinical assessment data — keep it out of source control and off shared drives.

Output Options

Parameter	Alias	Required	Description
`--output`	`-o`	No	Output file path for `--single` and `--plan`. If not specified, uses a default filename in the current directory.
`--overwrite`		No	Overwrite existing output file if it exists.

Display Options

Parameter	Alias	Description
`--verbose`	`-v`	Enable verbose output with detailed processing information.
`--quiet`		Suppress non-essential output.
`--debug`	`-d`	Enable debug mode with maximum detail for troubleshooting.
`--hideemptyfields`		Leave out fields that have no data instead of printing the `—` placeholder.

Usage Examples

Single Record Export

Export a referral record to PDF using a specific form configuration:

WhanauTahi.Xpm.Tooling.CLI print --single `
  -e "https://myorg.crm6.dynamics.com" `
  --ClientId "12345678-1234-1234-1234-123456789abc" `
  --Secret $env:DATAVERSE_SECRET `
  -n "mag_referral" `
  -r "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" `
  -f "f1e2d3c4-b5a6-4c3d-9e8f-7a6b5c4d3e2f" `
  -o "C:\Output\referral-export.pdf"

Plan Mode Export

Generate a comprehensive plan PDF for a family group with date filtering:

WhanauTahi.Xpm.Tooling.CLI print --plan `
  -e "https://myorg.crm6.dynamics.com" `
  --ClientId "12345678-1234-1234-1234-123456789abc" `
  --Secret $env:DATAVERSE_SECRET `
  -r "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" `
  --startdate "2024-01-01" `
  --enddate "2024-12-31" `
  --completedonly `
  -o "C:\Output\family-plan.pdf" `
  --verbose

Export with Specific Individuals and Referrals

Limit the plan export to specific individuals and referrals:

WhanauTahi.Xpm.Tooling.CLI print --plan `
  -e "https://myorg.crm6.dynamics.com" `
  --ClientId "12345678-1234-1234-1234-123456789abc" `
  --Secret $env:DATAVERSE_SECRET `
  -r "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" `
  --individuals "guid1,guid2,guid3" `
  --referrals "guid4,guid5" `
  -o "C:\Output\filtered-plan.pdf"

List the Plans in an Environment

Find the plan record IDs to export, and see how many there are in total:

WhanauTahi.Xpm.Tooling.CLI print --query `
  -e "https://myorg.crm6.dynamics.com" `
  --ClientId "12345678-1234-1234-1234-123456789abc" `
  --Secret $env:DATAVERSE_SECRET `
  --top 50

Bulk Plan Export

Export a page of 100 plans, four at a time, with CCMS assessments folded into each plan PDF:

WhanauTahi.Xpm.Tooling.CLI print --bulk `
  -e "https://myorg.crm6.dynamics.com" `
  --ClientId "12345678-1234-1234-1234-123456789abc" `
  --Secret $env:DATAVERSE_SECRET `
  --top 100 `
  --skip 200 `
  --parallelism 4 `
  --outputdir "C:\Output\plans" `
  --ccmsassessmentfolder "C:\ccms-cache\by-nhi"

Test Mode

Prove the credentials and environment URL work, without generating output. The connection is opened first, so a failure here is a genuine connection failure:

WhanauTahi.Xpm.Tooling.CLI print --test `
  -e "https://myorg.crm6.dynamics.com" `
  --ClientId "12345678-1234-1234-1234-123456789abc" `
  --Secret $env:DATAVERSE_SECRET

Supported Content Types

The print command processes various content types from Dataverse records:

Content Type	Description
Standard Fields	Text, number, date, optionset, and lookup fields from forms
Dynamic Assessments	Complex assessment data with nested structures
Images	Record images and attachments
Subgrids	Related record collections displayed in grids
Notes	Activity notes and annotations
Party Lists	Multi-party relationship fields
HTML Content	Rich text and HTML field content
Field Configurations	Custom field configuration data

Architecture

The print command uses a modular architecture with specialised processors:

PrintOrchestrator - Coordinates the overall export workflow
DataverseService - Handles Dataverse API connections and data retrieval
FormProcessor - Parses and processes form configurations
PdfGenerator - Generates PDF output using QuestPDF
Specialised Processors - Handle specific content types (assessments, images, etc.)
Section Handlers - Process specific form sections (appointments, contact details, etc.)

Exit Codes

Code	Description
0	Success - PDF generated successfully (or, for `--query` and `--test`, the mode completed)
1	Error - Check console output for details
3	Refused - `--ClientId` or `--Secret` was not supplied. Nothing was attempted and no environment was contacted.

Troubleshooting

Common Issues

Refused before it starts (exit 3)

Both --ClientId and --Secret must be given on every run; the tool has no credentials of its own
The message on stderr names which of the two was missing

Authentication Errors

Verify the --Secret value is correct
Ensure the service principal has appropriate Dataverse permissions
Check the --EnvironmentUrl is correctly formatted

Missing Form Configuration

Verify the --formid GUID exists in the target environment
Ensure the form is published and active

Empty Output

In plan mode, verify the date range contains activities
Check that the specified individuals/referrals exist
Use --verbose or --debug for detailed processing information

Permission Errors

Ensure the service principal has read access to all required entities
Verify table permissions for related records (activities, notes, images)

Table of Contents