Design a stable Flex Query template contract

A saved Flex Query is an external schema owned in Client Portal. Its query ID addresses the template, while the template decides which report family, accounts, models, sections, fields, formats, and period the service returns. Treat editing that template like changing a production data contract.

Choose the report family before the fields

An Activity Flex Query and a Trade Confirmation Flex Query have different freshness and configuration boundaries. Do not reuse one query ID as though it were only a different view of the same report.

The current Activity Flex Query setup guide documents section selection followed by field selection and ordering within each section. The Trade Confirmation setup guide additionally documents a detail-level choice for each selected section. Record a detail-level setting only where the selected report family and portal configuration expose one; do not project the Trade Confirmation control onto Activity sections.

Make sections and fields the schema manifest

For each selected section, record the exact portal label, selected fields, and field order. The official Activity Flex Query Reference is the catalog of possible Activity sections and fields, not proof that a particular saved query contains them.

Keep a non-secret manifest beside the consumer configuration:

template_name: DAILY_ACTIVITY_XML
report_family: activity
query_id_setting: FLEX_QUERY_ID
schema_revision: activity-v1
scope:
  accounts: authorized-account-set
  models: portal-selected-model-scope
delivery:
  format: XML
  period: Last Business Day
  date_format: portal-selected-date-format
  time_format: portal-selected-time-format
  date_time_separator: portal-selected-separator
sections:
  - name: exact-portal-section-label
    detail_level: null
    fields:
      - exact-portal-field-label

The manifest contains labels and policy, never a real query ID, account ID, token, or statement value. Store the actual query ID in sensitive configuration and bind it to schema_revision through deployment configuration.

Field order is part of the contract even when the XML parser uses attribute names. It lets an operator compare the saved portal template with the reviewed manifest and prevents a text or CSV consumer from silently receiving reordered columns.

Set account and model scope deliberately

The Activity setup flow uses the Account Selector and exposes model choices in Delivery Configuration. Two current official pages use different labels for those choices:

• the Activity setup instructions, updated August 4, 2026, say to choose Optional or All; and
• the Models reference, updated March 20, 2025, describes All, Consolidated, and Select a Model for advisors who created models in TWS.

The pages do not explain whether Optional maps to one of the older reference choices. Treat the available labels as portal-version-, account-role-, and configuration-dependent: record exactly what the authorized account exposes, and do not infer that Optional, Consolidated, or Select a Model are interchangeable. When the Models reference applies, its choices mean:

Model scope	Report meaning
All	Join data for all available models.
Consolidated	Consolidate all models for one account.
One selected model	Limit the statement to that model for the selected account set.

The Models reference says the Model field is available in the other Activity Flex sections. Select it wherever the consumer must preserve model identity; choosing a model scope without carrying the identifying field can make downstream reconciliation ambiguous. If the authenticated portal offers only Optional and All, verify the resulting XML privately before promising consolidated or single-model behavior.

Account selection and account layout are separate decisions. The official Delivery Configuration reference describes concatenating subaccounts as separate report sections or consolidating them into a merged layout. A consumer that reconciles per account should preserve separate account identity and reject a template change that unexpectedly consolidates it.

Separate transaction currency from base-currency reporting

Do not interpret a field named Currency without its section context. In the Account Information field reference, Currency means the account's base currency. The Activity section index separately lists Currency Conversion Rate and several summaries explicitly labeled in Base.

For any money-bearing consumer, record which of these meanings it requires:

• the account base currency from Account Information;
• the currency attached to a section's underlying records, when that section offers it;
• conversion-rate evidence needed to explain translated amounts; and
• base-currency summary sections used for account-level reporting.

Select each required field explicitly and retain its section name in the schema manifest. Never infer that an unlabeled amount is already converted, or that a missing currency attribute inherits the Account Information value.

Fix the period and serialization format

The Activity setup guide currently lists these period choices:

• Last Business Day, Last Business Week, Last Month, or Last Quarter;
• Last 30 Calendar Days, Last 365 Calendar Days, or Last N Calendar Days; and
• Month to Date, Quarter to Date, or Year to Date.

Choose the period that matches the ingestion schedule and record its exact portal label. A daily reconciliation consumer should not silently accept a switch to a cumulative period because duplicate and completeness expectations would change.

For automated ingestion, choose XML. The portal also offers CSV and pipe- or tab-delimited text, but those formats have different header, trailer, delimiter, and column-order concerns. The General Configuration reference documents Date Format, Time Format, and Date/Time Separator as template controls. Record their selected values rather than guessing how a returned string should parse.

This format choice does not make the XML self-describing. The saved fields still determine which sections and attributes exist, so the consumer must validate the returned shape against its expected revision.

Roll out a template change as a schema migration

The following is an operational policy derived from the official template controls:

1. Review the new sections, fields, scope, period, and formats in a non-secret manifest.
2. Give the revision a new immutable identifier or configuration hash.
3. Update the saved query and independently compare it with the reviewed manifest.
4. Retrieve a report through the bounded request-and-poll workflow described in the next guide.
5. Validate the XML shape without recording account data in logs or fixtures.
6. Deploy consumers that recognize the new revision before retiring the old expectation.
7. Treat any unplanned shape change as schema drift and quarantine the report.

Do not edit a shared production template merely to explore a field. Create a separately named query, use placeholder-only documentation, and keep every downloaded report private.

Template review checklist

• Report family is explicitly Activity or Trade Confirmation.
• Every section, field, field order, and applicable detail level is recorded.
• Account selection, account layout, and model scope match consumer authorization.
• Currency and base-currency meanings are explicit for every money-bearing section.
• Period matches the schedule and reconciliation window.
• Output is XML for the automated path.
• Date format, time format, and separator are versioned.
• Query ID and token remain in sensitive configuration, not the manifest.
• Consumer schema revision changes whenever the saved template changes.

Next, configure and rotate Flex Web Service access, binding its token and Query ID to this query contract before implementing the version 3 request-and-poll lifecycle.