> For the complete documentation index, see [llms.txt](https://documentation.opencrvs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.opencrvs.org/v2.1/functional/markdown/workflows/administrative-structure/lifecycle-and-versioning.md). # Lifecycle & Versioning ### 1. Overview OpenCRVS tracks changes to locations and administrative areas over time. Every location — an office or a health institution — and every administrative area keeps one permanent identity for life, alongside a running history of every name, status, and reference code it has ever had, each tagged with the date it took effect. This means a record never has to choose between being accurate today and being accurate to history. A birth registered in Alaminos in 1995 — before the town was renamed Alaminos City in 2001 — still shows Alaminos on its record and on any certificate printed today. A birth registered after 2001 correctly shows Alaminos City. Nothing about the underlying place record needs to change for either case to be true. A location or administrative area can be created, renamed, given a new reference code, or marked inactive (closed) — and any of these changes can be scheduled ahead of time for a future date. None of this is destructive: nothing is ever overwritten or deleted, so a closed or renamed place stays permanently on record and continues to resolve correctly wherever it's referenced. ### 2. Effective Dates & Historical Resolution One idea underlies everything in this guide: a location's identity is permanent, but its name is a matter of record for a particular date. Every location and administrative area has one permanent identity that never changes — think of it as the place's file number. Attached to that identity is an ordered history of **versions**: each version records the name, status (active or inactive), and reference code that were correct starting from a particular date. Nothing in that history is ever edited or removed once its date has passed — a further change is always recorded as a new version, never as a correction to an old one. Whenever the system needs to show a location's name, it doesn't default to "whatever it's called today." It looks up the one date that's actually relevant to what's being shown — called the **anchor date** — and finds the version that was in effect on that date. > **Resolution rule:** The name shown for a given date is the most recent version that had already taken effect by that date. If the date comes before any recorded version, the earliest available version is used instead. This same rule applies independently to every level of a location's hierarchy — the province, district, and municipality above it — so a full historical address resolves correctly as a whole, not just its lowest level. **Worked example — Alaminos → Alaminos City** | Anchor date | Version in effect | Name shown | | ------------------ | -------------------------------- | --------------- | | 1995 (birth event) | Version 1 — effective 0001-01-01 | "Alaminos" | | Today | Version 2 — effective 2001-03-05 | "Alaminos City" | Same identity, two versions — the anchor date decides which name is shown. Inactivation (closing a place) is handled the same way: it is simply a new version with status set to inactive, not a deletion. An inactive place is never removed from the system — it remains permanently available to anything that needs to resolve it at a past date. **Terms used in this guide** * **Identity** — The permanent, unchanging record for a place — same identity for its entire life, however many times it's renamed. * **Version** — One dated entry in a place's history: a name, status, and code, effective from a given date. * **Anchor date** — The specific date used to decide which version applies — varies by context (event date, record date, today). ### 3. Types of Changes OpenCRVS can keep track of different types of changes to locations and administrative areas. These changes are recorded as part of the place's history, so users can understand what information was valid at different points in time. When a location or administrative area is created, it is assigned a **parent** — the administrative area it belongs to. This parent remains fixed throughout the lifetime of that place. If a place needs to move to a different parent, it is handled by closing the existing place and creating a new one under the new parent. | Change | What happens | Example | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | **Create** | A new location or administrative area is created with a name, type, and parent. | A new health post is added to a district. | | **Rename** | The new name is recorded with an effective date. Previous names remain available in the place's history. | **Alaminos** is renamed to **Alaminos City**, effective 5 March 2001. | | **Change code** | An official code can be changed while keeping the same place. The previous code remains in its history. | A district receives a new government code. | | **Inactivate** | A location or administrative area can be made inactive from a specified date. It is no longer available for new selections, but its history and existing records are retained. | A registration office closes permanently. | | **Future-dated change** | A create, rename, code change, or inactivation can be scheduled to take effect on a future date. The change is stored in advance but does not affect the system until that date. | An office is scheduled to close three months from now. | | **Transfer** | A place cannot be moved directly to a different parent. Instead, the existing place is inactivated and a new place is created under the new parent. | A barangay moves from one municipality to another. | ### 4. Effect on Records & Certificates Changes to a location or administrative area do **not change existing records**. A record remains associated with the same place where it was originally created. However, when a record or certificate is viewed, OpenCRVS displays the **name and administrative information that was valid at the relevant time**. For example, if a child was born in **Alaminos** in 1995 and the location was renamed **Alaminos City** in 2001: * A record for a birth in **1995** continues to show **Alaminos**. * A certificate printed in **1995** shows **Alaminos**. * If the same certificate is reprinted today, it still shows **Alaminos**. * A birth registered after the rename shows **Alaminos City**. The date used to determine the correct information depends on what the location information represents: * **Event locations** — such as place of birth or place of death — use the **event date**. This ensures that the location reflects how it was known when the event occurred. * **Action-related locations** — such as the office where a registration was processed — use the **date of that action**. This means different locations shown on the same record may display different names if they changed at different times. The same principle applies to the **full administrative hierarchy**. When a location is displayed together with its district, region, or other parent areas, OpenCRVS shows the hierarchy that was valid at the relevant time. If a location is later **inactivated or closed**, existing records that use that location are not affected. The location remains available for those historical records, and its historical information can still be displayed correctly. ### 5. Locations in Forms and Selectors Which locations a form dropdown offers is configured per field, using two options: * **Active only** — offer only locations that are active, hiding closed locations and locations scheduled to open in the future. * **Anchor to date of event** — decide which locations are active, and which name to show, based on the event date entered on the form instead of today's date. Without these options, a dropdown lists every location, including closed ones, under its current name. The reference country configuration sets them as follows (all of these fields are active only): | Field | Locations are based on | | --------------------------------------------------------------------------------------- | ---------------------------------- | | **Place of event / place of delivery** (health facility, private home or other address) | The event date entered on the form | | **Residential and other addresses** (such as the mother's or informant's address) | The current date | For example, if an event occurred in 1995, the **Place of Event** dropdown will show the locations that were active in 1995, rather than only showing locations that are active today. On fields configured as active only, a location that is scheduled to become active in the future is stored in OpenCRVS but is **not available for selection until its effective date**. If the event date is changed after a location has been picked, and the picked location resolves differently at the new date (for example, it was closed or renamed), the selection is cleared and the user must choose again. **Correcting an Existing Record** When correcting an existing record, fields anchored to the date of event show the locations that were **valid on the date of the event**, rather than the locations that are active today — the same behaviour as in a new declaration. For example, when correcting a record for an event that occurred on **1 January 2020**, the location options would be based on the administrative structure that was valid on that date. ### 6. Searching Historical Locations A closed office doesn't take its records into hiding — Advanced Search is designed to keep them findable. Whether a search filter includes inactive places depends on what kind of location the filter represents: | Search filter | Includes inactive locations? | | -------------------------------------- | ---------------------------- | | Place of registration (office) | ✅ Yes | | Place of delivery (health institution) | ✅ Yes | | Residential address | ❌ No — active only | | Other address filters | ❌ No — active only | Selecting a closed office or health institution in a search filter returns every record ever created there — inactivation never removes records from being found. A renamed office or health institution is listed under every name it has had, so it can be found by its old name as well as its current one; all names return the same records. Address-type filters, by contrast, only ever list currently active administrative areas, since they describe present-day jurisdictions rather than a historical event location. ### 7. Workqueues & User Access * **Renaming or inactivating a place does not move a record.** A record's visibility in workqueues (Notified, Declared, Pending Registration, and so on) depends on comparing its location against the current administrative structure — unaffected by a name change or closure. * **Records at a closed office stay visible to nearby offices.** If an office is inactivated, records already created there remain visible and workable to any other office within the same administrative area — nothing is hidden or deleted. * **Users are never auto-reassigned.** Closing or restructuring an office does not move its staff to a different office. Where continued access is needed, an administrator manages that manually through existing user-management functions. **Lockout for users at an inactivated office** If a user's assigned office is made inactive, they are blocked from using the application until an administrator resolves the situation. They see a full-screen message: *"Your assigned office has been made inactive, please contact admin…"* — this overlay blocks all further use of the application. ### 8. Offline Behaviour OpenCRVS keeps location information accurate even when staff are working offline. * **Location history is synced to the device**, including past, current, and scheduled changes. * **Scheduled changes take effect automatically** on the device when their effective date arrives, even without a new sync. * **If a device has not synced recently**, it may show older location information until it connects and syncs again. ### 9. Implementation Guidance & Limitations **Guidance for country implementation teams** * **Plan how changes will be requested and applied.** Locations cannot currently be created, renamed, or inactivated through the OpenCRVS user interface. Changes are made through the location API by a user or system client with the `location.edit` scope, so country teams should establish an internal process for requesting and applying them. * **Plan for office closures.** Before closing an office, clear or redirect any pending work in its queue, as pending work is not automatically moved to another office. * **Plan location codes.** OpenCRVS rejects a change that would give two active locations (or two active administrative areas) the same reference code at the same time. A code can be reused once the location holding it has been inactivated, so close the old location before giving its code to a replacement. * **Test offline synchronisation.** Before a large-scale rollout, test offline synchronisation using the size and structure of your country's actual administrative hierarchy. #### Current Functional Limitations * **Moving a place to a different parent:** A place cannot be moved directly to a new parent. The existing place must be inactivated and a new place created under the new parent. * **Splitting or merging places:** A place cannot be split into multiple places or multiple places merged into one as tracked operations. * **Linking replaced places:** OpenCRVS does not currently link an inactivated place to the new place that replaces it. They remain separate locations in the system. * **Statistics and reporting:** Changes to locations do not affect how statistics or reporting figures are calculated. * **Managing locations through the user interface:** Locations cannot currently be created, renamed, or inactivated through an on-screen administrative tool. These changes are made through the location API, which requires the `location.edit` scope. * **Historical information before versioning:** OpenCRVS does not reconstruct the history of existing locations. Existing locations start with their current name and status as their initial version. * **Viewing location change history:** The system records changes to locations, but there is currently no user interface for viewing who made a change and when. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.opencrvs.org/v2.1/functional/markdown/workflows/administrative-structure/lifecycle-and-versioning.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.