Document One-Off Utilities Such as Data Migration and Cut-Over Scripts

This chapter explains how to document the one-off, disposable utilities used in support of an Application, such as data migration utilities, cut-over and conversion scripts, and one-time data-fix tools.

Why One-Off Utilities Must Be Documented

One-off utilities are often treated as disposable: they are written for a single migration or fix, run once, and forgotten. Yet they frequently change large amounts of important data. When questions arise later, such as why a customer’s history looks different, how a balance was converted, or what happened to records that are missing, the utility that caused the change is the key to the answer, and if it was not documented, the answer may be lost.

A Lighter but Mandatory Standard

One-off utilities fall under the Minimum Application Documentation Policy with a lighter, but still mandatory, documentation standard. For each one, record:

• What it did, and to which Applications and data.

• Who built it, who ran it, and who approved its use.

• When it ran.

• Results and evidence, such as record counts, reconciliation reports, and any errors and how they were handled.

• Where its code and outputs are archived.

Retain this documentation, and the archived code and outputs, for the same period as the data the utility touched.

Where One-Off Utility Documentation Lives

One-off utilities do not normally receive their own Application Record. Instead, their documentation is attached to the documentation of the Application or Applications they served, for example as part of the documentation of the Release that included the migration or cut-over.

Best Practice: Document One-Off Utilities with a Lighter but Mandatory Standard

Document every one-off utility, recording what it did, to which data, who built, ran, and approved it, when it ran, its results and evidence, and where its code and outputs are archived, attached to the documentation of the Applications it served and retained as long as the data it touched.

Benefits: Documenting one-off utilities preserves the explanation for large data changes that would otherwise be untraceable, which is invaluable for audits, investigations, and customer disputes. The lighter standard keeps this practical, so teams document disposable tools without the overhead of full Application Documentation.

Connections to Related IF4IT Practices and Inventories

The Release Management Best Practices addresses the Release activities, such as migrations and cut-overs, in which one-off utilities are typically used.