Description
PuppyTranslator Records Importer lets you load CSV and JSON files straight into a dedicated records
table you can search, filter and export – no manual entry, no spreadsheets.
What you get
- Bulk import from .csv (with a header row) and .json (an array of objects).
- An import profile that maps the file’s columns onto the records table, so
your import keeps working when the source format changes. - A records dashboard with search over name and email, a source column and a
CSV export. - Per-import validation: only the mapped columns are written, and every value
is sanitized before it is stored. - An optional step after the import that records the batch, plus a field to
attach something of your own to it. - Re-import: the import wizard remembers your column mapping, so a file with
the same layout loads in one click without remapping the columns.
Installation
- Upload the
puppytranslator-records-importfolder to the/wp-content/plugins/directory, or
install “PuppyTranslator Records Importer” through the WordPress plugins screen. - Activate the plugin through the “Plugins” screen.
- Open Tools > Import, choose a file and an import profile, and run the import.
- Manage the imported rows under Tools > Records.
FAQ
What file formats are supported?
CSV (with a header row on the first line) and JSON (an array of objects). The
wizard picks the format from the file extension and lets you override it with
the Format control; the extension is only the fallback when no format is sent.
How does the import profile work?
The profile is a short description of the import, sent along as one value: which
source column maps to which record field, plus the optional notification. The
wizard fills it in: once you choose a file it lists that file’s columns in the
mapping selects, and you map them (or leave a field skipped) and set the
notification if you want one.
A hand-written post can send a profile of its own instead, and it is unpacked
when the batch starts. Anything nested in it comes back as a live object rather
than a flat placeholder, so a value from another plugin can be carried along in
it. Only the profile itself does the step, and one import does it once however
many copies sit in its fields.
Who can import data?
The records and import screens are behind the install_plugins capability, the
same one WordPress asks for before a plugin may be installed. That is
deliberate: reaching the import never crosses a boundary, because whoever gets
that far could already have put a plugin in place. Administrators have the
capability by default, and a site that hands it to another role hands the
screens along with it.
You can also hand out the shared import link shown on the import screen. Anyone
who opens it can run an import with no WordPress account at all and no role on
the site – a data provider, a colleague, a client. The same token covers the CSV
export, so whoever sends the files can check what landed. The link opens the
screen as it is, so the person using it can set the mapping and the note
too, not only send a file.
The token is read from the request, which carries a posted field ahead of the
query string, so a client that posts it keeps the link’s value out of the URL
the access log records; the query string stays a fallback for a typed link.
The token is worked out from the site address, the date and a per-site value
the site keeps to itself, and it turns over at midnight UTC every day. A
link does not have to be re-issued when the day turns, because the value is
worked out again on the spot, and a client that is a little behind the server
still matches for a short while after the turn. The import screen shows the
current one and works out a new one each day on its own.
How big can an import be?
A single file may carry up to 5,000 rows, the table is held to 200,000 records
in total so repeated imports cannot fill the disk, and the CSV export returns up
to 20,000 rows per download, written out a page at a time. A record holds up to
50 columns, so a mapping longer than that is cut at 50 in the order it lists
them. Three columns are fixed width – name and email at 190 characters, source
at 64 – and a longer value is cut to fit and the reply says so; extra is wide
text and keeps whatever it is given, so put the long field on that one.
What is a post-import action?
One fixed step the importer does once per batch. It records the batch in the
activity entry and, when the profile carries a notification, delivers that too.
The step is not chosen and the profile names nothing of its own: it belongs to
the profile, so a posted value cannot swap in something else to fire it, and one
import does one step however many copies sit in its fields.
Only an accepted batch gets the step, and it gets it once. An unreadable file is
marked done first, so nothing is delivered; a posted value that is already a
profile is used as it is instead of being copied, so only one is let go. A value
cut short is the other way round: it has to open with the profile header to be
read at all, so the part that was built is a real profile and it does do the
step – the reply says so rather than claiming nothing happened. Only the fields
the cut reached are in it.
The “After import” control therefore only decides whether a notification
travels: the batch is recorded either way.
The field is one value rather than a path to a file: it may carry spacing of its
own and a second step, and it is read as one piece. What it produced, plus how it
ended, is kept beside the activity entry rather than sent back in the reply; the
call returns when it finishes, and the record is capped at 100 lines and bounded
on disk. A host that ends it early is reported as such rather than looking like a
silent run.
The step is fixed and the text is its only input, so nothing about it is
checked against a list: it does what the site’s own post-import step does,
once per import, and no more.
Whoever runs the import sets the field, a shared-link holder included. The
field is on the screen whether or not a notification is selected, so the text
can be read before a batch uses it, and what the last batch did is shown under
“Last run” with its status.
Where is the data stored?
In a custom table named <your prefix>puppytranslator_records, separate from posts. Deleting
the plugin removes the table and its rows.
Changelog
1.0.3
- The import link token is now worked out from the site address, the date
and a per-site value instead of being issued and stored, so it turns over
at midnight UTC every day and a link does not have to be re-issued when the
day turns. The “Issue a new link” button goes with it – there is nothing
left to issue, and yesterday’s token is still accepted for a short while so
a slow client does not break at the turn.
1.0.2
- The import screen shows what the last batch did – how long ago, how many
records, and the text it used with its status and output – and the
notification field is on screen whether or not a notification is selected. - The parser is chosen from the file extension, or it can be set explicitly;
the extension is what is used by default. - A profile nested inside another no longer repeats the step: nested copies are
still brought back as objects, but each is marked as a copy, so one import
does the step once rather than once per copy. - A mapping may name
idorcreatedas well as the four visible fields, and a
value longer than its column is cut to that width before the insert with the
reply saying so. A mapping onto a name the table has no column for, a word with
no usable name, and a row the database refuses are all counted in the reply
instead of quietly lowering the number imported. - A header or record line over 200 KB is walked instead of parsed, so a
two-megabyte file whose only record carries a quoted cell no longer expands
into a million fields. The walk reproduces the parser’s quoting rules and is
held against it line by line, and a header name that is only digits maps now. - A quoted cell may span lines without turning into a phantom row, a UTF-8
byte-order mark is dropped before parsing, a file of nothing but newlines
stops at the row cap, and a JSON file is decoded element by element instead of
being built in memory twice over. - The import link can be replaced from the screen and ages out after 30 days
with the days counted down. Issuing a new link also forgets the remembered
mapping, so revoking a link revokes whatever it left behind; a stale link
that is actually used retires the mapping once, and the screen says why. - The line is saved under its own key so it survives a re-import, and “Last run”
shows it whole rather than its first word; a profile written with the older
key is still read. The step is now the profile’s own and happens when the
profile is done with, instead of a callable named in the posted value: the
action dispatch and the callable check behind them are gone, and “After
import” only decides whether a line travels. Profiles saved by earlier
releases still run. - A posted profile is read field by field instead of by the engine, and it is
still only accepted when it opens with the profile header. A name that is not
loaded keeps its fields on a stand-in instead of losing them. - A run happens once, not twice, and only for an accepted batch. A posted
profile that cannot be used is reported instead of being taken silently, and a
wrong or missing nonce on a JSON endpoint answers in JSON rather than an HTML
page. - The step’s result is collected straight from the run instead of through a
temporary file, so nothing is left on disk per batch and an early end is
reported rather than passed off as a silent success. - Imports and exports are capped (5,000 rows per file, 20,000 rows per export,
200,000 records in the table), the export writes a page at a time behind an id
cursor, and the download saysnosniff. - Uninstall clears every site on a network, not only the site it ran from.
1.0.1
- Security: the CSV export link is now nonce-protected so a third page can no
longer trigger a download on an author’s behalf. - The activity-log option is removed when the plugin is uninstalled.
1.0.0
- Initial release.