Generating the Final Document: On-Demand Engagement Details

The Word master report is generated on demand, never inside the analysis pipeline. A study’s workflow — review, sign-off, archiving — runs on its own clock; the document is built whenever the sign-off authority needs it, from the study’s settled record. Building it writes the resulting files onto the study and, for a study still sitting at REPORT_GENERATED, takes the one canonical forward step to DOCUMENT_GENERATED; from any later state the workflow is left exactly where it was. This page is the flow: who triggers it, what the popup collects, and what happens between clicking Generate and the files being on the study.

Who can trigger it

• Roles. The final-document action is available to the Partner, the Firm Admin and the platform-level Superadmin — the three roles on the endpoint’s allow-list (FINAL_DOCUMENT_ROLES). Every other role gets a 403; the action itself is the role boundary.
• From where. The study’s results detail view: the Generate Final Document action opens the engagement popup for that study. The action is hidden while a generation job for that study is already running, so the UI cannot stack two builds on one record.
• The state gate. A formal 19-chapter document is only built from a review-complete record: IN_REVIEW, REPORT_GENERATED, DOCUMENT_GENERATED, SIGNED_OFF or ARCHIVED. Anything earlier (DRAFT, STUDY_INITIALIZED, PROCESSING) has partial or stale results, and REJECTED / FAILED must be re-submitted first — either way the endpoint answers 409 with the current state named.
• The data gate. The study must have persisted benchmarking results; with no analysis_data the endpoint returns 409 (“run the analysis before generating a final document”). Report jobs share a dedicated queue, and a full one returns 429 rather than queuing behind the backlog. The sign-off workflow itself is in Partner sign-off; the document is the artifact that workflow produces, not a step in it.

The engagement popup

The benchmarking data itself is derived from the persisted study — the analysis data and the parameters. What the popup collects is the engagement identity the study cannot derive, injected into the report’s narrative slots and its cover:

Field	Required	Where it lands
Prepared By	Yes	The cover’s “Prepared by”. A real field, not a defaulted one: the request rejects a blank value
Prepared For	No	The cover’s “Prepared for” (defaults to the tested party entity)
Report Date	No	The cover’s “Date of report”. Validated as a calendar date (YYYY-MM-DD, the date picker’s format); left blank it resolves to the day the build runs
Database Used	No	Chapter 12, Engagement Search Details — the line renders only when supplied
Comparable Years	No	Chapter 12, Engagement Search Details — the line renders only when supplied
Regions Searched	No	Chapter 12, Engagement Search Details — the line renders only when supplied
Purpose of Study	No	Chapter 2 (Introduction) — narrative override
Company Overview	No	Chapter 5 (Company Overview) — narrative override
Transaction Description	No	Chapter 7 (Controlled Transactions) — narrative override
Functions, Assets and Risks	No	Chapter 8 (Functional Analysis) — narrative override
Group Companies	No	Chapter 4 — a table of entity / jurisdiction / relationship / business, up to 50 rows, each needing a name
Shareholding	No	Chapter 5, Shareholding Pattern — a table of shareholder / relationship / holding / jurisdiction, up to 50 rows, each needing a shareholder name

Only Prepared By gates the submit; the rest are engagement detail. Leaving a narrative slot empty leaves the report’s deterministic fallback in place — the chapter is never blank — and leaving either schedule empty is its own statement: the chapter prints that the detail is not recorded in the study data rather than an empty table. A schedule row that names nobody is dropped before the request goes out, so an abandoned half-row cannot fail the whole generation.

What happens on submit

1. The request. POST /api/v1/studies/{id}/final-document with the popup payload. The endpoint checks the role (403), loads the study (404 if it does not exist), checks the state and the persisted results (409 for either), and refuses early if the report queue is full (429). The task is dispatched once the response has committed.
2. The job. A Job row is created for the generation — the file it will produce, named Transfer-Pricing Report-{entity}.docx — and the generate_final_document Celery task is dispatched on the report queue, the queue that keeps document builds from wedging new analyses. No study mutation happens at request time: the job carries the progress, not the study.
3. The build. The task first checks the retention window on the study’s raw dump (see The retention edge), then rebuilds the report context from the persisted Study.parameters and Study.analysis_data merged with the engagement fields and the narrative overrides. Two reconciliations happen here, both so the document matches the record a reviewer settled on: the accept/reject overrides recorded during review are applied to a build-only copy of the results, and the jurisdiction’s rules are resolved as of the financial year end, so a prior-year study is documented against the law in force then. The report engine then renders the 19-chapter document from that context — deterministically, with no AI step.
4. The two files. The finished .docx uploads to storage and its file id is stored on the study as report_docx_file_id. Only then is the branded PDF built — from the same context, so the two deliverables cannot disagree on a number or on the range methodology — and stored as report_pdf_file_id. The PDF leg is best-effort by design: the Word report is already safe by that point, so a PDF failure is recorded as pdf_error on the job’s summary and leaves report_pdf_file_id null. A null PDF means “no PDF available for this study”, not a failed generation.
5. The completion. The job moves to completed with both file ids and filenames in its summary (report_docx_file_id, report_pdf_file_id when present, plus pdf_error if that leg failed); the UI polls the job (GET /api/v1/jobs/{id}) and surfaces the result. On a successful build the study takes its one canonical document step, REPORT_GENERATED → DOCUMENT_GENERATED; a study already at DOCUMENT_GENERATED, SIGNED_OFF or ARCHIVED stays exactly where it is.
6. The failure. A failed build marks the job failed with the reason. The study’s state, its data and its previously generated files are untouched — the last good document stays the document of record until a generation replaces it.

What the run does — and does not — change

This is the design boundary that keeps the document useful.

• One permitted step, and only one. A successful build advances a study sitting at REPORT_GENERATED to DOCUMENT_GENERATED, because that is the canonical meaning of the state. From DOCUMENT_GENERATED, SIGNED_OFF or ARCHIVED the state does not move: no rollback to review, no re-approval, no reopening of anything.
• Generation runs alongside the workflow. Review, overrides and sign-off continue while the document builds. The build takes no lock and records no review action — it writes file ids and, in the one case above, a state.
• Re-generation is safe. After sign-off — or after a correction to the engagement details — the document can be regenerated from the settled record without reopening the study. Each run stores new files and the study links the latest ids; those are the current documents of record.
• Two separate downloads. The Word and PDF files are downloaded independently, so a study whose PDF leg failed still serves its Word report: the UI says no PDF is available and offers regeneration, rather than failing the Word download with it.
• Contrast with the Excel workbook. The workbook is part of the workflow — report generation is a stage the study passes through when it is approved, and it stays the primary benchmarking deliverable. The Word (and PDF) document is a side channel: the same record, rendered into the narrative form, on the authority’s schedule.

The retention edge

The build works from the study’s persisted record plus its raw dump. If the dump has passed the tenant’s retention window by the time the task runs, the job fails with a clear DUMP_EXPIRED result rather than building a degraded document — the remedy is to re-run the study (a fresh run captures a fresh dump) and regenerate.

FAQ

Can I generate the document more than once? Yes. Each submission is a new job producing new stored files, and the study’s file ids point at the latest generation — regenerate after correcting an engagement detail rather than editing the document.

Does generating the document change the study’s state? Not from the endpoint, and barely from the build: the request never mutates the workflow, and a successful build advances a study only from REPORT_GENERATED to DOCUMENT_GENERATED. Regenerating from DOCUMENT_GENERATED, SIGNED_OFF or ARCHIVED changes nothing about the state — only the linked files.

I generated a document and there is no PDF — did it fail? Check the job’s summary. If report_docx_file_id is there and pdf_error is set, the Word report built and stored correctly and the PDF leg alone failed; the job is still completed, and the study simply has no PDF on it. Regenerate to try the PDF again. Note also that the PDF is intentionally narrower than the Word report — six chapters and Annexures A–G on the firm’s house template, not all nineteen — so a short PDF is not a truncated one. See Word and PDF: one record, two shapes.

Does the platform file the document anywhere? No. It builds, stores and links the deliverables for download; filing and submission are outside the platform.

The job failed — what should I check first? The job’s failure reason: DUMP_EXPIRED means the retention window closed on the raw dump (re-run the study); anything else is a generation fault to report, and the study and its earlier reports are unaffected either way.