Pull line items from an FS engagement (cross-product, Phase 3)

Who does this: XBRL Preparer · XBRL Reviewer · Senior Accountant · Platform Admin When: The same client has a FsEngagement at NOTES_COMPLETE for the same period and you want to skip the DOCX parse entirely. Result: XbrlLineItem rows produced from the FS engagement's latest FsGeneratedStatement.statementsJson. Mappings auto-confirmed where the synonym library carries a HIGH-confidence SFRS key → ACRA element correspondence; the rest are unconfirmed for manual review.

NOTE

This is a Phase 3 capability. Available when the endpoint POST /ops/xbrl/filings/:id/from-fs-engagement is live and the FS module has shipped Phase 1.

Before you start

• [ ] Filing at DRAFT with fsEngagementId set at creation (or via PATCH if supported).
• [ ] FS engagement at NOTES_COMPLETE.
• [ ] Same clientId on both.
• [ ] You hold INGEST_XBRL_DOCUMENT AND VIEW_FS_ENGAGEMENT.

Steps

1. Open the filing → Documents tab. The Pull from FS engagement button is visible because fsEngagementId is set.
2. Click. The handler reads the latest FsGeneratedStatement.statementsJson and expands it into XbrlLineItem rows.
3. For each line item, attempts an auto-confirm:
   • Looks up the SFRS taxonomy key in mapping_library.json for a HIGH-confidence ACRA element correspondence.
   • If found → auto-confirms with you as the confirmedById.
   • Otherwise → leaves unconfirmed.
4. Filing transitions DRAFT → DOCUMENTS_INGESTED → MAPPING_IN_PROGRESS.

How to know it worked

1. Line items appear on the Mappings tab, grouped by statement.
2. A subset of mappings is already confirmed (auto-confirmed by you); the rest are unconfirmed.
3. Activity log shows xbrl.cross_product.pulled with line-item count and auto-confirmed / unconfirmed split.
4. Each auto-confirmed row also has xbrl.mapping.confirmed with you as the actor.

When to use this vs DOCX upload

Path	Use when…
Pull from FS engagement	The same client used the platform's FS module — most-precise line items, zero parser ambiguity, auto-confirmation possible
DOCX upload (independent path)	The financial statements were prepared outside the platform, or the FS engagement is incomplete

Common situations

If you see…	It means…	What to do
Button not visible on the Documents tab	fsEngagementId was not set at filing creation	Set via PATCH (if supported), or upload the DOCX instead
409 reason: "fs_engagement_not_ready"	The FS engagement is not at NOTES_COMPLETE (e.g. it's at NOTES_ERROR)	Resolve the FS engagement first
Auto-confirmation rate is low	The synonym library is thin for this SFRS-to-ACRA correspondence	Confirm manually; consider saving the new synonyms (Reviewer / Senior only)
400 reason: "mismatched_client"	The filing and FS engagement belong to different clients	The cross-product path is same-client only

Related runbooks

• Confirm tag mappings — next step
• Save a new synonym
• X-02b userflow
• XBRL Filing SOP §6 / Step 2.0