---
id: WF-MBR-MEM-023
title: Export a roster of the members in scope
trigger: Staff or an officer request a filtered roster export.
product_area: membership
module: memberships
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-MBR-MEM-017
  - CAP-MBR-MEM-015
moves: []
crosses:
  - SVC-MBR-MEM-memberships
idempotency: >-
  Batch row replacement uses positions to tolerate a repeated batch. A new
  export request creates a new job and captures its membership set again.
concurrency: >-
  The captured set fixes inclusion, but row values are read during execution and
  can reflect later changes. Scope withdrawal does not recall an existing
  export.
hops:
  - 'n': 1
    actor_or_service: Staff or officer through the API
    action: >-
      Evaluate export reach and capture the matching membership identifiers,
      rejecting selections above the supported limit.
    anchor: >-
      services-membership:modules/memberships/services/rosters/roster-exports.ts:requestRosterExport
    seam: sync
    on_failure: A caller with no reachable holdings captures an empty selection.
    left_inconsistent: No partial local change remains.
    observer: Export submission answer and captured count
    provenance: test
    source: >-
      services-membership:modules/memberships/tests/integration/services/unit-scope.integration.spec.ts#captures
      the ids the requester’s set reaches at request time
  - 'n': 2
    actor_or_service: Roster export job
    action: >-
      Generate rows for the captured identifiers on the requested date in
      batches and settle job totals.
    anchor: >-
      services-membership:modules/memberships/aws/logic/roster-export.step-function.ts
    seam: state_machine
    on_failure: Record execution failure in the job’s evidence.
    left_inconsistent: A failed export can retain rows from earlier completed batches.
    observer: Export job-step evidence and status
    provenance: observed
    source: >-
      services-membership:modules/memberships/services/rosters/roster-export-workflow.ts
      (header)
  - 'n': 3
    actor_or_service: Requester through the API
    action: >-
      Return status and paged rows to the requester or an authorized
      workspace-wide reader.
    anchor: >-
      services-membership:modules/memberships/services/rosters/roster-exports.ts:rosterExportOf
    seam: sync
    on_failure: >-
      Return not found to a caller who neither requested the job nor holds
      workspace-wide export reach.
    left_inconsistent: No partial local change remains.
    observer: Caller-visible API result
    provenance: test
    source: >-
      services-membership:modules/memberships/tests/integration/services/unit-scope.integration.spec.ts#answers
      the export to the person who asked for it and to staff
branches:
  - >-
    A unit-filtered export has the known grace-visibility gap despite the
    workspace roster setting.
waits: []
evidence:
  - >-
    services-membership at 5994c270: modules/memberships/services/rosters/*.ts;
    aws/logic/roster-export.*.ts; services/persistence/roster-exports.ts
controls: [TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-005, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004]
---

# Export a roster of the members in scope

## What It Does

Roster export captures which holdings the requester may include, then produces their rows asynchronously. The job uses those captured identifiers rather than evaluating the requester’s permissions again.

## The Flow

```mermaid
flowchart TD
  H1["Evaluate export reach and capture the matching membership identifiers, rejecting selections above the supported limit"]
  H2["Generate rows for the captured identifiers on the requested date in batches and settle job totals"]
  H1 --> H2
  H3["Return status and paged rows to the requester or an authorized workspace-wide reader"]
  H2 --> H3
```

## When Something Fails

A failed export can contain partial rows and records failure for the requester. Startup can remain waiting without a deployed reconciler. A new request provides a separate attempt, with fresh access capture.