Import historical maintenance work orders

In this guide

Keep the original export and map assets first

Export completed work from your previous CMMS and keep an unchanged copy. Import or map the asset register first. Each history row requires an existing asset_code in your workspace. Retired assets are supported so old maintenance records remain attached to the equipment they describe.

Use a stable source and external ID

Download the exact CSV contract from the authenticated importer. Choose a source identifier such as old-cmms and keep the original external_id for each job. The importer rejects repeated source IDs within the file and records already imported into the workspace. It does not overwrite prior work.

Preserve dates and closeout notes

Supply created_at, optional started_at and completed_at in UTC using YYYY-MM-DD HH:MM:SS. Completion cannot precede creation or lie in the future. Supported dates begin in 2000. Include the original title, description, work type, priority, actual minutes, failure code, root cause, corrective action and verification notes when available.

Preview, resolve every error, then commit

Upload at most 500 completed rows in a CSV of at most 1 MB. Preview does not create records. Commit rechecks the workspace and writes the entire batch in one transaction. Imported records retain their original dates and source identity; they do not send technician notifications or create new open work.

Reconcile the result before the next batch

Compare source counts, asset IDs and representative timestamps against the imported records. Attachments, original user accounts, checklist responses, detailed labor entries and historical stock consumption are not imported by this CSV. Preserve those source exports and plan them separately.

Define the history you need to preserve

A work-order history migration should help a technician understand what happened to an asset before the new system was introduced. Useful history includes the original problem, the work performed, the completion date and the evidence available at closeout. A large count of imported rows is less valuable if those rows are attached to the wrong equipment or contain dates that have lost their original meaning.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Start by agreeing the scope of the migration. PreventiveHQ’s CSV workflow imports completed work records. It does not recreate an entire previous CMMS, including all users, attachments, checklist answers, stock movements and approval events. Preserve a complete source export separately where available, then identify the supported completed records that should become searchable asset history in the destination.

Separate active work from historical work. An open repair that still needs action belongs in the current operational queue, with an owner and an accurate status. Marking it completed merely to fit the history importer would conceal an outstanding obligation. Likewise, recurring plans belong in the schedule import workflow, not in a file of completed jobs.

Choose a migration owner who can resolve mapping questions with maintenance staff. A data specialist may understand CSV formatting without knowing that two equipment nicknames refer to different pumps. A technician may understand the equipment without knowing how the source system represents timestamps. The first batch benefits from both perspectives.

Preserve source identity before transforming rows

Keep the original export unchanged and work on a separate mapping copy. Record which system produced it, when it was exported and which filters were applied. If the source export excludes archived assets or older dates, document that limit before calling the result a complete maintenance history.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Each imported record needs a source and external_id. Use a stable source identifier, such as old-cmms, and retain the original work-order identifier as external_id. The source accepts lowercase letters, numbers, underscores and hyphens, with a maximum length of sixty characters. The external identifier can contain up to 120 characters. Avoid using a changing spreadsheet row number when a stable source record ID exists.

The combination of source and external ID identifies the historical record within the workspace. The importer rejects duplicates in the same file and records already imported. This protects against repeating a batch, but it also means a corrected row cannot silently overwrite an earlier import. Resolve corrections through a deliberate review rather than inventing a new external ID to bypass the duplicate check.

If two source systems both contain work order 1042, use distinct source identifiers. If the same source system has been exported twice, keep its source identifier consistent. These choices preserve meaning across batches and make later reconciliation possible without guessing which spreadsheet produced a record.

Map historical assets without rewriting equipment identity

Import or prepare the destination asset register first. Every history row needs an existing asset_code in the current workspace. Retired assets are supported because old work remains relevant to equipment that is no longer in service. The destination still needs a real asset record; a free-text equipment description does not create one automatically.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Build a crosswalk from source equipment IDs to destination asset codes. Include the source name, destination name and a reviewer when identities are ambiguous. Two machines can share a model name while having different serial numbers and service histories. A location such as “boiler room” may contain several maintainable assets and should not become a substitute for equipment identity.

Consider an illustrative site that replaced pump P-07 with a new unit in the same location. If the old and new units have separate physical identities, preserve that distinction in the asset register and history mapping. Attaching all old failures to the replacement merely because it occupies the same position can distort later reliability analysis.

For missing equipment, pause the affected rows and resolve the register first. Do not map unknown history to a convenient generic asset to pass validation. If a record genuinely describes site-level work rather than a particular machine, decide how your organization represents that maintainable entity before importing it.

Use the exact fifteen-column contract

Download the current template from the authenticated history importer. Keep the headers in their original order and preserve empty cells for optional values. The file supports up to five hundred completed records and a maximum upload size of one megabyte. Split larger exports into documented batches without changing source identity between them.

The narrative closeout fields support up to ten thousand characters each. They are useful for preserving explanation, but they are not a way to recreate structured checklist responses or detailed labor records. Keep those source datasets in the archive and explain their availability to users who may need them later.

Convert timestamps deliberately

Supply timestamps in UTC using YYYY-MM-DD HH:MM:SS. Supported creation and completion dates begin in 2000 and cannot lie in the future. Completion cannot precede creation. When started_at is present, it must fall between creation and completion. These checks catch invalid chronology, but they cannot determine whether the source timezone was interpreted correctly.

For an illustrative source timestamp recorded at 14:30 in a fixed UTC+02:00 timezone, the corresponding UTC time is 12:30 on the same day. A date near midnight can move to the previous UTC day. Regions with daylight-saving changes require the offset that applied on the historical date, not necessarily today’s offset.

Determine whether the previous system exports local time, UTC or timestamps with an explicit offset. Do not apply a conversion twice. Test a known job whose original completion time can be confirmed by a maintenance record or source interface. Keep the conversion rule in the migration notes so another person can reproduce it.

If the source contains only a completion date without a time, decide and document the convention used to represent that limited precision. Do not describe an invented time as an observed event timestamp. Where required chronology cannot be established responsibly, exclude the row from the supported import and preserve it in the source archive for review.

Preserve missing information honestly

An empty root-cause field can be more accurate than a guessed cause. If the original record says “bearing replaced” but does not explain why it failed, preserve the corrective action without inventing a diagnosis. Migration should improve access to evidence, not make old records appear more complete than they were.

Treat actual_minutes carefully. It is a supported whole-number value, not an automatic reconstruction of detailed technician labor. Elapsed time between creation and completion may include waiting for parts, weekends and production access. Do not fill actual_minutes with that elapsed duration unless it matches the source field’s intended meaning and your approved mapping.

Priority mappings also need a defined rule. A previous system might use numeric levels or labels such as emergency and routine. Map them consistently to the supported values and retain the original export. The fact that a row validates does not prove that a source priority of one means critical rather than low.

Use the description or closeout fields to retain relevant source context when appropriate, while avoiding unnecessary personal information. The objective is an understandable maintenance record. Long pasted administrative histories can make the useful repair evidence harder to find without restoring the original system’s structured audit trail.

Work through a small migration example

Suppose a team has forty completed jobs from an old system. Three refer to an asset that has not yet been mapped, two have completion times earlier than creation and one is a duplicate export of another record. The team should resolve those six issues before committing the batch rather than assuming the importer will repair them.

AI-generated editorial illustration; not a customer photograph or product screenshot.

The migration owner maps the missing equipment using the asset crosswalk, checks the two timestamps against the source and removes the repeated row from the working file. The unchanged original export remains preserved. A fresh preview then shows forty intended source jobs only if the original count actually represented forty distinct records; the reconciliation log should distinguish source rows from unique work orders.

For a sample pump repair, the reviewer compares the source ID, destination asset, title, original creation time, completion time and corrective action. A second sample covers a retired asset, and a third covers a record with no start time. This exercises real variations that a sample of three identical records would miss.

After commit, the team checks the imported records in the application and compares counts with the approved batch. The records appear as completed history with their original dates and source identity. They do not become new open jobs or trigger technician notifications merely because the migration happened today.

Understand preview, expiry and atomic commit

Preview reads and validates the proposed records without creating work orders. Use it to inspect errors and compare representative mappings with the source. The preview is temporary and tied to the signed-in user and workspace. If its thirty-minute review window expires, upload and preview again rather than relying on an old browser state.

Commit rechecks the current workspace and writes the batch in a transaction. If any row has become invalid, the batch does not partially create historical work. This matters when another user imports overlapping records or changes relevant data between preview and commit. A successful preview is a review aid, not a guarantee that the destination will remain unchanged indefinitely.

When a commit reports a duplicate, check whether the batch or part of its source identity has already been imported. Do not assume that clicking again will replace records. Compare the destination and your migration log before preparing a corrected file. Stable IDs make this investigation possible.

For large migrations, keep batch boundaries simple: a documented source range, a date range or a reviewed asset group. Record the file name, intended unique count, operator and result. This is your migration control process; the CSV importer should not be described as automatically managing every project-level reconciliation step.

Reconcile content as well as counts

Matching row counts is necessary but insufficient. A file of one hundred records can import one hundred records while assigning every one to the wrong asset. Check identity, chronology and narrative meaning alongside totals. Include samples from different sites, work types, priorities and date ranges.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Compare the earliest and latest completion dates in the batch with the source. Inspect records around timezone boundaries and any known source-system migration date. Review long descriptions for truncation or formatting problems in the original CSV preparation. Confirm that quoted commas and line breaks did not shift content into the wrong columns.

Ask a technician to find the last repair on a selected asset and explain what was done. That task tests whether the migrated history is usable. If they cannot distinguish two similarly named assets or understand the closeout notes, resolve the mapping or presentation issue before importing the next large batch.

Keep a discrepancy list with an owner and resolution. Do not erase the source archive after a clean sample review. Unsupported attachments, detailed labor and stock evidence may remain necessary for future questions even when the supported work history has migrated correctly.

Interpret historical reports with migration context

Imported completed records can improve historical context, but they do not automatically make every before-and-after metric comparable. The old system may have used different definitions for failure, completion, labor or downtime. A new field being populated more consistently can change a report without indicating a change in physical equipment performance.

AI-generated editorial illustration; not a customer photograph or product screenshot.

Record the migration date and the source coverage period. Explain which datasets were imported and which remain outside the application. If the source omitted minor repairs or archived equipment, a reliability comparison should acknowledge that gap. Avoid presenting missing history as proof that no failures occurred.

Use the maintenance evidence method when preparing customer-facing or management claims. Distinguish observed work counts from estimated savings, and separate actual repair duration from elapsed administrative time. A migration preserves evidence; it does not create causal proof of improvement.

Questions before importing historical work

Will original users and attachments come across?

This CSV does not import original user accounts, attachments, checklist responses, detailed labor entries or historical stock consumption. Preserve those exports separately and agree how authorized staff will retrieve them. Do not describe the supported work-record import as full specialist-system parity.

Can the same source job be imported again with corrections?

The source and external ID combination is protected against duplicates. The importer does not overwrite the earlier record. Review the existing destination record and the intended correction through an explicit process instead of changing identity merely to create a second copy.

Can retired equipment retain its service history?

Yes, when the retired asset exists in the current workspace and the history row maps to its asset code. This preserves the distinction between historical equipment and a replacement that may now occupy the same location.

What proves the migration is ready for wider rollout?

A representative batch should reconcile by count, identity, dates and content, and a technician should be able to use it to answer a real maintenance question. Keep unresolved exceptions visible and preserve the original source before expanding to the remaining records.