Migration Sources

A Migration Source is the contract between the legacy system and MFI Suite — it says 'this file shape, from this system, mapped to these production fields, is acceptable.' Sources are registered once per tenant migration and edited freely until the first Commit, after which they become immutable.

Anatomy of a source

Every Source has a header (who, what, where, file format) and a Mapping Studio (legacy field -> MFI Suite field, with an optional Python transform). The Mapping Studio is where the bulk of the work happens.

• Header: Name, Legacy System, Template, File Format (CSV/XLSX/Fixed-width/SQL), Encoding (UTF-8/Windows-1252/Latin-1), Date format, Decimal separator, Owner (Migration Lead), Reviewer (Data Steward).
• Mapping Studio: a table of target_field, legacy_field, transform_python, default_value, required, sample_value. The sample_value column is auto-populated from the first 100 rows of a test upload.
• Business rules: per-source toggles such as 'Treat negative balance as overdraft', 'Snap deposit dates to month-end', 'Bucket loans older than 5 years into Historical'.
• Test runner: upload a 100-row sample. The Source shows green only after a sample passes validation.

Registering a Loan Performer source — worked example

Loan Performer 8.x is the most common legacy system in Kenyan SACCO migrations. Here is the exact recipe.

1. Open MFI Suite -> Migration -> Sources -> New.
2. Name: 'Tujikomboe SACCO — Members extract — Nov 2025'.
3. Legacy System: 'Loan Performer 8.x'.
4. Template: 'src.loanperformer.v8' (loads the default field map).
5. File Format: CSV, Encoding: Windows-1252 (Loan Performer's default), Date format: dd/mm/yyyy, Decimal separator: comma.
6. Owner: Jane Wambui (Migration Lead). Reviewer: Peter Otieno (Data Steward).
7. Open Mapping Studio. The template prefills 41 fields. Verify these manually because Loan Performer installations are customised:
8. MemberNo -> source_key (required), Surname + ' ' + FirstName -> full_name (concat transform), IDNo -> id_number, Tel1 -> phone (strip spaces and prefix +254), DOB -> date_of_birth, JoinDate -> joined_on, Branch -> branch_code, Status -> status (transform: 'A' -> active, 'D' -> dormant, 'C' -> closed).
9. Upload a 100-row test extract. The Test Runner shows 98 green, 2 red — the 2 reds are members with a Tel1 of 'NIL'.
10. Add a transform to coerce 'NIL' to empty string. Re-run test. 100 green. Source is now 'Verified' (green badge).

File formats and their gotchas

MFI Suite accepts five file formats. Each has Kenya-specific gotchas worth flagging at source-registration time, not at validation time.

Mapping Studio transforms

Each mapping line accepts an optional Python transform. The expression has access to value (the raw legacy value) and row (the entire legacy row as a dict). The result must be a string for text targets, a date for date targets, or a float for monetary targets.

# Normalise Kenyan phone numbers to +254 format
value = (value or '').strip().replace(' ', '').replace('-', '')
if value.startswith('0'):
    value = '+254' + value[1:]
elif value.startswith('254'):
    value = '+' + value
elif value.startswith('7') and len(value) == 9:
    value = '+254' + value
result = value or False

# ----
# Concatenate Loan Performer surname + first name into full_name
result = (row.get('Surname', '') + ' ' + row.get('FirstName', '')).strip().title()

# ----
# Coerce Loan Performer status flag to MFI Suite enum
map_ = {'A': 'active', 'D': 'dormant', 'C': 'closed', 'B': 'blacklisted'}
result = map_.get(value, 'active')

Freezing and versioning a source

Once the Data Steward signs off on a source mapping, click 'Freeze Mapping'. The mapping becomes read-only and a version number (v1, v2, ...) is stamped on every staging row that uses it. If the legacy system later produces a slightly different extract, the operator does not edit the frozen source — they clone it ('Copy as new version'), tweak, and freeze a v2. This keeps lineage clean.

Worked scenarios

Reference

Source states

A Source moves through six states. Only Frozen sources can feed a Migration Run.

Default mapping for src.loanperformer.v8 (Members)

Every line is editable. Required lines cannot be removed without breaking validation.

Troubleshooting

See also

• Migration
• Staging
• Validation
• Mapping Audit