Skip to Content

Wiki source code of 1. Overview

Version 9.1 by Admin User on 2026/07/13 12:51
Hide last authors
Admin User 2.1 1
2
3
4
5
6
7
8
9
10
11
12
13 ONEcount Fulfillment Module
14 System Administration Guide
15
16 Configuration, permissions, and integration setup
17
18 = 1. Overview =
19
20 Before circulation staff can use the Fulfillment module, a system administrator must complete a set of one-time configuration tasks. These tasks establish the link between ONEcount's audience data and the fulfillment workflow, define the publications that will be managed, configure reporting periods and lot-split templates, set up third-party integrations, and assign the correct permissions to each user role.
21
22 This guide covers every step in the order you should perform them. If you are enabling fulfillment on a tenant for the first time, work through Sections 2 through 9 sequentially. If you are adding a new publication to a tenant that already has fulfillment enabled, skip to Section 3.
23
24 [[image:fulfillment-system-admin-guide_fa6253b3edd60478.png||height="430" width="586"]]
25
26 = 2. Enabling Fulfillment for a Tenant =
27
28 Fulfillment is controlled at the tenant level by the fulfillment_enabled column on the onecount_super.oc_clients table. A value of 1 turns the module on; a value of 0 (the default) keeps it off.
29
30 To enable fulfillment for a tenant, run the following SQL statement on the super database:
31
32 **UPDATE oc_clients SET fulfillment_enabled = 1 WHERE client_id = <client_id>;**
33
34 Replace <client_id> with the numeric client identifier from oc_clients. The change takes effect on the next page load for any user on that tenant.
35
36 **When fulfillment is enabled:**
37
38 * The Fulfillment top-level menu item appears in the admin sidebar for users who hold at least the fulfillment.view permission.
39 * All Fulfillment URLs (reports, setup screens, artifact downloads) become accessible according to each user's permission set.
40 * The Issue Builder link appears in the Data Management section, allowing saved lists to be promoted to issues.
41
42 **When fulfillment is disabled:**
43
44 * The Fulfillment menu item is hidden from the sidebar for all users.
45 * Direct navigation to any Fulfillment URL returns a 404 response.
46 * Existing data (publications, issues, runs, artifacts) is preserved in the database and will reappear if the module is re-enabled.
47
48 = 3. Publication Setup =
49
50 [[image:fulfillment-system-admin-guide_2b0bd3948351f4b6.png||height="430" width="586"]]
51
52 Navigate to Fulfillment, then Setup, then Publications & Issues. Click Add Publication to create a new publication record.
53
54 == 3.1 Required Fields ==
55
56 Every publication requires the following fields at a minimum:
57
58 * Title: the display name of the publication as it should appear in reports and the sidebar.
59 * Resource ID: the ONEcount Resource to which this publication is linked. Each publication maps to exactly one Resource. Subscribers subscribe to the Resource via Packages (Terms), and this link is how the fulfillment system determines who is subscribed to the publication. Select the Resource from the dropdown; only Resources not already linked to another publication are shown.
60 * Frequency: how often the publication is issued. Options are weekly, biweekly, monthly, bimonthly, quarterly, semiannual, and annual. The frequency drives expected issue counts in RPT-02 and RPT-11.
61 * Publication type: paid, controlled, or mixed. This determines which reports are relevant and how circulation categories are classified.
62 * Audit bureau: AAM_consumer, AAM_business, or none. This controls which report templates appear and which validation rules apply.
63
64 == 3.2 Optional Fields ==
65
66 The following fields are optional but should be completed before filing any statements or postal forms:
67
68 * ISSN: International Standard Serial Number, printed on the publication masthead.
69 * Publication number: USPS publication number (required for Form 3526).
70 * USPS permit: the Periodicals mailing permit number.
71 * Office of publication: the city and state where the publication is entered as Periodicals mail, along with the ZIP code (office_of_publication_zip). Required for USPS Form 3526 Item 5.
72 * Annual subscription price: the standard annual rate. Used in RPT-03 and RPT-10.
73 * Publisher, editor, managing editor: names and mailing addresses. These populate USPS Form 3526 Items 8, 9, and 10.
74 * Owners: names and addresses of all owners holding 1% or more of total stock (Form 3526 Item 11).
75 * Security holders: names and addresses of bondholders, mortgagees, and other security holders (Form 3526 Item 12).
76 * Tax status: whether the organization's tax-exempt status has changed during the preceding 12 months (Form 3526 Item 13).
77
78 == 3.3 The Resource ID Link ==
79
80 The resource_id is the single most important field on the publication record. It connects the fulfillment module to ONEcount's subscription engine. When a user subscribes to a Resource via a Package (Term), that subscription record is what the fulfillment system reads to determine whether the user should appear on a mailing list. Without a valid resource_id, the publication cannot produce any subscriber-based report.
81
82 == 3.4 Rate Base ==
83
84 If the publication declares a rate base (rate_base_claimed = 1), navigate to Setup, then Rate Base Declarations to enter the effective rate base. Each declaration includes the rate base amount, the period start date, and the period end date. RPT-12 (Rate Base Compliance) compares actual paid circulation against the declared rate base and flags shortfalls. A publication may have multiple declarations over time as the rate base changes.
85
86 == 3.5 Demographics ==
87
88 For AAM Business publications, set business_type_question_id and job_function_question_id to the ONEcount demographic question IDs that capture the subscriber's business classification and job function. These drive the cross-tabulation in RPT-05 (Demographic Cross-Tab) and Section 5 of RPT-13 (Paragraph 13).
89
90 == 3.6 Nonqualified Cap ==
91
92 The nonqualified_cap_pct field sets the maximum percentage of total qualified circulation that may be classified as nonqualified before a warning is raised. The default is 0.50% (one half of one percent). RPT-13 checks this threshold and flags the issue if nonqualified recipients exceed it.
93
94 == 3.7 Domestic Country Set ==
95
96 Enter a comma-separated list of ISO 3166-1 alpha-2 country codes that should be treated as domestic for circulation reporting. Typically this is US,PR,VI,GU,AS,MP for US publishers. RPT-04 (Geographic Distribution) uses this list to separate domestic from international circulation.
97
98 = 4. Reporting Periods =
99
100 [[image:fulfillment-system-admin-guide_d495329def3aabdd.png||height="430" width="586"]]
101
102 Navigate to Setup, then Reporting Periods. Reporting periods define the time windows over which circulation is measured and statements are filed.
103
104 == 4.1 Standard AAM Periods ==
105
106 AAM-audited publications use two standard half-year periods: H1, running from January 1 through June 30, and H2, running from July 1 through December 31. Create both periods for each calendar year in which the publication will file statements.
107
108 == 4.2 Custom Periods ==
109
110 Publications with non-standard audit windows (quarterly filings, fiscal-year reporting, or non-AAM cadences) can define custom periods with arbitrary start and end dates. The only requirement is that periods for the same publication must not overlap.
111
112 == 4.3 Period Status Lifecycle ==
113
114 Each reporting period moves through three statuses:
115
116 1. Open: the period is active. Issues can be created and closed within this period. Reports can be run and re-run.
117 1. Closing: the period is being assembled for filing. RPT-11 has been started. No new issues should be added. Existing reports can still be re-run if corrections are needed.
118 1. Filed: the statement has been submitted to the audit bureau. The period and all its data become read-only. Reopening requires the setup and statement_file permissions.
119
120 == 4.4 Period-Issue Binding ==
121
122 Each period is bound to a publication. All issues whose issue_date falls between the period's start and end dates automatically belong to that period. There is no manual assignment step; the date range determines membership.
123
124 = 5. Issues =
125
126 [[image:fulfillment-system-admin-guide_9ddc0dcaf40acc74.png||height="637" width="586"]]
127
128 == 5.1 Creating Issues from Saved Lists ==
129
130 Issues are created from saved lists. The workflow is: navigate to Data Management, then List Wizard. Build and run the query that defines the recipient universe for the issue. Save the query as a saved list, then use Save as Issue to promote it to a fulfillment issue. Once created, the saved_list_id is bound to the issue and cannot be changed.
131
132 == 5.2 Issue Fields ==
133
134 * Publication: the publication this issue belongs to.
135 * Issue date: the cover date of the issue. Determines which reporting period the issue falls into.
136 * Mail date: the date the issue is mailed. Used for postal documentation and AccuZip processing.
137 * Saved list ID: the List Wizard saved list that defines the recipient universe. Set at creation and immutable thereafter.
138
139 == 5.3 Issue Status Lifecycle ==
140
141 Each issue moves through four statuses:
142
143 1. Planned: the issue has been created but no reports have been run.
144 1. Open: reports are being generated against this issue.
145 1. Locked: RPT-13 has been completed and the issue's recipient list is frozen. No changes to the underlying saved list will affect the locked data.
146 1. Finalized: RPT-19 (Issue Close) has been completed. The issue is fully processed, mailing documentation has been generated, and all artifacts are available for download.
147
148 == 5.4 Special Issues ==
149
150 Set is_special = 1 to mark an issue as a special or bonus distribution. Special issues are excluded from period averages in RPT-02 and RPT-11. Examples include bonus distributions at trade shows, sample copies, and promotional mailings.
151
152 == 5.5 Audit and Analyzed Flags ==
153
154 Designate one issue per reporting period as the audit issue. The audit issue retains its full recipient list for auditor review. Separately, designate one issue per period as the analyzed issue. The analyzed issue drives Paragraph 7 (geographic distribution by state and country) in the Publisher's Statement. These may be the same issue or different issues depending on your audit bureau's requirements.
155
156 = 6. Lot Split Templates =
157
158 [[image:fulfillment-system-admin-guide_4187bc9c32d1eaa6.png||height="430" width="586"]]
159
160 Navigate to Setup, then Lot Split Templates. Lot split templates define how a mailing is divided into lettershop lots for postal processing and presort optimization.
161
162 == 6.1 Template Structure ==
163
164 Each template belongs to a publication and contains one or more lot definitions. Each lot definition specifies a lot_id and the criteria that determine which recipients fall into that lot. Criteria can be based on subscription classification (paid, controlled, etc.), geography (domestic vs. international, specific states or countries), or segment membership.
165
166 == 6.2 Usage in RPT-19 ==
167
168 When running RPT-19 (Issue Close), Step 3 prompts the operator to select a lot split template. The template determines how the recipient list is divided into separate presort files for the lettershop. Each lot is processed independently through AccuZip for address standardization and postal presorting.
169
170 == 6.3 Example ==
171
172 A template named "Standard Print" for a mixed publication might contain the following lots:
173
174 * Lot 1 — Paid Print Domestic: paid subscribers with domestic addresses, sorted for USPS automation rates.
175 * Lot 2 — Paid Print International: paid subscribers with international addresses, sorted by country.
176 * Lot 3 — Controlled: qualified nonpaid recipients.
177 * Lot 4 — Passalong: copies distributed through pass-along channels (office copies, waiting rooms, etc.).
178
179 = 7. AccuZip Integration =
180
181 [[image:fulfillment-system-admin-guide_8dd9c9c653a04ccd.png||height="430" width="586"]]
182
183 Navigate to Setup, then System Integrations. The AccuZip integration provides CASS-certified address standardization, NCOALink change-of-address processing, and USPS postal presorting.
184
185 == 7.1 Configuration ==
186
187 Enter your AccuZip API key in GUID format. This key is provided by your AccuZip subscription and is found in the AccuZip account management portal.
188
189 == 7.2 Test Connection ==
190
191 Click Test Connection to verify the API key. A successful test displays the account type, service level, and remaining credits. The connection status indicator shows one of the following states:
192
193 * Ready (green): credentials are valid and the service is responding normally.
194 * Slow (orange): credentials are valid but response latency exceeds 2 seconds. The service is usable but may cause longer processing times during issue close.
195 * Not configured (grey): no API key has been entered.
196 * Auth failed (red): the API key was rejected. Verify the key in your AccuZip account portal.
197 * Unavailable (red): the AccuZip service is not responding. Retry later or contact AccuZip support.
198
199 == 7.3 PAF Requirement ==
200
201 Before NCOALink processing can be used, a signed Processing Acknowledgment Form (PAF) must be on file with AccuZip. Complete the PAF at accuzip.com/products/ncoalink/paf/new. Without a signed PAF, CASS processing will still work but NCOALink moves will not be returned.
202
203 == 7.4 Credit Model ==
204
205 AccuZip charges credits per file upload. Each lot processed during RPT-19 consumes credits based on the number of records in the file. Monitor your credit balance via the Test Connection screen. If credits are exhausted during issue close, the AccuZip step will fail and the operator will need to purchase additional credits before retrying.
206
207 == 7.5 What AccuZip Does at Issue Close ==
208
209 When RPT-19 (Issue Close) reaches the AccuZip processing step, the following operations are performed on each lot file:
210
211 1. CASS address standardization: every address is validated against the USPS Address Matching System. ZIP+4 codes are appended, suite numbers are normalized, Delivery Point Validation (DPV) confirmation codes are assigned, and vacant addresses are flagged.
212 1. NCOALink change-of-address matching: addresses are checked against the USPS National Change of Address database (48-month window). Moved addresses are updated to the new address; records with no forwarding address are flagged.
213 1. Postal presorting: the lot is sorted according to USPS automation rate requirements to maximize postage discounts.
214 1. USPS documentation generation: a PDF bundle is produced containing the Mailing Statement (PS Form 3600), CASS Certification Summary, and Qualification Report.
215
216 = 8. Permissions =
217
218 The Fulfillment module defines five permission roles. These are managed under the standard ONEcount permission management screen and appear under the Fulfillment category.
219
220 == 8.1 Permission Definitions ==
221
222 1. fulfillment.view: allows the user to see completed report runs and download artifacts. This is the minimum permission required for any access to the Fulfillment module.
223 1. fulfillment.run: allows the user to create new report runs and complete report wizards. Includes all view capabilities.
224 1. fulfillment.close_issue: allows the user to sign off on RPT-13 and lock an issue. Includes all run capabilities.
225 1. fulfillment.statement_file: allows the user to finalize RPT-11 (Publisher's Statement) and RPT-10 (USPS Form 3526) for filing. Includes all run capabilities.
226 1. fulfillment.setup: allows the user to edit publications, rate base declarations, lot split templates, and system integrations. Also allows deleting report runs and reopening filed periods. This is an administrative permission and should be granted sparingly.
227
228 == 8.2 Stacking ==
229
230 Permissions stack upward. The close_issue permission includes everything in run, which includes everything in view. The statement_file permission also includes everything in run. However, close_issue and statement_file are independent of each other; a user can have one without the other.
231
232 == 8.3 Superadmin Bypass ==
233
234 Users with user_type = 'F' (superadmin) in oc_be_users bypass all permission gates. They have full access to every Fulfillment function regardless of their assigned permissions.
235
236 == 8.4 Recommended Role Assignments ==
237
238 * Circulation managers: view + run + close_issue. This allows them to generate reports and close issues as part of their daily workflow.
239 * Audit and compliance staff: add statement_file to the above. This allows them to assemble and file Publisher's Statements and USPS forms.
240 * Module administrators: add setup to the above. This allows them to manage publications, integrations, and system configuration.
241
242 = 9. Health Check =
243
244 [[image:fulfillment-system-admin-guide_b8152ed71ab52393.png||height="434" width="586"]]
245
246 Navigate to Setup, then Setup Health. The health check screen provides a diagnostic overview of the fulfillment module's configuration state.
247
248 == 9.1 What It Shows ==
249
250 * Schema migration status: which SQL and CQL migrations have been applied to this tenant and which are pending.
251 * Unlinked publications: publications that do not have a valid resource_id. These publications cannot produce subscriber-based reports until linked.
252 * Term-format coverage gaps: ONEcount Terms (subscription types) that exist on the linked Resource but have not been mapped to fulfillment classification categories (paid, controlled, etc.).
253 * Cassandra table presence: verifies that all required Cassandra tables exist in the tenant's keyspace.
254
255 == 9.2 Bulk Apply ==
256
257 The one-click bulk-apply button attempts to resolve common configuration issues using heuristic rules. For example, it will auto-map Terms whose names contain 'paid' or 'free' to the corresponding fulfillment categories. Review the proposed changes before confirming.
258
259 == 9.3 When to Run ==
260
261 Run the health check after every migration deployment, after adding or modifying publications, and whenever a report produces unexpected results that might stem from a configuration issue.
262
263 = 10. Migration Rollout =
264
265 The Fulfillment module requires SQL migrations applied to each silo's MySQL database on the write host (wh-write-cl01) and CQL migrations applied to each silo's Cassandra keyspace. Always apply SQL migrations first, then CQL migrations.
266
267 == 10.1 SQL Migrations ==
268
269 The following SQL migrations must be applied in order on the silo write host:
270
271 * 014: Base fulfillment tables — publication, issue, run, artifact, and log tables.
272 * 015: Issue summary and outbox tables, implementing the saga pattern for multi-step operations.
273 * 016: Super-level fulfillment_enabled flag on oc_clients.
274 * 017: Lot definitions and lot split template tables.
275 * 018: Magazine resource refactor — adds the resource_id link to the publication table.
276 * 019: Publication classification defaults.
277 * 020: Issue builder enhancements (additional fields and constraints).
278 * 021: Publication demographic priority configuration.
279 * 022: Artifact SHA-256 checksums for integrity verification.
280 * 023: Bulk reason codes for mass status changes.
281 * 024: AccuZip integration — adds configuration to oc_config and creates the address validation log table.
282
283 == 10.2 CQL Migrations ==
284
285 The following CQL migrations must be applied to each silo's Cassandra keyspace:
286
287 * CQL 001: fulfillment_issue_serve table.
288 * CQL 002: subscription_meta tables for enriched subscription data.
289 * CQL 003: serve_log_zip table for compressed serve logs.
290 * CQL 004: saved_list_user_details schema for list-level detail storage.
291 * CQL 005: adds and removals log tables for tracking subscriber changes between issues.
292 * CQL 006: status change history table for audit trail of subscription status transitions.
293
294 == 10.3 Verification ==
295
296 After applying each batch of migrations, run the Setup Health check (Section 9) to verify that all expected tables and columns are present. Address any warnings before proceeding to the next batch.
297
298 == 10.4 Fresh Silo Installation ==
299
300 For new silos that have never had the Fulfillment module, use the consolidated install scripts (install_fulfillment_v1 through v12). These scripts are idempotent and contain the cumulative effect of all individual migrations. They can be run safely on a silo that already has some migrations applied.