Inventory
Source name, owner, extraction date, record and file counts, format, sensitivity and retention decision.
Union database migration guide
Move union data with evidence, ownership and a rollback path.
A practical migration framework for membership records, positions, structure, grievances, documents, communication references and the relationships that make the data useful.
Migration is a controlled change
Do not copy ambiguity into the new system.
A union database contains more than rows. It carries naming conventions, historical compromises, implicit relationships, access assumptions and local workarounds. A successful migration makes those decisions visible before treating the destination as authoritative.
Start by defining the first useful operating outcome and the target UnionStack model. Inventory sources, profile quality, map fields and values, stage a representative sample, reconcile the result and obtain approval from the people who own the data and workflows.
Not every historical field should move. Keep information when there is a lawful, operational or historical reason to retain it; archive or exclude data through an approved process when there is not.
Migration checklist
Eight gates from discovery to stabilization.
- 01
Scope and ownership
List every source, data owner, business owner and migration decision-maker. Define which records, history, files and relationships are in scope.
- 02
Target model
Configure representative people, entity, position and case types, fields, statuses and relationships before finalizing column mappings.
- 03
Source profiling
Measure record counts, missing identifiers, duplicates, invalid dates, inconsistent values, orphaned relationships and unreadable attachments.
- 04
Mapping and transformation
Document each source field, target field, transformation, default, controlled-value translation, exclusion and unresolved decision.
- 05
Representative rehearsal
Stage common and exceptional records with fake or approved test data. Include historical positions, multi-entity members and active grievances.
- 06
Reconciliation
Compare counts and totals, sample critical records, validate relationships and record every exception with an owner and disposition.
- 07
Cutover and rollback
Freeze or control source changes, run the approved migration, preserve the recoverable source and define the conditions that trigger rollback.
- 08
Stabilization
Monitor user questions, duplicates, missing relationships, report variances and integration failures. Obtain formal acceptance before retiring the source.
Field-mapping checklist
Record every mapping decision before the rehearsal.
Use one row for each source field and a separate relationship register for joins that connect people, positions, entities, cases, documents or other records.
| Mapping column | Decision to document | Validation question |
|---|---|---|
| Source | System, file, table, worksheet, column, extraction date and business owner. | Can the value be reproduced from an approved source extract? |
| Target | UnionStack record type, field, relationship or document destination. | Does the target model support the intended operational use? |
| Transformation | Trim, parse, combine, split, normalize, calculate or translate controlled values. | Is the rule deterministic and repeatable on a second rehearsal? |
| Required and default | Required status, accepted null behaviour and any approved default. | Can a default be distinguished from a value supplied by the source? |
| Identity key | Stable source identifier and matching rule for existing people or records. | Could the rule merge two different people or duplicate one person? |
| Relationship key | Keys that connect position to person, workplace to bargaining unit, participant to case or document to owning record. | Can sampled users follow the relationship in the destination? |
| Retention decision | Migrate, archive, exclude or defer, with the legal or operational reason. | Has the authorized owner approved exclusion and retention handling? |
| Exception handling | Severity, owner, correction path and treatment of unmapped or invalid values. | Is every unresolved exception visible before cutover approval? |
| Evidence and status | Test record, expected result, actual result, reviewer, approval and date. | Can the team reproduce the evidence during final reconciliation? |
Data-domain decisions
Validate each kind of union record differently.
| Domain | Migration focus | Validation evidence |
|---|---|---|
| People | Identifiers, names, statuses, contacts, locations, consent or communication preferences and duplicates. | Representative users can find the correct person and distinguish similar records. |
| Positions and terms | Effective dates, status, employer, workplace, bargaining unit, steps, pay and dues context. | Current and historical relationships are understandable from the member record. |
| Organizational structure | Entity types, parent-child and other relationships, leaders, agreements and identifiers. | A representative branch matches the approved union model and supports downstream records. |
| Cases and grievances | Type, requestor, participants, assignments, stages, dates, outcomes, awards and related entities. | An authorized representative can reconstruct active and sampled closed cases. |
| Documents | File integrity, naming, provenance, relationship, version, access and retention. | Checksums or equivalent controls and sampled opening confirm files are intact and connected. |
| Email and meetings | Decide whether to migrate content, metadata or only references; preserve participants and case context. | Material communication and meeting evidence remains discoverable where the procedure requires it. |
| Reports | Definitions, filters, controlled values and historical comparability. | Source and destination results reconcile for an agreed period and population. |
| Integrations | Authoritative system, identifiers, credential replacement, failure handling and restart order. | Each integration completes a controlled end-to-end test after cutover. |
Reconciliation pack
Keep the evidence needed for approval.
Mapping workbook
Source-to-target fields, transformations, defaults, value translations, exclusions and open decisions.
Exception register
Duplicate, invalid, missing or unmapped records with severity, owner, disposition and approval.
Test evidence
Representative records, expected results, actual results, screenshots or exports and sign-off status.
Cutover runbook
Sequence, responsibilities, communications, freeze window, validation gates and rollback conditions.
Acceptance record
Counts, material variances, known limitations, owner approvals and the date the destination becomes authoritative.
Common failure patterns
Catch migration risk before cutover.
- The target is configured while mapping is already underway, forcing repeated transformation changes.
- Source names are treated as unique identifiers even though members share names or names change.
- Current positions import successfully but effective history or organizational relationships disappear.
- Case documents move without provenance, version or a dependable relationship to the grievance.
- Record counts match, but controlled values, totals or representative workflows do not.
- Users receive access before role design and sensitive-data validation are complete.
- The source is retired before reports, integrations and exception handling stabilize.
- No one owns post-launch duplicate correction or mapping decisions for later imports.
Buyer guidance
Make migration part of product evaluation.
Ask every shortlisted vendor to map and stage the same representative sample. Record which work is included, which requires professional services, what the union must clean, how files and relationships are handled and what acceptance looks like.
A vendor that can explain exceptions, reconciliation and rollback is giving more useful evidence than one that promises to “import everything.” Pair the migration exercise with the buyer’s guide scorecard and verify the resulting records inside membership, grievance, reporting and portal workflows.
From the UnionStack blog
Continue with evidence-led analysis
Migrating from spreadsheets or legacy union software
Prepare, map, reconcile and cut over union membership and case data without losing the relationships that make records useful.
Read the article →Related implementation guides
Prepare, migrate and validate UnionStack data
Use these maintained UnionStack 2.0 guides to evaluate the workflow in detail.
Data
Prepare data for UnionStack onboarding
Clean, map and stage source information before creating production records.
Support Team · UnionStack 2.012 min read → Data qualityEstablish naming and data-quality standards
Keep records consistent enough to search, connect, report and maintain over time.
Support Team · UnionStack 2.08 min read → ConfigurationConfigure types and custom fields
Use types and fields to reflect union terminology without creating avoidable complexity.
Support Team · UnionStack 2.011 min read → StructureBuild your union structure
Model entities and relationships around the way responsibility and representation actually work.
Support Team · UnionStack 2.010 min read → PeopleManage people and positions
Create dependable member records and connect positions, terms, pay and dues.
Support Team · UnionStack 2.09 min read → CasesCreate and progress a case
Move from intake through participants, progress, evidence and outcome.
Support Team · UnionStack 2.012 min read →Built for connected work
Plan the migration before moving production data.
Use the trial to stage a representative sample and validate the target model.