An import in Altru rarely fails for no reason. When it says it finished but nothing changed, or it stops with a pile of exceptions, or it won’t start at all, the cause almost always falls into one of a few groups: the file, the mapping, the data inside the file, permissions, or the background process that actually runs the import. Importing a selection has its own catches, which we cover separately below.
This guide goes through each group in the order we’d check them. Most problems turn up in the first two.
Start with the result, not the file
Before you change anything, open the import process and look at its most recent run. Note three things:
- Status. Did it complete, complete with exceptions, or fail outright? A run that never finishes points to a different problem than one that finished with zero records added.
- Counts. Compare the number of rows processed with the number of rows in your file. If those don’t match, Altru read the file differently than you expected.
- The exceptions output. When rows are rejected, Altru usually reports why for each row. Read a handful before guessing. One recurring message often explains hundreds of rejected rows.
1. The file itself
Spreadsheets cause more import failures than anything else, because Excel quietly changes data when you open and save it.
- Save as plain CSV. Not .xlsx, and preferably not a file that has been opened and resaved several times. If names with accents or special characters come through garbled, the file’s character encoding is the likely cause; try re-saving it with a different encoding option.
- Check the header row. Column headers need to match what the import process expects. A trailing space, a renamed column, or a missing header can break the mapping without an obvious warning.
- Look for stray rows and columns. Blank rows at the bottom, a totals row, or an empty column with formatting can all show up as bad records.
- Watch Excel’s auto-formatting. ZIP codes lose leading zeros, long ID numbers turn into scientific notation, and dates get reformatted. Open the CSV in a plain text editor to see what Altru will actually read.
- Commas and quotes inside fields. An address like “Suite 4, Building B” will split into two columns if the field isn’t quoted properly.
2. The mapping
An import process remembers how columns map to Altru fields. If you reuse an old process with a new file, the mapping may no longer line up.
- Open the process and confirm every column in your file is mapped to the field you expect, and that nothing important is left unmapped.
- Check that the process is set to add, update, or both, matching what you’re trying to do. An import set to update only will skip new people instead of creating them.
- If the process matches incoming rows to existing constituent records, review how matching is configured. Too strict and everything comes in as new records, creating duplicates. Too loose and rows update the wrong person.
3. The data in the rows
Once the file reads correctly, rows get rejected for content reasons:
- Code table values that don’t match exactly. If your file says “Mr” and Altru’s title table has “Mr.”, or your file uses a state name where Altru expects an abbreviation, the row can fail. Pull the current values from Altru and match them character for character.
- Required fields left blank. A constituent without a last name, or a revenue row without an amount or date, won’t import.
- Values in the wrong format. Dates, currency with dollar signs, and phone numbers with unusual punctuation are common offenders.
A good habit: test with a ten-row file first. It’s much faster to find the problem in ten rows than in five thousand.
4. Permissions
If the import option is missing, greyed out, or fails immediately for one person but works for another, look at security. Import rights are assigned through system roles, and a user may be able to view records without being allowed to import or edit them. Ask your Altru system administrator to compare the two users’ roles.
5. The process never runs or never finishes
Imports in Altru run as background processes. If a job sits pending, or the page times out on a very large file, the issue may not be your data at all. Try splitting the file into smaller batches. If small files also hang, contact Blackbaud support, since the processing side is hosted and not something an organization can restart on its own.
When the trouble is importing a selection
Importing a selection, meaning a list of records loaded from a file rather than built from a query, fails for its own reasons:
- The wrong kind of ID. Altru records have more than one identifier, typically a lookup ID that staff see and an internal system record ID. The selection import expects a specific type. If your file has one and the import expects the other, nothing matches.
- The wrong record type. A selection is tied to a record type, such as constituents. A file of membership or revenue IDs won’t match a constituent selection.
- Formatting of the ID column. Leading zeros dropped by Excel, extra spaces, or a header the import doesn’t recognize will all cause misses.
- Records that no longer exist. IDs from an old export may point to records that have since been merged or deleted.
If you’re not sure which ID format the selection import wants, export a few records with both IDs from a query, then test importing each column. Whichever one matches tells you what to use going forward. Running this in a sandbox environment first, if your organization has one, is safer than experimenting in production.
When to escalate
Contact Blackbaud support if a ten-row test file with clean, verified data still fails, if the same import works for one user and not another after roles are checked, or if processes stay stuck. Send them the exceptions output, a sample of the file with personal data removed, and the name of the import process. That saves a round of back-and-forth.
Quick answers
The import said it completed, so why don’t I see any changes?
Check the counts and the add/update setting. A process set to update only, or matching that fails silently, can complete without changing anything.
Can I import straight from an Excel workbook?
Save as CSV first and check it in a text editor. That removes most of the formatting surprises.
