# Welcome ### 1. Introduction OpenCRVS is an open-source digital solution for civil registration and available as a Digital Public Good. This functional documentation is written for **governments, business analysts, systems Integrators, and development partners** to design, configure, operate, and maintain an OpenCRVS system that meets your country's needs. *** ### 2. How to use this documentation #### 2.1. Understanding CRVS and OpenCRVS * **CRVS Systems:** Understand what effective digital CRVS looks like and the role that OpenCRVS can play πŸ‘‰ [Effective digital CRVS systems](/general/crvs-systems/publish-your-docs) * **Value Proposition:** Learn why governments, Systems Integrators, and development partners are choosing OpenCRVS * πŸ‘‰ [Value Proposition](/general/opencrvs/value-proposition) #### 2.2. Exploring OpenCRVS functionality * **Product Specifications:** Detailed functional architecture and system capabilities πŸ‘‰ [Functional architecture](/functional/markdown) * **Default Configuration:** Explore the OpenCRVS reference implementation for Farajaland πŸ‘‰ [Example: Farajaland](/implementation/example-farajaland) #### 2.3. Technical implementation * **Quick Start:** Run OpenCRVS on your laptop for development πŸ‘‰ [Quick Start](/technical/guides/installation/quick-start) * **Architecture:** Understand how OpenCRVS works technically πŸ‘‰ [Technical architecture](/technical/architecture) * **Configuration:** Technically configure OpenCRVS for your country context πŸ‘‰ [Configuration](/technical/guides/configuration) * **Deployment:** Deploy a configured version of OpenCRVS to a server πŸ‘‰ [Deploy](/technical/guides/installation/deploy-set-up-a-server-hosted-environment) #### 2.4. Project setup and planning * **Setup:** Establish your OpenCRVS project and team πŸ‘‰ [Project planning](/implementation/your-opencrvs-project/project-planning) * **Product Roadmap:** See what's coming next for OpenCRVS πŸ‘‰ [Product roadmap](/releases/roadmap) * **Upgrading:** Update your instance to the latest OpenCRVS release πŸ‘‰ [Version upgrades](/technical/guides/version-upgrades) {% hint style="info" %} **Additional resource:** We recommend using this documentation in combination with the [CRVS Digitisation Guidebook](http://www.crvs-dgb.org/en/), which provides step-by-step guidance for countries to implement digitised systems and automated processes for CRVS. {% endhint %} # CRVS Systems Successful OpenCRVS implementations begin with a strong understanding of the civil registration domainβ€”not the software. This section introduces the principles, terminology, and operating models that underpin effective Civil Registration and Vital Statistics (CRVS) systems. It explains both **what a well-functioning CRVS system looks like** and **why digital technology alone is not enough** to achieve better registration outcomes. Whether you are a Business Analyst, Systems Integrator, Solution Architect, or Project Manager, these pages will help you build the domain knowledge needed to translate legislation, policy, and operational processes into successful OpenCRVS implementations. In this section you will learn: * [**Understanding CRVS**](/general/crvs-systems/quickstart) – the fundamentals of civil registration, key concepts, international standards, and recommended learning resources. * [**Effective Digital CRVS Systems**](/general/crvs-systems/publish-your-docs) – the organisational, legal, operational, and governance foundations required for sustainable digital transformation. A solid understanding of these concepts will make the configuration, implementation, and long-term support of OpenCRVS significantly more effective. # Understanding CRVS ### 1. Introduction Before designing or implementing a CRVS system with OpenCRVS, implementers, Business Analysts, and Systems Integrators must develop a solid understanding of the **civil registration and vital statistics domain**. This includes understanding legal frameworks, administrative workflows, stakeholder responsibilities, data quality principles, and international standards. A strong domain foundation ensures that system requirements align with country-specific policies, international best practices, and the operational realities of registration offices, health facilities, and statistical offices. {% hint style="info" %} **For implementers:** The resources below provide essential context for translating policy and legal requirements into functional specifications, user journeys, and system behaviours that can be reliably implemented and maintained. {% endhint %} *** ### 2. Recommended learning resources #### World Bank Group / Global CRVS Group – Self-Paced Online Course A foundational course covering the principles, benefits, and design of CRVS systems. Free and available online. **Best for:** New team members, Business Analysts, and project managers who need a comprehensive introduction to CRVS principles. πŸ‘‰ [Take the course on the World Bank Open Learning Campus](https://www.worldbank.org/en/olc/course/34651) *** #### UN Handbook on Civil Registration and Vital Statistics Systems An exhaustive reference covering administrative arrangements, operational functions, quality assurance, interoperability, and digitisation of CRVS systems. **Best for:** Deep dives into operational processes, data quality standards, and system management. Essential for Business Analysts writing functional specifications. πŸ‘‰ [Download from the UN Stats website](https://unstats.un.org/unsd/demographic-social/Standards-and-Methods/files/Handbooks/crvs/crvs-mgt-E.pdf) *** #### Regional CRVS strengthening initiatives **APAI-CRVS: Africa Programme on Accelerated Improvement of CRVS** The regional initiative guiding CRVS strengthening across Africa, with country assessments, frameworks, and advocacy materials. πŸ‘‰ [Visit the APAI-CRVS website](https://apai-crvs.uneca.org/) **Get Every One in the Picture – Asia–Pacific CRVS Platform** A regional CRVS strengthening platform offering frameworks, assessments, advocacy materials, and eLearning resources tailored to the Asia–Pacific context. πŸ‘‰ [Visit the Get in the Picture website](https://www.getinthepicture.org/) *** #### CRVS Digitisation Guidebook An online resource providing step-by-step guidance for countries to plan, analyse, design, and implement digitised systems and automated processes for CRVS. **Best for:** Understanding digitisation strategies, technology assessments, and change management approaches. πŸ‘‰ [Visit the CRVS Digitisation Guidebook](http://www.crvs-dgb.org/en/) *** {% hint style="info" %} **Next steps:** After reviewing these resources, proceed to the functional specification sections of this documentation to understand how OpenCRVS implements CRVS workflows, forms, certificates, and system integrations. {% endhint %} # Effective digital CRVS systems ### 1. Introduction Digital technology is a powerful enabler for civil registration, but **digitisation alone cannot transform an under-performing CRVS system**. Effective digital CRVS systems require legal frameworks, operational capacity, stakeholder coordination, sustainable funding, and a clear understanding of the real-world context in which the system will operate. This page provides guidance on setting realistic expectations, defining business requirements, and applying implementation principles that support long-term success. *** ### 2. High-performing CRVS operating model The diagram below illustrates the operational aspects that must be in place for a digital CRVS system to deliver its intended results and benefits. Digitisation is just one component of a broader ecosystem. [High-performing CRVS operating model](https://documentation.opencrvs.org/~gitbook/image?url=https%3A%2F%2Flh7-us.googleusercontent.com%2FPzXcW10hhijzf4HzPdMjg9GD3JChu-GGd_6uQ0oDNAMpmzbi6_y1Q4OR8N3d3VtujGu991920Qlc4ZV8Q9RCFXmbAm3zQ8i4qEfJoNO48vYYiiGNmfyHGu_1zyh9CnjH0pBuKcEKMpdqlzlI3PtQfkgbJw%3Ds2048\&width=768\&dpr=3\&quality=100\&sign=66a415ef\&sv=2) << DIAGRAM! >> {% hint style="info" %} **Implementation reality:** Many CRVS digitisation projects fail because they focus exclusively on technology while neglecting legal reform, change management, training, infrastructure readiness, or sustainable funding models. A successful implementation requires coordinated effort across all dimensions of the operating model. {% endhint %} *** ### 3. Business requirements of a digital CRVS system A successful digital CRVS system must be built on a clear set of business requirements that reflect the core purpose and priorities of civil registration in a digital era. These requirements guide system design and implementation, and help governments evaluate whether a digital solution will meet their strategic objectives. #### Core functional requirements Below is a list of typical expectations that governments may have for a digital CRVS system. This can serve as a reference point for CRVS modernisation efforts: * **Increase completeness of registration** for all vital events across all geographic and population groups * **Adopt digital-first processes** by eliminating manual, paper-based steps prone to error and delay * **Digitise and archive historical paper records** to create a searchable digital archive and reduce physical storage needs * **Improve operational efficiency** by reducing the time required to process registrations and issue certificates * **Enable interoperability** with other national systems, positioning civil registration as a key component of Digital Public Infrastructure * **Ensure robust data security** and full compliance with national and international data protection regulations * **Maintain data integrity** across the foundational identity ecosystem, including civil registration and digital ID systems * **Enhance the accuracy and consistency** of registered information through validation rules and reference data * **Generate high-quality, timely statistics** directly from civil registration records to support policy and planning * **Standardise and harmonise procedures** across all registration offices to ensure consistent service delivery nationwide {% hint style="info" %} **OpenCRVS alignment:** OpenCRVS is designed with these requirements in mind, ensuring the platform delivers real value from day one of implementation. While each country may have its own unique priorities, any modern CRVS system should aim to meet most, if not all, of these requirements. {% endhint %} *** ### 4. Implementation principles for digital CRVS When implementing OpenCRVSβ€”or any digital CRVS systemβ€”it is critical to apply a set of foundational principles that maximise value and avoid common pitfalls. {% hint style="info" %} **Key insight:** Digitising a civil registration system is **not** simply a matter of transferring manual processes into a digital format. It requires rethinking how registration services are delivered, how data flows, and how long-term sustainability will be maintained. {% endhint %} #### 4.1 Design for the real operating context * Understand the environments in which the system will function: Many CRVS systems operate in areas with low or intermittent internet connectivity, limited power supply, and few technical personnel * **Avoid designing for capital city conditions** and expecting the same performance in rural or remote areas * Consider where **offline functionality** is essential, and plan for synchronisation models that work with existing infrastructure * Conduct site assessments to understand real-world constraints before finalising technical architecture decisions #### 4.2 Define the appropriate level of digitisation * Consider which levels of the system should be digitised based on feasibility and sustainability * In low-resource areas, initiating the process with paper-based **notifications** at the community or health facility level may still be the most reliable starting point * Focus on **progressive digitisation**, where events are captured digitally as early in the process as realistically possible * Systems should be scaled as infrastructure improvesβ€”avoid over-ambitious rollouts that cannot be sustained #### 4.3 Capture data digitally at source * Wherever possible, enter data directly into the digital system at the **point of registration**, rather than transcribing from paper forms later * This approach improves data quality, eliminates duplication, and reduces administrative burden * Use **reference data and validation rules** such as drop-down lists for occupation, place names, and relationship types to reduce errors and enforce consistency at the point of entry * Digital data capture also enables real-time analytics and monitoring #### 4.4 Avoid simply digitising paper-based processes * Laws and regulations often reflect outdated paper workflows. **Replicating these processes in digital form will limit the benefits of digitisation** * Instead, define the **strategic long-term vision** of a digital civil registration system and use this vision to create a phased roadmap for legal and operational reform * Ask foundational questions such as: * *"Where is the authoritative registry?"* * *"What legal reforms are needed to enable digital signatures, electronic certificates, or online verification?"* * *"Can we eliminate duplicate registries maintained by different institutions?"* * If the authoritative registry is still "in the paper registers", then the system design may be fundamentally constrained #### 4.5 Plan for scalable and sustainable infrastructure * Be realistic about **operational costs** (OPEX). Highly decentralised architectures often require extensive hardware deployments and increase maintenance costs * **Centralised or semi-centralised models** may be more cost-effective, especially where local infrastructure is weak * Evaluate how much data can realistically be transmitted from local offices to central servers, and use this to inform requirements for digital forms, supporting documents, and sync intervals * Consider cloud hosting, managed services, or hybrid models that balance control with operational efficiency #### 4.6 Establish a single source of truth * Aim to build a **master digital registry** of all civil registration data * This central repository should support controlled access for different users based on defined roles and permissions * **Avoid fragmented systems** for autonomous institutions that duplicate data or require parallel maintenance. These increase complexity, reduce data reliability, and create reconciliation challenges * A single source of truth enables consistent reporting, reliable analytics, and streamlined interoperability #### 4.7 Design for interoperability from the start * Civil registration data is foundational for many other public services, including identity, health, education, and social protection * Think about how the system will both **receive data** (e.g. birth notifications from health systems) and **share data**(e.g. with national ID or statistics offices) * Use **open standards** such as HL7 FHIR, W3C Verifiable Credentials, and ISO specifications where applicable * Design secure, auditable APIs that support controlled data exchange while protecting individual privacy {% hint style="info" %} **For Systems Integrators:** These principles should inform architectural decisions, system design specifications, and implementation roadmaps. OpenCRVS is built to support these best practices and adapt to a wide range of legal, infrastructural, and operational contexts. {% endhint %} *** ### 5. Next steps By following these principles, countries can ensure that their investment in CRVS digitisation leads to long-term success, even if full digitisation takes time. **Recommended reading:** * Understand how OpenCRVS fits within broader systems architecture and interoperability frameworks * Review functional specifications for workflows, forms, and certificates * Explore role-based permissions and scope-based access control models # OpenCRVS OpenCRVS is a free, open-source digital system purpose-built for civil registration and vital statistics (CRVS). It helps governments register life events β€” births, deaths, marriages and others β€” and produce the reliable vital statistics that underpin planning, legal identity and public services. Unlike a generic database or a repurposed health or identity system, OpenCRVS is designed around civil registration itself and around the realities of delivering it: it works on low-cost devices, supports low-connectivity and offline working, and is built to reach every person, including the hardest to register. {% hint style="info" %} **A digital public good.** OpenCRVS is openly licensed and standards-based, designed to be adopted, configured and run by governments as part of their national Digital Public Infrastructure. {% endhint %} #### What makes OpenCRVS different * **Purpose-built for CRVS** β€” modelled on civil registration processes, roles and legal requirements, not adapted from another domain. * **Configurable** β€” each country defines its own events, forms, business rules, user roles, certificates and languages, without changing the core software. * **Built for real conditions** β€” mobile-friendly, usable on modest hardware, and resilient to intermittent connectivity. * **Interoperable** β€” integrates with identity, health, statistics and social-protection systems through open standards. * **Inclusive by design** β€” focused on universal registration and on removing barriers for under-served populations. # Why OpenCRVS? ### 1. Introduction Civil registration is the foundation of legal identity and rights-based service delivery. A Civil Registration and Vital Statistics (CRVS) system records the details of all major life events, such as births, deaths, marriage, and divorce. It is an essential component of the "leave no one behind" agenda, and without it working effectively, it is virtually impossible to ensure inclusive growth. ### 2. The civil registration challenge Unfortunately, in many countries CRVS systems are broken: * **1 in 4 children** under the age of 5 have not had their birth registered and hence do not officially exist * As a result, they struggle to access basic rights like education, healthcare, and social protection * **Two thirds of the world's deaths** are not recorded, meaning governments cannot design effective public health policies or measure their impact ### 3. Common challenges faced by users Through extensive research of CRVS systems around the world, we understand many of the specific challenges experienced by civil registration staff and families trying to register vital events: **For families and informants:** * Civil registration processes are bureaucratic and time-consuming, with requests for supporting documents that family members do not possess and unofficial payments * Family members need to travel long distances to register vital events, with several trips often required before the registration process is complete and a certificate is obtained * Systems are not integrated, so birth registration does not lead to automatic access to other rights such as vaccination programmes or enrolment in social protection schemes **For civil registration staff:** * Manual, paper-based processes are prone to errors, delays, and loss of records * Limited visibility into registration backlogs, performance metrics, or data quality issues * Fragmented systems that do not communicate with each other, requiring duplicate data entry and reconciliation # Value proposition ### 1. Introduction **Our vision is that every person on the planet is recognised, protected and provided for from birth.** OpenCRVS is more than a digital platformβ€”it is a catalyst for ensuring universal civil registration, enabling legal identity for all, and strengthening the foundational systems that underpin rights, services, and national development. This page explains the value proposition of OpenCRVS for governments, Systems Integrators, and development partners. *** ### 2. Value proposition for governments Governments face significant challenges when digitising civil registration systems, including high license fees, vendor lock-in, long implementation timelines, and limited local capacity. OpenCRVS addresses these challenges head-on. #### **2.1. No license fees or vendor lock-in** OpenCRVS is open-source software with no license fees. Governments are not tied to specific vendors and have full control over their system, avoiding the two biggest challenges that have historically constrained CRVS digitisation efforts. #### **2.2. Quickly configurable for country context** OpenCRVS can be configured to reflect country-specific legal frameworks, administrative structures, and workflows without requiring years of custom development. Governments can evaluate whether the system is fit for purpose early in the implementation process. #### **2.3. Local capacity and ownership** Local teams can be trained to configure, deploy, and maintain the system. This builds sustainable in-country capacity and reduces long-term dependency on external consultants or vendors. #### **2.4. Data sovereignty and hosting choice** The country owns their instance of the system and their data. They can choose where to host itβ€”on-premises, in a local data centre, or in a cloud environment of their choosing. #### **2.5. Global community and peer learning** Countries join a global community of OpenCRVS implementers, enabling them to learn from other countries' experiences, share best practices, and benefit from each other's investments. #### **2.6. Standards-based interoperability** OpenCRVS provides standards-based integration with national ID, health, and social protection systems, allowing countries to unlock the real value of civil registration as foundational Digital Public Infrastructure. #### **2.7. High performance and scalability** The system is designed to deliver high levels of performance even for the largest populations, with proven deployment in countries with millions of vital events per year. #### **2.8. Security and compliance** OpenCRVS is built to the highest security standards and is regularly penetration tested, giving countries peace of mind that their foundational identity data is protected. #### **2.9. Free upgrades and ongoing support** Governments receive free software upgrades, technical support, and training on an ongoing basis from the OpenCRVS community and core team. {% hint style="info" %} **For government decision-makers:** OpenCRVS offers a sustainable, cost-effective path to CRVS digitisation that prioritises local ownership, interoperability, and long-term capacity building. {% endhint %} *** ### 3. Value proposition for Systems Integrators Systems Integrators play a critical role in implementing, configuring, and supporting OpenCRVS deployments. OpenCRVS provides significant advantages for integrators seeking to deliver high-quality CRVS solutions. #### **3.1. Configurable platform for global RFPs** OpenCRVS is highly configurable and can be used to respond to requests for proposals (RFPs) around the world, instead of building something from scratch for each engagement. This significantly reduces development costs and time to deployment. #### **3.2. Centrally maintained core product** The core product is centrally maintained and supported by the OpenCRVS organisation, meaning lower cost to serve and reduced technical debt for integrators. #### **3.3. Digital Public Good status** OpenCRVS is the only Digital Public Good (DPG) for CRVS, increasingly a characteristic requested in RFPs from governments and development partners. #### **3.4. Business development and capacity building** The OpenCRVS organisation provides access to business development materials, implementation playbooks, and a community of CRVS experts to build knowledge and capacity within integrator teams. #### **3.5. Ongoing product development and research** Integrators benefit from ongoing product development, research, and innovation led by the OpenCRVS organisation and community, ensuring the platform remains at the cutting edge. {% hint style="info" %} **For Systems Integrators:** OpenCRVS enables you to deliver proven, scalable CRVS solutions to governments while benefiting from a centrally maintained core platform and a global community of implementers. {% endhint %} *** ### 4. Value proposition for development partners Development partners, including UN agencies, bilateral donors, and international NGOs, support CRVS strengthening as a critical foundation for legal identity, human rights, and sustainable development. #### **4.1. Contributes to strategic development outcomes** OpenCRVS directly contributes to SDG 16.9: "Everyone has the right to a legal identity, including birth registration." It also supports progress across multiple other SDGs, including health, education, gender equality, and reduced inequalities. #### **4.2. Integrated programming and measurable impact** OpenCRVS can be used as part of an integrated programme that delivers measurable positive impact in line with development partner objectives, including improved registration completeness, reduced time to registration, and enhanced data quality. #### **4.3. Standardised, rights-based product** OpenCRVS is a standardised, rights-based product that simplifies CRVS strengthening efforts around the world, enabling development partners to support multiple countries with a proven solution. #### **4.4. Compliance with UN standards** The system complies with UN standards and recommendations for civil registration and vital statistics, ensuring alignment with international best practices. #### **4.5. Designed for low-resource settings** OpenCRVS has been designed with civil registration users and customers around the world and responds to the operational realities and constraints of countries in low-resource settings. #### **4.6. Empowers local ownership and capacity** The platform empowers countries to build local technical capacity and have long-term ownership over their civil registration system, reducing dependency on external support. #### **4.7. Global CRVS community** The growing OpenCRVS community creates opportunities for peer-to-peer learning, shared investments, and South-South cooperation, amplifying the impact of development partner investments. {% hint style="info" %} **For development partners:** Supporting OpenCRVS is an investment in sustainable, locally owned CRVS systems that deliver measurable development outcomes and contribute to legal identity for all. {% endhint %} *** ### Conclusion OpenCRVS delivers value across the entire CRVS ecosystemβ€”from governments seeking sustainable digitisation, to Systems Integrators delivering proven solutions, to development partners supporting rights-based development outcomes. By prioritising open standards, local ownership, and community-driven innovation, OpenCRVS is building a global movement toward universal civil registration. # Design principles ### 1. Intoduction We continue to stand by our original product commitments for OpenCRVS, and these help steer the strategic direction of the product:\ \ Product commitments: 1. **Fully open-source**, with no license fees or ties to specific vendors 2. **Configurable** for all country contexts 3. **Interoperable** with other government systems 4. **Highly accessible** to ensure inclusion, even in remote areas 5. **Safe and secure** to keep personal data protected 6. **Easy to deploy and use** in low-resource settings 7. **Enabling new models** of civil registration that can help achieve universal registration *** ### 2. Our design principles We are passionate about designing a product that fulfills our mission: to make civil registration easy and valuable for everyone by making high-quality and cost-effective digital systems widely available and sustainable. Our design principles provide a clear framework for all those working on OpenCRVS to make design decisions that affect how the product works. #### 2.1. Start with users' needs Listen to, engage with, and observe users. Spend time to understand their needs, assume nothing, and work with your users to create designs. #### 2.2. Prioritise offline Every product feature must work offline and in areas of low connectivity. Where connectivity is required to complete an action, tell the user what's happening and always consider the loading state. #### 5.3. Give guidance throughout The user shouldn't have any questions about what to doβ€”it should be intuitive. Make the product simple and offer clear guidance every step of the way. #### 5.4. Test, learn, and iterate The best way to develop new features is to get an early version into the hands of users, then listen β†’ learn β†’ iterate. #### 5.5. Enable rights We want to empower and protect those who use and are served by OpenCRVS. Is what you are designing likely to exclude or discriminate against anyone? How can this be avoided? #### 5.6. Be consistent Every part of the product should look and feel part of the whole. Always use the component library. #### 5.7. Be hyper-accessible Our users are from across the world with varying levels of digital literacy. Whatever we design must be intuitive, legible, and as accessible as possible. #### 5.8. Words matter Every word should be understood by users, with no room for ambiguity. When drafting text, avoid administrative language and test it with local users. #### 5.9. Design with data Use data generated from the system to inform design improvements. #### 5.10. Consider other contexts OpenCRVS is a global product. Consider the variability of what you are designingβ€”will it work in other countries and contexts, and how will it be easily configured # Glossary OpenCRVS uses a consistent set of concepts across modules: * **Event** – a civil registration event type such as birth, death, marriage, etc. * **Record** – the data instance for a single event. * **Notification** – a preliminary capture of event details that may form the basis of a formal declaration. * **Declaration** – a formal statement that an event has taken place. * **Registration** – the process by which an event record is reviewed and legally registered. * **Certified copy / certificate** – an official document representing a registered event. * **Informant** – the person who formally reports the event. * **Workflow** – the ordered steps and rules that govern a record through its lifecycle. * **Status** – the state of a record in the workflow (for example, Draft, Notified, Declared, Registered). * **Action** – a user or system operation that changes a record or its status (for example, Notify, Declare, Validate, Register, Correct, Issue certificate). * **Form** – the structured data capture for an event, defined by fields, conditional logic, and validations. * **Business rule** – a configurable rule that validates data or controls workflow behaviour. * **Administrative unit** – the organisational unit responsible for services for a specific area. * **User / role** – the authenticated user and their permission set. # Functional Architecture ### 1. Introduction The OpenCRVS **functional architecture** is a generic, country-agnostic model of how the application works. It describes the system in terms of its **functional building blocks** rather than its infrastructure, so that the same core product can be configured to meet the specific civil registration needs of any country. This page: * Defines the **core concepts and vocabulary** used throughout the documentation. * Describes the main **functional modules** β€” Events, Workflows, Records, Search, Access, Aggregate Data, Interoperability, and Legacy Data. * Summarises the **record lifecycle**, from notification through to certification and beyond. * Clarifies the boundary between **configuration** and **customisation**. The focus is deliberately on the **functional model**. Infrastructure, deployment, and technology choices are covered in other sections of the documentation. *** ### 2. How to read this section The architecture is organised into a small number of **modules**, shown in the diagram below. The first five modules describe the journey of a record β€” from the definition of an event, through the workflow that moves it, to the record itself, how it is found, and how its data is aggregated. The remaining modules β€” Access, Interoperability, and Legacy Data β€” are **cross-cutting foundations** that support the whole system rather than sitting at a single point in the lifecycle. Each module summarised here has its own documentation section with fuller detail.
*** ### 3. Audience The functional architecture is written for: * **Product owners** defining the civil registration solution. * **Business analysts** translating law and policy into requirements. * **Solution architects** designing how OpenCRVS fits into the wider digital ecosystem. * **Implementation teams** configuring and operating OpenCRVS for a country. No prior knowledge of the OpenCRVS codebase is assumed; the concepts below are sufficient to reason about the product. *** ### 4. Core concepts and vocabulary OpenCRVS uses a consistent vocabulary across every module. The terms below recur throughout the documentation. | Term | Meaning | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Event** | A civil registration event type, such as a birth, death, or marriage. | | **Record** | The data instance for a single occurrence of an event. | | **Notification** | A preliminary capture of event details that may form the basis of a formal declaration. | | **Declaration** | A formal statement that an event has taken place. | | **Registration** | The process by which an event record is reviewed and legally registered. | | **Certificate / certified copy** | An official document representing a registered event. | | **Informant** | The person who formally reports the event. | | **Workflow** | The ordered steps and rules that govern a record through its lifecycle. | | **Status** | The state of a record within the workflow (for example Draft, Notified, Declared, Registered). | | **Action** | A user or system operation that changes a record or its status (for example Notify, Declare, Validate, Register, Correct, Issue certificate). | | **Form** | The structured data capture for an event, defined by fields, conditional logic, and validations. | | **Business rule** | A configurable rule that validates data or controls workflow behaviour. | | **Administrative unit** | An organisational unit responsible for delivering services to a specific area. | | **User / role** | An authenticated user and the permission set (scopes) attached to their role. | These concepts underpin the modules described below. *** ### 5. Functional modules #### 5.1 Events module β€” *defines what can be registered* The Events module is the configurable catalogue of everything OpenCRVS can register and the rules that shape each event type. * **Types** β€” the event catalogue and the type-specific behaviour for each registrable event. * **Forms** β€” event forms built from fields, conditional logic, and validation, used for Notify/Declare, Correct, and other actions. * **Business rules** β€” configurable rules that control eligibility, late registration, approvals, and other event-specific behaviour. #### 5.2 Workflows module β€” *how records move through the system and how users interact with them* The Workflows module governs the path a record takes and what each user is permitted to do with it. * **Administrative structure** β€” the hierarchy of administrative units and offices responsible for delivering services in each area. * **Users** β€” roles, scopes, jurisdictions, and the workqueue access that determine what each user can see and do. * **Jurisdictions** β€” the geographic and organisational boundaries that control which records a user can view and action. * **Actions** β€” the configured operations users can perform on records (Notify, Declare, Validate, Register, Correct, Issue, and so on). * **Workqueues** β€” pre-filtered lists of records that require a user's attention or action. * **Offline working** β€” record assignment, the Outbox, and predictable synchronisation behaviour when devices reconnect. * **Deduplication** β€” detection and review of potential duplicate records before they are registered. * **Comms** β€” SMS and email notifications to informants and users, linked to actions. #### 5.3 Records module β€” *how a single event record is represented and evolves over time* The Records module describes the record itself: its data, its state, and its complete history. * **Record data** β€” the journaled data model holding event content, supporting documents, and action metadata. * **Statuses** β€” lifecycle states such as Draft, Notified, Declared, Validated, Registered, and Corrected. * **Flags** β€” additional workflow markers that complement status, such as late-registration, pending-attestation, or protected. * **Certificates** β€” official certificates and certified copies generated from registered records. * **Verifiable Credentials** β€” cryptographically verifiable digital proofs issued from registered records. * **Protected data** β€” mechanisms for hiding sensitive records or fields from general search and view. * **Audit** β€” an immutable history of every action taken on the record. #### 5.4 Search module β€” *finding and retrieving records* A civil registration system must reliably store, file, archive, and retrieve records. The Search module lets users narrow the search scope to find a record quickly. * **Quick search** β€” look up a record by a unique identifier, such as a Tracking ID, Registration number, National ID, or phone number. * **Advanced search** β€” used when no unique identifier is available; search by record status, place of registration, date of registration, and any configurable event parameters (for example child, mother, or father details). Search results respect the user's scope: a user may be permitted to search all records of an event type, or only those within their own jurisdiction. #### 5.5 Access module β€” *who can do what, and see which data* The Access module governs authentication, accounts, and security. * **User management** β€” user accounts, role assignment, and assignment to offices. * **Applications** β€” the client applications through which users reach OpenCRVS, including the core web and mobile interfaces and any country-specific custom apps. * **Security** β€” authentication, two-factor authentication, screen-lock PIN, and the audit of security-relevant actions. #### 5.6 Aggregate Data module β€” *how operational data is aggregated for performance and statistics* The Aggregate Data module turns the record store into operational insight and statistical output. * **Performance views** β€” operational dashboards covering workload, timeliness, and rejection and correction rates. * **Vital statistics export** β€” structured, non-personally-identifiable outputs for the production of vital statistics. * **Person centricity** β€” person-level views that link multiple records together where identifiers permit. #### 5.7 Interoperability module β€” *how OpenCRVS exchanges data with other systems* The Interoperability module connects OpenCRVS to the wider digital government ecosystem. * **APIs** β€” ... * **Action triggrers** β€” ... * **MOSIP** β€” ... #### 5.8 Legacy data module β€” *how existing records are brought into the system* The Legacy Data module covers the transformation of pre-existing records so they can be used within OpenCRVS. * **Legacy data import** β€” import existing digital records for ongoing use. * **Legacy paper import** β€” capture and digitise paper records for ongoing use. *** ### 6. Lifecycle model Each event type has a **state machine** that describes how its records move through the system. A typical flow is: > **Draft β†’ Notified β†’ Declared β†’ Registered** with auxiliary flows for: * **Editing** β€” amending a declared record before registration. * **Correction** β€” correcting data after registration through a governed process. * **Archiving** β€” archiving erroneous or invalid declarations. * **Revocation** β€” revoking erroneous or invalid registrations. **Business rules** determine, at every step: * Which actions are available in each status. * Who can perform those actions, based on role, scope, and jurisdiction. * Which flags are set or cleared when an action completes. *** ### 7. Configuration vs customisation Country implementations should meet their requirements primarily through the **configuration package**, which covers: * Event types, forms, and validation rules. * Business rules and workflows. * Roles, scopes, and administrative structure. * Certificates, communications, and aggregate data views. * Deduplication logic and offline behaviour. **Custom code** should be considered only when configuration cannot reasonably meet a requirement. When customisation is necessary, it should: * Follow the core architecture patterns. * Minimise divergence from the standard product. * Be designed so that future upgrades remain feasible. *** ### 8. Cross-cutting concerns Several concerns apply across every module: * **Security and privacy** β€” role-based access, audit trails for all changes, data minimisation, field-level validation, and configurable retention policies. * **Offline and synchronisation** β€” predictable sync behaviour, idempotent writes, and conflict resolution when devices come back online. * **Internationalisation and localisation** β€” support for multiple languages and country-specific formatting. * **Accessibility and usability** β€” consistent, usable interfaces for every type of user. * **Logging, monitoring, and performance** β€” observability of system health and adherence to performance expectations. Together, these modules and cross-cutting concerns form the OpenCRVS functional architecture that the rest of the documentation builds upon. # Events ## Overview As part of the **Functional Architecture**, the **Events** section describes the events module in OpenCRVS β€” how different civil event types are modelled and configured. It is organised into the following modules: * **Types** β€” describes how event types (for example, birth, death, marriage) are defined and linked to forms, statuses, actions, and outputs. * **Business Rules** β€” shows how legislation and policy are translated into configurable rules that control which actions are available, when declarations become late, when approvals are required, and related behaviour. * **Forms** β€” explains how event forms are configured to capture Notify/Declare, Correct, and other action data, including pages, fields, validations, and evidence uploads. * **UINs** β€” describes how unique identifiers (for example, Tracking ID, Registration number, National ID integration) are generated or captured for events and how they are used across workflows and search. Together, these modules show how to configure each event type so that it reflects national law and policy while using a consistent model across OpenCRVS. # Type ### 1. Introduction In OpenCRVS, an **event type** represents a kind of civil event that can be declared, registered, and certified. Each event type: * Relates to one or more specific people (for example, child, mother, spouse, deceased). * Occurs on a specific date (and optionally at a specific time and place). * Has a set of data fields that describe what happened (for example, cause of death, place of birth). OpenCRVS is not limited to births and deaths. Any civil event that can be clearly defined in terms of **who** it affects and **when** it occurred can be modelled as an event type. *** ### 2. Examples of civil event types Common examples of civil events that can be configured in OpenCRVS include: * Birth * Death * Stillbirth * Foundling * Marriage * Divorce * Adoption * Legitimation * Recognition * Name change * Address change Countries can choose which event types to enable and how to name them, based on their legal framework and CRVS policy. *** ### 3. Configuring event types in OpenCRVS Each event type can be configured to match country requirements. At a high level, configuration covers: * **Forms and data** * Which fields are captured (for example, parents’ details, cause of death, place of marriage). * Which fields are mandatory vs optional. * **Workflows and approvals** * Which record actions are available (for example, Notify, Declare, Validate, Register, Correct). * What deduplication checks should run. * Which workqueues surface records for review. * **Roles, scopes, and jurisdiction** * Which user roles can create, review, approve, or correct records for that event type. * Jurisdiction rules based on event location, declared-in, or registered-in. * **Outputs and post-registration steps** * Certificate templates for each event type. * Optional integrations such as verifiable credentials. This configuration model allows a country to support **all relevant civil events** in a consistent way, while tailoring details to national law and practice. # Business Rules ### 1. Introduction In OpenCRVS, **business rules** express how civil registration should work in a specific country. They translate **legislation and policy** into concrete system behaviour, such as: * What information must be captured on a declaration. * Who is allowed to validate or register a record. * When senior approval is required. * When a certificate can be issued or a correction made. Business rules ensure that every registration follows the same logic, regardless of where it is completed or who processes it. *** ### 2. What business rules can control OpenCRVS supports configuration of many types of business rules. At a high level, they can control: * **Forms and data** * Which fields are mandatory or optional. * When specific supporting documents are required. * Which values are allowed (for example, minimum ages, valid date ranges). * **Workflows and approvals** * Which actions are available at each status (for example, Notify, Declare, Validate, Register, Correct). * When an additional review or senior approval is required (for example, late registration). * When a declaration can be rejected, archived, or escalated. * **Roles, scopes, and jurisdiction** * Which roles can create, edit, validate, register or print records etc. * Which records a user can act on, based on their jurisdiction. * **Outputs and post-registration steps** * When certificates or certified copies can be printed. * When corrections can be requested or applied. * When additional notes or data (for example, cause of death) can be added after registration. These rules are implemented using a combination of **forms**, **actions**, **flags**, **scopes**, and **workqueues**. *** ### 3. Example business rules The examples below illustrate the kinds of rules that can be configured. The exact rules vary by country. #### 3.1 Declaration form rules * All mandatory questions must be completed before a declaration can be submitted. * A specific supporting document is required when a condition is met (for example, marriage certificate required for legitimation). * Mother’s age must be above a configured minimum at the time of birth registration. * Bride’s and groom’s ages must be above a configured minimum at the time of marriage registration. * Informant’s identity and signature (or equivalent) must be captured. * Certain fields can be prepopulated (for example, notifier’s name and role when a hospital official logs in). * Place of event must be within the user’s allowed jurisdiction when declaring or notifying. #### 3.2 Registration workflow rules * Allow incomplete submissions (**Notified** status) to be completed later by another user. * Require validation by a Registration Agent before final registration. * Allow a Registration Agent or Registrar to reject a declaration for correction. * Require senior approval for specific scenarios (for example, late registrations). * Require a health administrator to attest a death before registration at the local office. * Require a Registrar to review potential duplicates before registration. * Restrict registration to specific roles (for example, Registrar only). * Allow or disallow edits by certain roles at particular statuses. * Enable escalation to higher-level offices for review and opinion. * Ensure users can only act on records within their jurisdiction. #### 3.3 Printing and certification rules * Require capture of requester’s details and identity before issuing a certificate or certified copy. * Use a specific certificate template for first issuance. * Allow different templates for re-issuance (for example, full certificate vs extract vs certified copy). #### 3.4 Correction rules * Require capture of requester’s details and identity before processing a correction * Allow correction requests to be submitted by a Registration Agent and approved by a Registrar. * Permit direct corrections by a Registrar in defined scenarios. * Require senior approval for sensitive corrections (for example, changing a child’s date of birth). *** ### 4. From legislation to configuration In practice, configuring business rules in OpenCRVS involves: 1. **Reviewing legislation and policy** β€” understanding legal requirements for each event type. 2. **Identifying rules** β€” listing conditions, approvals, and constraints that must be enforced. 3. **Mapping to configuration** β€” applying those rules using forms, actions, flags, scopes, and workqueues. 4. **Testing and iteration** β€” validating that real cases behave as expected. This approach allows countries to encode their civil registration laws into OpenCRVS in a transparent, testable way, while still benefiting from a common product foundation. # Forms ### 1. Introduction In OpenCRVS, a **form** is the user interface used to collect and validate data for a specific action on a record. For example, different forms can be used when: * Declaring a birth or death. * Requesting a correction. * Printing a certificate or certified copy. Forms are fully configurable so that countries can match their legal requirements and data standards, while reusing common field types and behaviours. *** ### 2. Feature overview Forms provide a flexible mechanism for collecting and validating data across many workflows in OpenCRVS, while keeping the experience manageable for frontline users. **Core capabilities** With forms, OpenCRVS supports: * Unlimited configurable forms for different workflows (declarations, corrections, custom actions, print flows). * Grouping questions into **pages** and sections to structure complex declarations. * Conditional show / hide of pages and fields based on record data, user role, and previous answers. * Field‑level **validation rules** (required, patterns, min / max, date ranges) to protect data quality at source. * Marking specific fields as **analytics‑relevant** so that only safe, aggregated data flows to dashboards. * Capturing and reviewing **supporting documents** via upload fields as part of the same flow. * Triggering and clearing **flags** based on form conditions (for example, late registration, requires senior approval). * Controlling which fields can be updated later as part of **correction** workflows. {% hint style="warning" %} **Versioning** β€” OpenCRVS does not currently support form versioning. Once a configuration is live, adding or removing fields (especially mandatory ones) can impact existing records and workflows. Plan carefully and test forms thoroughly before go-live. {% endhint %} *** ### 3. Form properties Each form has a small set of core properties that control how it behaves. * **Pages** * **Declaration / record forms**, **Print** forms, and **Correction** forms can all have one or more pages. * Pages are used to group related questions and improve usability. * **Custom action forms** are shown in a dialog and are limited to a **single page**, but can still use conditional show / hide logic for individual fields. * **Inputs (fields)** * Each page contains one or more input fields. * Each input can have an optional **label** and **hint/help text** to explain what should be entered. * Fields like **Text** and **Number** can also include a **prefix** (for example, currency symbol) and **postfix** (for example, unit such as "years"), to make expected values clearer. * **Conditionals (show / hide)** * Pages and fields can be shown or hidden based on: * Values of other fields (for example, show spouse details only if "Married"). * User role or scope (for example, hide fields for the Health Official). * *Role-scoped form shape:* Role-based conditional visibility is a workflow design tool, not just a convenience feature. A single form definition can present materially different experiences to different actors: a health facility clerk sees 5 fields and submits a Notification; a Registration Agent using the same form sees 20 fields and submits a full Declaration. Role-scoped form shape and action scopes compose: * A role with `record.notify` scope and a shortened form (mandatory registration fields hidden) can submit what they have captured β€” Notify accepts incomplete data and produces a Notified record for follow-up. * A role with `record.declare` scope and the full form can submit a complete declaration β€” Declare requires all mandatory fields before the button is enabled. * **Validations** * Field-level validations (for example, required, pattern, min / max, date ranges). * Error messages shown inline to guide users. * **Analytics flag** * Mark fields whose data may be used in **performance / analytics dashboards** (for example, Metabase performance views). * Only fields with `analytics = true` are exposed to Metabase for dashboarding, to ensure that personally identifiable information (PII) is not available in analytics datasets. * Should **not** be set on fields that contain PII or other sensitive information. * **Corrections** * Mark whether a field can be corrected as part of a correction workflow after registration. * ~~**Security**~~ * ~~Mark sensitive fields that require special handling (for example, visibility restricted to certain roles).~~ * **Flags** * Configure flags to be added or removed based on form conditions (for example, late registration, requires senior approval, requires health attestation). *** ### 4. Input field types The following input field types are supported: #### 4.1 Text Free-text input for short strings (for example, names, occupations). * Supports configurable max length and validation patterns. * Use for data that cannot be reliably constrained to a fixed list. * Avoid using for values that should be standardised (for example, sex, country) β€” prefer **Select** instead. * **Storybook:** *(embed Text input example here)* #### 4.2 Number Numeric input (for example, age, number of children, parity). * Supports min / max, step values, and integer or decimal constraints. * Use for quantities that will be used in validation or analytics. * **Storybook:** *(embed Number input example here)* #### 4.3 Number with unit Numeric input with a visible unit next to the field (for example, years, months, kg). * Use when you want to standardise the unit (for example, always capture age in **years** or weight in **kg**). * Helps users understand exactly what to enter and reduces ambiguity in reporting. * **Storybook:** *(embed Number with unit example here)* #### 4.4 Email Email address input. * Applies basic email pattern validation (for example, must contain `@` and a valid domain). * Use when capturing contact details that may be used for email notifications or follow-up. * **Storybook:** *(embed Email input example here)* #### 4.5 Phone Phone number input. * Can apply country-specific formatting and validation. * Use where follow-up SMS or phone contact is required. * **Storybook:** *(embed Phone input example here)* #### 4.6 Select Drop-down or select list. * Use when values should come from a **controlled vocabulary** (for example, sex, marital status, relationship to child). * Options can be localised and ordered. * Reduces data cleaning and improves reporting quality. * **Storybook:** *(embed Select input example here)* #### 4.7 ID Reader (QR / e-signat) Specialised input for reading identifiers from QR codes or e-signat. * Use to capture national ID, health ID, or other machine-readable identifiers. * Can be combined with lookups to prepopulate other fields. * **Storybook:** *(embed ID Reader example here)* #### 4.8 Registration number validator / lookup Field that validates or looks up data from another event record using a registration number or tracking ID. * Use for scenarios such as: * Linking a marriage declaration to the bride’s or groom’s birth record. * Verifying an existing registration before issuing a certificate. * Can populate related data fields read-only to avoid retyping. * **Storybook:** *(embed Registration number lookup example here)* #### 4.9 Date Date (and optionally time) input. * Use for dates of event, declaration, registration, or document issue. * Supports validation (for example, cannot be in the future, must be after another date). * **Storybook:** *(embed Date input example here)* #### 4.10 Radio Single-choice options presented as radio buttons. * Use when there are few options and you want all options visible at once (for example, place of birth: facility / home / other). * Behaviour is similar to **Select**, but optimised for short lists. * **Storybook:** *(embed Radio input example here)* #### 4.11 Checkbox Boolean or multi-select using checkboxes. * Single checkbox: yes/no conditions (for example, "Father’s details are unavailable"). * Multiple checkboxes: select all that apply (for example, signs and symptoms). * **Storybook:** *(embed Checkbox input example here)* #### 4.12 File Upload File upload (JPG, PNG and PDF). * Use for supporting documents (for example, medical certificates, ID scans). * Consider storage, security, and retention policies on devices when enabling uploads. * **Storybook:** *(embed Upload input example here)* #### 4.13 HTTP (external link / integration) Actionable button to open an external service. * Use when users need to visit an external system (for example, external ID verification) as part of the workflow. * Can be combined with **Data** fields that display results from previous integrations. * Can be used to trigger notifications to informants * **Storybook:** *(embed HTTP? / external link example here?)* #### 4.14 Data (read-only display) Displays data in read-only form. * Use to show calculated values, lookup results, or existing record data alongside editable fields. * Helps users validate that they are acting on the correct record without allowing changes. * **Storybook:** *(embed Data display example here)* #### 4.15 Print Button used to generate a printable document using a preconfigured SVG template. * Takes data captured in the form and populates an SVG template, which is then exported as a PDF. * Can be used to generate a printable view of the declaration data, a certificate, a payment receipt or other official outputs. * **Storybook:** *(embed Print trigger example here)* *** ### 5. Layout and formatting options Forms can also include non-input blocks to structure content and guide users. * **Headings (H1, H2)** β€” group related questions under clear titles. * **Divider** β€” visually separate sections. * **Paragraph** β€” provide instructions or legal text. * **Bulleted lists** β€” explain requirements or examples. Use these elements to: * Explain why certain data is needed. * Provide examples of acceptable values. * Call out legal statements or consent text. *** Worked example: 2 pager … #### Configuration input .. *** ### 6. Record review When reviewing a declaration or registration, OpenCRVS presents: * The **captured form data** for the record. * Any **supporting documents** uploaded via Upload fields (for example, medical certificates, ID scans, marriage certificates). The review experience is designed so that users can see data and documents **side by side**, making it easier to: * Verify that key data values (for example, names, dates, locations) match the evidence provided. * Spot inconsistencies or missing information before validation or registration. * Capture additional notes if something requires follow-up. * Capture informant signature. \ *** # UINs ### 1. Introduction In OpenCRVS, **UINs (Unique Identification Numbers)** are identifiers that make it possible to: * Track a declaration during the registration process. (Tracking ID) * Uniquely identify a registered event record. (Registration no) * Optionally link a person in OpenCRVS to an external National ID system eg MOSIP. (National ID) OpenCRVS supports multiple identifiers, each with a clear purpose and lifecycle. *** ### 2. Core identifiers managed by OpenCRVS #### 2.1 Tracking ID A **Tracking ID** is generated when a declaration is submitted. * Used to follow the progress of a declaration (for example, from Notify β†’ Declare β†’ Validate β†’ Register). * Can be shared with the informant in SMS or email notifications. * Can be printed on receipts or acknowledgement slips. * Does not change if the declaration is updated before registration. #### 2.2 Registration number A **Registration number** is generated when a declaration is successfully registered. * Uniquely identifies the **registered event record**. * Can appear on certificates and certified copies. * Can be used in searches, verifications, and integrations with other systems (for example, statistics, health, ID systems). * Remains stable even if corrections are applied to the record (subject to country policy). Both identifiers can be formatted to match country standards (for example, include year, office code, serial number). *** ### 3. Integration with National ID systems OpenCRVS can integrate with an external **National ID system** such as MOSIP. #### 3.1 Creating a National ID on registration For eligible events (typically **births**), OpenCRVS can: * Send key data from the registered record to the National ID system. * Request creation of a **National ID** for the person. * Store the returned National ID on the record for future use (for example, verification, updates). Eligibility rules (for example, β€œat least one parent must be a citizen”) are configured as **business rules** and can differ by country. #### 3.2 Revoking or updating National ID on death For **death registrations**, OpenCRVS can: * Notify the National ID system that a person has died. * Request deactivation or status update of the National ID, depending on integration design. This helps keep identity systems and civil registration aligned and reduces identity fraud. *** ### 4. Configuration overview Key configuration points for UINs include: * **Formats** * How Tracking IDs and Registration numbers are structured (for example, office code + year + sequence). * Which parts are human-readable vs system-generated. * **When generated** * Tracking ID: on declaration submission. * Registration number: on successful registration. * National ID: on registration of eligible events, if integrated. * **Where displayed** * In the UI (search results, record views, review screens). * On certificates, certified copies, and receipts. * In notifications sent to informants. By clearly defining and configuring UINs, countries can ensure that every record is traceable, every certificate can be verified, and integrations with other national systems remain consistent. # Records ### Overview The **Records** section focuses on the lifecycle and structure of individual event records in OpenCRVS. It is organised into the following pages: * **Record data** β€” describes the underlying data model for a record, including form data vs action metadata, and how Notify/Declare, Edit, and Correct all operate on the same event form. * **Statuses** β€” explains the record status model (for example, Draft, Notified, Declared, Registered, Corrected), including which actions move a record between statuses and how status is used in workqueues and search. * **Flags** β€” covers flags as additional workflow markers (for example, pending-attestation, correction-requested, protected) that complement status when a new status is not needed. * **Certificates** β€” describes how registered records produce certificates and certified copies from configured templates, and how those outputs relate to the underlying record data and status. * **Verifiable Credential** β€” explains how a registered record can produce a verifiable credential (VC), how it links back to the source record, and how it can be verified. * **Protected data** β€” explains how some records or fields can be marked as protected, how this hides them from general search, and how access is controlled via protected search scopes. * **Audit** β€” describes how every action on a record is written to the audit log, including who did what, where, and when, and how this supports accountability, investigations, and quality improvement. These pages together show how OpenCRVS treats each event record as a journaled, auditable history from first notification through registration, correction, and output. # Statuses ### 1. Introduction In OpenCRVS, **record status** describes the current legal state of an event record (for example, Draft, Notified, Declared, Registered). Statuses are used to: * Express the **legal state** of a record (for example, not yet registered vs registered). * Control which **actions** are available at each stage (for example, Notify, Declare, Register, Correct). * Drive **workqueues**, approvals, and reporting. *** ### 2. Feature overview Record status provides a simple, shared language for understanding **where a record is in its lifecycle** and what can or cannot happen next. #### Core capabilities With record status, OpenCRVS supports: * A **standard lifecycle** for event records (Draft β†’ Notified β†’ Declared β†’ Registered). * Clear separation between the **legal state** of a record and finer workflow details (handled by **flags**). * **Deterministic availability** of actions based on status, so users always know what they can do next. * Consistent inputs for **workqueues, reporting, and analytics** across all event types. * Integration with **deduplication, corrections, and approvals** while keeping the core status model stable. Statuses are: * **Simple** β€” only a small number of core statuses are used. * **Reusable** β€” the same set of statuses can be applied across event types and countries. * **Configurable at the edges** β€” flags, scopes, and actions provide the flexibility for country-specific rules. *** ### 3. Core statuses The following core statuses are used by OpenCRVS to support standard registration workflows. * **Draft** * A saved declaration that has not yet been submitted. * Data can still be edited freely by the user who is preparing the declaration. * **Notified** * A declaration submitted with **incomplete** information. * Often used when a notifier (for example, health facility) captures partial data for follow-up by a Registration Agent. * **Declared** * A declaration submitted with all **required** information. * Ready for validation, duplicate review, and potential registration. * **Archived** * A notified or declared declaration that is no longer being processed. * Typical reasons include: identified as a duplicate, informant did not complete missing information within a defined timeframe, or the declaration was withdrawn. * **Registered** * The event has been formally registered according to law. * A registration number is assigned and certificates can be issued. {% hint style="info" %} Record statuses **β€œRegistered (inactive)”** or **β€œRevoked”** are not currently supported. They can ben configured as a record **flag**, so the core status remains Registered while flags express that the registration is inactive or revoked. {% endhint %} *** ### 4. Status flow Records move through statuses in a predictable order: 1. **Draft** β€” user is preparing a declaration. 2. **Notified** β€” partial information submitted. 3. **Declared** β€” complete information submitted. 1. **Archived** β€” declaration is no longer in process (for example, duplicate, abandoned). 4. **Registered** β€” declaration has been validated and registered. This flow can vary by event type and country policy (for example, some countries may not allow incomplete declarations to be submit therefore the Notified status is not required). *(Insert status flow diagram or screenshot here)* #### Core actions change a record status Core record actions (see the **Actions** page) are responsible for moving a record between statuses. * **Notify** β‡’ sets status to **Notified**. * **Declare** β‡’ sets status to **Declared**. * **Archive** β‡’ sets status to **Archived**. * **Register** β‡’ sets status to **Registered**. Custom actions **do not** change status directly. Instead, they can add or remove **flags** and capture additional metadata while the record remains in the same status. #### Available actions at each status Other core actions and custom actions can be mapped to and controlled be the record status. As an example: | Status | Actions | | ---------- | ----------------------------------------------------------------------------------------------- | | Draft | Update, Notify, Declare, Delete | | Notified | Edit, Declare, Reject, Archive | | Declared | Edit, Validate, Reject, Archive, Approve, Escalate, Register, Mark as duplicate / not duplicate | | Archived | Reinstate | | Registered | Correct, Print, Issue Verifiable Credential, Revoke | The exact set of actions will vary by country and event type, but the **status model remains the same**, providing a stable backbone for workflows. *** ### 7. Relationship between status and flags More detailed workflow nuances can be represented using **flags**. Example: * A birth declaration is submitted **late** (for example, the child is more than 1 year old at the time of declaration). * Country policy requires **senior approval** before such a declaration can be registered. This can be modelled as: * Status: **Declared** (the declaration is complete but not yet registered) * Flags: `late-registration-approval-required` Configuration can then ensure that: * Only users with the appropriate **Senior Registrar** role and scopes see a custom action **Approve** for records with `late-registration-approval-required` flags. * The **Register** action is only available once this flag has been cleared by the **Approve** action. This approach keeps the status model **simple and consistent** (Draft β†’ Notified β†’ Declared β†’ Registered), while flags and actions handle country-specific business rules and sub-states such as late registrations, special approvals, or escalation reviews. Please see the documentation of Flags for more details documentation and examples. # Flags ### 1. Introduction In OpenCRVS, **flags** are labels attached to records that describe important workflow conditions or states that do **not** require a new record status. Flags are used to: * Indicate that extra steps are needed (for example, senior approval required, pending attestation, correction requested). * Control which **actions** appear in the record action menu. * Drive **workqueues** so that the right users see the right records (for example, β€œReady to attest”, β€œPending corrections”). Flags work alongside **statuses**: * Status describes the main lifecycle stage (Draft, Notified, Declared, Registered, Archived). * Flags capture additional, often temporary, conditions within that status. *** ### 2. Feature overview Flags capture important workflow conditions **within** a status, so you can add rich business rules without changing the core status model. #### Core capabilities With flags, OpenCRVS supports: * **Fine-grained workflow states** inside a status (for example, Declared + `pending-attestation`, Registered + `correction-requested`). * **Gating of actions** based on the presence or absence of one or more flags. * **Sequencing of steps** by adding and removing flags as actions complete. * **Targeted workqueues** that surface exactly the records a team needs to see. * **Country-specific business rules** without introducing new statuses. Flags are: * **Composable** β€” multiple flags can apply to the same record. * **Temporary or long-lived** β€” some flags are cleared quickly (for example, `pending-attestation`), others may remain for audit (for example, `rejected`). * **Configuration-driven** β€” defined entirely via configuration, alongside actions, scopes, and workqueues. *** ### 3. What flags can control Flags can be used in configuration to: * **Gate actions** * Make an action available only when a specific flag is present (for example, β€œApprove late registration” only when `late-registration-approval-required` is set). * **Sequence workflow steps** * Add or remove flags as actions are completed, ensuring steps happen in the correct order (for example, pending-attestation β†’ attested β†’ validated β†’ registered). * **Drive workqueues** * Filter queues by status + flags (for example, Declared + `pending-attestation`). * **Highlight special handling** * Mark records that require extra care (for example, potential duplicate, correction requested, protected record). Flags are always configured in combination with **Actions**, **Scopes**, and **Workqueues**. *** ### 4. Example flags Common examples of flags include: * `potential-duplicate` β€” declaration has potential duplicate matches and requires review. * `pending-attestation` β€” declaration requires attestation (for example, by a health administrator) before further processing. * `attested` β€” attestation step has been completed. * `validated` β€” validation step has been completed. * `correction-requested` β€” a correction has been requested and awaits review. * `rejected` β€” declaration has been rejected * `late-registration-approval-required` β€” late registration that requires approval from a senior registrar. You can define additional flags to match country-specific business rules, as long as they are backed by clear actions and workqueues. *** ### 5. Worked example: death attestation The example below shows how flags can enforce a required **attestation** step for hospital-declared deaths. #### Business requirement: 1. If a **Hospital Officer** declares a death, a **Health Administrator** must first attest the record. 2. A **Registration Agent** may only validate the death after attestation. 3. A **Registrar** may only register the death after it has been attested and validated. #### Flags used * `requires-attestation` β€” set when a Hospital Official declares a death. * `attested` β€” set when the Health Administrator attests the record. * `validated` β€” set when the Registration Agent validates the record. #### Resulting workflow 1. **Declare** (Hospital Officer) * Status: Declared * Flags: add `requires-attestation` 2. **Attest** (Health Administrator) * Allowed only when `requires-attestation` is present. * Flags: remove `pending-attestation`, add `attested` 3. **Validate** (Registration Agent) * Allowed only when `attested` is present. * Flags: add `validated` 4. **Register** (Registrar) * Allowed only when `attested` and any other required conditions (for example, `validated`) are met. * Status: Registered Workqueues can then be configured, for example: * **Pending attestation** β€” Status: Declared, Flags: `requires-attestation`, Declared at: my-administrative-area. * **Pending validation** β€” Status: Declared, Flags: `attested` (optional), Declared at: my-administrative-area. *** ### 6. Worked example: late birth registration Another example is **late birth registration**. #### Business requirement 1. If a birth is declared when the child is more than 1 year old, a **Senior Registrar** must approve the registration. 2. A Registrar cannot register the birth until that approval has been given. #### Flags used * `late-registration-approval-required` β€” set automatically when the age-at-declaration > configured threshold (for example, > 1 year). #### Resulting workflow 1. **Declare** (Registration Agent) * Status: Declared * Flags: add `late-registration-approval-required`. 2. **Approve late registration** (Senior Registrar) * Action visible only to users with the Senior Registrar role and appropriate scopes. * Flags: remove `late-registration-approval-required`. 3. **Register** (Registrar) * Action only available when the `late-registration-approval-required` flag is no longer present. * Status: Registered. This ensures that late registrations are always reviewed by a senior official before registration. *** ### 7. Summary To implement flags effectively, you configure: * **Actions** * Which flags they require to be present (or absent) to be available. * Which flags they add or remove when completed. * **Scopes and roles** * Which user roles can perform which actions (for example, only Health Administrators can β€œAttest”). * **Workqueues** * Which combinations of status + flags should be shown to which roles. This combination allows you to express complex country-specific workflows while keeping the core status model simple and stable. Please review documentation pages for Users, Actions and Workqueues for worked examples on how flags are configured. # Data ### 1. Introduction In OpenCRVS, **record data** is the structured information captured for a civil registration event (for example, a birth, death, or marriage). This data is: * First captured when a user **notifies** or **declares** an event. * Updated or completed (for notifications) using the **Edit** action while the record is still in progress. * Corrected later using the **Correct** action after the record has been **Registered**. The same underlying data structure is used throughout the lifecycle. Actions (Notify/Declare, Edit, Correct) determine **when** and **how** users are allowed to change the data, but they all work with the same event record. It is useful to distinguish between: * **Form data** β€” information entered in the event form itself (for example, child’s details, parents’ details, event dates and places). * **Action metadata** β€” additional data captured when an action is completed (for example, date and place of registration captured on the **Register** action, or data captured as part of a custom action). Form data describes the event itself. Action metadata describes **what happened to the record, when, where, and by whom** as it moves through the workflow. *** ### 2. Feature overview Record data provides a **single, consistent view** of the information about an event across its entire lifecycle, from first notification through to registration and any later corrections. #### Core capabilities With record data, OpenCRVS supports: * A **single event record** that is reused across Notify/Declare, Edit, and Correct actions. * Clear separation between **form data** (the facts of the event) and **action metadata** (what happened to the record, when, where, and by whom). * Safe **in-progress editing** before registration using the Edit action, with full audit history. * Controlled **post-registration corrections** using the Correct action, preserving original values for legal and audit purposes. * Consistent data for **certificates, verifiable credentials, search, reporting, and interoperability**. *** ### 3. Capturing data with a single form (Notify or Declare) The first time data is entered for an event is through a **single event form**. At the end of this form, the user chooses whether to **Notify** or **Declare**, depending on whether all mandatory fields have been completed. * **Single event form** * Configured per event type (for example, birth, death, marriage). * Contains all fields that may be required for registration. * Enforces mandatory fields for registration according to national law and policy. At the end of the form: * If **not all mandatory fields** for declaration are completed, the user can save the record as a **Notification (Notify)**. This creates a record in a **Draft** or **Notified** status that can later be completed using **Edit**. * If **all mandatory fields** for declaration are completed, the user can proceed to **Declare** the event. This creates a declared record that can move through subsequent steps (for example, review, approval, registration) using other actions. This approach ensures that data is captured once, while still supporting both partial notifications and full declarations, depending on how complete the information is at the time of capture. Both Notify and Declare use the **same form** configured per event type. The form definition specifies: * Which fields are displayed. * Which fields are mandatory or optional. * Validation rules and allowed values. *** ### 4. Editing record data with the Edit action After a record has been created (via Notify or Declare) and before it is fully **Registered**, authorised users can change the data using the **Edit** action. Typical use cases for **Edit** include: * Completing missing fields that were not captured at notification. * Correcting obvious data entry mistakes identified during review. * Updating information following additional verification (for example, clarifying spellings of names or updating contact details). When a user selects **Edit**: 1. The system opens the event form with the current record data pre-filled. 2. The user can adjust any fields. 3. On completion, the user is presented with two options depending on their scopes: * **Declare with edits** (requires `record.declare` scope) β€” saves the changes and keeps the record in Declared status. The change is logged. Available to any user with the `record.edit` + `record.declare` scopes. * **Register with edits** (requires `record.register` scope) β€” saves the changes *and* registers the record in a single step, transitioning the record from Declared to Registered. Available only to users who also hold the `record.register` scope (typically a Registrar). This option allows a Registrar to review, edit, and register in one flow All edits are stored in the system’s journaled data model, and appear in audit views showing **who** changed **what** and **when**. *** ### 5. Correcting data after registration with the Correct action Once a record has reached the **Registered** status, the original data becomes the official record for that event. Further changes must follow a **correction** process rather than ordinary editing. The **Correct** action is used for post-registration changes, for example: * Fixing a spelling error in a name on a registered record. * Updating a date or place when an error is discovered after registration. * Correcting mis-recorded relationships or other key details, following an approved correction procedure. When a user selects **Correct** on a registered record: 1. OpenCRVS presents the **same event form** that is used for Notify/Declare, pre-filled with the current registered data. 2. The user completes an upfront from about the corrections. (eg. reason for correction, requester) 3. The user proposes changes to specific fields, according to configured rules and any required supporting documentation. 4. Depending on configuration, the correction may require review or approval before it is applied. 5. Once approved, the system updates the record, maintaining a clear history of the old and new values. The journaled data model ensures that: * The original registered values remain visible for audit purposes. * The corrected values are applied for future outputs (for example, certificates, search results, and statistics) *** ### 6. Form data vs action metadata In configuration, it is important to decide whether a piece of information should be treated as **form data** or **action metadata**. * **Form data** * Captured in the single event form used for Notify/Declare (and re-used for Edit and Correct). * Represents the content of the civil event record itself (for example, date of birth, place of birth, parents’ identities, cause of death). * Can be viewed and, when allowed, edited or corrected through the relevant actions. * **Action metadata** * Captured at the moment an action is completed, not as part of the main event form. * Includes a standard, non-configurable set of fields for **action timestamp**, **user**, and **assigned user location**. These are always recorded for every action. * Additional metadata can be captured as part of specific actions. Examples include: * Details captured as part of a custom action (for example, supervisor approval details, reason for cancellation, or notes recorded when marking a record as protected). * Describes the **workflow history** of the record (what actions were taken, when, where, and by whom), rather than the underlying event facts. * For offline working, the **action timestamp** records the date and time when the user triggered the action on their device, not when it later reaches the backend server. This ensures that the timeline reflects when actions actually occurred, even if the user was offline for an extended period. Configuration guidelines: * Use **form data** for information that legally forms part of the civil event record and may need to be corrected via the **Correct** action. * Use **action metadata** for operational or procedural details that are tied to specific actions (such as Register, Approve, Mark protected, Issue certificate) and should be stored alongside the record’s action history. By separating form data from action metadata in this way, OpenCRVS keeps the core event record clear, while still providing a rich, auditable history of how and when the record was processed. *** ### 7. Relationship between Notify/Declare, Edit, and Correct The three actions work together over the life of a record: * **Notify / Declare** β€” create the event record and capture the initial data. * **Edit** β€” update or complete data **before** registration, while the record is still in progress. * **Correct** β€” change data **after** registration, following the configured correction workflow. By using these actions consistently, OpenCRVS ensures that event data is captured once, updated responsibly, and corrected transparently, with a full history of changes maintained for legal, operational, and statistical purposes. # Certificates ### 1. Introduction In OpenCRVS, **certificates and certified copies** are printable documents generated from registered event records. They are produced from configured templates and populated automatically with data from the record. OpenCRVS can generate pdf: * **Certificates / full copies** β€” documents containing all key registration data for an event. * **Certified copies** β€” copies of a certificate or registration entry that carry the same legal value. * **Extracts** β€” shorter summaries containing only a subset of data (for example, name, date of birth, place of birth). Certificates and certified copies: * Are always generated **from registered records** (status: Registered). * Can include any record data (eg. childs name) and record metadata (eg. date of registration) * Can include the record’s **registration number** and other UINs as key identifiers. * Can be controlled by **business rules** (for example, only certain roles can print, or only within certain timeframes). By configuring certificate templates, print actions, and related business rules, countries can issue legally compliant certificates, certified copies, and extracts directly from OpenCRVS. *** ### 2. Feature overview Certificates and certified copies provide a **standard, printable representation** of a registered record that can be issued, reissued, and verified consistently. **Core capabilities** With certificates and certified copies, OpenCRVS supports: * Generation of **legally compliant documents** directly from registered records. * Multiple **template types** per event (for example, full certificate, certified copy, extract). * **Automated population** of templates from record data and metadata (including UINs and registration details). * Configurable **business rules** that govern when, how often, and by whom documents can be issued. * Support for **multi-page layouts**, security features, and digital signatures. * Full **auditability** of print events via the Print action and journaled data model. Certificates and certified copies are: * **Data-driven** β€” they always reflect the underlying registered record. * **Template-based** β€” layout and content are defined via configurable SVG templates. * **Workflow-aware** β€” issuing is an action that can be controlled by scopes, flags, and status. *** ### 3. Certificate templates A **certificate template** defines the design and content of a printable document. #### **3.1 Types of templates** Examples include: * **Certificate** β€” a partial set of registration data, typically used for first issuance. * **Certified copy** β€” a full copy of the registration entry, used for reissuance. * **Extract** β€” simplified version containing a subset of fields. Countries can configure multiple templates per event type (for example, separate birth, death, and marriage certificates). #### **3.2 Template properties** Each template typically includes: * **Design** * Page size and orientation (for example, A4, A5). * Layout, fonts, colours, and images. * Placement of data fields (for example, name, date of event, registration number). * **Business rules** * When the template can be issued (for example, only after registration). * Whether it can be issued once or multiple times. * Whether it must be issued before other template types (for example, first issuance before extracts). * **Fees (optional)** * Fee schedules based on timing or type (for example, within legal time, delayed, late). Templates are implemented as SVG designs populated with record data and exported as PDFs. {% hint style="info" %} See our guide on how to design and configure a certificate [Guide: Certificate configuration](/implementation/your-opencrvs-project/gathering-requirements/design-and-specification/guides/guide-certificate-configuration) {% endhint %} *** ### 4. Printing and issuing certificates Certificates and certified copies are generated via the **Print** action. #### **4.1 Print action** The Print action typically includes a form that allows the user to: * Select which **template** to use (for example, full certificate, extract, certified copy). * Capture **requester details** and verify their identity. * Record **fees** collected and generate a receipt if required. #### **4.2 Preview and export** Before finalising, OpenCRVS can: * Display a **preview** of the generated certificate or extract. * Allow the user to confirm that all details are correct. * Export the final document as a **PDF** ready for printing. This ensures that printed documents match the registered data and adhere to the configured template design. *** \ \ \ \ \ This document covers printable documents in OpenCRVS β€” what they are, how they work end-to-end, and how to configure them. *** ### What Are Certificates? Certificates are printable PDF documents generated from event records. They are produced from SVG templates that are automatically populated with record data at print time. Core provides the rendering pipeline, the `PRINT_CERTIFICATE` action type, and the data available to templates. Everything else β€” which templates exist, when they are shown, what form is shown during printing, and what flags are set β€” is configured in countryconfig. Certificates are: * **Data-driven** β€” content is drawn from the live record, not typed manually. * **Template-based** β€” layout and design are controlled by SVG files defined in countryconfig. * **Auditable** β€” every print is recorded as a `PRINT_CERTIFICATE` action on the event, with who printed, when, where, and which template was used. * **Workflow-aware** β€” when and by whom documents can be printed is controlled via action conditionals and flags, all defined in countryconfig. *** ### Document Types From core's perspective, there is only one concept: a **template**. Core does not distinguish between a "certificate", "certified copy", or any other document type β€” those are naming conventions. Any number of templates can be registered per event. Each template is an SVG file with its own label, fee schedule, and display conditions. The Farajaland countryconfig registers these templates for birth as an example of how templates can be structured: | Template ID | Label | When shown | | ----------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- | | `birth-certificate` | Birth Certificate | Only before any certificate has been printed (`not(event.hasAction(PRINT_CERTIFICATE))`) | | `birth-certified-certificate` | Birth Certificate certified copy | Only after the original has been printed at least once | This sequencing β€” first issuance followed by re-issuance β€” is a countryconfig convention, not a core rule. You can register as many or as few templates as your country needs, with any conditions. *** ### End-to-End Flow ``` 1. User opens a record ↓ 2. The PRINT_CERTIFICATE action is available (controlled by conditionals in the event config) ↓ 3. User triggers Print β†’ the print form opens (defined in printForm of the action config) ↓ 4. User completes the print form (what pages appear is entirely up to the countryconfig) ↓ 5. Certificate preview is displayed ($review = true during this step) ↓ 6. User confirms β†’ PDF is generated: - SVG template fetched from countryconfig - Handlebars expressions compiled with record data ($declaration, $metadata, etc.) - SVG converted to PDF via pdfmake ↓ 7. PDF downloaded or sent to printer ↓ 8. A PRINT_CERTIFICATE action is written to the event record, capturing: - User, role, office - Template ID used - Timestamp - Registrar's signature (if captured during registration) - Annotation values from the print form ↓ 9. Flag side-effects defined in the action config are applied to the record ``` *** ### Template Configuration Templates are defined in countryconfig in the certificate handler: ``` src/api/certificates/handler.ts (Farajaland path β€” your countryconfig may vary) ``` The handler exports a `certificateConfigs` array. Core reads this endpoint to know which templates are available for each event. Each entry has this shape (`ICertificateConfigData`): ```ts { id: 'birth-certificate', // unique template ID event: Event.Birth, // which event type this belongs to label: { id: 'certificates.birth.certificate', defaultMessage: 'Birth Certificate', description: 'Label shown in the template selection UI' }, isDefault: true, // pre-selected when the print form opens fee: { onTime: 7, // fee within the legal timeframe late: 10.6, // fee in the late window delayed: 18 // fee in the delayed window }, svgUrl: '/api/countryconfig/certificates/birth-certificate.svg', fonts: { ... }, // font families for PDF rendering conditionals: [ // when this template appears in the list { type: 'SHOW', conditional: not(event.hasAction(ActionType.PRINT_CERTIFICATE)) } ] } ``` #### Key fields **`id`** β€” The template's unique identifier. Referenced in `withTemplate()` conditionals and in `ALPHA_PRINT_BUTTON` field configs. **`isDefault`** β€” If `true`, this template is pre-selected when the print form opens. **`fee`** β€” Three-tier fee amounts. What counts as "on time", "late", or "delayed" is determined by the event's registration rules, not by this config. **`svgUrl`** β€” URL path to the SVG template file served by countryconfig. **`fonts`** β€” Font families to embed in the PDF. Each font family is an object with `normal`, `bold`, `italics`, `bolditalics` keys pointing to font file URLs. **`conditionals`** β€” Controls when this template appears in the selection list. Uses the same condition API as the rest of the event config. If omitted, the template always appears. #### Conditional examples ```ts // Show only before any certificate has been printed conditionals: [ { type: 'SHOW', conditional: not(event.hasAction(ActionType.PRINT_CERTIFICATE)) } ] // Show only after a specific template has been printed at least once conditionals: [ { type: 'SHOW', conditional: event .hasAction(ActionType.PRINT_CERTIFICATE) .withTemplate('birth-certificate') .minCount(1) } ] // Never show in the print flow (used for templates triggered only by ALPHA_PRINT_BUTTON) conditionals: [ { type: 'SHOW', conditional: never() } ] ``` *** ### Template Files (SVG) The SVG template files can live anywhere in countryconfig as long as the `svgUrl` in the config points to the correct URL. In Farajaland, they are placed in: ``` src/api/certificates/source/ ``` and the certificate handler serves them at `/api/countryconfig/certificates/` like this: ```ts if (request.params.id) { const filePath = `${__dirname}/source/${request.params.id}` return h.file(filePath) } ``` Templates are Handlebars SVG files β€” standard SVG syntax with `{{` expressions `}}` for dynamic content. See Template Design for details. *** ### Configuring the Print Action `PRINT_CERTIFICATE` is a built-in action type. It is configured in the event's `actions` array: ```ts { type: ActionType.PRINT_CERTIFICATE, label: { defaultMessage: 'Print', id: 'event.birth.action.collect-certificate.label', description: '...' }, printForm: BIRTH_CERTIFICATE_COLLECTOR_FORM, // form shown during printing conditionals: [...], // when the action is available flags: [...] // side-effects after printing } ``` #### `printForm` The form shown to the user before the PDF is generated. Defined with `defineActionForm()`. The structure, pages, and fields are entirely up to the countryconfig. Core renders whatever pages are defined there. #### `conditionals` Controls when the Print action appears and whether it is enabled. Uses `ConditionalType.SHOW` and `ConditionalType.ENABLE`: ```ts // Hide the action when a flag is set { type: ConditionalType.SHOW, conditional: not(flag('some-flag')) } // Disable without hiding { type: ConditionalType.ENABLE, conditional: status('REGISTERED') } ``` #### `flags` Side-effects applied to the record when the print action completes. Flags are set or removed conditionally: ```ts flags: [ { id: 'my-custom-flag', operation: 'add', conditional: field('collector.requesterId').isEqualTo('SOME_VALUE') }, { id: 'another-flag', operation: 'remove' } ] ``` Flag IDs are defined entirely in countryconfig β€” core has no built-in certificate-specific flags. *** ### The Print Form The print form is defined using `defineActionForm()` and can have any number of pages. Core supports these page types that are particularly useful in print flows: * **`PageTypes.enum.FORM`** β€” a standard data-entry form page * **`PageTypes.enum.VERIFICATION`** β€” a page that shows record data alongside controls for the user to confirm or deny identity The Farajaland countryconfig implements the print form as three pages as an example of one way to structure this: **Page 1 β€” Collector selection:** A `FORM` page with a select field asking who is collecting the certificate. Farajaland uses values like `INFORMANT`, `OTHER`, and `PRINT_IN_ADVANCE`, with additional fields appearing conditionally based on the selection. **Page 2 β€” Identity verification:** A `VERIFICATION` page (shown conditionally based on the selection in page 1) that renders key record fields from `$declaration` alongside a confirm/deny action. This lets the registrar cross-reference the collector against the record without leaving the flow. ```ts { id: 'collector.identity.verify', type: PageTypes.enum.VERIFICATION, conditional: field('collector.requesterId').isEqualTo('INFORMANT'), fields: [ { id: 'collector.identity.verify.data', type: FieldType.DATA, configuration: { data: [{ fieldId: 'applicant.name' }, { fieldId: 'applicant.dob' }] } } ], actions: { verify: { label: 'Verified' }, cancel: { label: 'Identity does not match', confirmation: { title: 'Print without proof of ID?', body: '...' } } } } ``` **Page 3 β€” Payment:** A `FORM` page using `FieldType.DATA` to display the fee and service. The values can be hardcoded or derived conditionally. Your print form does not need to follow this structure. It can have more or fewer pages, different fields, or no collector step at all. #### Accessing print form values in the template All annotation fields captured in the print form are accessible in the SVG template: ```handlebars {{$lookup ($action "PRINT_CERTIFICATE") "annotation.collector.requesterId"}} {{$lookup ($action "PRINT_CERTIFICATE") "annotation.collector.OTHER.firstName"}} ``` *** ### Business Rules and Flags Flags are boolean markers on a record that any action can set or remove. They are defined entirely in countryconfig β€” core provides the flag mechanism but has no certificate-specific built-in flags. #### Controlling access with conditionals ```ts // Show the Print action only when the record is registered { type: ConditionalType.SHOW, conditional: status('REGISTERED') } // Disable when a flag is set { type: ConditionalType.ENABLE, conditional: not(flag('some-blocking-flag')) } ``` #### Sequencing templates To enforce that one template must be printed before another appears, use `withTemplate().minCount()` in the template config: ```ts conditionals: [ { type: 'SHOW', conditional: event .hasAction(ActionType.PRINT_CERTIFICATE) .withTemplate('birth-certificate') .minCount(1) } ] ``` This is how the Farajaland countryconfig ensures the certified copy only becomes available after the original certificate has been printed. #### Tracking print count Core automatically tracks how many times a given template has been printed in `$metadata.copiesPrintedForTemplate`. Use it in your template to mark re-prints: ```handlebars {{#ifCond ($lookup $metadata "copiesPrintedForTemplate") ">" "0"}} DUPLICATE {{/ifCond}} ``` *** ### Template Design Certificate templates are **SVG files with Handlebars expressions**. The SVG defines the visual layout; Handlebars expressions pull in record data at print time. This is implemented in core (`compileSvg` in `pdfUtils.ts`). #### How rendering works 1. The SVG file is fetched from the `svgUrl` in the template config. 2. Handlebars compiles the SVG string, resolving all `{{...}}` expressions against the record's data. 3. The compiled SVG is converted to a PDF via pdfmake. 4. The PDF is downloaded or sent to the printer. #### What data is available Four top-level variables are available in every template β€” these are provided by core: | Variable | Contains | | -------------- | ------------------------------------------------------------------------------------ | | `$declaration` | All form field values from the declaration, pre-resolved into human-readable strings | | `$metadata` | Event lifecycle data β€” registration number, dates, users, offices, legal statuses | | `$review` | `true` when previewing before print, `false` when actually printing | | `$references` | Raw location and user maps (rarely used directly) | #### Reading values Use `$lookup` to navigate into any variable: ```handlebars {{$lookup $declaration "child.name.fullname"}} {{$lookup $metadata "legalStatuses.REGISTERED.registrationNumber"}} {{$lookup $metadata "legalStatuses.REGISTERED.createdBy.name"}} {{$lookup ($action "PRINT_CERTIFICATE") "createdAt"}} ``` #### Built-in helpers These are all registered by core in `pdfUtils.ts`: | Helper | Purpose | | ----------------------------------------- | --------------------------------------------- | | `$lookup obj "path"` | Navigate into any data object by dot-path | | `$intl "key.part1" dynamicValue` | Translate an i18n key built from joined parts | | `$intlWithParams "id" "paramName" value` | Translate with interpolated values | | `$join ", " val1 val2 val3` | Join values, filtering out empty ones | | `$or val1 val2` | First truthy value | | `{{#ifCond v1 "===" v2}} ... {{/ifCond}}` | Conditional blocks with comparison operators | | `$action "TYPE"` | Most recent action of a given type | | `$actions "TYPE"` | All actions of a given type as an array | | `$json value` | JSON string representation (debug only) | #### Registrar signature The registrar's signature is stored on the `REGISTER` action and accessible via: ```handlebars ``` #### Review mode `$review` is `true` during the preview step and `false` when actually printing. Use it to show draft watermarks or hide print-only elements: ```handlebars {{#if $review}} DRAFT {{/if}} ``` #### Multi-page templates Core supports multi-page certificates via the `data-page` attribute on SVG groups. See certificate-multipage.md for the full guide. #### Custom helpers Countryconfig can define additional Handlebars helpers in: ``` src/certificate/handlebars/helpers.ts (Farajaland path β€” your countryconfig may vary) ``` Core compiles this file to JavaScript, serves it at `/handlebars.js`, and loads it before rendering any template. See certificate-custom-helpers.md for the full guide. *** ### Further Reading | Topic | Document | | ---------------------------------------------------------------- | ------------------------------------------------------------------------ | | All template variables and built-in helpers (detailed reference) | [certificate-builtin-helpers.md](https://certificate-builtin-helpers.md) | | Writing custom Handlebars helpers | [certificate-custom-helpers.md](https://certificate-custom-helpers.md) | | Multi-page certificate templates | [certificate-multipage.md](https://certificate-multipage.md) | # Verifiable Credentials ### 1. Introduction A verifiable credential (VC) is a digital credential that asserts claims about a civil registration event β€” currently a **birth** β€” and can be cryptographically verified by a third party without contacting OpenCRVS. In OpenCRVS, a VC: * Is derived from a **registered** event record. * Is digitally signed on behalf of the issuing authority, so that any tampering can be detected. * Can be designed to reveal only the minimum data needed for a given use case (selective disclosure), where the chosen credential format supports it. **OpenCRVS issues verifiable credentials. It does not hold or verify them.** Once a credential has been issued, the holder (the requester and their wallet or app) controls how and where it is presented, and relying parties verify it against the issuer's published keys. OpenCRVS is not in the loop at presentation or verification time. Verifiable credentials **complement** paper certificates rather than replacing them. They provide a reusable, digital way to prove that a vital event has been registered, usable across multiple services. #### What the reference implementation supports The reference implementation supports issuance of birth credentials, from a registered birth record, in two forms: * **Digital credential** β€” a credential offer the requester consumes into their own wallet or VC app, for example by scanning a QR code or opening a link. This form can support selective disclosure (sharing only selected attributes). * **Paper credential** β€” a signed credential rendered onto a printed or PDF document the requester can carry, and verify offline. Both forms are issued on demand by an authorised user, in the same way they would issue a certified copy, and both derive their data from the same authoritative registered record. *** ### 2. Feature overview Verifiable credentials give a country a portable, digital proof of registration that can be reused across many services and channels, without sharing the full underlying record. The feature lets you: * Issue a **digital** proof of a registered birth that the requester loads into their own wallet or VC app. * Issue a **paper** proof of a registered birth, signed and renderable onto a document. * Guarantee authenticity through digital signatures tied to an issuer you operate. * Share only selected attributes, where the credential form supports selective disclosure (the digital form does; the paper form carries a fixed set of attributes). * Support reuse across multiple relying parties β€” schools, health facilities, social protection programmes β€” each verifying independently. * Record issuance in the audit trail, alongside certificates and other record actions. Verifiable credentials are: * **Digital-by-design** β€” intended for wallets, apps, and online services (with the paper form bridging to offline use). * **Complementary to certificates** β€” they do not replace paper, but offer a more convenient, machine-verifiable option. * **Policy-driven** β€” your configuration decides which data is exposed, who may issue, and (for the wider vision) how status is handled. *** ### 3. What a birth verifiable credential contains A credential issued from OpenCRVS encodes a small, deliberately minimal set of claims drawn from the registered record. In the reference implementation a birth credential carries the **registration number**, the child's **given and family names**, and the **date of birth**. The credential also carries issuer and lifecycle information: * **Subject identifier.** The subject is identified by an identifier that is consistent for a given record but **pseudonymous** β€” it does not expose OpenCRVS's internal database identifiers. * **Credential identifier.** Each issuance gets its own unique identifier, so re-prints and re-issues are independently traceable in the audit trail. * **Expiry.** A credential expires **365 days** after issuance by default. This window is configurable. * **Issuer.** The credential is signed by the issuer **you** operate (see Β§7). > **Adapt the claim set to your context.** The fields above match the reference birth schema. Adjust them to match your own event declaration schema, your national legal requirements, and your data-minimisation policy before going to production. *** ### 4. When a verifiable credential is issued Verifiable credentials are issued only for **registered** records. #### On demand after registration An authorised user opens a registered birth record and chooses to issue a credential, much as they would issue a certified copy. They can issue the digital form, the paper form, or both. This is the only trigger in the reference implementation. #### Planned triggers The following are part of the feature vision but are **not** in the reference implementation: * *Planned β€”* **On registration.** When a record first reaches *Registered* status, a credential could be issued automatically (for example, emailed to the informant). * *Planned β€”* **As part of a service flow.** For example, when a parent applies for a digital benefit, the system could request or verify a child's birth credential as part of that flow. *** ### 5. Issuance and verification #### 5.1 Issuance β€” the registration-office view From the perspective of registration staff, issuing a credential is similar to printing a certificate: 1. An authorised user opens a **Registered** birth record. 2. They select the credential action β€” the **digital** VC action or the **paper** VC action. 3. A configured **template** determines which fields are included and how the credential is structured. 4. OpenCRVS derives the credential from the record and signs it through the issuer you operate: * The **digital** form produces a credential **offer** the requester consumes β€” for example, a QR code scanned into a wallet, or a link. * The **paper** form produces a signed credential that can be rendered onto a printed or PDF document. 5. The issuance is written to the **audit trail**, just like certificates and other actions. Once a digital credential has been issued for a record, the record is marked accordingly (see Β§6), which prevents the digital credential action from being offered again for the same record. #### 5.2 Verification β€” the relying-party view Relying parties (schools, health facilities, social protection agencies) verify a credential without contacting OpenCRVS, by: * Scanning a QR code on a printed or digital document, or * Loading the credential into a wallet or web-based verifier. The verifier checks that: * The credential's **signature** is valid. * It was issued by a **trusted issuer** β€” one whose keys the verifier recognises, published by you. * The credential has **not expired**. This lets a service trust the registration without calling OpenCRVS for every check or storing a full copy of the civil registration record. > **Status and revocation are not provided out of the box.** The reference implementation enforces **expiry**, but does **not** include a revocation or status-list mechanism. If your policy requires the ability to invalidate a credential before it expires β€” for example after a correction or revocation of the underlying registration β€” that status infrastructure is part of the issuer environment **you** design and operate. Treat revocation as *Configurable / implementer-provided*, not as a built-in feature. *** ### 6. What you can configure The feature is policy-driven: configuration decides who can issue credentials, what they contain, and where they are signed. The points below describe *what* is configurable and why it matters; the [technical guide](https://documentation.opencrvs.org/v2.0/technical/guides/configuration/integrations/verifiable-credentials) covers exactly how to set each one. * **Who can issue.** Issuing the digital credential is a permissioned action, so you decide which roles can see and submit it, and for which events. In the reference implementation that is limited to birth. * **Issue-once behaviour.** A record is marked once a digital credential has been issued, which stops the action being offered again and prevents accidental duplicate issuance. Deliberate re-issues are still possible and remain individually traceable in the audit trail, because each issuance mints a fresh credential identifier. * **What the credential contains.** The claim set, the subject identifier, and the 365-day expiry are all defined in editable templates β€” one for the digital (selective-disclosure) form and one for the paper form. This is where you align the credential with your event schema, legal requirements, and data-minimisation policy. * **Where signing happens.** OpenCRVS calls out to an issuer **you operate** to sign each credential. You point it at your own signing endpoints via configuration. > **OpenCRVS does not provide, host, or manage credential issuers.** Key generation, certificate management, DID-document hosting, status/revocation infrastructure, and the overall security of the issuer are the implementer's responsibility. The demo issuer referenced in the technical guide exists only for local development and must not be used in production. *** ### 7. Relationship to certificates and identifiers Verifiable credentials sit **alongside** existing OpenCRVS outputs and identifiers rather than replacing them: * **Certificates / certified copies** remain the paper or PDF representation endorsed by the registration authority, and remain important for many legal and operational processes. * **Identifiers** β€” the tracking ID, registration number, and (where integrated) national ID β€” identify the record and, where appropriate, the person. The reference birth credential carries the **registration number** as its core identifier, which lets a credential be cross-checked against both the paper certificate and the underlying digital record in OpenCRVS. A credential **may** also carry a national ID where policy permits, to link the digital proof back to a person β€” but this is a policy decision for the implementer, governed by data-protection law. *** ### 8. Example use cases Representative uses for birth credentials issued from OpenCRVS: * **Proving birth for school enrolment.** A parent presents a birth credential to a school, which verifies authenticity without needing the paper certificate. * **Accessing health and nutrition services.** A health provider verifies a child's birth and age to determine eligibility. * **Social protection enrolment.** An agency verifies a registered birth digitally to establish or update benefit eligibility. * **Cross-border services.** With appropriate agreements, a credential could help prove an event to another country's systems, reducing manual document exchange. *** ### 9. Setting it up The functional behaviour described here is delivered through country configuration. The step-by-step setup β€” roles and scopes, the issue-once flag, the credential templates, the issuer environment variables, and the Farajaland reference files to start from β€” is documented in the technical guide: [Verifiable credentials integration β†’](https://documentation.opencrvs.org/v2.0/technical/guides/configuration/integrations/verifiable-credentials) # Audit ### 1. Introduction OpenCRVS maintains a detailed **audit log** of all important actions taken on: * **Records** (for example, declarations, registrations, corrections, certificate issuance). * **User accounts** (for example, login, password changes, user management). Every change to a record, and every key event on a user account, is written as a time-stamped audit entry. Taken together, these entries form a **complete, chronological history** of how records are processed and how user accounts are used across the system. Audit information is used to: * Provide **accountability** for service providers (who did what, where, and when). * Support **investigations** of suspected fraud or misuse (for example, unusual corrections or registrations). * Demonstrate **compliance** with laws and policies during audits or reviews. * Inform **management and quality improvement**, by highlighting patterns such as high rejection rates or repeated corrections. *** ### 2. Feature overview Audit provides a **complete, time-ordered history** of key actions across records and user accounts, so that countries can see who did what, where, and when. #### Core capabilities With audit, OpenCRVS supports: * **End-to-end traceability** of record workflows, from initial declaration through to registration, correction, and certificate issuance. * **Standardised metadata** on every action, including timestamp, user, role, and location. * **Detailed action histories** for individual records and user accounts. * **Support for investigations, supervision, and external audits**, using a reliable, immutable log of activity. * **Accurate timelines in offline scenarios**, based on when actions were taken on the device. Audit is: * **Journal-based** β€” ~~built on the same underlying action journal as workflows and record data.~~ * **Non-editable** β€” audit entries cannot be altered once written. * **\~\~Configurable at the access layer** β€” countries can decide which roles and scopes are allowed to view audit details.\~\~ *** ### 3. Record audit The **record audit** shows the full history of actions performed on a specific event record (for example, a birth or death). Each audit entry includes a standard, non-configurable set of fields: * **Action name** β€” what was done (for example, Declared, Registered, Corrected). * **Action timestamp** β€” the date and time when the user triggered the action on their device. * **User name** β€” who performed the action. * **User role** β€” which role they held at the time (for example, Registrar, Registration Agent). * **User location** β€” the location (office) associated with the user. Additional audit details based on the action include: * **Annotations / metadata** β€” additional data captured in the action form (for example, reason for rejection, correction details). For offline working, the **action timestamp** reflects the moment the user triggered the action on their device, not the time it eventually reached the backend server. This ensures that the audit timeline accurately records when actions actually occurred, even if a user was offline for one or more days. #### Core record audit actions: * **Created** β€” a declaration was created. * **Notified** β€” an incomplete declaration was submitted. * **Declared** β€” a complete declaration was submitted. * **Updated** β€” a declaration was edited. * **Rejected** β€” a declaration was rejected and sent back for updates. * **Flagged as potential duplicate** β€” the system flagged a declaration as a potential duplicate. * **Marked as a duplicate** β€” a user confirmed the declaration is a duplicate. * **Marked not a duplicate** β€” a user confirmed the declaration is not a duplicate. * **Archived** β€” a declaration was archived * **Registered** β€” an event was registered. * **Certified** β€” a certificate or certified copy was issued. * **Correction requested** β€” a correction request was submitted. * **Correction rejected** β€” a correction request was rejected. * **Correction approved** β€” a correction request was approved and the correction finalised. * **Corrected** β€” a registered record was corrected. * **Viewed** β€” a record was viewed by a user (where tracked). * **Assigned** β€” a record was assigned to a user. * **Unassigned** β€” a record was unassigned from a user. Custom action are also recorded in audit and will use the configured copy eg. * **Validated** β€” a declaration was validated * **Attested** β€” a declaration was attested These entries provide a chronological view of how a record moved through the workflow and who was involved at each step. *** ### 4. User audit The **User Audit** provides a **complete, chronological history of activity related to an individual user account**, including both operational record actions listed above in 'Core record audit actions' the following system-level account events are recorded. #### System-level actions: * **Logged in** β€” user successfully logged in. * **Logged out** β€” user logged out. * **Username reminder requested** β€” a username reminder was triggered. * **Password changed** β€” the user changed their password. * **Profile updated ??!?** β€” the user’s account details were edited (for example name, phone, email, role, office, or device assignment) These entries provide a clear audit trail of when the user accessed the system, what administrative changes were made to their account and which event records they worked on. Together, this ensures accountability, supports investigations, and helps maintain secure system operations. *** ### 5. System admin audit For users with the scope to create and update other users. Their user audit log also records **user management** actions taken on other users. #### System admin audit actions: * **Created user** β€” a new user account was created. * **Edited user details** β€” user details (such as role, location, contact information) were updated. * **Username name reminder sent** β€” a username reminder was sent for a user * **Password reset**β€” a user password was reset * **Deactivated user** β€” a user’s access to OpenCRVS was revoked. * **Reactivated user** β€” a previously deactivated user’s access was restored. These entries provide a transparent history of how access to the system is granted, changed, or revoked. *** ### 6. Using audit information Audit information can be used in several ways: * **Case investigation** β€” supervisors can review the full action history on a record when a complaint or anomaly is reported. * **Performance and quality monitoring** β€” managers can identify patterns (for example, high rejection rates by a specific office) for follow-up and training. * **Fraud detection** β€” auditors can look for unusual activity patterns, such as repeated corrections or registrations by the same user under unusual conditions. OpenCRVS provides the underlying audit data; how it is reviewed, escalated, and acted on is defined by each country’s governance and oversight processes. # Protected data (backlog) ### 1. Introduction Some records in OpenCRVS may contain especially sensitive information, or be subject to special safeguarding rules (for example, adoption, domestic or gender-based violence cases, or court-ordered restrictions). To support stronger privacy controls in these situations, OpenCRVS allows certain records to be marked as **protected**. When a record is protected: * It is **removed from all standard search results** (quick search and advanced search) for most users. * Only users with a specific **protected-search scope** can find and open the record. This helps countries comply with data protection requirements and safeguarding policies by ensuring that highly sensitive records are only accessible to authorised roles. *** ### 2. What it means for a record to be protected A **protected record** behaves differently from ordinary records in three main ways: 1. **Hidden from search results** * The record does not appear in quick search or advanced search results for users who do not have the required protected-search scope. 2. **Restricted retrieval** * Only users with the correct `search` scope (including the `protected` qualifier) can retrieve and view the record. 3. **Audited access** * Access to protected records is logged in **User Audit** for traceability and oversight. Protected status does **not** change the underlying data of the record itself; it changes **who can find and view it** through the application. *** ### 3. Controlling access with search scopes Access to protected records is controlled through the user’s **search scope configuration**. For each event type that may include protected records (for example, birth, death, marriage), countries can define scopes of the form: * `search[event= protected]` Where `` is the event type, such as `birth`, `death`, or `marriage`. #### 3.1 Examples * A specialist role that must be able to search protected birth records: * `search[event=birth protected]` * A national-level role that can search all protected birth and death records: * `search[event=birth protected]` * `search[event=death protected]` Only users whose roles include the appropriate `protected` search scopes will see protected records in their search results and be able to open them. *** ### 4. Interaction with other search scopes and jurisdiction Protected search always **builds on top of** existing search and jurisdiction rules: * A user must still have the **underlying event search scope and jurisdiction** for the record (for example, `search[event=birth declared_in=my-administrative-area registered_in=my-administrative-area]`). * The `protected` qualifier further restricts access to only those users explicitly allowed to include protected records in their searches. In practice, a role that can search both ordinary and protected birth records in its own administrative area might combine scopes like: * `search[event=birth declared_in=my-administrative-area registered_in=my-administrative-area]` * `search[event=birth protected]` Countries can decide whether protected access should be limited to national-level users, specific supervisory roles, or specialised units (for example, a data protection officer). *** ### 5. Reasons for protecting records Countries may choose to protect records, or specific data within a record, in situations such as: * **Adoption** β€” the original birth record is hidden once a child is legally adopted. Only the new birth record (showing adoptive parents) and the associated adoption record can be found in search. Access to the original record is restricted to authorised roles. * **Domestic or gender-based violence cases** β€” records where disclosure of a parent's or informant's identity or address could put someone at risk. * **High-profile or sensitive persons** β€” records relating to specific individuals (for example, public figures or protected witnesses) where additional privacy is required. * **Court-ordered restrictions** β€” records that must be hidden or limited following a court decision (for example, sealed records). * **Special safeguarding policies** β€” any other category defined in national policy (for example, children in alternative care, humanitarian protection cases). These examples are illustrative. Each country should define its own criteria for when records or specific fields should be protected, and how long protection should apply. *** ### 6. Marking a record as protected or no longer protected Protected status is typically controlled through a **custom action** on the record, for example **Mark protected**. #### 6.1 Marking a record as protected A user with the appropriate permissions can mark a record as protected from the record view: 1. Open the event record (for example, a birth record). 2. Select the **Mark protected** custom action. 3. Confirm the action (for example, in a confirmation dialog explaining that the record will be hidden from general search). When **Mark protected** is applied: * The system automatically adds a **Protected** flag (for example, `protected`) to the record. * The record immediately behaves as a protected record: * It is removed from standard search results for users without the protected-search scope. * It remains visible only to users who have the relevant `search[event= protected]` scope and the necessary jurisdiction. * The action, including who performed it and when, is recorded in **Audit**. #### 6.2 Removing protected status When a record should no longer be treated as protected (for example, after a policy-defined period or following a supervisory decision), authorised users can reverse the protection: 1. Open the event record. 2. Select a corresponding custom action (for example, **Remove protected status**). 3. Confirm the change. When protected status is removed: * The **Protected** flag is cleared from the record. * The record returns to normal search behaviour and can be found by any user whose search scopes and jurisdiction allow access to that event. * The change is logged in **Audit**, alongside the original protection action. These actions ensure that protection of records is explicit, auditable, and reversible only by appropriately authorised users. *** ### 6. Configuration considerations When introducing protected records, countries should decide: * **Which event types** can have protected records. * **Which roles** should be allowed to search protected records (and in which jurisdictions). * How to align protected access with broader **privacy and safeguarding policies** (for example, adoption law, child protection guidelines, or data protection legislation). By carefully configuring protected records and the associated `search[event= protected]` scopes, OpenCRVS helps ensure that only appropriately authorised users can retrieve and view the most sensitive records, while keeping them hidden from general search. # Workflows ### Overview As part of the **Functional Architecture**, the **Workflows** section describes the workflow module in OpenCRVS β€” how records move through the system and how users interact with them at each step. It is organised into the following modules: * **Administrative Structure** β€” * **Users** β€” describes how user roles, scopes, and jurisdictions determine who can see which records and perform which actions in a workflow. * Jurisdictions * **Actions** β€” explains the building blocks of workflows: the actions users can take on a record (for example, Notify, Declare, Register, Correct), how actions change status and flags, and how custom actions are configured. * **Workqueues** β€” covers how records are surfaced to users as work items, using filters, assignment, and queue configuration to support day-to-day operations (review, validation, approval, certification). * **Offline working** β€” describes how users can continue workflow steps when offline, including assignment, Outbox behaviour, and how offline actions are synchronised and audited. * **Deduplication** β€” explains how OpenCRVS detects and manages potential duplicate records, and how review actions (Mark as duplicate / Mark not duplicate) fit into the overall record workflow. * **Comms** β€” describes how communications (SMS, email) are triggered from actions in the workflow, for example sending notifications to informants when a record is registered, rejected, or requires correction. These modules together show how to translate country business rules into concrete, action-driven workflows in OpenCRVS. # Administrative structure ### 1. Introduction The **administrative structure** in OpenCRVS models how a country organises its geography and registration offices. It defines the hierarchy of locations (for example, country β†’ province β†’ district) and the registration offices that operate within those locations. This structure underpins: * How addresses are captured in forms * Locations where users can be assigned * Which users can **see and act on** which records (via assigned location, scopes and jurisdictions). * Where events are **declared**, **registered**, and **certified**. * How data is **aggregated** for reporting and vital statistics. OpenCRVS does not impose a fixed hierarchy. Instead, each country defines a structure that mirrors its own administrative model and civil registration responsibilities. *** ### 2. Feature overview The administrative structure provides a configurable foundation for modelling the administrative areas and the locations where civil registration activities occur. #### Core capabilities With the administrative structure, OpenCRVS supports: * **Custom administrative hierarchies** (for example, Country β†’ State β†’ District). * **Multiple location types** (for example, β€œRegistration Office”, β€œHealth Facility”, β€œCommunity Point”). * **Offices at any administrative level** (for example State A Office, in State A) * **Jurisdiction-aware access control** through integration with scopes (for example, `placeOfEvent`, `declared_in`, `registered_in`). * **Routing of records** based on event location, declared-in location, registered-in location. * **Location-based reporting and analytics** (for example, births registered per district). The administrative structure is: * **Shared** across features such as Users, Workqueues, Actions, and Reports. * **Configurable** per deployment to reflect country specific adminstrative structures. * **\~\~Stable** over time, but able to support **historical changes** (for example, boundary changes) via configuration and data migration.\~\~ *** ### 3. Location hierarchy The location hierarchy represents the **geographic and administrative units** of a country. #### Location properties Each location typically includes: * **Name** β€” Human-readable name displayed in the UI. * **Code** β€” Unique code for … * **Type** β€” Administrative type (for example, District, CRVS Office, HealthFacility). * **Parent** β€” The location one level above in the hierarchy. * **Status** β€” Whether the location is active (usable) or retired. This hierarchy is used by: * Forms (for selecting event location and rendering address fields) * Users (for assigning office locations). * Scopes and workqueues (for filtering by β€œwithin my administrative area”). *** ### 4. Registration offices and service points Within the administrative hierarchy, different location types can be distinguished such as **registration offices** and health facilities. #### Registration offices A **registration office** is represented as a location in the hierarchy and can appear at **any level** (for example, a province-level office or district-level office). Being an β€œoffice” does **not** in itself define what can be done there. What happens at an office is determined by the **users based at that office** and their **configured roles and scopes**: * If users at an office have scopes that allow them to register events, that office effectively functions as a registration point. * If users only have scopes for notifying or declaring, the office functions as an or declaration point. In other words, **responsibilities are not configured on the office itself**. They are derived from: * The **roles** assigned to users located there, and * The **scopes and jurisdictions** attached to those roles. #### Other service points Other service points may include: * **Health facilities** (for facility notifications and declarations). * **Community points** (for outreach or mobile registration). These locations are treated like any other location type; what they can do depends on the users and scopes assigned to them. *** ### 5. Jurisdiction and access control The administrative hierarchy is tightly integrated with **Users roles and scopes** to control who can act on which records. Scopes can refer to a user’s **administrative area,** which is defined using the administrative hierarchy and the user assigned location. For example: > record.register\[event=birth|death, placeOfEvent=my-administrative-area] Interpretation: * The user may register births and deaths that **occurred anywhere within their assigned area**, where β€œmy administrative area” includes the user’s primary office location and all child locations beneath it (for example, district + all health facilities and community points in that district). This ensures that: * Local staff cannot action records outside their authorised area. * Senior and national staff sitting in offices are higher admin levels can be given broader access where needed To learn more about jurisdictions please see Users and Jurisdictions *** ### 6. Routing records between offices & users Routing in OpenCRVS is ultimately driven by how Users, Actions and Workqueues have been configured. When a record changes **status** or gets a **flag**, it appears in the relevant workqueues for users who are allowed to act on it. Think of routing as: **Status/flag changes β†’ record state matches a workqueue filter β†’ eligible users can see and act on it.** #### Typical routing patterns Below are common routing scenarios with step-by-step examples. **Facility β†’ District office** **Scenario:** A birth or death is declared at a health facility and must be validated by the district registration office. **Flow:** 1. A **Health Facility user** creates and submits a declaration for District A Health Facility 2. The record status becomes **Declared**. 3. Record appears in the Pending validation workqueue filtered by: 1. Status = Declared 2. User search scope eg. `search[event=birth|death declared_in=my-administrative-area` 4. **Registration Officer** at the **District A Registration Office** sees the record and can validate it. **Result:** * District A Registration Officer automatically receives the declaration for review. * District B Registration Officer will **not** see the record in their Pending validation workqueue *** #### **Community point β†’ District office** **Scenario:** A community worker reports an event that must be formally registered at the district level. **Flow:** 1. A **Community worker** submits a notification from a **Sub-district Community Point**. 2. The record status becomes **Notified**. 3. Record appears in the Notifications workqueue filtered by: * Status = Notified * User search scope eg. `search[event=birth|death placeOfEvent=my-administrative-area)` 4. **District A Registration Agents** see it and can help to progress the notification to a validated declaration **Result:** * District A Registration Officer automatically receives the notification * District B Registration Officer will **not** see the record in their Notification workqueue *** #### **Escalation β†’ Higher-level office** **Scenario:** A case needs senior approval (for example, a late registration). **Flow:** 1. A district user flags the record as **Late registration**. 2. The system adds a **flag** to the record. 3. Record appears in the Escalated workqueue filtered by: * Flag = Late registration * `search[event=birth|death declared_in=my-administrative-area)` 4. **State A Provincial Officer** sees it and can approve or reject the late registration **Result:** * Only State A Provincial Officer can see the escalated record * Provincial Officers in other States can not see the escalated record. Routing in practice is the combination of: * **Actions** (what action changed that record status or added/removed a flag) * **Workqueues** (which filter for specific record state) and filtered further based on a users * **Search scope and assigned location** (which specifies their jurisdiction) Together, these determine **who sees a record next and who can act on it**. *** ### 7. Worked example #### Business requirement: Super Simple Administrative Structure Farajaland has only 1 Province and 1 District with the following offices where civil registration activities occur: * Farajaland HQ office * Review escalations * Audit * Review performance * Langa Province Registration Office (Office) * Review escalations * Audit * Review performance * Ibombo District Registration Office (Office) * Registers births and deaths that occurred within Ibombo District. * Issues certificates and manages corrections. * Ibombo Health Facility (Health Facility) *** #### Configuration input | **Location** | **Type** | Location | Type | Location | Type | Location | Type | | ------------ | -------- | -------------------- | -------- | --------------------- | -------- | ----------------------------------- | --------------- | | Farajaland | Country | | | | | | | | Farajaland | Country | Farajaland HQ Office | Office | | | | | | Farajaland | Country | Langa Province | Province | Langa Province Office | Office | | | | Farajaland | Country | Langa Province | Province | Ibombo District | District | Ibombo District Registration Office | Office | | Farajaland | Country | Langa Province | Province | Ibombo District | District | Ibombo District Health Facility | Health Facility | | | | | | | | | | *** ### 8. Summary A clear administrative structure is a prerequisite for configuring **Users, Scopes, Workqueues and Actions** in a way that accurately reflects how civil registration is organised in the country. # Users ### 1. Introduction **Users** represent individual system accounts in OpenCRVS. Each user is assigned a **role**, a set of **scopes** with **jurisdiction**, and access to specific **workqueues**. Together, these define what the user can see, which actions they can perform, and which records they are responsible for. Countries can create unlimited custom user role types aligned with their organisational structure. This makes it possible to: * Restrict sensitive operations to authorised staff. * Align responsibilities with real-world job roles. * Enforce geographic and workflow-based access control. *** ### 2. Feature overview User roles in OpenCRVS are the primary way to configure **who can do what, where, and how they see their work**. #### Core capabilities With Users and Roles, OpenCRVS supports: * Unlimited custom roles (e.g. Registrar, Field Agent, Data Clerk, Health Assistant, System Administrator). * Fine-grained permissions using **scopes**. * Jurisdiction-aware access control to records based event location, declared in or registered in, etc.). * Role-based assignment of workqueues for task-focused navigation. * System-level actions for creating, editing, deactivating, and reactivating user accounts. Users are: * **Role-based** β€” capabilities are defined by the role configuration. * **Scope-driven** β€” every operation is controlled by one or more scopes. * **Jurisdiction-aware** β€” access to records is constrained by geography and organisational structure. *** ### 3. User role configuration overview A **role** is a reusable configuration that defines β€œwhat a type of user can do and see” in the system. Common examples include: * Registrar * Registration Agent * Data Clerk * Health Assistant * System Administrator Each role configuration includes:
ParameterDescription
Role nameThe label shown on the user profile, in audit history, and in admin tools.
ScopesA list of permissions that define which actions the user can perform, for which events (for example, record.register[event=birth declared_in=my-administrative-area]).
WorkqueuesThe set of queues that appear in the left-hand navigation (for example, Assigned to you, Pending registration, Pending corrections). These do not grant extra permissions by themselves, but shape how work is surfaced to the user.
When designing roles, countries should: * Start from real job functions (for example, Health Assistant, Registration Agent, Registrar, Supervisor, National Admin). * Define which **actions** each role needs, then translate them into scopes with appropriate event and jurisdiction qualifiers. * Attach only the **minimum necessary** workqueues to keep navigation focused and simple. *** ### 4. User role scopes A **scope** is a short text expression that gives a role permission to perform a specific action, for specific events, in specific jurisdictions. At a high level, a scope answers three questions: * **What** action is allowed? (for example, search, read, declare, register) * **For which events?** (for example, birth, death) * **On records from where?** (for example, declared\_in=my-administrative-area, declared\_in=any) #### 4.1 Scope format Record-related scopes follow this pattern: * `action[event=event {jurisdiction}]` Where: * `action` is the permission (for example `search`, `record.read`, `record.register`). * `event=` lists one or more event types (for example `birth`, `death`, or `birth|death`). * Jurisdiction (to learn more see Jurisdiction) is expressed via qualifiers such as: * `placeOfEvent` = based on where the event occurred * `declared_in` = based on the declaring users assigned location * `declared_by` = based on the user who declared the event * `registered_in` = based on the registering users assigned location * `registered_by` = based on the user who registered the event combined with values like `my-administrative-area`, `location`, `any`. `user` for `declared_by` and `registered_by` **Example scopes:** * `record.search[event=birth declared_in=my-administrative-area]` * Allows quick/advanced search for birth records declared in the user’s administrative area. * `record.create[event=birth|death event_location=my-administrative-area]` * Allows the user to create birth and death declarations for events that occurred in their administrative area. The declaration form will only offer places of event within that area. * `record.register[event=birth|death]` * Allows the user to register birth and death records for which they are assigned. In practice, these records will already be constrained to their jurisdiction by the create and assignment rules. #### 4.2 Core scopes and core record actions Each core scope in this table maps **directly to a core record action**. If a role does not have the scope, the corresponding action is not available in the UI, regardless of status, flags, or workqueues. The table shows the default intent; implementers still control where each scope applies via `event=`. | Scope (action) | Enables | | ------------------------- | ------------------------------------------------------------------------------------- | | `record.search` | Use quick search / advanced search to find records. | | `record.read` | Open and view record details (non‑mutating). | | `record.create` | Start a new declaration from the event form | | `record.notify` | Notify (submit an incomplete declaration). | | `record.declare` | Declare (submit a complete declaration) | | `record.edit` | Edit a notified or declared record | | `record.reject` | Reject a declared record | | `record.archive` | Archive a declared record | | `record.review-duplicate` | Review and decide on potential duplicates (Mark as duplicate / Mark not a duplicate). | | `record.register` | Register a record | | `record.print` | Print certified copies of a registered record | | `record.correct` | Correct a registered record | #### 4.3 Custom scopes Custom scopes are used for **country‑specific custom actions**. They follow the same pattern but use the `record.custom-action`verb, and each custom scope enabled the configured custom action via its `actionType` value. **Format** * `record.custom-action[event= actionType={my-custom-action}]` **Examples** * `record.custom-action[event=birth actionType=attest]` * Enables a custom **Attest** action for birth records, where `attest` matches the configured custom action type. * `record.custom-action[event=birth|death actionType=approve-late-registration]` * Enables an **Approve late registration** custom action for birth and death records. Custom scopes are paired with: * **Custom actions** (see the *Actions* page). * **Flags** that indicate special states such as `late-registration-approval-required`. * **Workqueues** that surface records needing those custom actions. Together, built‑in and custom scopes form the complete permission model for what roles can do with records in OpenCRVS. #### 4.4 Workqueue assignment Workqueues are attached to roles using a scope that references workqueue IDs. This scope controls **which queues appear in the user’s navigation**, not the underlying record permissions. Access to the records in those queues is still governed by record-related scopes and jurisdictions. **Example workqueue scope** ``` workqueue[id=assigned-to-you|recent|notification|in-external-validation|escalated|potential-duplicate|pending-updates|pending-registration|pending-approval|pending-certification|pending-issuance|correction-requested] ``` The user will have following queues in their side navigation: * Assigned to you * Recent * Notification * Pending updates * Potential duplicate * Pending registration * Pending approval * In external validation * Pending certification * Pending issuance For a full description of queue behaviour and configuration, see the **Workqueues** page. *** ### 6. Worked example From a business perspective, configuring a user role means describing **what this role is responsible for** and ensuring scopes, jurisdictions, and workqueues support that responsibility. #### Business requirement: District Registrar * The **District Registrar** is responsible for registering, correcting, and issuing certificates for birth and death records registered in their district. * They can search and read records for their district, but not for other districts. * They can review potential duplicates for declarations in their district. * Their work should be focused on queues that surface declared and registered records in their district that need action. #### Configuration Inputs | Requirement | Input | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Role name | District Registrar | | Can search for birth and death records declared and registered in their district. | `search[event=birth]` | | Can open and read birth and death records registered in their district. | `record.read[event=birth` | | Can create birth and death declarations for events that occurred in their district (the form will only allow places of event in their area). | `record.create[event=birth]` | | Can declare birth and death events (once assigned to the record). | `record.declare[event=birth]` | | Can reject birth and death declarations (once assigned to the record). | `record.reject[event=birth]` | | Can archive birth and death declarations (once assigned to the record). | `record.archive[event=birth]` | | Can register birth and death records (once assigned to the record). | `record.register[event=birth]` | | Can correct birth and death records (once assigned to the record). | `record.registered.correct[event=birth]` | | **Workqueues:** | | |

β€’ Records assigned directly to this Registrar.

  • Show declared records which have been validated in the district that are ready to be registered.

β€’ Recently registered records by their office that are ready for certificate printing.

| `workqueue[id=assigned-to-you\|recent\|notification\|in-external-validation\|escalated\|potential-duplicate\|pending-updates\|pending-registration\|pending-approval\|pending-certification\|pending-issuance\|correction-requested]` \| | *** ### 7. Core user management actions OpenCRVS also provides system-level actions for managing user accounts themselves (not records). These actions are restricted to administrators with the appropriate user scopes. #### User management actions (overview)
ScopeActionDescription
user.createCreate new userCreate a new user account, assign a role, and set initial credentials.
user.read.auditReadView a user profile page
user.updateEdit userUpdate user details such as role, location, status, or contact details.
user.updateDeactivate userDisable a user account so the user can no longer log in.
user.updateReactivate userRestore access for a previously deactivated user.
user.updateReset user passwordInitiate password recovery for a user who cannot log in.
user.updateSend username reminderSend the username to the user via configured communication channels.
*** ### 8. Summary * Users gain capabilities through **roles**, which group together scopes, jurisdictions, and workqueues. * **Scopes** are the only mechanism by which a user is allowed to perform actions on records. * **Jurisdiction** constraints ensure that access is organisationally limited. * **Workqueues** control visibility of record lists but do not bypass scope or jurisdiction rules. * All mutating actions taken by users are journaled, providing a complete audit trail. # Jurisdictions ### 1. Introduction Jurisdictions define the **scope within which a user is permitted to view, create, assign, and action records**. They are primarily an **access-control and workflow boundary**, not just a representation of administrative geography. While jurisdictions reference the country’s administrative structure (for example country β†’ province β†’ district), their purpose is to **control which events and records a user can act on**, based on where those events occurred or the location for where a past action was performed by a user. Jurisdiction rules are evaluated at the **user scope level** and applied consistently across recored creation, search and assignment. This ensures that civil registration work happens only within the location(s) a user is authorised to operate in, supporting legal compliance, data protection, and operational separation of responsibilities. In short, jurisdictions determine **what a user can do and which records they can access**, rather than simply describing where data belongs. *** ### 2. Feature overview Jurisdictions provide a **policy layer** that connects administrative locations to permissions and system behaviour. They enable OpenCRVS to enforce location-aware access and workflows across the platform. #### Core capabilities include: With jurisdictions, OpenCRVS supports: * **Location-scoped permissions** so users can only see and act on records relevant to their authorised area. * **Controlled creation of records**, restricting where events can be notified, declared, or registered. * **Scoped search results and workqueues**, ensuring users only work on records within their permitted locations. * **Consistent enforcement across actions**, including create, assign, update, and register operations. Jurisdictions in OpenCRVS are: * **Type-based** β€” permissions use predefined jurisdiction types (for example, β€œmy administrative area”, β€œlocation”, or β€œany”) * **Applied per scope** β€” each permission (such as create, search, or assign) can specify its own jurisdiction rule. * **User-specific** β€” different users in the same office may have different jurisdiction boundaries. This design allows fine-grained control over who can act on which records, while remaining flexible enough to match diverse civil registration operating models. *** ### 3. Jurisdiction configuration overview #### 3.1 Jurisdictions types The system currently supports four boundary types: | Type | Functional meaning | | ---------------------- | ------------------------------------------------------------------------------ | | my administrative area | My location and all child locations (for example, my district + all districts) | | location | Only my exact office or facility | | user | Only records personally declared/registered by me | | any | No location restriction | {% hint style="warning" %} More complex custom jurisdiction types eg. A Senior Registrar in a district office but has jurisdiction over all District offices in the State; are planned to be supported in future releases. {% endhint %} Jurisdictions can be applied to different **location characteristics** of a record. | Characteristic | What it represents | | -------------- | --------------------------------- | | Place of event | Where the event actually occurred | | Declared in | Where it was formally declared | | Registered in | Where final registration happened | #### 3.2 Jurisdictions and users Jurisdiction is enforced at a user scope level. From a user’s perspective therefore, jurisdictions determine: * What records they can see (search results only include records inside their jurisdiction) * What event declarations they can create (for example, only events that occurred in their jurisdiction) * What records they can work on (they can only validate, edit, register or print records that fall inside their jurisdiction If a record is outside their jurisdiction: * it will not appear in search, or * actions will be blocked Example user scopes: * `record.create[event=birth placeOfEvent=my-administrative-area]` * user can only create declarations for events that occurred in their administrative area * place of birth locations are automatically filtered * `record.search[event=birth declared_in=my-administrative-area registered_in=my-administrative-area]` * user can only see records in search results for records either notified, declared or registered in their administrative area {% hint style="info" %} As jurisdiction are enforced at the individual scope level (rather than being determined solely by the user's assigned office location). As a result: * Different users in the same office can be assigned different jurisdictions. * A single user role can have different jurisdictions for different scopes {% endhint %} #### 3.3 β€œDeclared in” & β€œRegistered In” Sometimes a single location rule is not enough. For example: * β€œIn search results show only records declared in my district” (single location rule) * or β€œShow records either declared OR registered in my district” * or β€œOnly records both declared AND registered in my district” To support real operational needs, jurisdictions support **AND** and **OR** logic. **AND logic (stricter filtering)** When multiple conditions are applied together in the same rule, **all must be true**. This narrows access. Example: A district registrar is only allowed to see records that were: * declared in their district **AND** * registered in their district Result: * records handled entirely inside the district only * excludes records declared in their district but registered elsewhere ``` { type: 'search', options: { event: ['birth'], declaredIn: 'administrativeArea', registeredIn: 'administrativeArea' } } ``` By definition, these filter out events that have not been registered. Out of the registered events, only the ones that were both declared and registered within user's administrative area are returned. **OR logic (broader filtering)** When separate rules are defined for the same action, **any rule may match**. This broadens access. Example: A supervisor wants to see records: * declared in their district **OR** * registered in their district Result: * includes locally declared records * includes records registered locally but declared elsewhere ``` [ { type: 'search', options: { event: ['birth'], declaredIn: 'administrativeArea', } }, { type: 'search', options: { event: ['birth'], declaredIn: 'administrativeArea', } } ] ``` Out of all birth events, the ones that are declared within the administrative area, or registered within the administrative area are returned. ### 4. Worked example #### **Business requirement: Health Official** * A health official working at a specific health facility can only work on records for events that occurred in **their own facility**. * They must not see or modify records from other facilities or districts. #### Configuration input | Permission | Event | Jurisdiction | Meaning | | ---------- | ------------ | ------------------------ | ---------------------------------------------------------------------------------------------------- | | Create | Birth, Death | placeOfEvent = location | Can only create records of events that occurred in their facility (filters place of event locations) | | Search | Birth, Death | placeOfEvent = location | Can only see records for events that occurred in their facility | | Declare | Birth, Death | placeOfEvent = location | Can only declare events that occurred in their facility | | Edit | Birth, Death | declared\_in = my-office | Can only edit declarations declared be someone in their health facility | ### 5. Summary # Actions ### 1. Introduction In OpenCRVS, **Actions** are system operations that can be performed on a record. Actions may change a record’s status, add or remove flags, modify record data, or use record data to generate outputs such as certificates or verifiable credentials. OpenCRVS uses a **journaled database** to record every action performed on a record. Each action is written as an immutable entry in a sequential audit log (the β€œjournal”), ensuring full traceability and auditability of all changes over time. OpenCRVS supports: * **Core actions**, which implement standard civil registration workflows * **Custom actions**, which allow countries to model additional, country-specific business processes *** ### 2. Feature Overview Actions provide a controlled and auditable way to progress records through their lifecycle. #### Core capabilities With Actions, OpenCRVS supports: * Strict control over which actions are available at each record status * Permission-based access using user scopes (including jurisdiction constraints) * Conditional availability based on record flags * Optional user input captured at action time (forms) * Fully auditable state transitions * Conditionally add or remove flags * Configure custom actions to support custom workflows Actions are: * **Contextual** β€” only visible when applicable * **Deterministic** β€” availability depends on record state, flags, and user permissions * **Journaled** β€” every action is recorded immutably *** ### 3. Record Action Menu (User Experience) Actions are presented to users through the **Record Action Menu**. An action appears in the menu when **all** of the following conditions are met: 1. The user has the required scope 2. The record is in a compatible status 3. Any required flags are present 4. The record is assigned to the user (where assignment is required) If an action is visible but currently unavailable, it will appear disabled until the required conditions are met. #### Example action menu state For a record with status **Registered**, and a logged-in user assigned to the record with the scopes: * `record.assign[event=birth]` * `record.print[event=birth]` * `record.correct[event=birth]` * `record.customAction[event=birth actionType=Issue-Verifiable-Crendential]` The action menu would display: * Print * Correct * Issue verifiable credential * Unassign Actions remain disabled until the user assigns the record to themselves. This supports safe offline working and prevents conflicting updates. *** ### 4. Core Record Actions Core record actions are maintained by OpenCRVS to support standard civil registration workflows. These actions cover declaration, review, registration, correction, and issuance processes. #### Core record actions | Action | Description | Required status | Required flag | | ------------------------------------------------ | --------------------------------------------------- | ------------------ | -------------------- | | Create | Create an event record | - | | | Update | Update a draft declaration | Draft | | | Notify | Submit an incomplete declaration for follow-up | Draft | β€” | | Declare | Submit a completed declaration | Draft, Notified | β€” | | Mark as duplicate | Mark a declaration as a duplicate during review | Declared | Potential duplicate | | Mark not a duplicate | Confirm a declaration is not a duplicate | Declared | Potential duplicate | | Archive | Archive a declaration | Declared | β€” | | Reject | Reject a declared or validated record | Declared | β€” | | Edit β†’ Declare with edits or Register with edits | Edit notification or declaration data during review | Notified, Declared | β€” | | Register | Finalise and register a declaration | Declared | β€” | | Request correction | Flag a registered record for correction | Registered | β€” | | Review correction request | Review a submitted correction request | Registered | Correction requested | | β†’ Reject correction | Reject a correction request | Registered | Correction requested | | β†’ Approve correction | Approve a correction request | Registered | Correction requested | | Print | Generate and issue a certified copy | Registered | β€” | | Assign | Assign the record to yourself | Any | β€” | | Unassign | Release or change record assignment | Any | β€” | #### Configurable flags on core actions Core actions can be configured to conditionally add or remove flags based on the context in which they are performed. This allows for flexible workflow customization while maintaining standard action behaviour. **Examples:** * When a registration agent **Creates** and performs the **Declare** action, it can append the `validated` record flag to indicate the declaration has been reviewed by an authorised agent * If a declaration is late (based on configured time limits), the **Declare** action can add the `late-registration` flag This configuration allows countries to adapt core workflows to their specific requirements without modifying the core action definitions. #### Core actions by status The table below summarises which actions are available at each stage of the record lifecycle. | Record status | Available actions | | ------------- | ---------------------------------------------------------------------------------- | | Draft | Update, Notify, Declare | | Notified | Assign, Unassign, Declare, Edit | | Declared | Assign, Unassign, Archive, Reject, Edit, Mark duplicate, Mark not a duplicate | | Archived | Assign, Unassign | | Registered | Assign, Unassign, Request correction, Approve correction, Reject correction, Print | *** ### 6. Custom Actions (Overview) Custom Actions allow implementers to extend the system beyond core workflows to support **country-specific or programme-specific business processes**. Custom actions are similar to core actions in that: * They are permission-controlled * They are deterministic based on the record status and flags * They are journaled * They can add and/or remove record flags * They can capture additional metadata viewable in record audit * They appear in the same action menu They differ by: * They can not change the status of a record * They can not edit/correct data in the record * Support only a one page form within a dialog #### Custom action parameters Each custom action is defined using a configuration that controls its visibility, behaviour, and side effects. | Property | Description | Example | | ---------------------------- | ---------------------------------------------- | ---------------------------------------------------- | | **Icon** | Icon displayed in the action menu and dialog | warning | | **Name** | Display text shown in the action menu | Attest | | **Audit copy** | Text written to the audit log | Attested | | **Required scope** | User permission required to perform the action | `custom.attest[event=birth, jurisdiction=my-office]` | | **Required status(es)** | Record status(es) required | Declared | | **Required flag(s)** | Flag(s) required for availability | senior-approval-required | | **Disable if** | Conditions that disable the action | Disable if record has `rejected` flag | | **Dialog supporting copy** | Explanatory text in the confirmation dialog | β€” | | **Dialog confirmation form** | Optional form to capture metadata | Comments, reason dropdown | | **Output flags added** | Flags added when action completes | attested | | **Output flags removed** | Flags removed when action completes | pending-certificate-issuanc | #### Example custom actions The following examples illustrate possible custom actions you could configure: | Action | Description | | --------------------- | -------------------------------------- | | Attest | Attest a declaration before submission | | Grant senior approval | Approve late registrations | | Escalate | Request senior-level review | | Give feedback | Add guidance or notes to a record | | Collect search fees | Record fee collection for access | *** ### 7. Worked example This section illustrates how a real-world business rule is translated into a custom action configuration. #### Business requirement - Attest * All death declarations declared by a Health Official must be Attested by the Hospital Administrator * Registration is not allowed until the event has be attested #### Configuration input - Action: Attest | Property | Value | | ---------------------------- | ------------------------------------------------------------------------------------ | | **Icon** | Check | | **Name** | Attest | | **Audit copy** | Attested | | **Required scope** | `record.custom.action[event=death, actionType=Attest]` | | **Required status(es)** | Declared | | **Required flag(s)** | Pending attestation | | **Disable if** | - | | **Dialog supporting copy** | By attesting this record you confirm that the event occurred in your health facility | | **Dialog confirmation form** | Comments - Text Area Field - (optional) | | **Output flags added** | - | | **Output flags removed** | Pending attestation | #### Configuration input - Action: Register The Register action must be disabled when the record has the `pending-attestation` flag | Property | Value | | ---------- | ------------------------- | | Disable if | flag: pending attestation | #### Configuration input - Workqueue: Pending attestation A **Pending attestation** workqueue that displays all records with the `pending-attestation` flag | Workqueue | Query | | ------------------- | --------------------------- | | Pending attestation | flag: `pending-attestation` | #### Configuration input - User Role: Hospital Administrator The **Hospital Administrator** need to be given the scope to perform the custom action Attest and the Pending Attestation workqueue | Role | Scope | | ---------------------- | ------------------------------------------------------------------------------------------ | | Hospital Administrator | `record.custom.action[event=death, actionType=Attest]` `workqueue[id:pending-attestation]` | See: Workqueues, User Roles and Flags to learn more. *** *** ### 8. Core User Management Actions In addition to record-based actions, OpenCRVS includes system-level actions for managing users. These actions are available only to administrators with appropriate user scopes. #### User management actions | Action | Description | | ---------------------- | -------------------------------------------- | | Create | Create a new user account | | Edit | Update user details (role, location, status) | | Deactivate | Disable user access | | Reactivate | Restore user access | | Reset password | Initiate password recovery | | Send username reminder | Send username via email or SMS | *** # Workqueues ### 1. Introduction In OpenCRVS, **Workqueues** are role-based, pre-filtered lists of vital event records, organised to help registration staff clearly see pending tasks and what needs their attention. Instead of searching for records, users may open a Workqueue from the left-hand navigation to get a task-focused view of records at a particular status or that require a specific action, such as declaration review, validation, approval, certificate printing, or issuance. Each Workqueue combines configurable filters with role-based visibility so that: * Users are able to see records relevant to them at that moment in time * Users only see queues that are relevant to their responsibilities * Users can stay in a focused workflow with less searching and context switching *** ### 2. Feature overview Workqueues provide a flexible mechanism for showing records relevant for the user based on workflow state, timing, location, user actions, and record data. #### Core capabilities OpenCRVS supports: * Unlimited custom workqueues * Role-based access to workqueues * Filtering by event type and record status * Date-based filtering using exact dates, ranges, or relative periods * Location-aware filtering using administrative hierarchies and jurisdictions * User- and role-based filtering (e.g. β€œupdated by me”, β€œupdated by registrar”) * Filtering based on record data (e.g. date of event, event location, calculated values such as age) Filters can be combined to create precise, task-oriented views such as: > β€œAll birth declarations rejected by a Registrar in the last 7 days within my district.”
*** ### 3. Configuration overview Each Workqueue is defined by a small set of parameters that control how it appears in the user interface and which records it displays. #### 3.1 Workqueue parameters | Property | Description | | --------------------------- | ------------------------------------------------------------------ | | **ID / Slug** | Unique identifier for the Workqueue. Used internally and in URLs. | | **Icon** | Icon displayed in the left-hand navigation. | | **Name** | User-facing display name shown in the navigation. | | **Actions** | Required quick action from the workqueue table | | **Query (search criteria)** | A set of filters that determine which records appear in the queue. | #### 3.2 Supported query filters Workqueues are powered by a flexible query system. Multiple filters can be combined to create highly targeted views of records. | Filter | Type | Description | Examples | | ----------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **Event type(s)** | Any of | Filter records by civil event type. | Any of (Birth, Marriage) | | **Record status(es)** | Any of | Filter records by workflow status. | Any of (Declared, Validated) | | **Created at** |

Exact date
Date range
Relative

| Filters by when the record was first created. | After 01/01/2024 | | **Updated at** |

Exact date
Date range
Relative

| Filters by when the last ~~mutating~~ action occurred. | Before 01/02/2024 | | **Created at location** |

Exact
Within

| Filters by where the create action was performed. | Exact: Ibombo | | **Updated at location** |

Exact
Within

| Filters by where the last ~~mutating~~ action occurred. |

In user’s primary office
Within Langa District

| | **Created by** |

Exact
Me

| Filters by the user who created the record. |

User ID: 123-456
Me

| | **Updated by** | Exact | Filters by the user who last updated the record. |

User ID: 123-123
Me

| | **Updated by role** |

Exact role
Any role

| Filters by the role of the user who last updated the record. | Registrar | | **Record data fields** | Field-type dependent | Filters on values within the record data. Available operations depend on the field type. |

Child age > 1 year
Event location = Ilanga District Hospital
Date of event between 2023–202

| #### 3.3 Filter type options The following matching types are used across filters: * **Exact** – Matches a single, precise value (e.g. a specific date, user, or location). * **Within** – Matches a location and all of its child locations in the administrative hierarchy. * **Any of** – Matches at least one value from a selected set. * **Range / Relative** – Matches a date range or a period relative to the current date (e.g. β€œlast 14 days”). * **Me** – A special selector representing the currently logged-in user. *** ### 4. Worked example Here we illustrates how a real-world business rule is translated into a **workqueue configuration** and then into **code in the country configuration package**. #### Business requirement: Pending validation workqueue * Show all birth and death declarations that are ready to be reviewed by the Registration Officer, so that they can quickly identify declarations that are ready for them to validate. * Show all birth declarations that: * Have been declared in the Registration Officer’s administrative area * Have not yet been validated * Have the status β€œdeclared” * Have not been rejected * Do not require senior approval #### Configuration input | Configuration input | Value | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **id** | pending-validation | | **Icon** | Stamp | | **Name** | Pending validation | | **Action** | Review | | **Query** |

Event: Birth, Death
Status: Declared
Flags: noneOf: Validated, Rejected, Approval required for late registration

| *** ### 5. Pre-configured workqueues OpenCRVS includes several pre-configured workqueues that support common civil registration workflows. These queues can be customised, extended or removed as needed. | Workqueue | Description | | ------------------------- | -------------------------------------------------------------------- | | **Drafts** | Records at draft status. Shown if user has the `record.create` scope | | **Assigned to you** | Records currently assigned to the user | | **Recent** | Recently created or updated records | | **Notifications** | Incomplete declarations missing mandatory information | | **Pending validation** | Declarations ready to be validated | | **Pending updates** | Records flagged for additional data | | **Potential duplicate** | Declarations that have been flagged as potential duplicates | | **Pending registration** | Declarations that have been validated and ready to be registered | | **Escalated** | Records that have been escalated to senior user roles | | **Pending approvals** | Records forwarded for higher-level approval | | **Pending certification** | Registered records ready for certificate printing | | **Pending issuance** | Certified copies that have been printed off inadvance of issuance | | **Pending corrections** | Records with pending correction requests | *** ### 7. Workqueue assignment and access control Workqueues are assigned to user roles alongside other scopes. Assigning a workqueue makes the workqueue visible in the navigation pane and allows the user to see the full list of filtered records, however it **does not** grant additional β€œaction” permissions on the records themselves. Multiple workqueue IDs can be combined using the pipe (`|`) separator to tailor queue visibility by role and responsibility. #### Example workqueue scope ``` workqueue[id=assigned-to-you|recent|pending-updates|pending-validation|pending-certification] ``` **Meaning:** Users with this scope can access the listed workqueues, enabling them to view and manage the corresponding filtered record sets. # Offline working ### 1. Introduction OpenCRVS enables civil registration staff to work reliably in **low-connectivity** or **offline** environments. The Offline Working feature ensures that key registration activities can continue even when there is no internet connection, and that all actions are synchronised safely once connectivity is available. Offline working is built on three core ideas: * Users can **create and update records** while offline. * Actions are queued in an **Outbox** on the device. * When connectivity returns, queued actions are **synchronised** to the backend and written to the audit log with accurate timestamps based on when the user confirmed the action For details on how action timestamps and audit entries are recorded, see **Record data** and **Audit**. {% hint style="danger" %} While you can complete all assigned record actions (such as Register, Edit, or Approve) while offline, the action should not be considered "legally final" until the users device has synchronised with the backend central e-registry {% endhint %} *** ### 2. Feature overview Offline working allows users to continue **end-to-end workflows** even when connectivity is unreliable, while keeping the data model and audit history consistent. #### Core capabilities With offline working, OpenCRVS supports: * **Creating and submitting declarations offline**, including Notify and Declare actions. * **Working on assigned and downloaded records offline**, including review, approval, and corrections where permitted. * A local **Outbox** that queues actions safely on the device until connectivity returns. * **Accurate audit timelines** based on the time actions were taken on the device, not when they synced. * **Conflict prevention** through record assignment and unassignment rules. * Reliable workflows in **low-connectivity or intermittently connected environments**. Offline working is: * **Assignment-driven** β€” only assigned records are available for offline mutation, reducing conflicts. * **Action-based** β€” all offline changes are still captured as actions in the journal. * **Transparent** β€” users can see which records are assigned and which actions are pending in the Outbox. *** ### 3. Core offline use cases #### 2.1 Creating a new declaration Users can create and submit declarations while offline: * The user completes the **event form** for Notify/Declare on their device. * When they choose to **Notify** or **Declare**, the action is stored locally if there is no connectivity. * The declaration is added to the device’s **Outbox** and will be synchronised automatically when a connection is available. {% hint style="warning" %} If a form includes fields that require **online validation** (for example, national ID verification): * An internet connection is required to complete that validation step. * Countries are encouraged to configure a **fallback option** so that a declaration can still be completed and submitted offline when online validation is not possible, with follow-up checks performed later. {% endhint %} #### 2.2 Working on assigned records Users can also work offline on records that have been assigned to them: * When a record is **assigned** to a user, it is downloaded to their device for offline access. * Depending on the user’s role and permissions, they can **edit, validate, approve, print or correct** or other configured actions to the record while offline. * All offline actions are added to the **Outbox** and synchronised when connectivity is restored. {% hint style="danger" %} While you can complete all assigned record actions (such as Register, Edit, or Approve) while offline, the action should not be considered "legally final" until the users device has synchronised with the backend central e-registry {% endhint %} *** ### 4. Assignment and conflict prevention Assignment is used to control who can work on a record offline and to reduce the risk of conflicting edits. When a user assigns a record to themselves, it is downloaded to their device for offline access. The assignment mechanism includes safeguards: * **Assignment visibility** β€” the record’s assigned status is visible to other users in the workqueue, indicated by the profile icon of the assigned user. * **Conflict prevention** β€” only one user can edit a record at a time, which helps avoid concurrent offline edits on the same record. * **Unassignment** β€” users with the appropriate unassign scope can unassign another user from a record. This action discards any unsynchronised changes made by the previously assigned user on their device. This assignment behaviour, combined with the Outbox, supports robust offline working while minimising data conflicts. *** ### 5. Outbox The **Outbox** acts as a queue for offline actions, similar to the Outbox in an email client. It temporarily stores updates made while offline and ensures they are securely processed once connectivity is restored. Key behaviours: * **Workflow continuity** β€” Field Agents can create declarations offline, and Registration Agents can review or approve records assigned to them without needing continuous internet access. * **Automatic synchronisation** β€” when connectivity is reestablished, the Outbox automatically synchronises all stored actions with the backend. Records are forwarded to the appropriate Registration Office or the next workflow stage. * **Data security and reliability** β€” the Outbox reduces the risk of data loss caused by intermittent connectivity. Users can be confident that their offline actions are stored safely on the device until they are successfully synchronised. The Outbox and assignment model together ensure that OpenCRVS supports consistent, secure workflows even in challenging connectivity conditions. *** ### 6. Offline actions and audit Every action taken while offline is written to the audit log once synchronised. Important characteristics: * Each action includes standard, non-configurable metadata (for example, **action timestamp**, **user**, and **assigned user location**). * The **action timestamp** records the date and time when the user triggered the action on their device, **not** when it later reaches the backend server. * This ensures that the audit timeline accurately reflects **when actions actually occurred**, even if a user was offline for one or more days. For further detail on how this is represented in the data model and audit trails, see the **Record data** and **Audit** documentation pages. # Deduplication ### 1. Introduction **Deduplication** is the process by which OpenCRVS detects and manages potential duplicate event records (for example, multiple declarations for the same birth). It is designed to prevent errors and fraud, and to protect the integrity of the civil register. OpenCRVS uses Elasticsearch-based matching to compare new declarations against existing records. When a potential duplicate is found, a user with the appropriate scope is prompted to review the records side by side and decide whether the new declaration should proceed or be treated as a duplicate. *** ### 2. Feature overview Deduplication supports a controlled, reviewable process for detecting and resolving potential duplicates. #### Core capabilities With Deduplication, OpenCRVS supports: * Automated matching of new declarations against existing records using configurable rules. * Per–event-type configuration (for example, separate rules for birth vs death). * Fuzzy matching on names, dates, and other key fields (for example, using Levenshtein distance for names). * Business-rule based checks (for example, biological plausibility checks such as two births within 9 months to the same mother). * Role- and scope-based review of potential duplicates (for example, Registrar review). * Side by side review experience with matched records * Clear outcomes for each review: **mark as duplicate** or **mark as not duplicate**. * Full audit trail of matching results and human decisions. Deduplication is: * **Proactive** β€” aims to catch duplicates before registration. * **Deterministic** β€” behaviour is driven by explicit configuration per country and event type. * **Transparent** β€” configuration and decisions can be inspected and adjusted over time. * **Configurable** β€” matching logic can be tailored per event type (for example birth, death). * **Early in the workflow** β€” potential duplicates are flagged at declaration / review, before registration. * **Auditable** β€” decisions (duplicate vs not duplicate) are journaled for future review. *** ### 3. Configuring deduplication logic Deduplication logic is configured **per event type** (for example, birth, death, marriage) using Elasticsearch queries. #### 3.1 What a deduplication configuration defines A deduplication configuration typically defines: * **Fields to match on** β€” for example: * Child’s first name(s) * Child’s last name * Date of birth * Mother’s first name(s) * Mother’s last name * Mother’s date of birth or age * Mother’s national ID * **Matching rules per field** β€” for example: * **Names (strings):** fuzzy match using edit distance (Levenshtein), with allowed edits depending on name length. * **Dates:** exact or within a configured range (for example, Β±5 days or Β±3 years). * **IDs:** exact match. * **Boosting and weighting** β€” certain fields can be given higher weight in the overall match score (for example, national ID vs name similarity). * **Thresholds** β€” only matches above a certain relevance score are presented for review. Business owners define **what should be considered β€œclose enough”** for each field and event type, and technical teams implement that as Elasticsearch queries and scoring. {% hint style="info" %} You can configure more than one check per event to target different types of potential duplicates or fraudulent activity. {% endhint %} #### 3.2 Impact of allowing multiple ID types in declarations When the declaration form allows multiple ID types (for example, **National ID**, **Passport**, **BRN**) with a type selector, there are some important considerations: * **ID matches are strongest when the same ID type is reused.** If the same mother is recorded twice with the **same ID type and value** (for example, NID vs NID), ID‑based deduplication is a strong signal. * **Different ID types weaken ID‑based matching.** If the same mother is recorded once with a Passport and once with a National ID, deduplication cannot treat these as the same identifier. In these cases, matching must rely primarily on **name and date‑of‑birth similarity**. To mitigate these limitations, countries should: * Treat a single, stable ID type (for example, **National ID**) as the **primary deduplication identifier** where available. * Always configure additional checks that **do not depend on IDs at all**, using combinations of names, dates of birth, locations, and other demographics to catch duplicates where ID types differ or are not provided. *** ### 4. Reviewing potential duplicates When a new declaration is submitted, OpenCRVS automatically runs the configured deduplication checks for that event type. If one or more potential matches are found: 1. A user with the scope `record.review-duplicate` can perform the action: Review potential duplicates 2. The system displays a **side-by-side view** of the new declaration and matching existing records. 3. The reviewer compares key data fields (for example, child’s name, date of birth, mother’s details) and any additional context. 4. The reviewer chooses one of the following outcomes: * **Mark as duplicate** β€” the new declaration is archived as a duplicate of the existing record. * **Mark as not a duplicate** β€” the declaration proceeds through the normal workflow (for example, validation and registration). All review outcomes are audited, including: * Which record was reviewed. * Which potential matches were presented. * Who made the decision. * The decision taken (duplicate / not duplicate). *** ### 5. Worked example From a business perspective, configuring deduplication logic means describing **what kinds of mistakes or duplicate situations you want the system to catch**, and then defining **what β€œclose enough” means for each field**. #### **Business requirement:** Detect cases where the **same birth is accidentally declared more than once** (mistaken redeclaration). **Why this happens in practice** Common causes include: * Parents returning to the office and submitting the same declaration twice * Staff re-entering an event because the first submission appeared to fail * Spelling differences between declarations (e.g., *Sara* vs *Sarah*) * Small date entry mistakes (e.g., 12 vs 14 May) * The same mother using the same ID but slightly different name spelling Because these are not intentional duplicates, we expect: * Most core details to be very similar * At least one strong identifier (often the mother’s national ID) #### Configuration input
CheckReason for checkRequired matching criteria
Standard checkMistaken redeclaration
  • Similar child's first name(s)
  • Similar child's last name
  • Date of birth within Β±5 days
  • Similar mother's first name(s)
  • Similar mother's last name
  • Similar mother's date of birth or same age
  • Exact mother's national ID |
#### Name matching configuration To support fuzzy name matching, OpenCRVS uses the following Levenshtein-based rules: * **Similar first name** * 0–3 characters: 0 edits allowed * 4–6 characters: 1 edit allowed * 7+ characters: 2 edits allowed * **Similar last name** * Applies the same Levenshtein rules as first names. * For compound surnames (for example, "von Thiele Schwarz"), all parts must match in some form. * Word-level distance is applied so that small spelling errors or transpositions (for example, "Thoele" vs "Thiele") can still be detected as potential matches. These rules balance **sensitivity** (catching likely duplicates) with **specificity** (avoiding too many false positives). They can be tuned during implementation based on real-world data. *** ### 8. Summary At a high level, implementers can think of deduplication as: * A set of **Elasticsearch queries** defined per event type. * A **matching pipeline** that runs when declarations are notified, declared or edited. * A **UI component** that renders the side-by-side comparison and captures the reviewer’s decision. * A set of **journal entries and actions** (for example, archive as duplicate) triggered by that decision. # Communications ### 1. Introduction Communications in OpenCRVS keep both system users and informants informed about key steps in the civil registration process. Notifications can be triggered by record actions (for example, Notify, Declare, Register) or by system events (for example, onboarding a new user), and can be delivered via SMS and/or email. *** ### 2. Feature overview Communications supports a range of notification scenarios for both internal users and external informants. #### Core capabilities With Communications, OpenCRVS supports: * SMS and email notifications triggered by **record actions** (for example, Notify, Declare, Validate, Reject, Register). * System notifications for **user account events** (for example, onboarding, password reset, username reminder). * Per–event-type and per–action configuration of message templates. * Use of **template variables** (for example, `name`, `trackingId`, `registrationNumber`) to personalise messages. * Integration with external SMS gateways (for example, Infobip, Twilio) and email services (for example, SMTP providers). * Optional bulk communications to system users (for example, platform updates). Notifications are designed to: * Guide informants through the registration process. * Reduce missed appointments and uncollected certificates. * Keep staff informed of account-related activity. *** ### 3. System users notifications User notifications are messages sent to **system users** (for example, Registrars, Field Agents, System Administrators). #### 3.1 Core user notifications The following notifications are sent to a user: * **Onboarding invite** β€” invite a new user to activate their account and set a password. * **Two-factor authentication codes** β€” send one-time codes for secure login * **Username reminder** β€” send the username to a user who has forgotten it. * **Password reset** β€” notify a user that a password reset has been initiated. #### 3.2 Bulk email to system users A user with the scope `config.update:all` can send **mass email** to all system users. Typical use cases include: * Informing users about upcoming system maintenance. * Announcing new functionality or workflow changes. * Providing guidance on updated policies. *** ### 4. Informant notifications Informant notifications are messages sent to the **informant** or other contact person linked to a record (for example, parent, relative, or informant). Any **record action** can be configured to send an informant notification. Configuration is specific to each event type (for example, birth, death) and each action. #### Example record-action notifications * **Record Action – Notify** * Purpose: Inform the informant that an incomplete declaration (notification) has been received and explain next steps. * Example content: Include the tracking ID and instructions on what information or documents are still required. * **Record Action – Declare** * Purpose: Confirm receipt of a completed declaration and set expectations for review time. * Example content: Inform the informant of the expected wait time for validation and registration. * **Record Action – Validate** * Purpose: Update the informant that the declaration has passed validation and is awaiting final approval and registration. * **Record Action – Reject** * Purpose: Inform the informant that the declaration has been rejected. * Example content: Include the reason for rejection and any next steps. * **Record Action – Register** * Purpose: Confirm that the event has been registered. * Example content: Share the registration number and next steps for certificate collection. Each notification can be configured separately for SMS and email, and can be enabled or disabled per action. *** ### 5. Configuring notifications overview Notification behaviour is controlled through configuration that links **events and actions** to **channels and templates**. #### 5.1 Configuration elements * **Event type** β€” for example, Birth, Death. * **Trigger** β€” record action or system event (for example, Notify, Declare, Register, UserCreated). * **Recipient** β€” informant, user, specific role, or all users. * **Channel(s)** β€” SMS, email, or both. * **Template** β€” message content with placeholders. * **Language** β€” message variants per supported language. #### 5.2 SMS configuration SMS notifications require integration with one or more SMS gateway providers (for example, Infobip, Twilio). The exact provider and connection details are set during deployment. **Example SMS (Record Action: Register)** > Congratulations, the birth of {{name}} has been registered. Visit your local registration office in 5 days with your ID to collect the certificate. Your tracking ID is {{trackingId}}. Key characteristics: * Short, clear language suitable for SMS length constraints. * Use of placeholders (for example, `name`, `trackingId`). * Country-specific guidance on timeframes and required documents. #### 5.3 Email configuration Email notifications require integration with an email service (for example, SMTP server or cloud email provider). Email templates can: * Use richer formatting than SMS (for example, headings, bullet points, links). * Include more detailed instructions, supporting documents, or links to external resources. * Be localised per language and tailored per event type. For example, the email version of a β€œRegistered” notification might include: * A summary of the registered event. * The registration number and tracking ID. * A link to information about office locations and opening hours. * A reminder of documents required for certificate collection. To learn more ..> *** ### 6. Worked example Here we illustrates how a real-world business rule is translated into a comms **configuration** and then into **code in the country configuration package** #### **Business requirement:** When a birth is successfully registered, automatically notify the informant so they: * Know registration is co * * mplete * Receive the registration number * Understand what to do next (certificate collection) * Have a tracking ID for follow-up #### Configuration input Email template: Link to design | Action | Channel | Content | | -------- | ------- | ---------------------------- | | Register | Email | Birth registration completed | Hello {{informantName}}, Congratulations, the birth of {{childName}} has been registered. Registration number: {{registrationNumber}} Please visit {{crvsOffice}} with your ID to collect the birth certificate. Your tracking ID is {{trackingId}}. Best regards, {{applicationName}} *This is an automated message. Please do not reply.* | > insrt html/svg code # Search # Quick search ### 1. Introduction In OpenCRVS, **quick search** is the global search field in the application header. It is used when the user has one or more **strong identifiers** and needs to locate a record quickly. Quick search focuses on a small set of configurable identifier fields and only returns records that the user is authorised to see, based on scopes and jurisdiction. It complements **advanced search**, which is used when identifiers are not known and multiple data points are needed to find a record. Typical use cases include entering a **Tracking ID**, **Registration number**, or **national ID** to locate a specific record. *** ### 2. Feature overview Quick search provides a **fast, identifier-based entry point** to find records from anywhere in the application. #### Core capabilities With quick search, OpenCRVS supports: * **Instant lookup** of records using strong identifiers (for example, Tracking ID, Registration number, national ID). * **Scope-aware results** that only return records the user is authorised to see. * **Per-event configuration** of which identifier fields can be searched. * A consistent search experience from the **global header**, without navigating to a dedicated search page. * Complementary behaviour with **advanced search** for cases where identifiers are not known. Quick search is: * **Identifier-first** β€” optimised for exact or normalised matches on a small number of fields. * **Predictable** β€” the same input returns the same results for a given user and configuration. * **Secure** β€” always filtered by scopes and jurisdiction. *** ### 3. Configuration overview Quick search is **configured per event type** (for example, birth, death, marriage) and per identifier field. Configuration defines: * Which **fields** are queried by quick search. * Which **events** quick search is allowed to return for a given user. Key principles: * Focus on fields that are likely to be unique or highly discriminating. * Avoid including free‑text name fields, which are better handled by advanced search. * Keep behaviour predictable: the same input should consistently return the same record set for a given user. #### Search fields For each event type, you can configure which data points quick search should use. Recommended fields are identifiers that are either unique or nearly unique, such as: * **Registration number** * **Tracking ID** * **National ID** (where captured) * **Phone number** * **Email address** Configuration should specify, per event type: * Which fields are enabled for quick search. * Whether the search is **exact match** only, or allows normalised matching (for example, phone numbers without country code). #### Access control and scopes Quick search & advanced search is always subject to the standard access control model: * Users only see records that their **scopes and jurisdictions** allow. * Search results never include records outside the user’s permitted scope, even if the identifier matches Access to search (quick search and advanced search) is controlled by **search scopes** on the user’s role. * `search[event= placeOfEvent=my-administrative-area]` where `` is the relevant event type (for example, `birth`, `death`, `marriage`). To learn more about users scopes please refer to Users, Jurisdictions *** ### 5. Worked example configuration Below is an example configuration for quick search for birth records. #### Business requirement Users can quickly search for birth records based on names of individuals in the birth record and available unique identifies. #### Configuration Input | Data | Event | Type | | ----------------------- | ----- | ----------------------------------------- | | **Names** | Birth | Fuzzy on Informant, Child, Mother, Father | | **Tracking ID** | Birth | Exact match | | **Registration number** | Birth | Exact match | | **National ID** | Birth | Exact match | | **Phone number** | Birth | Exact match | *** ### 6. Relationship to advanced search Quick search and advanced search are complementary: * **Quick search** is for users who have a strong identifier and need fast access via the application header. * **Advanced search** is for users who do not have identifiers and need to combine multiple data points (names, dates, locations) to find records. Both features use the same underlying access control model and scope patterns; configuration should be kept consistent so that a user’s experience of which records they can find is predictable across both search methods. # Advanced search ### 1. Introduction In OpenCRVS, **advanced search** provides a structured way to search for event records using multiple data points when the user does not have a unique identifier. Advanced search: * Uses fields from the event data (for example, names, dates, locations) to narrow down results. * Respects the same **scopes, roles, and jurisdictions** that apply elsewhere in the system (users only see records they are authorised to see). * Complements **quick search**, which is optimised for simple keyword or ID lookups. Typical use cases include: * A Registrar searching for a birth record with only the child’s name and approximate date of birth. * A Registration Agent locating a declaration using the mother’s details and place of birth. * Staff investigating potential duplicates or historical records without a Tracking ID. *** ### 2. Feature overview Advanced search provides a **flexible, form-based way** to find records when strong identifiers are not available. #### Core capabilities With advanced search, OpenCRVS supports: * **Multi-field search** using names, dates, locations, and other event data. * **Configurable search forms** per event type, grouped into logical sections (for example, registration, child, mother, father). * **Scope- and jurisdiction-aware results**, aligned with the wider access control model. * Efficient triage and investigation when users only have partial or approximate information. * Complementary behaviour with **quick search**, so users can move between identifier-based and data-based search. Advanced search is: * **Form-driven** β€” users fill in structured fields rather than entering free text. * **Filter-friendly** β€” supports narrowing down large datasets using combinations of criteria. * **Policy-aligned** β€” fields and visibility can be configured to respect privacy and governance rules. *** ### 3. Configuration overview Advanced search is **configurable per event type** (for example, birth, death, marriage). Configuration defines: * Which fields appear on the **advanced search form**. * How those fields are grouped (for example, Registration details, Child’s details, Mother’s details). Key principles: * Only include fields that help meaningfully narrow down results. * Avoid including sensitive fields that are not needed for search. * Ensure configuration is aligned with country policy on who may search for which records. #### Access control and scopes Quick search & advanced search is always subject to the standard access control model: * Users only see records that their **scopes and jurisdictions** allow. * Search results never include records outside the user’s permitted scope, even if the identifier matches Access to search (quick search and advanced search) is controlled by **search scopes** on the user’s role. * `search[event= placeOfEvent=my-administrative-area]` where `` is the relevant event type (for example, `birth`, `death`, `marriage`). To learn more about users scopes please refer to Users, Jurisdictions *** ### 4. Worked example Below is an example of how advanced search for birth records might be configured. **Business requirement:** Users can perform an advanced search for birth records based on registration, child, mother and father details #### Configuration input | Section | Data | ... | | ------------------------ | ------------------------------- | --- | | **Registration details** | Record status | | | | Place of registration | | | | Date of registration | | | | Time period since status change | | | | | | | **Child’s details** | First name(s) | | | | Last name | | | | Date of birth | | | | Place of birth | | | | | | | **Mother’s details** | First name(s) | | | | Last name | | | | Date of birth | | | | | | | **Father’s details** | First name(s) | | | | Last name | | | | Date of birth | | | | | | | | | | # Aggregated Data ## Overview As part of the **Functional Architecture**, the **Aggregate Data** section describes the aggregation and analytics module in OpenCRVS β€” how data from records and workflows is combined for reporting and statistics. It is organised into the following modules: * **Performance Views** β€” describes performance dashboards (for example, workload, timeliness, rejection rates, correction volumes) built using Metabase on top of aggregated data. * **Vital Statistics Export** β€” explains how registered records are transformed into tabular exports and dashboards for vital statistics production and monitoring. * **Person Centricity (backlog)** β€” shows how records can be linked around a person (for example, using UINs or probabilistic matching) to support person‑centric analytics and life‑course views. Together, these modules describe how OpenCRVS data can be aggregated, visualised, and used for performance management and vital statistics, while keeping individual record data secure. # Performance dashboards ### 1. Introduction In OpenCRVS, **performance dashboards** surface near real-time performance and vital statistics data using configurable dashboards powered by **Metabase**. They are used by operational managers, programme leads, and policy makers to monitor workload, coverage, timeliness, completeness, and data quality across locations and over time. Dashboards draw on aggregated, de-identified data rather than individual records, helping to answer questions such as how many events were registered, how quickly, and where there are gaps in coverage. *** ### 2. Feature overview Performance dashboards provide a **near real-time view** of how the CRVS system is performing, using aggregated, de-identified data. #### Core capabilities With performance dashboards, OpenCRVS supports: * **Configurable metrics and visualisations** built on analytics-ready datasets from OpenCRVS. * **Policy and planning insights** based on trends in births, deaths, and other events. * **Role- aware views** so users see dashboards relevant to their responsibilities and jurisdiction. * **Operational monitoring** of workload, bottlenecks, and data quality by office, role, and event type. * **Programme oversight** for coverage, timeliness, and completeness of registration across locations and time periods. Performance dashboards are: * **Aggregated and de-identified** β€” driven by analytics fields only, not raw personal data. * **Metabase-powered** β€” implemented as Metabase dashboards connected to OpenCRVS data sources. * **Extensible** β€” countries can add new charts, filters, and dashboards as their CRVS monitoring needs evolve. *** ### 3. Data sources and metrics Performance dashboards rely on structured data from OpenCRVS, including **only fields that have been explicitly marked as suitable for analytics** (that is, form fields with the `analytics = true` property). This ensures that personally identifiable information (PII) is excluded from dashboard datasets. They draw on: * **Event registrations** β€” births, deaths, marriages, and other event types. * **Key timestamps** β€” date of event, date of declaration, date of registration. * **Locations** β€” where events occurred, where they were declared, where they were registered. * **Statuses and flags** β€” Draft, Notified, Declared, Registered, Archived; late registrations; correction requested. * **User and office information** β€” which office and which role performed key actions. From these data, common **metrics** include: * **Volume** β€” number of registrations by event type, time period, and location. * **Timeliness** β€” time from event to registration (for example, within 30 days, 31–365 days, > 1 year). * **Completeness / coverage (proxy)** β€” registrations per 1,000 population or compared against targets (where reference data is available). * **Data quality** β€” share of records rejected, corrected, or with missing key fields. * **Process efficiency** β€” time spent in each status (Declared, Validated, Registered), number of rejections or escalations. Countries can decide which metrics to prioritise based on their CRVS strategy and available reference data. *** ### 4. Configuration overview Performance dashboards in OpenCRVS are delivered using **Metabase**, an open-source business intelligence and analytics platform. Dashboards are created and managed in Metabase and then securely embedded within the OpenCRVS application. From a user perspective, dashboards appear as part of the OpenCRVS interface. From a configuration perspective, they are defined and maintained separately in Metabase. #### How dashboards are integrated Dashboards are: * **Embedded in the OpenCRVS UI** via links in the side navigation. * **Access-controlled by scope and role**, ensuring users only see dashboards and data relevant to their jurisdiction (for example national, provincial, or district level). #### What is configured in Metabase Configuration primarily happens inside Metabase and includes the following components. **Dashboards** Collections of charts that answer specific operational or policy questions (for example registration volumes, timeliness, or completeness). Each dashboard typically aligns to a use case such as: * Completness rates * Registrations * Operations monitoring * Data quality **Datasets / models** Analytics-ready tables or models that structure OpenCRVS data for reporting. These commonly include: * Event β€œfact” tables (registrations, actions, timestamps) * Dimensions (event type, date, location hierarchy, office, role, status) * Pre-calculated indicators (for example timeliness buckets or monthly aggregates) Using curated models improves consistency, performance, and reuse across multiple dashboards. **Metrics (data visualisation)** Charts and tables that present metrics in an interpretable way, such as: * Time series trends * Bar or stacked charts by location or event type * KPIs and summary cards * Tables for operational detail Metrics are built on top of datasets and reused across dashboards where needed. **Filters** Interactive controls that allow users to narrow the data displayed, for example: * Date of event * Event type * Event location * Registration location Filters can apply to individual charts or entire dashboards to support flexible exploration. **Access control** Role-based permissions determine: * Which dashboards a user can open * What event data they can view based on their jurisdiction This ensures that sensitive operational insights are visible only to authorised users while supporting decentralised monitoring. #### Extending and maintaining dashboards Dashboards are designed to evolve as country needs change. Teams can: * Add new charts or metrics * Create additional dashboards for new programmes * Refine models as data structures mature * Introduce new analytics fields as forms are updated (with `analytics = true`) Because dashboards are configuration-driven rather than hard-coded, updates can be made without changes to the core OpenCRVS application. *** ### 5. Use and interpretation Performance dashboards should be interpreted in context: * **Data lags** β€” some indicators may be based on partial data if registrations are still being processed. * **Population denominators** β€” coverage estimates depend on the quality of population estimates or target numbers. * **Operational factors** β€” spikes in workload or outages can affect short-term trends. Dashboards are most powerful when used as part of a regular **review and action cycle**, for example: * Monthly or quarterly performance review meetings. * Joint analysis sessions between CRVS, health, and statistics stakeholders. * Targeted support or supervision for offices with persistent performance or data quality issues. OpenCRVS provides the underlying data and integration to support these dashboards; each country decides which indicators to track, how often to review them, and what actions to take based on the insights. # Vital statistics export ### 1. Introduction OpenCRVS supports the export of **vital statistics data** by configuring **tabular dashboards in Metabase**. Each export dashboard is a **table of records** that: * Is built from OpenCRVS registration data (for example, births, deaths, marriages). * Includes only **non‑PII analytics fields** (fields with `analytics = true`). * Can be **filtered** and **exported** (for example, as CSV) by authorised users. This model is similar to performance dashboards, but focused on **structured tables for export**, rather than charts. It enables National Statistical Offices and other stakeholders to obtain data extracts that are ready for analysis in external tools, while protecting privacy. *** ### 2. Feature overview Vital statistics export provides **structured, analytics-ready tables** that authorised users can filter and download for further analysis outside OpenCRVS. #### Core capabilities With vital statistics export, OpenCRVS supports: * **Regular provision of vital statistics datasets** to national statistics offices and other stakeholders. * **Configurable tabular views** per event type, built from non-PII analytics fields only. * **Flexible filtering** by time period, location, event type, and other dimensions before export. * **Standards-friendly outputs** (for example, CSV) that can be loaded into statistical tools and data warehouses. * Consistent alignment with the **analytics flag** so that only approved fields are exposed. Vital statistics exports are: * **De-identified by design** β€” based on analytics-safe fields, not raw personal data. * **Table-first** β€” focused on rows and columns rather than charts. * **Extensible** β€” countries can add new export tables as indicator needs evolve. *** ### 3. Vital statistics exports configuration overview Vital statistics exports are configured as **tabular dashboards in Metabase** that present rows and columns of data ready for download. They draw on the same underlying OpenCRVS data as performance dashboards. * Only fields from forms marked with `analytics = true` are included in exportable datasets. * Personally identifiable information (PII) such as names, exact addresses, and contact details must **not** be marked as analytics and therefore never appear in exports. * Data is typically **aggregated or de‑identified** at the row level (for example, including age, sex, district, and dates, but not names or IDs). Each export dashboard typically defines: * **Rows** β€” the unit of analysis (for example, one row per registered birth, one row per registered death). * **Columns** β€” which analytics fields are included (for example, year of event, district, sex, age group, place of occurrence). * **Filters** β€” parameters that users can adjust before export (for example, year, event type, district). Examples of fields commonly included: * Event type, date of event, date of registration. * Sex, age groups, place of occurrence (for example, facility vs home). * Registration location (district / province). * Flags such as late registration or correction requested (where appropriate for statistics). *** ### 4. Use cases Vital statistics export dashboards support common CRVS and statistics use cases, such as: * Preparing **annual vital statistics reports** (for example, births and deaths by age, sex, and district). * Supplying data to the **National Statistics Office** or Ministry of Health for integration into broader statistical systems. * Supporting **research and planning**, such as analysing mortality patterns or fertility trends over time. By configuring export dashboards carefullyβ€”selecting only analytics‑safe fields and appropriate filtersβ€”countries can maximise the value of their OpenCRVS data while maintaining strong privacy protections. # Person centricity ### 1. Introduction In OpenCRVS, **person‑centric views** are a planned feature in the backlog. They are not yet built, but this page describes the current understanding of the concept and requirements. Today, OpenCRVS functions as a **standard civil registration system** that records the specifics of each civil event (for example, a birth or death) in an electronic registry. Person‑centric views extend this by linking event records at the **person level**, providing a unified view of life events linked to an individual where this is legally permitted and technically possible. *** ### 2. Feature overview (proposed) Person‑centric views aim to provide a **single, supervised view** of all relevant life events for a person, while respecting existing access control, privacy, and legal constraints. **Core capabilities (proposed)** With person‑centric views, OpenCRVS could support: * **Linking vital event records** (birth, death, marriage, and others) to an individual using available identifiers and safe matching rules. * **Consolidated person overviews** that show a person’s registration history to authorised staff. * **Suggested links** based on probabilistic matching, which users can confirm or reject. * **Safer data reuse** in forms and workflows by reusing verified person‑level information across events. * **Improved data quality checks** by highlighting gaps and inconsistencies across a person’s events. These capabilities are subject to further design and country‑level governance decisions. The rest of this page outlines the current, high‑level model and requirements for such a feature. The goal of person‑centric views is to: * Link **vital event records** (birth, death, marriage, etc.) to an **individual person** using available identifiers (for example, National ID, Registration number, or another UIN). * Present a **single, consolidated view** of that person’s life events to authorised civil registration staff. * Support **safe, supervised linkage** by showing probable matches that a user can **confirm or reject**. This will help civil registration authorities: * Understand a person’s **full registration history** (for example, birth β†’ marriage β†’ death). * Detect potential **gaps or inconsistencies** (for example, death registered without a corresponding birth registration). * Improve the quality and usefulness of data for planning and interoperability with other systems. *** ### 3. Linking model Person‑centric views rely on a combination of: * **Deterministic links via UINs** * When a record contains a stable identifier (for example, National ID from MOSIP, or a person‑level UIN), OpenCRVS can link records that share that identifier. * **Probabilistic matching for suggestions** * Where no shared UIN exists, OpenCRVS can propose **probable matches** based on attributes such as name, date of birth, sex, and location. * These suggestions are **not applied automatically**; they require human review. Each person‑centric view will therefore be based on: * A **person anchor** (for example, a National ID or a synthetic person ID). * A set of **linked event records** (confirmed links). * A set of **suggested event records** (pending review by a user). *** ### 4. User experience #### 3.1 Person overview From a person‑centric view, an authorised user can see: * **Person header** * Core identifiers (for example, National ID, Registration number, synthetic person ID). * Basic attributes (for example, name, date of birth, sex), where permitted. * **Timeline or list of events** * Birth registration. * Marriage(s). * Death registration. * Other configured event types (for example, adoptions, name changes), when available. This gives civil registration staff a **β€œlife course”** view for that individual. #### 3.2 Probable matches and confirmation When OpenCRVS identifies potential links (for example, a death record that might correspond to an existing birth registration), the UI will: * Show a **β€œSuggested links”** section listing **probable matches**, with a similarity score or short explanation (for example, same name, same date of birth, same National ID). * Allow the user to **review each suggestion** side‑by‑side: * Suggested event record details. * Current set of linked events. * Provide explicit actions: * **Confirm link** β€” permanently link the event record to this person. * **Reject link** β€” mark that this record should *not* be linked, so the same suggestion is not shown again. All confirm / reject decisions will be: * Controlled by **scopes** and **roles** (for example, only certain roles can confirm cross‑event links). * Written to the **audit log** so that future reviews can see who linked which records, and when. *** ### 5. Configuration and controls To support person‑centric views safely and flexibly, configuration will cover: * **Identifiers used for linking** * Which UINs and external IDs can be used as person anchors (for example, National ID, synthetic person ID). * **Matching rules for suggestions** * Which fields to compare (for example, full name, date of birth, sex, location). * Thresholds for suggesting vs ignoring a potential match. * **Permissions and scopes** * Scopes such as `person.view` and [`]()[person.link]()[`](http://person.link/) to control who can see person‑centric views and who can confirm/reject linkage. * **Privacy and data protection** * Ensuring that visibility of person‑level aggregates and event history follows existing jurisdiction and role rules. * Avoiding person‑centric views in contexts where person‑level aggregation is not legally permitted. *** ### 6. Benefits Once implemented, person‑centric views will: * Help civil registration staff **see the whole picture** for an individual, not just separate event records. * Enable **smarter forms and business rules**, for example: * Pre‑populating event forms with known information about a person (for example, name, date of birth, sex, previous events) once they are linked. * Conditionally enforcing what events can and cannot be declared based on existing life events (for example, preventing a second marriage declaration when an active marriage already exists, or flagging unusual sequences). * Support **better governance and error detection**, such as: * Identifying unlinked deaths for people with known birth registrations. * Spotting inconsistent information across events. * Lay groundwork for **stronger interoperability** with identity, social protection, and health systems by making it easier to align person‑level data while keeping CRVS records authoritative. This feature is currently in the **backlog** and will require further design of the matching logic, UI patterns for suggested links, and the security model for person‑level views. # Access # Applications ### 1. Introduction In OpenCRVS, **Applications** describes how people access the system in practice: * The **core OpenCRVS interface** that most registration staff use every day in their browser (or installed as a PWA). * Optional **custom applications ("side apps")** that connect to the OpenCRVS backend eRegistry using APIs for specialised use cases. This page explains when the core interface is sufficient, and when a country may decide to build additional side apps. *** ### 2. Core OpenCRVS interface OpenCRVS provides a core web interface for registration staff, built as a responsive progressive web application (PWA) that works on mobile phones, tablets and desktop devices. The core interface is the primary way that registrars and other authorised users interact with the eRegistry. It provides: * **Event registration workflows** for births, deaths, marriages and other civil events, including notification, declaration, review, registration, correction and revocation. * **Workqueues** that show users the records they need to work on, filtered by role, scope and location (for example: "New birth declarations to review" or "Corrections awaiting approval"). * **Search and retrieval** of registered records, with support for protected records and audit. * **Offline working** so that users can capture and process records even when connectivity is unreliable, with actions queued in an Outbox and synchronised when a connection is available. * **Outputs and communications**, such as printing certificates and certified copies, and sending SMS or email notifications when actions are completed. The core interface runs in a browser and can be installed to a device home screen like an app. It is designed for day‑to‑day use by registration staff in offices, health facilities and mobile registration teams. *** ### 3. Custom applications ("side apps") Although most business needs can be met using the core interface, countries may also develop custom applications that interact with the OpenCRVS backend eRegistry using standard APIs. These are often referred to as **"side apps"**. Side apps: * Are built and maintained outside the core OpenCRVS codebase. * Use OpenCRVS APIs and authentication to read and write records in the eRegistry. * Implement specialised user interfaces and workflows for specific use cases or user groups. * Must follow the same data protection, security and audit requirements as the core interface. Side apps are optional. They should only be introduced where there is a clear need that is not well served by the standard OpenCRVS interface. #### 3.1 Example custom app: digitisation app for historical records A common side app use case is **digitising old paper civil registration records**. In this scenario: * The country has a large volume of historical paper records (for example, birth and death registers stored in district offices or archives). * A dedicated digitisation team is contracted to scan and capture these records into the OpenCRVS eRegistry. * The team uses a custom digitisation app, designed for high‑throughput data entry and document capture. A digitisation side app: * Allows operators to **scan or photograph** pages from old paper registers. * Provides **data entry forms** that map to the same event data model used by OpenCRVS, including mandatory and optional fields. * Validates data locally and then **submits records via the OpenCRVS APIs** into the eRegistry as declarations or as directly registered events, depending on the agreed business rules. * Records **who digitised each record and when**, so that audit trails remain complete. * May support **batch processing**, so that many records from a single book or time period can be captured efficiently. The digitisation app does not replace the core OpenCRVS interface. Instead, it complements it by providing a specialised tool for one task: converting historical paper records into structured, searchable digital records in the same eRegistry that serves routine day‑to‑day registration. # Security ### 1. Introduction OpenCRVS includes several built-in features to protect access to the system and reduce the risk of unauthorised use: * Username and password-based authentication. * Two-factor authentication (2FA) using SMS or email. * A PIN to quickly lock and unlock the application on a device. These features work together to ensure that only authorised users can sign in, and that sessions remain protected even when devices are shared or temporarily unattended. *** ### 2. Feature overview Authentication and session security provide a **multi-layered approach to protecting user access**, ensuring that identities are verified at login and that active sessions remain protected throughout daily work. #### Core capabilities With authentication and session security, OpenCRVS supports: * **Unique username and password credentials** for every user account. * **Temporary passwords and mandatory first-login password change** during onboarding. * Optional **two-factor authentication (2FA)** using SMS or email verification codes. * **Time-limited one-time codes** to prevent replay or reuse during login. * A **screen lock PIN** for quickly securing active sessions without full re-authentication. * **Administrative password reset and recovery workflows** through User Management. * Automatic **audit logging** of authentication events, credential changes, and security actions. Authentication and session security are: * **Identity-based** β€” every action is tied to a unique named user. * **Layered** β€” multiple controls protect both login and active sessions. * **Configurable** β€” deployments can enable or require 2FA based on policy. * **Auditable** β€” all authentication and recovery events are recorded in User Audit. *** ### 3. Username and password Each OpenCRVS user is issued a **unique username and password**. #### Username * Automatically generated when the account is created * Serves as a stable identifier across the system * Appears in audit logs and activity records #### Password * Initially issued as a **temporary password** * Must be changed on first login * Can be reset through self-service or by an administrator * Never displayed in clear text to administrators *** ### 4. Two-factor authentication (2FA) OpenCRVS can require **two-factor authentication (2FA)** to strengthen login security. #### Behaviour 1. User enters username and password 2. System prompts for a one-time verification code 3. Code is delivered via SMS or email 4. User enters the code to complete login The 2FA code is: * Time-limited to 10 minutes * Codes can only be used once * Invalid or expired codes result in login failure * All challenges and outcomes are logged *** ### 5. Screen lock PIN OpenCRVS supports a **screen lock PIN** to protect active sessions on a device. This allows users to quickly secure their session without fully signing out. #### Behaviour * After inactivity, the lock screen is shown * User enters their PIN to continue * Multiple incorrect attempts may require full re-authentication The PIN is: * Device- and session-specific * Faster than full login * Logged as part of session activity This feature is particularly useful in shared offices or mobile field environments. *** ### 6. How these features work together These controls operate together to provide layered protection: * **Username + password** verify the user’s identity * **2FA** confirms control of a trusted communication channel * **Screen lock PIN** protects an authenticated session Combined with scoped permissions and role-based access control, these mechanisms help maintain a secure, accountable environment for civil registration operations. # User management ### 1. Introduction OpenCRVS provides user-friendly tools for administering user accounts and access across the civil registration system. System administrators can: * Create and edit user profiles * Assign offices and roles * Support users with login issues * Reset credentials * Deactivate and reactivate accounts * Review a full audit history of user actions All administrative actions are automatically recorded in **User Audit**, supporting transparency, accountability, and compliance with governance requirements. > **Note** > > Roles and permission scopes are not configured through the User Management interface. > > Role definitions and scope assignments are set by system developers or implementers during system configuration. *** ### 2. Feature Overview User Management provides a **secure, controlled way to administer system access** across offices and jurisdictions, ensuring that only authorised personnel can view, create, and manage user accounts. #### Core capabilities With **OpenCRVS** User Management, the system supports: * Creation of **role-based user accounts** aligned to organisational structure (eg. National Administrator, State Administrator). * **Scoped access control** that limits which users an administrator can view or manage. * Editing of **user profile information**, roles, and office assignments. * **Credential support actions**, including username reminders and password resets. * **Account lifecycle management**, including activation, deactivation, and reactivation. * Automatic **audit logging** of all administrative actions for compliance and accountability. User Management is: * **Scope-driven** β€” permissions determine what each administrator can see and modify. * **Organisation-aware** β€” access follows office and jurisdiction boundaries. * **Security-focused** β€” credentials and access can be quickly recovered, restricted, or revoked. * **Fully auditable** β€” every change to a user account is recorded in User Audit. *** ### 3. Configuration Overview #### 3.1 Viewing organisations These scopes grant users the ability to browse the administrative structure and view office team pages | Scope | Description | | --------------- | ----------------------------- | | `organisation` | View all office locations | | `organisation:` | View only their team location | *** #### 3.2 Viewing user profiles and audit history These scopes grant a user the ability to view a user’s profile and audit history. | Scope | Description | | --------------------------- | --------------------------------------- | | `user.read:all` | View all users in the country | | `user.read:my-jurisdiction` | View users within the same jurisdiction | | `user.read:my-office` | View only users in the same office | *** #### 3.3 Creating users These scopes grant a user the ability to create users | Scope | Description | | ----------------------------- | ---------------------------------------------- | | `user.create:all` | Create and assign users to any office | | `user.create:my-jurisdiction` | Create users only within the same jurisdiction | **Example** An administrator in a State Office with `user.create:my-jurisdiction` can create users for any District office within that State, but not for other States. *** #### 3.4 Updating users These scopes grant a user the ability to update a user. * Editing user details * Sending username reminders * Resetting passwords * Deactivating/reactivating accounts | Scope | Description | | ----------------------------- | ----------------------------------------- | | `user.update:all` | Update any user | | `user.update:my-jurisdiction` | Update users within the same jurisdiction | *** ### 4. User Management Actions #### 4.1 Creating users From the **Office view**, authorised administrators can create new user accounts for that location. **Required details** | Data | Description | | ----------------- | --------------------------------------------------------------- | | First name(s) | User’s given name(s) | | Last name | User’s family name | | Phone number | Used for SMS notifications and login support | | Email address | Used for email notifications (if enabled) | | National ID (NID) | Unique identifier where required | | Role | e.g. Registration Agent, Registrar, National Registrar | | Digital signature | Required for Registrar or National Registrar roles | | Device | Assigned mobile or web device (if device assignment is enabled) | **Output** * Username is generated automatically (e.g. Jane Smith β†’ `j.smith`) * Temporary credentials are sent via SMS or email * User completes onboarding at first login * Event is recorded in **User Audit** *** #### 4.2 Updating users Administrators can update user information from the **Office view** or **User Audit**. **Steps** 1. Locate the user 2. Open the menu (β‹―) 3. Select **Edit user** **Editable fields** * Assigned office * Name * Phone * Email * National ID * Role * Digital signature * Device All changes are logged. *** #### 4.3 Sending a username reminder Administrators can send a reminder if the user cannot retrieve their username. #### Steps 1. Locate the user 2. Open the menu 3. Select **Send username reminder** The username is sent via SMS or email. *** #### 4.4 Resetting a password Users can reset passwords themselves, but administrators can assist when necessary. #### Steps 1. Locate the user 2. Open the menu 3. Select **Reset password** The system: * Sends a temporary password * Requires password change at next login *** #### 4.5 Deactivating a user Deactivation removes access while preserving the account and history. #### When to use * User leaves employment * Temporary suspension * Suspected misuse * Security concerns #### Steps 1. Locate the user 2. Open the menu 3. Select **Deactivate** 4. Choose a reason and optionally add comments Once deactivated, the user cannot log in. *** #### 4.6 Reactivating a user Administrators can restore access when appropriate. #### Steps 1. Locate the deactivated user 2. Open the menu 3. Select **Reactivate** Access is restored according to the user’s current: * Role * Office * Scopes *** ### 5. User onboarding New accounts are created in a **pending** state. The user activates their account by completing onboarding at first login. **Steps** 1. Receive username and temporary password (via SMS or email) 2. Log in and create a new password 3. Set security questions 4. Confirm profile details, assigned office, and role Once complete, the account becomes **active** and the user signs in with their new password. *** ### 6. Audit and Accountability All user management actions are automatically recorded, including: * Creation * Edits * Role changes * Password resets * Deactivation/reactivation Audit logs provide: * Timestamp * Administrator performing the action * Type of change * Before/after values This supports compliance, investigations, and operational transparency. *** ### 6. Summary OpenCRVS User Management enables administrators to securely control system access through scoped permissions and organisational boundaries. Key benefits include: * Controlled access based on jurisdiction * Secure onboarding and credential recovery * Temporary or permanent access removal * Full audit history of all administrative actions Together, these features ensure a secure, accountable, and maintainable user administration model for civil registration operations. # Interoperability ### 1. Introduction Civil registration systems do not operate in isolation. They exchange information with other government systems to support public services, improve data quality and reduce duplicate data entry. OpenCRVS has been architected from its inception to interoperate with other e-Government systems in a standardised, safe and secure manner. This page provides a high-level overview of interoperability in OpenCRVS and how it relates to [solution architecture](/implementation/your-opencrvs-project/solution-architecture). The detailed technical guidance for implementing integrations is provided in the [integration architecture](/technical/architecture/integration-architecture) and [configuration](/technical/guides/configuration/integrations) documentation. **Where this sits:** Interoperability requirements are identified during **Design & Specification** as part of the solution architecture and are implemented during **Configuration** and **Deployment**. *** ### 2. Why interoperability matters A civil registration system forms part of a wider government digital ecosystem. Depending on national requirements, OpenCRVS may exchange information with systems such as: * National identity systems * Social protection systems * Population registers * Health information systems * Immigration systems * Statistics platforms * Notification services * Digital identity and authentication providers * Other government & private sector applications Interoperability enables information to be shared electronically, reducing manual processes, improving data accuracy and allowing government services to operate more efficiently. {% hint style="info" %} Every integration should have a clearly defined business purpose and should exchange only the information required to support that purpose. Integration should not be "gamified" at the expense of privacy and consent. {% endhint %} *** ### 3. Interoperability and solution architecture Before any integrations are developed, the project's [Solution Architecture](/implementation/your-opencrvs-project/solution-architecture) defines how OpenCRVS fits within the wider government technology landscape. The solution architecture helps identify: * which external systems need to communicate with OpenCRVS * the direction in which information flows * the business events that trigger data exchange * the security, privacy and governance requirements for each integration * the responsibilities of each participating system Developing the solution architecture early ensures that interoperability requirements are agreed before implementation begins and that all stakeholders understand how OpenCRVS will interact with the surrounding digital ecosystem. *** ### 4. How OpenCRVS supports interoperability OpenCRVS provides a flexible interoperability framework that allows external systems to exchange information securely without modifying the core platform. At a high level, interoperability is achieved through two complementary mechanisms: [Application Programming Interfaces (APIs)](/functional/markdown/interoperability/apis) β€” OpenCRVS provides a range of APIs designed for different consumers and business use cases. These APIs allow authorised systems to securely retrieve information from OpenCRVS, submit information to OpenCRVS or perform approved business operations. [Action Triggers](/functional/markdown/interoperability/action-triggers) β€” OpenCRVS can automatically notify external systems when defined business events occur, such as the registration or certification of a vital event. This enables other government systems to respond automatically without requiring manual intervention. Together, APIs and Action Triggers enable OpenCRVS to participate in event-driven government architectures while maintaining clear security boundaries and auditability. *** ### 5. Designing interoperable solutions Interoperability should always be driven by business requirements rather than technology. When planning integrations, implementation teams should consider: * the business outcome the integration is intended to achieve * which system owns each item of information * when information should be exchanged * what level of security, authentication and authorisation is required * how failures, retries and audit trails will be managed These decisions are captured within the solution architecture before technical implementation begins. *** ### 6. Resources and support For further guidance, see: * [Solution Architecture](/implementation/your-opencrvs-project/solution-architecture) – understanding how OpenCRVS fits within the wider government ecosystem. * [Integration Architecture](/technical/architecture/integration-architecture) – defines how OpenCRVS connects securely with a country's wider digital ecosystem, enabling it to exchange information with external systems while remaining agnostic. * [Integration Configuration](/technical/guides/configuration/integrations) – technical guidance on configuring event-driven integrations with external systems. * [ID Integration & MOSIP](/functional/markdown/interoperability/mosip-id-integration) - Integrating OpenCRVS with a National ID system creates a trusted foundation for legal identity, ensuring that vital events automatically support accurate and secure identity management throughout life. These guides describe how to implement secure integrations using these capabilities while following OpenCRVS architectural principles. # APIs ### 1. Introduction This page is a functional overview of the APIs OpenCRVS supports β€” what each one is for, who uses it, and how they fit together. It is the orientation layer above the detailed reference: each API is documented endpoint-by-endpoint in an OpenAPI specification, generated directly from the codebase and linked throughout this page. OpenCRVS is API-first. All capabilities are exposed over **REST**, described with **OpenAPI**, so that clients, country configurations and external government systems can integrate against a stable, documented contract. *** ### 2. The API landscape OpenCRVS exposes three distinct API families, each serving a different audience: * **Core APIs** β€” exposed by OpenCRVS Core through its gateway. This is the system of record for civil registration. * **Country-config APIs** β€” exposed by each country's own configuration server. This is the country's integration and policy layer, and the peer that Core calls. * **Toolkit** β€” a TypeScript package (`@opencrvs/toolkit`) that is the developer-facing API for *building* a country configuration. It is a code-level interface rather than an HTTP API. ```mermaid flowchart LR Clients["OpenCRVS clients (web / mobile)"] -->|REST via gateway| Core["Core APIs"] Core <-->|"webhooks / interception"| CC["Country-config APIs"] Ext["External & government systems"] -->|preferred| CC Ext -. "discouraged" .-> Core Toolkit["@opencrvs/toolkit"] -. "builds" .-> CC ``` *** ### 3. Core APIs The Core APIs are exposed by OpenCRVS Core through the API gateway. They are used by the OpenCRVS client applications and, where appropriate, by the country configuration server acting on a record's behalf. | API | What it does | Reference | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | **Events** | Create and act on civil registration records β€” declare, validate, register, correct and certify. The authoritative source of truth for every event. | [Events](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis/events) | | **Search** | Query and list records quickly (Elasticsearch-backed), powering search screens and reporting. | [Search](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis/search) | | **Locations** | Read the administrative hierarchy and facilities used across records. | [Locations](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis/locations) | | **Integrations** | Register and manage the system clients used for system-to-system integration. | [Integrations](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis/integrations) | | **Attachments** | Upload and retrieve supporting documents, backed by S3-compatible storage. | [Attachments](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis/attachments) | | **Models** | The shared data models and schemas referenced by the other Core APIs. | [Models](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis/models) | The full specification is published as the [Core OpenAPI spec](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis). *** ### 4. Country-config APIs Core is country-agnostic, so country-specific behaviour lives in a configuration server that each country owns and runs. The Country-config APIs are the endpoints that server exposes. Core calls them on every meaningful event β€” to deliver notifications and to intercept, approve or reject registration actions β€” and they double as the country's stable contract for any external system that needs to integrate (see section 6). | API | What it does | Reference | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | **Events** | The endpoints your country configuration exposes for Core to call on each event: sending notifications, and intercepting actions to approve or reject them. | [Events](https://documentation.opencrvs.org/v2.0/technical/apis/country-config-apis/events) | | **Models** | The shared schemas for country-configuration payloads. | [Models](https://documentation.opencrvs.org/v2.0/technical/apis/country-config-apis/models) | The full specification is published as the [Country-config OpenAPI spec](https://documentation.opencrvs.org/v2.0/technical/apis/country-config-apis). *** ### 5. Toolkit The [`@opencrvs/toolkit`](https://documentation.opencrvs.org/v2.0/technical/apis/toolkit) package is the primary dependency for building a country configuration. Rather than an HTTP API, it provides typed TypeScript builders and helpers, so that configuration is written in code and validated at compile time. | Module | What it does | Reference | | ----------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Configuration** | Typed builders for defining events and forms, including advanced search configuration. | [Configuration](https://documentation.opencrvs.org/v2.0/technical/apis/toolkit/configuration) Β· [Advanced search](https://documentation.opencrvs.org/v2.0/technical/apis/toolkit/configuration/advanced-search) | | **Conditionals** | Builders that return JSONSchema for field and action conditionals; combine them with `and`, `or` and `not`. | [Conditionals](https://documentation.opencrvs.org/v2.0/technical/apis/toolkit/conditionals) | | **Deduplication** | Builders for defining duplicate-detection rules. | [Deduplication](https://documentation.opencrvs.org/v2.0/technical/apis/toolkit/deduplication) | | **API Client** | A typed client for calling the Core APIs from your country configuration. | [API Client](https://documentation.opencrvs.org/v2.0/technical/apis/toolkit/api-client) | {% hint style="info" %} **Match the version.** The toolkit version must match your OpenCRVS Core version exactly β€” for OpenCRVS 2.0.0, install `@opencrvs/toolkit@2.0.0`. When upgrading, upgrade the toolkit first so configuration breaking changes surface at compile time. {% endhint %} *** ### 6. Integrating with OpenCRVS {% hint style="info" %} **Integrate through country config, not Core directly.** External and government systems should route through the Country-config APIs rather than calling the Core APIs directly. Country config is the country's trust and policy boundary β€” it owns authorisation, audit and data-shaping, and it insulates integrators from changes to Core's internal APIs. {% endhint %} Requests are authenticated in one of two ways: * **User JWT** β€” a token representing a signed-in user. The request is performed as that user, with that user's permissions. Appropriate when acting on behalf of a specific human action. * **System client token** β€” a service-to-service token issued for a registered system client. Appropriate for background jobs and any flow with no human user in the loop. Tokens are signed with RS256, and the matching public key is published at the `/.well-known` endpoint so downstream services can verify them without sharing secrets. *** ### 7. Standards and versioning The Core and Country-config APIs are **REST** and described with **OpenAPI**; the specifications are generated automatically from the codebase, so they stay in step with the running system. Releases follow semantic versioning (`MAJOR.MINOR.PATCH`). Patch releases are always backwards-compatible. Minor releases may change country-config contracts but never require a data migration; data migrations are reserved for major releases. For the full list of standards the platform conforms to, see the [Standards](https://documentation.opencrvs.org/v2.0/technical/architecture/standards) page. *** ### 8. Resources and support * [Core OpenAPI spec](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis) β€” Events, Search, Locations, Integrations, Attachments, Models. * [Country-config OpenAPI spec](https://documentation.opencrvs.org/v2.0/technical/apis/country-config-apis) β€” Events, Models. * [Toolkit](https://documentation.opencrvs.org/v2.0/technical/apis/toolkit) β€” Configuration, Conditionals, Deduplication, API Client. * [Integration architecture](https://documentation.opencrvs.org/v2.0/technical/architecture/integration-architecture) β€” how Core and country config communicate. # Action triggers ### 1. Introduction **OpenCRVS** provides a flexible, event-driven way for countries to extend and customise system behaviour through **action triggers.** Action triggers allow country implementations to react to important actions performed on civil registration records β€” such as declarations, registrations, approvals, certificate printing, or user management events. Instead of embedding integrations and notifications inside the core system, OpenCRVS delegates control to the country configuration, enabling safer upgrades, greater flexibility, and full ownership of business logic. This approach replaces the earlier single notification endpoint used in v1.x and introduces a generalised, extensible mechanism that works across all life events and workflows. *** ### 2. Feature overview Action triggers enable country configuration packages to: #### Listen to actions across all life events Triggers can be attached to actions such as: * declare * register * approve/reject * print certificate * view * notify * custom actions These apply to **all configured events**, including: * births * deaths * marriages * adoptions * any custom event type *** #### Access the complete record When a trigger fires, the configuration service receives: * the full record document * all form data * metadata * the complete change history This supports: * statistical reporting * audit trails * compliance checks * downstream integrations *** #### Send fully customised notifications Countries control: * SMS templates * Email templates * Language logic * Message timing Notifications can use any field from the record payload, enabling personalised, branded communication. *** #### Integrate with external systems Triggers provide a clean integration point for: * national ID databases * population registers * health systems * payment gateways * document management systems * analytics pipelines Typical use cases: * validating identity numbers * generating national IDs * syncing data to other ministries * exporting statistics *** #### Pause or intercept workflows Triggers can temporarily **hold the workflow** while processing: * return `202 Accepted` to pause * perform async validation or external calls * confirm completion later This ensures data integrity before registration is finalised. *** #### Handle user lifecycle events Triggers are also available for system users. | Endpoint | Purpose | | ------------------------------------ | -------------------------------------------- | | `POST /triggers/user/user-created` | Send welcome or onboarding messages | | `POST /triggers/user/reset-password` | Send customised password reset notifications | *** ### 4. Worked example #### Business requirement: Send confirmation SMS on marriage registration When a marriage is registered: 1. Send confirmation SMS 2. Include name of bride and groom 3. Include registration number 4. Include the next steps to collect marriage certificate #### Configuration Code: Register trigger endpoint ``` POST /triggers/events/marriage/actions/register ``` Implement logic ```jsx server.route({ method: 'POST', path: '/triggers/events/marriage/actions/register', handler: async (request, h) => { const record = request.payload // Send SMS await sendSMS(record.contact.phone, `Marriage registered. Certificate No: ${number}`) return h.response().code(200) } }) ``` All logic remains outside core, in country-configuration making upgrades safe and maintenance simpler. *** ### 5. Summary Action triggers in OpenCRVS provide a powerful, event-driven extension mechanism that: * works across all life events * supports full record access * enables complete notification control * integrates cleanly with third-party systems * allows workflow interception * replaces legacy single-endpoint notifications By moving custom behaviour into country configuration, implementations gain flexibility while keeping the core platform stable and upgradeable. **In short:** action triggers turn OpenCRVS into a highly adaptable platform that can meet each country’s legal, operational, and technical requirements without modifying core code. Examples: MOSIP Email notifications # ID Integration & MOSIP ### 1. Introduction Civil registration and national identity systems are complementary components of a country's digital public infrastructure. While civil registration provides the legal record of vital events throughout a person's life, a National ID system provides individuals with a trusted means of proving their identity when accessing government and private sector services. This page provides a high-level overview of why countries integrate OpenCRVS with National ID systems and how OpenCRVS supports these integrations. The detailed implementation guidance is provided in the technical interoperability documentation. **Where this sits:** National ID integration requirements are identified during **Design & Specification** as part of the solution architecture and implemented during **Configuration** and **Deployment**. *** ### 2. Why integrate OpenCRVS with a National ID system? Civil registration provides the authoritative source of truth for vital events. Every birth, death and other legally recognised event recorded in OpenCRVS represents trusted information that can be shared with other government systems. Integrating civil registration with a National ID system enables governments to automate important identity lifecycle processes. For example: * following the registration of a birth, OpenCRVS can notify the National ID system so that a unique identity can be created for the child at birth * following the registration of a death, OpenCRVS can notify the National ID system that the individual is deceased, helping to prevent identity fraud and the continued use of a deceased person's credentials This close relationship between civil registration and National ID forms the foundation of a nation's identity infrastructure. Together they establish trusted legal identity from birth, support efficient public service delivery and improve the integrity of government records. *** ### 3. Which National ID systems can OpenCRVS integrate with? OpenCRVS is designed to be **National ID agnostic**. It does not depend on any particular identity platform and provides standard interoperability mechanisms that allow it to integrate with whichever National ID solution a country has adopted. The interoperability guidance is organised around common business use cases rather than specific products, allowing the same architectural approach to be applied regardless of the chosen National ID platform. OpenCRVS includes a production-ready integration library for [**MOSIP**](https://www.mosip.io/) and [**e-Signet**](https://www.mosip.io/eSignet) identity verification, both Open Source Digital Public Goods. Dedicated implementation guidance is available for these integrations, building on the same standard interoperability capabilities available to all National ID systems. *** ### 4. National ID integration capabilities OpenCRVS provides configurable integration capabilities that support a range of National ID business processes. At a high level, these include: **Identity verification** β€” authenticate and verify the identity of informants, parents or other participants during the registration process, whether services are delivered online or in person. **Configurable business rules** β€” determine which civil registration events should trigger interaction with the National ID system based on country-specific policies and legislation. **Registration integration** β€” exchange information with the National ID system when a civil registration event is completed. Integrations can operate synchronously where an immediate response is required, or asynchronously where processing occurs independently. These capabilities allow countries to implement National ID integration in a manner that aligns with their own legislation, operational processes and technical architecture. *** ### 5. Designing National ID integrations Successful National ID integration begins with clearly defined business requirements rather than technical interfaces. Implementation teams should first determine: * the business events that should trigger identity processes * which system is authoritative for each item of information * how identity verification should occur * what information should be exchanged * the security, privacy and consent requirements governing the integration These requirements are captured during solution architecture before technical implementation begins. *** ### 6. MOSIP integration MOSIP Integration Phase 3 establishes a configurable, event-driven integration framework between OpenCRVS (civil registration) and MOSIP (digital identity). All integration behaviour is driven by country-level configuration, the OpenCRVS core contains no country-specific logic. | Capability | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------- | | UIN lifecycle management | Manages UIN creation, biographic correction, and life-status changes based on civil registration actions. | | Identity authentication | Authenticate individuals involved in civil registration events using MOSIP e-Signet services. | *** Regardless of country configuration, the OpenCRVS core evaluates every civil registration action against the country’s configured MOSIP integration rules and triggers the appropriate operation. For every civil registration event, OpenCRVS: * Evaluates the (event\_type + action\_type) combination. * Applies the business rules defined in the country’s configuration. * Triggers the mapped MOSIP operation. * Handles success and technical failure states. * Logs resulting outcomes to the record audit history. #### 6.1 Configuration Overview | Event type | Action type | Eligibility rule | MOSIP operation | Response handling | | ---------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------- | | Birth | Register | Configurable per country (e.g. child at birth or foundling) | UIN Creation | Record moves to β€˜Awaiting external validation’ | | Birth (UIN creation on correction) | Approve Correction | Configurable (e.g. informant identity authenticated on correction) | UIN Creation | Record moves to β€˜Awaiting external validation’ | | Birth | Approve Correction | Corrected field is within MOSIP biographic schema and child has not yet enrolled for biometrics (e.g. under 10 years old) | Biographic Data Update | Send and continue: no response from MOSIP is tracked | | Death | Register | Individual has a MOSIP VID | Flag VID as deceased | Send and continue: no response from MOSIP is tracked | {% hint style="info" %} Eligibility rules are evaluated at the point of action execution. If no rule is satisfied, no MOSIP operation is triggered and the record proceeds through the standard OpenCRVS workflow. {% endhint %} *** #### 6.2. ID Lifecycle Management #### 6.2.1 UIN Creation on Registration The primary UIN creation trigger is confirmation of a birth registration by an authorised Registrar. Countries define configurable eligibility rules that determine whether and when a UIN is created. | Parameter | Value | | ----------------- | ------------------------------------------------------------------------------------------ | | Event type | Birth | | Action type | Register | | Eligibility | Configurable per country (e.g. child at birth where MOSIP is enabled) | | Data shared | Configurable set of birth data fields (schema), sent via the MOSIP Packet Manager | | Response handling | Record moves to β€˜Awaiting external validation’ work queue | | On success | On MOSIP confirmation: record moves to 'registered' and a VID is issued to the individual. | {% hint style="warning" %} MOSIP does not return failure responses. Records that stall in 'Awaiting external validation' must be investigated directly with MOSIP and manually removed from the work queue by the country implementation team or system integrator. {% endhint %} {% embed url="" %} *** #### 6.2.2 UIN Creation on Correction A UIN may not have been created at the time of original registration. For example, if eligibility conditions were not met. Phase 3 supports deferred UIN creation, triggered when an approved correction satisfies the eligibility rules. | Parameter | Value | | ----------------- | ------------------------------------------------------------------------------------------ | | Event type | Birth | | Action type | Approve Correction | | Eligibility | Configurable per country (e.g. parent identity authenticated as part of correction) | | Data shared | Configurable schema of birth data fields | | Response handling | Record moves to β€˜Awaiting external validation’ work queue | | On success | On MOSIP confirmation: record moves to 'registered' and a VID is issued to the individual. | {% embed url="" %} *** #### 3.3 UIN Biographic Corrections When a correction approved in OpenCRVS updates biographic information (e.g. name, gender, date of birth) that was previously shared with MOSIP, an updated packet is sent to keep the MOSIP identity record in sync. {% hint style="warning" %} Biographic corrections for individuals already enrolled with biometrics may compromise identity integrity in MOSIP. Consult the MOSIP documentation and your implementation partner before enabling this for your country. {% endhint %}
ParameterValue
Event typeBirth
Action typeApprove Correction
EligibilityCorrected field is within the MOSIP biographic data set (country-configured schema)
Data sharedUpdated biographic fields
Response handlingCorrect and continue: no response from MOSIP is tracked
On successMOSIP updates the biographic record and notifies the informant or subject via SMS or email
{% embed url="" %} *** #### 3.4 Flag Individual as Deceased When a death is registered for an individual with a MOSIP VID on record, OpenCRVS notifies MOSIP to flag the VID as deceased. | Parameter | Value | | ----------------- | ------------------------------------------------------------------------------ | | Event type | Death | | Action type | Register | | Eligibility | Individual has a MOSIP VID stored against the record | | Data shared | Individual’s VID and other country configurable data such as the date of death | | Response handling | Register and continue: no response from MOSIP is tracked | | On success | MOSIP flags the VID as deceased and notifies the informant via SMS or email | {% embed url="" %} *** ### 4. Identity Authentication OpenCRVS supports authentication of all individuals involved in civil registration events via MOSIP’s e-Signet service. Authentication is available for: Informant, Mother, Father, Spouse, Deceased, and Child, where applicable to the event type and country configuration. {% hint style="info" %} Authentication is currently available in all event declaration forms. Support for authentication in the print and correction flows is forthcoming. {% endhint %} *** #### 4.1 e-Signet Authentication Flow Authentication is initiated from within the OpenCRVS declaration form. On success, a configurable set of form fields is pre-populated from the individual’s MOSIP ID schema data. {% hint style="info" %} The field mapping from MOSIP ID schema to OpenCRVS form fields is defined in country configuration. {% endhint %} | UI State | Behaviour | | --------------------------- | --------------------------------------------------------------------------------------------------- | | Loading | Authentication request in progress. | | Authenticated | Authentication confirmed. Configured fields are pre-populated from MOSIP ID schema data. | | CRVS system offline | OpenCRVS cannot reach e-Signet. The e-Signet button is disabled. | | Timeout / technical failure | Request timed out or returned a technical error. Any data already entered in the form is preserved. | When an individual authenticates via e-Signet, MOSIP issues a Partner-Specific User Token (PSUT). This token represents the individual in the context of OpenCRVS as a MOSIP partner, and is stored against the registration record. It allows OpenCRVS to reference the individual’s MOSIP identity in subsequent flows without storing or exposing the UIN. *** #### 4.2 Identity Verification (Offline Ability) Identity verification validates an individual's identity data entered manually or pre-populated via QR code scan against MOSIP records at the point of submission. This supports offline civil registration workflows where e-Signet is not available at the point of data entry.\ \ Verification requests are sent to MOSIP via the MOSIP Authentication SDK once the system is online, which confirms whether the captured data matches a record in the National ID system. {% hint style="warning" %} Offline verification validates that biographic data matches a National ID record but does not authenticate the informant and can cause downstream identity issues. e-Signet authentication is the preferred approach. {% endhint %} | UI State | Behaviour | | ------------------- | ---------------------------------------------------------------------------------------------- | | Scan QR code | QR code scanned and declaration form fields are pre-populated from encoded identity data. | | Pending validation | Identity data is being validated against MOSIP records. | | ID verified | Identity confirmed. Registration can proceed. | | Verification failed | Identity could not be verified. The Registration Agent is prompted to review the entered data. | {% embed url="" %} # Legacy data Legacy data covers OpenCRVS capabilities for bringing historical civil registration records into the eRegistry. There are two related capabilities: * [Data migration](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data/data-migration) β€” for historical records that already exist in a digital source, such as a previous CRVS database, spreadsheet, or another electronic register. * [Digitise paper records](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data/digitise-paper-records) β€” for historical records that exist only in physical sources, such as register books, certificate counterfoils, bound volumes, or archive files. Both capabilities aim to make historical civil registration records usable in OpenCRVS for search, certified copies, correction, reporting, audit and interoperability, subject to the same record lifecycle, access control and configuration principles as records created in OpenCRVS. These Functional Architecture pages describe what OpenCRVS supports and the principles that apply. For project planning and readiness activities, see [Migrate legacy data](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/migrate-legacy-data). For technical implementation guidance, see [Legacy Data migration](https://documentation.opencrvs.org/v2.0/technical/guides/data-migration). # Data migration ### 1. Introduction **Data migration** is the process of bringing civil registration event records that already exist in a **legacy system** β€” a previous registration database, a spreadsheet-based register, or another CRVS application β€” into OpenCRVS, so that they become first-class records in the new eRegistry. A migrated record is not a static archive. Once it is in OpenCRVS it behaves like any other record of the same status: it can be **searched**, used to **print a certified copy**, **corrected**, shared with integrated systems, and counted in reporting. Migration is therefore a prerequisite for OpenCRVS to act as the approved single source of truth from the day a country goes live, rather than leaving staff to consult two systems. This page covers the **migration of existing digital records** from a legacy system. The related task of capturing historical **paper** registers is covered separately under [Legacy paper import](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data); the two share the same data model and many of the same considerations, but differ in how records are captured. {% hint style="info" %} Migration is a milestone in the [Go-live](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/go-live) readiness checklist: legacy digital data migrated, migrated data validated and cleaned, and migration tested and verified **before** go-live. {% endhint %} *** ### 2. Feature overview Data migration lets a country load existing event records into OpenCRVS through its APIs, mapping each legacy record onto the OpenCRVS event data model and giving it the correct status, identifiers and provenance. Migration starts with assessment, not loading. Before using the APIs, the country team should decide which sources are in scope, what legal status each source has, what data quality threshold applies, and what should happen to records that cannot be safely migrated. **Core capabilities** * **Map legacy records to the OpenCRVS event model** β€” each legacy record is transformed into an OpenCRVS event (birth, death, marriage, and so on) with its fields mapped to the configured form fields for that event. * **Land records at the correct status** β€” records are imported as `Registered`, `Declared`, or `Notified` according to business rules approved by the registration authority. A technical team should not infer legal registration status from the existence of a digital record alone. * **Preserve legacy identifiers** β€” legacy registration numbers, book/page/folio references, legacy system IDs, certificate numbers, PIN/UIN/National ID values, and amendment references should be preserved where available and relevant. * **Maintain a complete audit trail** β€” every migrated record records that it was created by a migration/system client, while also preserving original registration provenance where available, such as original registration date, office, registrar, source register, and book/page reference. * **Make records immediately usable** β€” once imported, records are indexed for search and, if registered, available for certified copies, corrections and onward sharing. * **Support batch processing** β€” records are loaded in bulk, in controlled batches, with validation and reconciliation. Migration is: * **API-driven** β€” records enter through the same Core APIs that the OpenCRVS applications use, so migrated records are indistinguishable in behaviour from records created in-product. * **Configuration-aligned** β€” the mapping targets the country's own configured events, forms and locations. * **Auditable** β€” the source and timing of every migrated record is journaled. Migration is NOT: * a substitute for legal approval of the legacy records and their status on the register. * a bulk cleansing exercise for all historical data. * an obligation to migrate every historical source if controlled legacy access is safer. *** ### 3. What migration produces The goal of migration is that a legacy record becomes a **native OpenCRVS record**, subject to the same status model, actions, access control, audit and search behaviour as any other record. A migrated record must arrive at a valid OpenCRVS status. A legacy record that represents a completed legal registration may be imported as `Registered`. A record that is incomplete, uncertain, or requires staff review may be imported as `Declared` or `Notified`, depending on the configured workflow and approved business rules. A digital legacy record is not automatically a completed legal registration. The target status is a registration-authority decision and may vary by source, event type, date range, location or data-quality band. For target-status assessment and sign-off, see [Migrate legacy data](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/migrate-legacy-data). *** ### 4. How migration works Records are migrated through the OpenCRVS **Core APIs** β€” principally the Events API, which is the authoritative source of truth for every record. Migration uses the same record model, actions and audit principles as records created through the OpenCRVS applications. There are two common delivery patterns: #### **4.1 Direct API migration (system client)** A migration script or middleware authenticates as a trusted system client and submits records directly to the Events API. This is the usual approach where the source is already structured, such as a legacy database, spreadsheet, or export from another CRVS system. #### **4.2 Migration via a custom application** Where records need human capture or review, a custom side application can be built against the same APIs. This may be useful for messy legacy data or paper-derived capture where operators need a dedicated high-throughput workflow. {% hint style="info" %} Both patterns write through the same Core APIs, so the resulting records are ordinary OpenCRVS records. The choice between them is about how records are sourced and reviewed, not about what they become. {% endhint %} For technical extraction, transformation, validation, loading, idempotency and reconciliation steps, see [Legacy data migration](https://documentation.opencrvs.org/v2.0/technical/guides/data-migration). *** ### 5. Mapping legacy data to the OpenCRVS model Migrated records must map to the configured OpenCRVS event model. This means the migration must use the country’s configured event types, form fields, identifiers, locations, statuses and attachment rules. OpenCRVS does not provide a generic legacy-data store for unmapped historical data. Data that cannot be mapped to the configured model should either be excluded, retained in the legacy source, or handled through an approved configuration decision. Detailed source assessment, mapping sign-off and exception handling are project activities. See [Migrate legacy data](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/migrate-legacy-data). Technical mapping, validation and loading steps are covered in [Legacy data migration](https://documentation.opencrvs.org/v2.0/technical/guides/data-migration). *** ### 6. Identifiers Migrated records must remain traceable to their legacy origins. Identifier policy affects certificates, search, corrections, reporting, and downstream systems. Decide whether the legacy registration number remains the canonical registration number in OpenCRVS, or whether it is stored alongside a new OpenCRVS number. * **Legacy registration number** β€” preserve the existing registration number on the migrated record so that historical certificates, citizen references and downstream systems continue to resolve. OpenCRVS holds the registration number on the registered record. * **Tracking IDs and internal references** β€” OpenCRVS assigns its own internal identifiers. Plan how legacy internal references are retained (for example, as a stored legacy reference) for reconciliation. * **National ID and other person identifiers** β€” where the legacy record carries a national ID or similar, map it onto the corresponding person field so future search and linkage work correctly. Where a national ID or UIN depends on civil registration numbers, reconcile those identifiers before go-live and confirm how they will appear on migrated records, certificates, and integrations. {% hint style="info" %} Decide your registration-number policy explicitly: keep the legacy number as the canonical number, or store it alongside a newly issued OpenCRVS number. This affects certificates, search and every integrated system that references the record. {% endhint %} *** ### 7. Administrative structure and historical locations Migrated records may reference several different location concepts: place of event, place of registration, current office, historical office, and source office. These may not be the same, especially where administrative boundaries, facility names, or office responsibilities have changed. Each location used by a migrated record must resolve to an entry in the OpenCRVS [administrative hierarchy](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/administrative-structure), not remain as free text. * **Map legacy place names to configured locations.** Build a lookup from legacy place names to OpenCRVS administrative areas and facilities. Historical-to-current location mapping decisions should be documented for traceability. Spelling variants, renamed areas and merged districts all need resolving during transformation. * **Locations are archived, never deleted.** A location that is no longer in use can be archived but is retained, precisely so that the historical name on an older record is preserved. This protects the integrity of migrated records that reference places no longer used for new events. {% hint style="danger" %} **Roadmap limitation β€” historical administrative structures.** Full versioning of the administrative structure over time (so that a record can reference an area exactly as it existed at the historical event date) is a planned capability and is **not yet available**. Until it lands, legacy records that reference abolished or restructured areas must be mapped to the nearest appropriate current or archived location, and that mapping decision should be documented. {% endhint %} *** ### 8. Data quality, validation and reconciliation Migrated records should only become usable in OpenCRVS when they meet the country’s approved quality, legal and business rules for the target status. OpenCRVS supports importing records through its APIs, but the migration programme is responsible for deciding what level of completeness, consistency, identifier matching and exception handling is acceptable. Records that do not meet approved rules should be reviewed, quarantined, excluded, or retained in controlled legacy access rather than silently loaded. Migration should not rewrite legally meaningful historical facts unless an approved correction policy exists. For migration governance, exception ownership and sign-off, see [Migrate legacy data](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/migrate-legacy-data). For technical validation, batching, idempotency and reconciliation outputs, see [Legacy data migration](https://documentation.opencrvs.org/v2.0/technical/guides/data-migration). *** ### 9. Deduplication OpenCRVS detects potential duplicate records. Migration interacts with this in two ways: * **Within the migration** β€” the same person may appear more than once in legacy data; de-duplicate during transformation. * **Between migrated and live records** β€” once migrated records are in the system, new declarations can be checked against them, and vice versa. Consider the order and timing of migration relative to go-live so that duplicate detection behaves as intended rather than flagging large volumes of expected matches. In phased or low-connectivity rollouts, late paper returns, or continued spreadsheet use can create duplicates after go-live. The cutover plan should explain how these cases are detected and resolved. *** ### 10. Audit and provenance Every record created through the APIs is journaled. For migration this means each record carries evidence that it was created by a **migration/system client** and when. This distinguishes a migrated historical record from one registered live in OpenCRVS. Migration audit should be separate from original civil registration source history. OpenCRVS should record that the record was migrated, but the migrated data should also preserve original source details where available: original registration date, registrar or office, source register/system, book/page/folio, amendment notes, and source record ID. Migrated historical records must follow the same configured access, search, correction, certificate, and privacy rules as other records, unless the country defines stricter controls for sensitive historical data. *** ### 11. Planning and implementation boundaries Data migration should be treated as a controlled capability, not as a one-off database dump. OpenCRVS supports migration through its Core APIs, so migration can be delivered in controlled batches or phases according to the country’s approved migration approach. This Functional Architecture page describes what OpenCRVS supports and the principles that apply to migrated records. The migration plan, readiness gates, cutover approach, exception handling and reconciliation sign-off are project activities. For project planning and readiness activities, see [Migrate legacy data](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/migrate-legacy-data). For technical batching, validation, loading and reconciliation guidance, see [Legacy data migration](https://documentation.opencrvs.org/v2.0/technical/guides/data-migration). *** ### 12. What's supported today, and what's on the roadmap * **Supported today.** Migrating existing digital records and capturing paper-derived records through the Core APIs, either directly via a system client or via a custom capture application. Countries still need project-specific extraction, transformation, validation and reconciliation tools, and signed business rules for mapping and target status. * **On the roadmap (not yet available).** A **native in-product legacy-digitisation workflow** β€” configurable roles to digitise, approve and reject digitised legacy records as a distinct in-app capability β€” is a planned feature and is not yet built. Likewise, **versioning of the administrative structure over time** (see Section 7) and additional record states such as a dedicated inactive/void status (today expressed using flags) are planned. Design your migration around what exists today, and treat these as future enhancements rather than assumptions. *** ### 13. Summary * Data migration brings existing legacy event records into OpenCRVS through its Core APIs, where they become native records subject to the same statuses, actions and access control. * Migration begins with source assessment and legal/business decisions, not API loading. * The most important business decision is the target status: `Registered`, `Declared`, `Notified`, quarantine, or controlled legacy access. * A digital source is not automatically a legal registration source. * Legacy identifiers, original registration source history, and historical location mapping should be preserved where available. * Migration readiness requires validation, reconciliation, exception reporting, test migration, and cutover planning. * A native in-product legacy-digitisation workflow and historical administrative-structure versioning are **planned** capabilities; today, migration is delivered through the APIs. *** #### Related pages * [Legacy data](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data) β€” the legacy-data module, covering digital import and paper digitisation. * [Record lifecycle and workflows](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows) β€” the statuses and actions a migrated record is subject to. * [Administrative structure](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/administrative-structure) β€” the hierarchy and locations migrated records must reference. * [APIs](https://documentation.opencrvs.org/v2.0/functional/markdown/interoperability/apis) β€” the Core APIs (Events, Search, Locations, Integrations, Attachments) used to load records. * [Go-live](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/go-live) β€” where migration sits in the readiness checklist. # Digitise paper records ### 1. Introduction **Digitisation of paper records** is the process of capturing historical civil registration events that exist only on **paper** β€” bound registers, register books, certificate counterfoils or loose register sheets held in district offices and archives β€” and turning them into structured digital records in OpenCRVS. Like [Data migration](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data/data-migration), digitisation deals with historical civil registration sources. In many cases these are completed legal registrations, such as entries in official register books. However, the registration authority should confirm the legal status of each paper source before capture. A register book, certificate counterfoil, loose sheet, index, or archive file may have different evidential value and may require different handling. Where the paper source is confirmed to represent a completed legal registration, the digitised record can arrive in OpenCRVS as a `Registered` record. Where the source is incomplete, uncertain, or not legally authoritative, it should be held back, reviewed, or treated as supporting evidence rather than imported as a registered record. A digitised record is not a static scan. Once captured it can be **searched**, used to **print a certified copy**, **corrected**, shared with integrated systems, and counted in reporting, exactly like a record created during day-to-day registration. > **Where this sits.** Digitisation is part of the legacy-data milestone in the [Go-live](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/go-live) readiness checklist: historical paper records digitised and uploaded (if required), the data validated and cleaned, and the process tested and verified before go-live. Digitisation is often a long-running programme that continues in parallel with live registration, rather than something completed in a single window. *** ### 2. Feature overview Digitisation lets a country convert paper registers into OpenCRVS records by capturing each one through a data-entry tool that maps to the configured event model, attaches the source image, and submits the record through the Core APIs as a registered record. #### Core capabilities * **Capture paper records against the OpenCRVS event model** β€” operators enter each paper record into forms that map to the same configured fields (birth, death, marriage, and so on) used for live registration. * **Attach the source image** β€” a scan or photograph of the original register page is captured and stored with the record, preserving the documentary evidence. * **Land confirmed legal registrations as Registered** β€” where the paper entry is confirmed to be an existing legal registration, it is captured as a `Registered` record. Revoked or inactive registrations are represented according to the current OpenCRVS status and flag model (see Section 3). * **Preserve legacy identifiers** β€” the original registration number and the book/volume/page reference are carried onto the record. * **Maintain a complete audit trail** β€” every record captures who digitised it and when, while preserving source details such as register book, volume, page, entry number, and source image. * **Support high-throughput, batch capture** β€” many records from a single book or time period can be captured efficiently, in controlled batches with verification. Digitisation is: * **Capture-driven** β€” the bottleneck and the quality risk are in human data entry, not in a database transform. * **Configuration-aligned** β€” capture targets the country's own configured events, forms and locations. * **Auditable** β€” the operator and timing of every digitised record is journaled. *** ### 3. Record states in scope Where paper entries are confirmed to be completed legal registrations, digitised records arrive as `Registered`. Three registration states are in scope: * **Registered** β€” an active, valid registration. It can be searched, certified and corrected like any registered record. * **Revoked** β€” a registration that was subsequently revoked or cancelled (for example, annotated as void in the register). * **Registered (inactive)** β€” a registration that has been deactivated or superseded but is retained for the historical record. > **How the three states are represented today.** OpenCRVS currently has a single **Registered** status; **Revoked** and **Registered (inactive)** are planned future statuses. Until they exist, both can be represented as **flags** on a Registered record. *** ### 4. How digitisation works Paper records are captured through a data-entry tool and submitted to the OpenCRVS **Core APIs** β€” principally the Events API, where accepted records become native OpenCRVS records. The common delivery pattern is a purpose-built capture application. #### 4.1 A dedicated digitisation application A country contracts a digitisation team and equips them with a **custom side application** built against the OpenCRVS APIs and designed for one task: high-throughput capture of paper records. Such an app typically: * Lets operators **scan or photograph** pages from old paper registers. * Provides **data-entry forms that map to the OpenCRVS event model**, including mandatory and optional fields. * **Validates data locally** and then submits records into the eRegistry as **Registered** records. * **Records who digitised each record and when**, so audit trails remain complete. * **Supports batch processing**, so many records from a single book or period can be captured efficiently. The digitisation app does not replace the core OpenCRVS interface; it complements it, providing a specialised tool that feeds the same eRegistry used for routine registration. #### 4.2 Capture and review Some programmes separate capture from approval β€” an operator captures the record and a supervisor checks it before it is committed. Today that check happens **within the capture application**, before the record is submitted to OpenCRVS as a Registered record. A dedicated in-product workflow to digitise, approve and reject digitised records is on the roadmap (see Section 13). > **Note.** Whichever tool is used, records are written through the same Core APIs, so the resulting records are ordinary registered OpenCRVS records. The choice of tool is about **how paper is captured and checked**, not about what the records become. *** ### 5. Capturing the record Every field on the paper record must be captured into a field in the configured OpenCRVS form, or deliberately omitted. Plan for: #### 5.1 Data entry Operators key the paper record into forms mapped to the configured event. Field-level mapping from the layout of each register type to the OpenCRVS form should be defined and documented before capture begins, because historical register formats vary across eras. #### 5.2 Document and image capture A scan or photograph of the original register page is attached to the record as supporting evidence. This preserves the documentary source behind the digital record and supports later verification and dispute resolution. #### 5.3 Mandatory fields OpenCRVS forms have required fields, and old paper records frequently omit some of them or record them illegibly. Where a digitised record will be imported as `Registered`, gaps must be resolved before capture is committed: sourced from another register, cross-checked against a certificate counterfoil, reviewed by a supervisor, or handled under an approved exception rule. A paper entry that cannot be completed to a valid registration should be held back rather than registered with missing mandatory data. #### 5.4 Reference data Values such as place of event and place of registration must resolve to **configured locations and facilities**, not free text (see Section 7). *** ### 6. Identifiers Digitised records must remain traceable to their paper source. Identifier policy affects certificates, search, corrections, reporting, and downstream systems. Decide whether the original paper registration number remains the canonical registration number in OpenCRVS, or whether it is stored alongside a newly issued OpenCRVS number. * **Original registration number** β€” preserve the registration number written on the paper record so historical certificates and citizen references continue to resolve. OpenCRVS holds the registration number on the registered record. * **Book / volume / page references** β€” capture the physical location of the source entry (register book, volume, page, entry number) so each digital record can be traced back to, and reconciled against, the original. * **National ID and other person identifiers** β€” where present on the paper record, map them onto the corresponding person field so future search and linkage work correctly. > Identifier decisions should be signed off before test digitisation. Changing number policy after records have been captured can affect certificates, search, duplicate detection, integrations, and reconciliation reports. *** ### 7. Administrative structure and historical locations Digitised records reference places β€” place of event, place of registration β€” and these must resolve to entries in the OpenCRVS [administrative hierarchy](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/administrative-structure), not free text. Digitised records may reference several different location concepts: place of event, place of registration, current office, historical office, and source office. These may not be the same, especially where administrative boundaries, facility names, or office responsibilities have changed. Each location used by a digitised record must resolve to an entry in the OpenCRVS administrative hierarchy, not remain as free text. * **Map paper place names to configured locations.** Build a lookup from the place names written in the registers to OpenCRVS administrative areas and facilities. Historical-to-current location mapping decisions should be documented. Spelling variants, historical names, renamed areas and merged districts all need resolving during capture. * **Locations are archived, never deleted.** A location no longer in use can be archived but is retained, precisely so the historical name on an older record is preserved. Archived locations should be governed so they remain available for digitised and historical records, but are not accidentally used for new registrations. > **Roadmap limitation β€” historical administrative structures.** Full versioning of the administrative structure over time (so a record can reference an area exactly as it existed at the historical event date) is a planned capability and is **not yet available**. Until it lands, paper records that reference abolished or restructured areas must be mapped to the nearest appropriate current or archived location, and that mapping decision should be documented. *** ### 8. Data quality, verification and reconciliation Digitisation is as much a quality exercise as a capture one β€” the quality risk sits in human transcription. The go-live checklist requires digitised data to be validated and cleaned, and the process tested and verified. * **Verify entry.** Use quality-control techniques such as double-entry (two operators independently key the same record) or supervised sampling to catch transcription errors before records are committed as registrations. * **Sample against the source.** Periodically compare digitised records against the original register pages to measure accuracy and catch systematic errors. * **Handle illegibility explicitly.** Define a convention for unreadable or ambiguous entries β€” resolve against another source or hold the record back β€” rather than letting operators guess. * **Reconcile by book and batch.** Track which books, volumes and date ranges have been captured, and reconcile counts so no register or page is missed or double-captured. *** ### 9. Deduplication OpenCRVS detects potential duplicate records. Digitisation interacts with this in the following ways: * **Within the programme** β€” the same event may be captured twice, for example from a register and from a certificate counterfoil; guard against double capture through book/page tracking and reconciliation. * **Across paper and digital sources** β€” the same event may exist in both a paper register and a legacy digital system. Digitisation and data migration plans should be sequenced so the same historical record is not loaded twice. * **Between digitised and live records** β€” once digitised records are in the system, new declarations can be checked against them, and vice versa. Consider the order and timing of digitisation relative to go-live so duplicate detection behaves as intended. *** ### 10. Audit and provenance Every record created through the APIs is journaled. For digitisation this means each record captures who digitised it and when, alongside the attached source image. This distinguishes a digitised historical record from one registered live in OpenCRVS. Digitisation audit should be separate from original civil registration source history. OpenCRVS should record that the record was digitised, but the captured data should also preserve original source details where available: original registration date, registrar or office, source register, book/page/folio, amendment notes, source image, and entry number. Digitised historical records must follow the same configured access, search, correction, certificate, and privacy rules as other records, unless the country defines stricter controls for sensitive historical data. *** ### 11. Planning, throughput and physical handling Treat digitisation as a controlled, long-running operation rather than a one-off task. A digitisation plan should normally include these gates: 1. Paper source assessment approved. 2. Digitisation scope approved. 3. Field, identifier, image, and location mapping signed off. 4. Test digitisation completed in a non-production environment. 5. Verification, reconciliation, and exception report signed off. 6. Physical handling and chain-of-custody plan approved. 7. Production capture started in controlled batches. 8. Post-capture verification completed. 9. Controlled legacy archive access plan confirmed. * **Pilot first.** Digitise a small, representative set of books, verify and reconcile them, and confirm records render, search and certify correctly before scaling. * **Plan for volume and throughput.** Historical archives can be very large; staffing, operator productivity, equipment (scanners, devices) and infrastructure load all shape the timeline. * **Manage the physical source.** Plan chain of custody for fragile registers, the handling and storage of originals, and what happens to paper after capture. * **Run in parallel with live registration.** Digitisation commonly continues after go-live; sequence it so it does not disrupt routine registration and so deduplication behaves predictably. The plan should explain how late-arriving paper records and continued archive access are handled. * **Test against a non-production environment.** Validate the full pipeline β€” capture, image attachment, submission, reconciliation β€” before capturing into production. *** ### 12. What's supported today, and what's on the roadmap * **Supported today.** Capturing paper records β€” and migrating existing digital records β€” by submitting them through the Core APIs from a custom capture application as **Registered** records, with audit, image attachment and search applying as normal. * **On the roadmap (not yet available).** **Revoked** and **Registered (inactive)** are planned future statuses; until they exist, both are represented as flags on a Registered record (see Sections 3 and 5). A **native in-product digitisation workflow** β€” configurable roles to **digitise**, **approve** and **reject** digitised legacy records as a distinct in-app capability β€” and **versioning of the administrative structure over time** (Section 7) are also planned. Design your digitisation programme around what exists today, and treat these as future enhancements rather than assumptions. *** ### 13. Summary * Digitisation captures paper civil registration sources into OpenCRVS through its Core APIs, where accepted records become native records subject to the same actions and access control as other records. * Digitisation begins with source assessment and legal/business decisions, not data entry alone. * Where the source is confirmed to be a completed legal registration, the target status is `Registered`; uncertain or incomplete sources should be held back or reviewed. * Because the source is paper, the work is human capture: data entry plus source-image attachment. The main operational risk is transcription quality. * Original registration numbers, book/page references, source images, original registration source history, and historical location mapping should be preserved where available. * Quality is managed through verification, sampling against the source, reconciliation by book and batch, exception reporting, and sign-off. * Distinct Revoked and Registered (inactive) statuses, a native in-product digitisation-and-approval workflow, and historical administrative-structure versioning are planned capabilities; today, digitisation is delivered through the APIs and a capture application. *** ### Related pages * [Legacy data](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data) β€” the legacy-data module, covering digital migration and paper digitisation. * [Data migration](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data) β€” the sibling capability for records that are already digital. * [Record lifecycle and workflows](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows) β€” the Registered status and the actions a digitised record is subject to. * [Administrative structure](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/administrative-structure) β€” the hierarchy and locations digitised records must reference. * [APIs](https://documentation.opencrvs.org/v2.0/functional/markdown/interoperability/apis) β€” the Core APIs (Events, Search, Locations, Integrations, Attachments) used to load records. * [Go-live](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/go-live) β€” where digitisation sits in the readiness checklist. # Example: Farajaland ### 1. Introduction Farajaland is a fictitious country used throughout the OpenCRVS documentation to **demonstrate a complete country configuration**. It shows, end‑to‑end, how real civil registration business rules can be translated into OpenCRVS features such as Users, Actions, Status, Flags, Workqueues, Certificates, and Integrations. Use Farajaland as a **reference country** when designing a real implementation: it provides concrete patterns to copy and adapt, not a template that must be followed exactly. *** ### 2. Why Farajaland exists Farajaland is designed to be: * **Realistic enough** to reflect common challenges in low‑resource CRVS settings. * **Opinionated enough** to show good practices (for example, who should approve late registrations, how to handle duplicates, how to stage certificates and certified copies). * **Flexible enough** that countries can change the rules while reusing the underlying configuration patterns. In the OpenCRVS demos: * Farajaland acts as the **default out‑of‑the‑box configuration**. * The demo workflows (birth and death registration, late registration, corrections, revocations, printing, performance monitoring) are all based on Farajaland’s requirements. *** ### 3. How Farajaland is organised Farajaland is a small sub‑Saharan African country with: * A population of approximately **2 million** people. * A **Province β†’ District β†’ Facility / Community** administrative hierarchy. * Many rural areas with **low population density** and **poor connectivity**. * Better mobile connectivity in urban centres. * Multiple local languages, with **English** more common in the north and **French** more common in the south. * The **US dollar** as the currency in the demo configuration. * A **National ID card** used to prove the identity of adults over 18 years of age. The **Civil Registration Authority (CRA)** is responsible for civil registration in Farajaland. It is headed by the **Registrar General**, based at the CRA HQ in Isamba District, and supported by provincial and district‑level civil registration offices. For more detail on the institutional context and strategic goals, see **β€œBackground & Goals”**. *** ### 4. Using Farajaland when designing a real country configuration When configuring OpenCRVS for a real country, treat Farajaland as a **worked example**: * Start from Farajaland’s **business rules** and ask whether similar rules apply in your context. * Use Farajaland’s configuration (roles, scopes, actions, statuses, flags, queues) as a **pattern**, not a prescription. * Adapt each rule to match your national legislation, policy, and operational practices. As you update or extend the Farajaland example, keep these questions in mind: * What problem in Farajaland’s CRVS system does this change solve? * Which law, regulation, or policy does this rule reflect? * Which OpenCRVS feature (scope, action, flag, workqueue, integration) is best suited to implement it? By keeping Farajaland realistic and coherent, the example remains a powerful tool for explaining OpenCRVS to stakeholders and for designing new configurations. # Background & goals ### 1. Introduction This page describes the **civil registration context in Farajaland** and the **goals of the Civil Registration Authority (CRA)**. It explains why Farajaland needs a digital CRVS system and what OpenCRVS is expected to achieve. *** ### 2. Civil registration in Farajaland today The **Civil Registration Authority (CRA)** has the legal mandate to register all births and deaths in Farajaland, as defined in the **Births and Deaths Registration Act**, last amended in 2021. Key characteristics of the current system: #### **2.1 Legal framework** The Births and Deaths Registration Act of 2021 recognises **electronic civil registration processes**, including: * Electronic signatures. * Electronic storage of vital event records. * The law provides a basis for digitising registration, but implementation is still in transition. #### **2.2 Institutional setup** * The CRA is headed by the **Registrar General**, who has overall accountability for civil registration in Farajaland. * The CRA’s **Headquarters (HQ)** is based in **Isamba District**. * HQ includes several key roles, such as: * **Operations Manager** – responsible for service delivery and performance. * **National System Administrator** – responsible for managing the OpenCRVS platform and integrations. #### **2.3 Decentralised service delivery** * Civil registration is administered at the **District level**. * There is a **Civil Registration Office in each of the 16 districts**. * In each district office: * A **Local Registrar** is responsible for formally registering vital events and issuing certificates. * **2–3 Registration Officers** support day‑to‑day operations. * A number of **Community Leaders** have a formal role in **notifying vital events** in the community. #### **2.4 Health–CRVS collaboration** * There is a **Memorandum of Understanding (MoU)** between the CRA and the **Ministry of Health**. * The MoU sets out how **health and civil registration systems are integrated**, so that: * Births and deaths captured electronically in **hospitals and health facilities** can be shared digitally with the Civil Registration Office. * A **Hospital Clerk** can declare births and deaths directly in OpenCRVS. #### **2.5 Historical reliance on paper** * Until recently, Farajaland relied heavily on **manual, paper‑based processes**. * As a result: * **Completeness rates** (registration within 1 year of event) are low: * \~40% for births. * \~15% for deaths. * Data quality is poor, with **many duplicate entries** in the civil registry. * The **customer experience is weak**: * Families often have to visit the Civil Registration Office multiple times. * Registration is time‑consuming and expensive, especially for rural households. *** ### 3. Strategic goals for 2026 In 2021, the CRA developed a **CRVS National Strategic Plan**. This plan defines a number of strategic goals to be achieved by **2026**. Headline goals include: * **90% completeness** for both **birth** and **death** registration (within the legally defined timeframe). * **95% certification rate** for both birth and death registration. * A **fully digitised and searchable civil registration archive** containing all historical records of births and deaths in Farajaland. * Increased **efficiency** of civil registration staff. * Improved **quality of vital events data**. * Increased **value of CRVS data** through interoperability and safe data sharing with: * Foundational ID systems. * Health information systems. * The National Bureau of Statistics. * Improved **cost‑effectiveness** of civil registration service delivery. * Better **customer experience**, including: * Reduced time taken to register events. * Reduced number of visits required. * Reduced out‑of‑pocket costs for families. These goals set the direction for how Farajaland configures OpenCRVS. *** ### 4. Strategies to reach these goals To achieve the strategic goals, the CRA is implementing a combination of **policy, process, and technology** changes. OpenCRVS is one of the key enablers. Core strategies include: #### **4.1 Digitally enabled service delivery models** * Deploy new models that bring registration services **closer to the community**, for example: * Community‑based notifications and declarations via **Community Leaders** and **Mobile Registration Agents**. * Facility‑based capture of events at **hospitals and health centres**. * District office registration supported by better case management. #### **4.2 Improved data quality and duplicate reduction** * Use automated validation and **duplicate detection** to reduce multiple registrations for the same person. * Apply **business rules** and **flags** to ensure cases that look suspicious are reviewed by a Registrar. #### **4.3 Performance management and monitoring** * Use dashboards and reports to identify **poor‑performing areas** (for example, districts with low completeness or high late registration rates). * Implement **remediation measures**, such as targeted outreach or additional training. #### **4.4 Automation of manual steps** * Automate repetitive and time‑consuming registration steps, such as: * Generating tracking numbers and registration numbers. * Producing certificates and certified copies. * Notifying other systems when records are registered, corrected, or revoked. #### **4.5 Digitisation of historical records** * Digitise paper archives of past births and deaths. * Make them **searchable** in OpenCRVS and link them to current records where relevant. #### **4.6Interoperability and data sharing** * Ensure that vital events data can be **safely shared** with other systems (Foundational ID, health, statistics), in line with policy and privacy requirements. *** ### 5. Role of OpenCRVS in Farajaland OpenCRVS is implemented in Farajaland as part of a broader **digital transformation programme** led by the CRA. The CRA has invested in the necessary infrastructure and connectivity at **District Registration Offices**, which now have stable broadband service. In the Farajaland configuration, OpenCRVS is used to: * Support **end‑to‑end workflows** for birth and death registration (declaration, validation, registration, printing, corrections, revocations). * Implement the **Farajaland business rules** described on the companion page (who can declare, who approves, how late registrations and corrections are governed, etc.). * Provide a **realistic example** of how a country can move from paper‑based CRVS to a modern, digital, interoperable system. When using Farajaland as a reference, this page provides the **context and rationale**, while other pages (Farajaland business rules, Users in Farajaland, Actions, Status, Flags, Workqueues, Certificates) show the concrete configuration that implements these goals. # Requirements
# Birth Requirements β€” Farajaland ### 1. Introduction OpenCRVS ships with an example country configuration called **Farajaland**. Farajaland is not a real country; it is a teaching and demonstration example used to show how civil registration business rules can be translated into OpenCRVS configuration. This page summarises the **key birth civil registration business rules** for Farajaland. These rules drive how birth events are declared, validated, registered, printed, corrected, and revoked. ### 2. Plain-Language Summary Farajaland registers births through four channels: health facilities (hospital notification), community (Community Leader declaration), district registration offices (walk-in declaration), and embassies (overseas births). When a birth occurs at a health facility, a Health Official captures a shortened notification form with key details. The notification is routed to the district Registration Officer, who completes the record into a full declaration with all required information, validates it, and presents it for registration. When a birth occurs in the community, a Community Leader captures a declaration using a shortened version of the declaration form (fields hidden by role). The Community Leader's declaration enters Declared status and must be validated by a Registration Officer before the Registrar can register it. At a registration office, a Registration Officer captures the full declaration directly from the informant and either submits it for the Registrar's review or, if the officer is also a Registrar, registers it themselves. Embassy Officials capture overseas birth declarations and submit them for registration by the Registrar General. If a birth is registered more than 365 days after the date of birth, the declaration is automatically flagged as a late registration. A Provincial Registrar must approve the late registration before the Registrar can register it. The Provincial Registrar may also reject the late registration, returning it for updates. Where a mother and/or father is authenticated via MOSIP eSignet during declaration, a UIN is created for the child at registration (provided at least one parent is a Farajaland citizen). The first birth certificate is free. Certified copies cost $10. Certificates can be printed in advance of issuance for offline registration drives. Certified copies require the original certificate to have been issued first. Corrections to registered records can be requested by a Registration Officer and approved by a Registrar. Corrections to the child's date of birth require Provincial Registrar approval. Corrections to the child's biographical data (name, date of birth, sex) trigger an update to the MOSIP National ID system. A correction that adds parent authentication (previously missing) triggers deferred UIN creation for the child. The Registrar General can revoke a birth registration (deactivating the child's UIN in MOSIP) and reinstate a previously revoked registration. Registrars can escalate records to the Provincial Registrar, to Legal, or to the Registrar General for guidance. *** ### 3. Channels in scope | Channel | Used for | Notes | | ------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Registration office | Full declaration | Walk-in declarations captured by Registration Officer. The primary channel for in-person registration. | | Health facility | Notification (shortened form) | Hospital Official captures a notification at point of birth using a shortened version of the declaration form (fields hidden by role). Must be completed into a full declaration by a Registration Officer before registration. | | Community | Declaration (shortened form) | Community Leader captures a declaration using a shortened version of the declaration form (fields hidden by role). Record enters Declared status. Must be validated by a Registration Officer before the Registrar can register it. | | Embassy | Full declaration | Embassy Official captures overseas birth declarations. Restricted to births of Farajaland citizens occurring outside the country. Registered by the Registrar General. | *** ### 4.1 β€” Notification * **Who can capture a notification?** Health Official (`health_official`). * **Which channels?** Health facility. * **Health facility channel:** The Health Official captures key birth details (child's name, sex, date and time of birth, place of birth, mother's details where available) using the declaration form with non-essential fields hidden by role. The Health Official's name is auto-populated from their user profile. Pre-populated data: none from external systems at notification stage (eSignet authentication is available but optional at this stage). * **How long can a notification remain?** Open Question β€” the time limit for notifications before automatic archive or escalation is not stated. * **Can the public see the notification?** Open Question β€” whether a citizen can look up a notification using a tracking ID is not stated. * **Automatic messages on notification:** Open Question β€” whether SMS/email is sent to the informant on notification is not stated. See A12 for the full notification trigger list. *** ### 4.2 β€” Declaration * **Who can submit a declaration?** Registration Officer (`registration_officer`), Registrar (`registrar`), Community Leader (`community_leader`), Embassy Official (`embassy_official`). Health Officials submit notifications, not declarations. * **Registration office channel:** Registration Officer captures the full declaration directly from the informant. All mandatory fields are visible and required. Pre-populated data: eSignet authentication of mother and/or father can pre-populate their biographical details from MOSIP. * **Health facility / Community channel (completion of notification):** Registration Officer opens the existing notification, completes all remaining mandatory fields, and submits as a full declaration. * **Embassy channel:** Embassy Official captures the full declaration for overseas births. Registered by the Registrar General. * **Informant hierarchy:** Open Question β€” the order of preference for informants (mother, father, other relative, legal guardian) and any conditions are not fully enumerated. Legal guardians must provide court documentation. * **Is the informant required to sign?** Yes β€” informant signature is mandatory. * **Are mother / father details mandatory or optional?** Mother and father details are optional. * **Conditions requiring additional documentary evidence:** Legal guardians must provide court documentation. Other conditions: Open Question. * **Late declaration rule:** At 365 days from the date of birth, the declaration becomes "late" and triggers a requirement for Provincial Registrar approval before registration can proceed. The system automatically adds a flag (`flag:late-registration-approval-required`) when `declarationDate βˆ’ dateOfBirth > 365 days`. The Provincial Registrar reviews and either approves (clearing the flag, allowing registration) or rejects (returning for updates). *** ### 4.3 β€” Validation * **Conditions requiring validation:** All records originating from a Community Leader (declarations using a shortened form) or a Health Official (notifications) must be validated by a Registration Officer before registration. Declarations submitted directly at a registration office by a Registration Officer do not require a separate validation step β€” the Registration Officer's act of completing the declaration serves as validation. * **Who can validate?** Registration Officer (`registration_officer`). * **Time limit for validation:** Open Question β€” not stated. * **Can the validator amend the declaration during review?** Yes β€” Registration Officers can modify declarations without recapturing the informant's signature. * **If amended, does the informant need to re-confirm or re-sign?** No. * **If the validator decides the record cannot be validated:** The record is rejected β€” see A5. *** ### 4.4 β€” Registration * **Conditions that must be met before registration:** * No outstanding duplicate concerns (potential-duplicate flag must be resolved) * If the record originated as a notification: validation by a Registration Officer must be complete * If the registration is late (over 365 days): Provincial Registrar approval must be obtained (flag:late-registration-approval-required must be absent) * All required supporting documents on file * No pending correction request * **Conditions requiring elevated approval:** Late registration (over 365 days from date of birth) requires Provincial Registrar approval via `action:APPROVE_LATE_REGISTRATION` before the Registrar can register. * **Does this event trigger NID integration at registration?** Yes β€” if at least one parent is a Farajaland citizen and has been authenticated via eSignet (PSUT stored on the record), UIN creation is triggered for the child via MOSIP Packet Manager. The record enters an *Awaiting external validation* workqueue while MOSIP processes the identity creation. See A14 for full integration requirements. * **Offline drive rule:** Yes β€” Registrars can print certificates before the record's registration has been synchronised to the central server, as part of registration drives to register and issue certificates offline. Acknowledged risk: the certificate is not "legally final" until the registration has synced. * **Who can register?** Registrar (`registrar`), Registrar General (`registrar_general` β€” for embassy declarations). * **Per-channel registration rules:** * Office: Registrar registers after reviewing the declaration submitted by the Registration Officer. Alternatively, a Registrar who holds `record.edit` + `record.register` scopes can review, edit, and register in one flow. * Health facility / Community: Registrar registers after the Registration Officer has validated and completed the declaration. * Embassy: Registrar General registers embassy declarations. * Offline drive: Registrar declares and registers directly (BIRTH-REG-5), printing the certificate immediately. *** ### 4.5 β€” Rejection and re-declaration * **Conditions under which a record may be rejected:** * Missing or incorrect data * Incomplete supporting documents * Policy non-compliance * Failed document or identity checks * **Who can reject?** Registration Officer (`registration_officer`), Registrar (`registrar`), Provincial Registrar (`provincial_registrar` β€” for late registration rejections), Registrar General (`registrar_general` β€” for embassy declaration rejections). * **What information is captured on rejection?** A reason for rejection and a free-text comment. * **Who can re-submit after rejection?** The original declarer * **When a rejected record is corrected and re-submitted:** The act of re-declaration (action:DECLARE) clears the `flag:rejected` and returns the record to the standard workflow. Alternatively, a Registrar with `record.edit` + `record.register` scopes can edit and register directly, clearing the `flag:rejected` without requiring re-declaration. *** ### 4.6 β€” Archive and reinstate * **Conditions under which a record is archived:** * Confirmed duplicate (marked as duplicate during review) * Abandoned notification (no follow-up declaration) * Withdrawn by informant * **Who can archive?** Registration Officer (`registration_officer`). * **Conditions under which an archived record may be reinstated:** Open Question β€” `record.reinstate` does not exist in v2.0. If reinstatement of archived records is required, it must be modelled as a custom action or the platform mechanism must be verified. Note: the user-provided workflows include BIRTH-ARCHIVE-1 (archive by Registration Officer) but do not describe a reinstate flow for archived (pre-registration) records. Reinstatement of *revoked registrations* is covered in A9. * **Who can reinstate (archived records)?** Registration Officer (`registration_officer`). * **What information is captured on archive?** A reason and a comment. *** ### 4.7 β€” Certificate and certified copy #### Template 1: Birth Certificate (primary) * **Template name:** Birth Certificate * **Output type:** Full certificate * **Fee:** Free (first certificate) * **Must the original certificate be issued before a certified copy can be requested?** N/A β€” this is the primary certificate. * **Can certificates be printed in advance of collection?** Yes β€” BIRTH-ISSUE-1 describes printing in advance of issuance. * **If advance-printed, must they be formally recorded at issuance?** Yes β€” Open Question on exact recording mechanism. * **Who can print?** Registrar (`registrar`), Embassy Official (`embassy_official` β€” for embassy declarations after registration by Registrar General), Registrar General (`registrar_general`). * **Conditions before printing:** Record must be Registered. No correction request in progress (`flag:correction-requested` must be absent). #### Template 2: Certified Copy * **Template name:** Certified Copy * **Output type:** Certified copy * **Fee:** $10 (or equivalent local currency) * **Must the original certificate be issued before a certified copy can be requested?** Yes β€” the primary certificate must have been printed first. * **Can certified copies be printed in advance?** Yes β€” with formal recording at issuance. * **Who can print?** Registrar (`registrar`), Embassy Official (`embassy_official`), Registrar General (`registrar_general`). * **Conditions before printing:** Record must be Registered. Primary certificate must have been issued (journal check β€” no flag needed). No correction request in progress. *** ### 4.8 β€” Correction * **Fields that cannot be corrected after registration:** Open Question β€” "all fields correctable through configured workflows" per source material, but practical restrictions may apply. * **Fields requiring elevated approval:** Corrections to the child's date of birth require Provincial Registrar approval. * **Does correction require the informant to re-confirm or re-sign?** Open Question β€” not stated. * **Must corrections be shared with the NID system?** Yes β€” corrections to the child's biographical data (name, date of birth, sex) must be shared with the Farajaland National ID system. See A14. * **Correction fee:** Open Question β€” not stated. * **Who can request a correction?** Registration Officer (`registration_officer`). * **Who can approve a correction?** Registrar (`registrar`). #### Correction to add parent authentication and trigger UIN creation When a correction adds eSignet authentication of the mother or father to a record where it was previously absent, and this now satisfies the eligibility rules for UIN creation (at least one citizen parent authenticated), the correction triggers deferred UIN creation for the child via MOSIP. This uses the same UIN creation flow as at-registration creation. *** ### 4.9 β€” Revocation / deactivation * **Who can revoke?** Registrar General (`registrar_general`). * **Conditions under which revocation is permitted:** When a registration is later found to have been made in error or fraudulently. * **What information is captured on revocation?** A reason, a legal reference, and supporting documentation. Open Question β€” exact fields not specified. * **Must revocation be shared with the NID system?** Yes β€” birth revocation triggers UIN deactivation in the MOSIP National ID system. * **Can a revocation be reversed?** Yes β€” the Registrar General can reinstate a previously revoked registration * **After revocation, can certificates still be printed?** No. A `flag:revoked` on the Registered record would gate Print (absent required). *** ### 4.10 β€” Escalation #### 4.10.1 β€” Escalation to Provincial Registrar * **How triggered:** Manually by the Registrar. * **When:** When the Registrar has a question or concern about a declaration that requires provincial-level guidance. * **Escalating from:** Registrar (`registrar`). * **Escalating to:** Provincial Registrar (`provincial_registrar`). * **Response action:** The Provincial Registrar reviews the record and provides a response (via a custom action). The record is returned to the Registrar's queue for further processing. #### 4.10.2 β€” Escalation to Registrar General * **How triggered:** Manually by the Registrar. * **When:** When the Registrar has a question requiring national-level authority. * **Escalating from:** Registrar (`registrar`). * **Escalating to:** Registrar General (`registrar_general`). * **Response action:** The Registrar General reviews and provides a response. The record is returned to the Registrar. *** ### 4.11 β€” Duplicate detection * **Working definition of a duplicate for birth:** Same child name (exact or near-exact match using fuzzy matching), same date of birth, same mother's details (name and/or National ID). Age plausibility rules applied. * **Who reviews potential duplicates?** Registrar (`registrar`). * **What happens to a record marked as a duplicate?** The new declaration is archived; the original record is unchanged. * **What happens to a record marked as not a duplicate?** The record continues through the lifecycle as if no duplicate had been flagged (the `flag:potential-duplicate` is removed). *** ### 4.12 β€” Informant notifications * **Channels:** Open Question β€” SMS, email, both, or neither not explicitly confirmed. The source material mentions informant notification capability but does not enumerate specific triggers. * **Moments that should trigger a message:** | Ref | Action | Recipient | Purpose | | ---------------- | ------------------------------- | --------- | ------------------------------------------------------------------------------------- | | birth-declared | When a declaration is submitted | Informant | Confirm receipt of declaration with tracking ID | | birth-rejected | When a record is rejected | Informant | Notify of rejection with reason and next steps | | birth-registered | When a birth is registered | Informant | Confirm registration with registration number and certificate collection instructions | * **What contact details do we need to capture?** Informant's phone number (for SMS) and/or email address (for email). These fields must be present in the declaration form. *** ### 4.13 β€” Search and record discovery * **Who can search?** Registration Officer (`registration_officer`), Registrar (`registrar`), Provincial Registrar (`provincial_registrar`), Registrar General (`registrar_general`), Embassy Official (`embassy_official`). * **Geographic scope of search results:** Varies by role: * Registration Officer / Registrar: records within their district (`placeOfBirth = my-administrative-area`) * Provincial Registrar: Records within their province (`placeOfBirth = my-administrative-area` at province level) * Registrar General: nationwide (`any`) * Embassy Official: Records they declared (`declared_by = user`) or nationwide? * **Can staff search using PII?** Yes β€” name, date of birth, National ID. *** ### 4.14 β€” Interoperability (event-specific) #### National ID system (MOSIP) **Actions triggering NID calls:** | Action | Purpose | Data shared (OpenCRVS β†’ MOSIP) | Data received | Failure handling | | ----------------------------------------- | ------------------------------ | -------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Registration (when eligible) | Create UIN for child | Child's biographical data (configurable field set) | VID returned on successful creation | Record enters *Awaiting external validation* workqueue. MOSIP does not return failure responses β€” stalled records require manual investigation. | | Correction (biographical fields) | Update child's identity record | Updated name, date of birth, and/or sex | None (send and continue) | System-wide default | | Correction (adding parent authentication) | Deferred UIN creation | Child's biographical data | VID returned | Same as registration | | Revocation | Deactivate child's identity | VID and revocation data | None (register and continue) | System-wide default | **Event-specific NID policy:** * UIN creation is restricted to children where at least one parent is a Farajaland citizen. * Corrections to the child's biographical data (name, date of birth, sex) trigger propagation to MOSIP. * Birth revocation triggers UIN deactivation. **eSignet authentication during declaration:** * Mother and/or father can authenticate via eSignet during declaration * On successful authentication: form fields pre-populated from MOSIP ID schema; PSUT stored against the record. * Offline alternative: CBOR-based QR code scanning of MOSIP credentials, with subsequent online verification. * Authentication of at least one citizen parent is a prerequisite for UIN creation at registration. #### Health information system * Health facilities submit birth notifications via the MoU with the Ministry of Health. * Pre-population: hospital official name auto-populated from user profile. *** ### 5. Using Farajaland as a reference These Farajaland rules are **illustrative**, not prescriptive. They show how: * Legal and policy decisions (for example, who can declare, how late registrations are handled, how many free certificates are allowed) map onto OpenCRVS configuration. * Business requirements around identity systems and fees can be integrated with registration workflows. When configuring OpenCRVS for a real country, use Farajaland as a starting point and adapt each rule to match national legislation, policy, and operational practice. # Birth Journeys β€” Farajaland | Ref | Journey | Starting point | Key actors | | --- | ------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------- | | J1 | Health facility notification to registration (BIRTH-REG-1) | New record | Health Official, Registration Officer, Registrar | | J2 | Community declaration to registration (BIRTH-REG-2) | New record | Community Leader, Registration Officer, Registrar | | J3 | Office declaration and registration (BIRTH-REG-3) | New record | Registration Officer, Registrar | | J4 | Late registration with Provincial Registrar approval (BIRTH-REG-4) | New record | Registration Officer, Provincial Registrar, Registrar | | J5 | Offline registration drive (BIRTH-REG-5) | New record | Registrar | | J6 | Embassy declaration and registration (BIRTH-REG-9) | New record | Embassy Official, Registrar General | | J7 | Birth with MOSIP parent authentication and UIN creation (BIRTH-REG-11) | New record | Registration Officer / Registrar, MOSIP | | N1 | Late registration rejected by Provincial Registrar (BIRTH-REG-6) | Existing record β€” Declared | Registration Officer, Provincial Registrar | | N2 | Rejection by Registration Officer, redeclared by Community Leader (BIRTH-REG-7) | Existing record β€” Declared | Registration Officer, Community Leader | | N3 | Rejection by Registrar, redeclared by Registration Officer (BIRTH-REG-8) | Existing record β€” Declared | Registrar, Registration Officer | | N4 | Embassy rejection and redeclaration (BIRTH-REG-10) | Existing record β€” Declared | Registrar General, Embassy Official | | N5 | Certificate printing in advance of issuance (BIRTH-ISSUE-1) | Existing record β€” Registered | Registrar | | N6 | Escalation to Provincial Registrar (BIRTH-ESCALATE-1) | Existing record β€” Declared | Registrar, Provincial Registrar | | N7 | Escalation to Legal (BIRTH-ESCALATE-2) | Existing record β€” Declared | Registrar, Legal Officer | | N8 | Escalation to Registrar General (BIRTH-ESCALATE-3) | Existing record β€” Declared | Registrar, Registrar General | | N9 | Archive declaration (BIRTH-ARCHIVE-1) | Existing record β€” Declared or Notified | Registration Officer | | N10 | Simple correction (BIRTH-CORRECT-1) | Existing record β€” Registered | Registration Officer, Registrar | | N11 | Correction to add MOSIP authentication for UIN creation (BIRTH-CORRECT-2-MOSIP) | Existing record β€” Registered | Registration Officer, Registrar, MOSIP | | N12 | Revoke a registration (BIRTH-REVOKE-1) | Existing record β€” Registered | Registrar General | | N13 | Reinstate revoked registration (BIRTH-REINSTATE\_REVOKED\_REGISTRATION-1) | Existing record β€” Registered (revoked) | Registrar General | *** ### The journeys Journeys J1–J7 begin with a new record β€” an informant initiates and the record progresses through the registration lifecycle. Journeys N1–N13 begin from a record already in the system, triggered by an exception, an error, or a post-registration need. *** #### J1 β€” Health facility notification to registration (BIRTH-REG-1) > **When this applies:** A birth occurs at a health facility. The Health Official captures a notification with partial details, which must be completed and validated by a Registration Officer before being registered by a Registrar. **In plain terms:** A baby is born in a hospital. The hospital clerk captures the basic birth details using a shortened form. This notification is sent to the district registration office, where a Registration Officer reviews the notification, contacts the family if needed, completes all required fields, and validates the record. The Registrar then reviews the completed declaration and formally registers the birth. The family receives a birth certificate. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | -------------------------------------------------------------- | | Health Official | Hospital Official | Captures the initial birth notification at the health facility | | Registration Officer | Registration Officer | Completes, validates, and submits the full declaration | | Registrar | Local Registrar | Reviews the declaration and registers the birth | | Informant | Parent / Guardian | Provides birth details and identity documents | **Step by step:** | # | Who | What happens | Where | Typical timeframe | Output / handoff | | - | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | 1 | Health Official | Captures birth notification using shortened form (child's name, sex, date/time of birth, place of birth, mother's details where available). Hospital official name auto-populated. | Health facility | Day 0 (at birth) | Notification submitted β†’ record in Notified status, routed to district Registration Officer's workqueue | | 2 | Registration Officer | Reviews notification, contacts family if needed, completes all remaining mandatory fields, validates the record | District registration office | Within 30 days | Full declaration submitted β†’ record in Declared status | | 3 | System | Runs duplicate detection against existing records | Automated | Immediate | If potential duplicate found β†’ flag added, routed to Registrar for review (see duplicate detection). Otherwise continues. | | 4 | Registrar | Reviews the completed declaration and registers the birth | District registration office | Within 30 days | Record in Registered status. Registration number assigned. | | 5 | Registrar | Prints birth certificate | District registration office | At registration or later | Certificate issued to informant/family | **Key decisions:** * If the birth is more than 365 days ago β†’ late registration rules apply; see J4 * If a potential duplicate is detected β†’ the Registrar must review the existing record before proceeding * If supporting documents are incomplete β†’ the Registration Officer rejects the notification or holds it for follow-up **What the informant / family receives:** Birth certificate (first copy free). Tracking ID provided at notification for status tracking. *** #### J2 β€” Community declaration to registration (BIRTH-REG-2) > **When this applies:** A birth occurs in a rural community. A Community Leader captures the declaration using a shortened form, which must be validated by a Registration Officer and then registered by a Registrar. **In plain terms:** A baby is born in a rural area. The Community Leader visits the family and captures the basic birth details using a shortened form on their device. The declaration is submitted (online or synced later if offline) to the district registration office. A Registration Officer reviews the Community Leader's submission, completes any missing details with the family, and validates it as a full declaration. The Registrar then registers the birth. The family receives a certificate. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | --------------------------------------------------------------------- | | Community Leader | Community Leader | Captures birth declaration in the community using shortened form | | Registration Officer | Registration Officer | Validates, completes missing fields, and submits the full declaration | | Registrar | Local Registrar | Registers the birth | | Informant | Parent / Guardian | Provides birth details and identity documents | **Step by step:** | # | Who | What happens | Where | Typical timeframe | Output / handoff | | - | -------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------- | | 1 | Community Leader | Captures birth declaration using shortened form. May work offline; data syncs when connectivity returns. | Community / home visit | Within days of birth | Declaration submitted β†’ record in Declared status, routed to district Registration Officer for validation | | 2 | Registration Officer | Reviews declaration, contacts family, completes any missing fields, validates the record | District registration office | Within 30 days | Validated declaration β†’ record ready for registration | | 3 | System | Runs duplicate detection | Automated | Immediate | If duplicate found β†’ flagged for review | | 4 | Registrar | Reviews and registers the birth | District registration office | Within 30 days | Record in Registered status | | 5 | Registrar | Prints birth certificate | District registration office | At registration or later | Certificate issued | **Key decisions:** * If the Community Leader is offline β†’ data queued in the device Outbox until connectivity returns * If the birth is more than 365 days ago β†’ late registration rules apply; see J4 * If a potential duplicate is detected β†’ Registrar reviews before proceeding **What the informant / family receives:** Birth certificate (first copy free). Tracking ID provided at declaration. *** #### J3 β€” Office declaration and registration (BIRTH-REG-3) > **When this applies:** A parent or guardian walks into a district registration office to declare a birth directly. **In plain terms:** The informant visits the registration office in person. A Registration Officer captures the full declaration, including all mandatory fields and supporting documents. The Registration Officer validates the declaration and submits it. The Registrar reviews and registers the birth. The family receives a certificate the same day or shortly after. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | ------------------------------------------------------------- | | Registration Officer | Registration Officer | Captures and validates the full declaration | | Registrar | Local Registrar | Registers the birth | | Informant | Parent / Guardian | Provides all birth details and supporting documents in person | **Step by step:** | # | Who | What happens | Where | Typical timeframe | Output / handoff | | - | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------- | ------------------------------------------------- | | 1 | Registration Officer | Captures the full declaration from the informant, including all mandatory fields. Informant signs. eSignet authentication of mother/father available. | District registration office | Day of visit | Declaration submitted β†’ record in Declared status | | 2 | System | Runs duplicate detection | Automated | Immediate | If duplicate found β†’ flagged | | 3 | Registrar | Reviews the declaration and registers the birth | District registration office | Same day or next day | Record in Registered status | | 4 | Registrar | Prints birth certificate | District registration office | At registration | Certificate issued | **Key decisions:** * If the birth is more than 365 days ago β†’ late registration; see J4 * If a potential duplicate is detected β†’ Registrar reviews * If the informant is a legal guardian β†’ court documentation required **What the informant / family receives:** Birth certificate (first copy free), typically same-day. *** #### J4 β€” Late registration with Provincial Registrar approval (BIRTH-REG-4) > **When this applies:** The birth occurred more than 365 days ago. The declaration is automatically flagged as a late registration requiring Provincial Registrar approval before the Registrar can register it. **In plain terms:** When a birth is declared more than a year after it occurred, the system automatically flags it as a late registration. The declaration follows the normal path (notification or office declaration) but before the Registrar can register it, a Provincial Registrar must review and approve the late registration. Once approved, the Registrar registers the birth. If the Provincial Registrar rejects it, the record is returned for updates (see N1). **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | ------------------------------------------------------- | | Registration Officer | Registration Officer | Captures or completes the declaration | | Provincial Registrar | Provincial Registrar | Reviews and approves (or rejects) the late registration | | Registrar | Local Registrar | Registers the birth after provincial approval | | Informant | Parent / Guardian | Provides birth details and supporting documents | **Step by step:** | # | Who | What happens | Where | Typical timeframe | Output / handoff | | - | -------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------ | | 1 | Registration Officer | Captures or completes the declaration as in J1/J2/J3 | District registration office | β€” | Declaration submitted β†’ record in Declared status | | 2 | System | Detects that `declarationDate βˆ’ dateOfBirth > 365 days`. Automatically adds late-registration flag. | Automated | Immediate | Record flagged for late-registration approval β†’ routed to Provincial Registrar's workqueue | | 3 | Provincial Registrar | Reviews the late registration. Checks supporting documentation and circumstances. | Provincial office | β€” | Approves β†’ flag cleared, record routed to Registrar for registration. Or rejects β†’ see N1. | | 4 | Registrar | Registers the birth | District registration office | After provincial approval | Record in Registered status | | 5 | Registrar | Prints birth certificate | District registration office | At registration | Certificate issued | **Key decisions:** * If the Provincial Registrar rejects β†’ see N1 (BIRTH-REG-6) * Open Question: whether a further "delayed" tier (beyond 365 days, e.g. requiring court order) applies **What the informant / family receives:** Birth certificate (first copy free), after provincial approval and registration. *** #### J5 β€” Offline registration drive (BIRTH-REG-5) > **When this applies:** A Registrar conducts a registration drive in a remote area. The Registrar declares and registers births directly, printing certificates on-site without waiting for server synchronisation. **In plain terms:** During a registration drive in an area with poor or no connectivity, the Registrar captures the full declaration directly from the informant, registers the birth, and prints the certificate β€” all in one session, offline. The data syncs to the central server when the Registrar's device reconnects. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | ----------------- | ------------------------------------------------------- | | Registrar | Local Registrar | Captures declaration, registers, and prints certificate | | Informant | Parent / Guardian | Provides all birth details | **Step by step:** | # | Who | What happens | Where | Typical timeframe | Output / handoff | | - | --------- | ----------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- | | 1 | Registrar | Captures full declaration directly from informant. Informant signs. | Field location (registration drive) | Day of drive | Declaration submitted β†’ record in Declared status (local) | | 2 | Registrar | Registers the birth | Field location | Immediate | Record in Registered status (local) | | 3 | Registrar | Prints birth certificate | Field location | Immediate | Certificate issued on-site | | 4 | System | When connectivity returns, data syncs to central server. Duplicate detection runs at sync time. | Automated | When online | Registration confirmed centrally. Audit timestamped at the time the Registrar performed each action on-device. | **Key decisions:** * If a duplicate is detected at sync time β†’ flagged for review; certificate has already been issued * Certificate is not "legally final" until sync completes β€” acknowledged risk **What the informant / family receives:** Birth certificate printed on-site during the drive. *** #### J6 β€” Embassy declaration and registration (BIRTH-REG-9) > **When this applies:** A Farajaland citizen gives birth overseas. The Embassy Official captures the declaration at the embassy, and the Registrar General registers it. **In plain terms:** A Farajaland citizen has a baby abroad. They visit the nearest Farajaland embassy, where an Embassy Official captures the full declaration. The declaration is submitted to the Registrar General, who reviews and registers the birth. The Embassy Official then prints the certificate for the family. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | --------------------------- | ---------------------------------------------------------------------- | | Embassy Official | Embassy Official | Captures the declaration and prints the certificate after registration | | Registrar General | Registrar General | Reviews and registers the embassy declaration | | Informant | Parent / Guardian (citizen) | Provides birth details and identity documents | **Step by step:** | # | Who | What happens | Where | Typical timeframe | Output / handoff | | - | ----------------- | ------------------------------------------------ | --------------- | ------------------ | ------------------------------------------------------------------------------ | | 1 | Embassy Official | Captures the full declaration from the informant | Embassy | β€” | Declaration submitted β†’ record in Declared status, routed to Registrar General | | 2 | Registrar General | Reviews the declaration and registers the birth | CRA National HQ | β€” | Record in Registered status | | 3 | Embassy Official | Prints birth certificate | Embassy | After registration | Certificate issued to family | **Key decisions:** * If the Registrar General rejects the declaration β†’ see N4 (BIRTH-REG-10) * Open Question: whether late registration rules apply to embassy declarations **What the informant / family receives:** Birth certificate printed at the embassy. *** #### J7 β€” Birth with MOSIP parent authentication and UIN creation (BIRTH-REG-11) > **When this applies:** During the declaration, the mother and/or father authenticates via MOSIP eSignet. At registration, this triggers UIN creation for the child (provided at least one parent is a Farajaland citizen). **In plain terms:** This journey overlays any of J1–J6. During the declaration, the parent authenticates their identity using the national ID system (MOSIP eSignet). Their details are pre-populated from the ID system. When the birth is registered, the system automatically sends the child's details to MOSIP for creation of a Unique Identification Number (UIN). The record is held briefly while the identity system processes the request. Once confirmed, a VID (Virtual ID) is stored on the record. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------------------- | --------------------------- | ------------------------------------------------ | | Registration Officer / Registrar | As per base journey | Captures declaration with eSignet authentication | | MOSIP system | National ID system | Authenticates parent identity; creates child UIN | | Informant | Parent / Guardian (citizen) | Authenticates via eSignet | **Step by step:** | # | Who | What happens | Where | Typical timeframe | Output / handoff | | - | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------ | ----------------------------------------------------------------------------- | | 1 | Registration Officer / Registrar | During declaration, initiates eSignet authentication for mother and/or father | Registration office / Embassy | During declaration | Parent's identity verified; form fields pre-populated from MOSIP; PSUT stored | | 2 | β€” | Base journey continues (declaration, validation, registration) | As per base journey | β€” | β€” | | 3 | System | At registration, evaluates eligibility (at least one citizen parent authenticated). Sends child data to MOSIP for UIN creation. | Automated | At registration | Record enters *Awaiting external validation* workqueue | | 4 | MOSIP system | Processes identity creation | External | Variable | VID returned to OpenCRVS and stored on record | | 5 | β€” | Registration completes. Certificate can be printed. | β€” | After MOSIP confirmation | Record fully registered | **Key decisions:** * If neither parent is a Farajaland citizen β†’ UIN creation does not trigger; registration proceeds normally * If the device is offline during eSignet β†’ QR code scanning of MOSIP credential as fallback (verification, not authentication) * If MOSIP does not respond β†’ record stalls in *Awaiting external validation* queue; requires manual investigation **What the informant / family receives:** Birth certificate. Child's UIN is created in the national ID system. *** #### Other journeys The journeys below begin from a record that already exists in the system. Each entry shows the status the record is in when the journey starts and what triggers it. *** #### N1 β€” Late registration rejected by Provincial Registrar (BIRTH-REG-6) **Triggered when:** A Provincial Registrar reviews a late registration (flagged at declaration) and determines it cannot be approved β€” due to insufficient evidence, documentation gaps, or policy non-compliance. **Record at the start:** Declared (with `flag:late-registration-approval-required`) **In plain terms:** The Provincial Registrar reviews the late registration request and rejects it, providing a reason. The record is returned to the Registration Officer who submitted it, who contacts the family, gathers additional evidence, and re-submits the declaration. The Provincial Registrar reviews again. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | --------------------------------------------------------------- | | Provincial Registrar | Provincial Registrar | Reviews and rejects the late registration | | Registration Officer | Registration Officer | Receives the rejection, gathers additional evidence, re-submits | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | -------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ | | 1 | Provincial Registrar | Reviews the late registration and rejects it with a reason and comment | Provincial office | Record flagged as rejected; routed back to Registration Officer | | 2 | Registration Officer | Reviews the rejection reason, contacts the family, gathers additional evidence or corrects the declaration | District registration office | Updated declaration re-submitted | | 3 | Provincial Registrar | Reviews the re-submitted late registration | Provincial office | Approves β†’ registration proceeds (J4 step 4). Or rejects again β†’ repeat. | **Key decisions:** * If the informant cannot provide the required evidence β†’ record may be archived (see N9) **What the informant / family receives:** Notification of rejection (if informant notifications are configured β€” see BQ-7). *** #### N2 β€” Rejection by Registration Officer, redeclared by Community Leader (BIRTH-REG-7) **Triggered when:** A Registration Officer reviews a community notification and determines the data is too incomplete or incorrect to proceed. **Record at the start:** Declared (after completion from Notified) or Notified **In plain terms:** The Registration Officer rejects the community submission with a reason. The Community Leader receives the rejected record, visits the family to gather the missing or corrected information, and re-submits. The Registration Officer then reviews the updated submission. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | ------------------------------------- | | Registration Officer | Registration Officer | Rejects the declaration with a reason | | Community Leader | Community Leader | Edits the record and re-submits | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | -------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------- | | 1 | Registration Officer | Rejects the declaration with a reason and comment | District registration office | Record flagged as rejected; routed to Community Leader | | 2 | Community Leader | Reviews rejection reason, visits the family, edits the record with corrected/additional information | Community | Updated record re-declared β†’ rejection flag cleared | | 3 | Registration Officer | Reviews the re-submitted declaration | District registration office | Proceeds to registration (via Registrar) or rejects again | **Key decisions:** * If the Community Leader cannot resolve the issue β†’ record may be archived **What the informant / family receives:** Updated record re-submitted by Community Leader on their behalf. *** #### N3 β€” Rejection by Registrar, redeclared by Registration Officer (BIRTH-REG-8) **Triggered when:** A Registrar reviews a declaration submitted by a Registration Officer and determines it cannot be registered as submitted. **Record at the start:** Declared **In plain terms:** The Registrar rejects the declaration with a reason. The Registration Officer who submitted it reviews the rejection, contacts the informant if needed, edits the record, and re-declares it. The Registrar reviews the updated declaration. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | ----------------------- | | Registrar | Local Registrar | Rejects the declaration | | Registration Officer | Registration Officer | Edits and re-declares | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | -------------------- | ------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------- | | 1 | Registrar | Rejects the declaration with a reason and comment | District registration office | Record flagged as rejected; routed to Registration Officer | | 2 | Registration Officer | Reviews rejection reason, edits the record, re-declares | District registration office | Rejection flag cleared; record back in Declared status | | 3 | Registrar | Reviews the updated declaration | District registration office | Registers or rejects again | **Key decisions:** * The Registrar may alternatively edit and register directly if they hold `record.edit` + `record.register` scopes (Open Question BQ-20) **What the informant / family receives:** Certificate after successful re-declaration and registration. *** #### N4 β€” Embassy rejection and redeclaration (BIRTH-REG-10) **Triggered when:** The Registrar General reviews an embassy declaration and rejects it. **Record at the start:** Declared **In plain terms:** The Registrar General rejects the embassy declaration with a reason. The Embassy Official receives the rejection, contacts the informant, edits the record, and re-declares. The Registrar General reviews again. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | ----------------- | ----------------------- | | Registrar General | Registrar General | Rejects the declaration | | Embassy Official | Embassy Official | Edits and re-declares | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | ----------------- | ----------------------------------------------------------------- | --------------- | ------------------------------------------------------ | | 1 | Registrar General | Rejects the embassy declaration with a reason | CRA National HQ | Record flagged as rejected; routed to Embassy Official | | 2 | Embassy Official | Reviews rejection, contacts family, edits the record, re-declares | Embassy | Rejection flag cleared | | 3 | Registrar General | Reviews the updated declaration | CRA National HQ | Registers or rejects again | **What the informant / family receives:** Certificate after successful redeclaration and registration at the embassy. *** #### N5 β€” Certificate printing in advance of issuance (BIRTH-ISSUE-1) **Triggered when:** A Registrar prints a certificate in advance of the informant's collection visit. **Record at the start:** Registered **In plain terms:** After registering a birth, the Registrar prints the certificate in advance so it is ready when the family comes to collect it. The certificate must be formally recorded at issuance. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | --------------- | --------------------------------- | | Registrar | Local Registrar | Prints the certificate in advance | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | --------- | ---------------------------------------------------- | ---------------------------- | --------------------------------------------- | | 1 | Registrar | Prints the birth certificate for a registered record | District registration office | Certificate printed and stored for collection | | 2 | Registrar | When the family collects, records the issuance | District registration office | Issuance recorded in the system | **What the informant / family receives:** Pre-printed birth certificate collected at a later date. *** #### N6 β€” Escalation to Provincial Registrar (BIRTH-ESCALATE-1) **Triggered when:** A Registrar has a question or concern about a declaration that requires provincial-level guidance. **Record at the start:** Declared **In plain terms:** The Registrar escalates the record to the Provincial Registrar with a question or comment. The Provincial Registrar reviews the record, provides guidance, and returns it. The Registrar then proceeds with registration or takes other action based on the guidance. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | -------------------- | | Registrar | Local Registrar | Escalates the record | | Provincial Registrar | Provincial Registrar | Reviews and responds | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | -------------------- | ----------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------- | | 1 | Registrar | Escalates the record to the Provincial Registrar with a reason/question | District registration office | Record flagged as escalated; routed to Provincial Registrar's workqueue | | 2 | Provincial Registrar | Reviews the record and provides a response | Provincial office | Escalation resolved; record returned to Registrar's workqueue | | 3 | Registrar | Acts on the Provincial Registrar's guidance | District registration office | Registration proceeds, or other action taken | **What the informant / family receives:** No direct output β€” internal workflow step. *** #### N7 β€” Escalation to Legal (BIRTH-ESCALATE-2) **Triggered when:** A Registrar has a legal question about a declaration. **Record at the start:** Declared **In plain terms:** The Registrar escalates the record to the Legal Officer for legal guidance. The Legal Officer reviews and responds. The Registrar proceeds based on the guidance. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | --------------- | -------------------- | | Registrar | Local Registrar | Escalates the record | | Legal Officer | Legal Officer | Reviews and responds | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | ------------- | ---------------------------------------------------- | ---------------------------- | ------------------------------------------------- | | 1 | Registrar | Escalates the record to Legal with a reason/question | District registration office | Record flagged; routed to Legal Officer | | 2 | Legal Officer | Reviews and provides legal guidance | CRA National HQ | Escalation resolved; record returned to Registrar | | 3 | Registrar | Acts on the legal guidance | District registration office | Proceeds accordingly | **What the informant / family receives:** No direct output β€” internal workflow step. *** #### N8 β€” Escalation to Registrar General (BIRTH-ESCALATE-3) **Triggered when:** A Registrar has a question requiring national-level authority. **Record at the start:** Declared **In plain terms:** The Registrar escalates the record to the Registrar General. The Registrar General reviews and responds. The Registrar acts on the guidance. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | ----------------- | -------------------- | | Registrar | Local Registrar | Escalates the record | | Registrar General | Registrar General | Reviews and responds | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | ----------------- | ----------------------------------------------------- | ---------------------------- | ------------------------------------------- | | 1 | Registrar | Escalates to Registrar General with a reason/question | District registration office | Record flagged; routed to Registrar General | | 2 | Registrar General | Reviews and provides guidance | CRA National HQ | Escalation resolved; record returned | | 3 | Registrar | Acts on guidance | District registration office | Proceeds accordingly | **What the informant / family receives:** No direct output β€” internal workflow step. *** #### N9 β€” Archive declaration (BIRTH-ARCHIVE-1) **Triggered when:** A Registration Officer determines that a notified or declared record cannot progress β€” confirmed duplicate, abandoned notification, or withdrawn by the informant. **Record at the start:** Notified or Declared **In plain terms:** The Registration Officer archives the record with a reason. The record is removed from active processing. It remains in the system as a historical record. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | ------------------- | | Registration Officer | Registration Officer | Archives the record | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | -------------------- | --------------------------------------------- | ---------------------------- | ---------------------------------------------------------- | | 1 | Registration Officer | Archives the record with a reason and comment | District registration office | Record in Archived status. Removed from active workqueues. | **Key decisions:** * Open Question: can an archived record be reinstated? (Not supported in v2.0 β€” see BQ-9) **What the informant / family receives:** No certificate. Record preserved but inactive. *** #### N10 β€” Simple correction (BIRTH-CORRECT-1) **Triggered when:** An error is discovered in a registered birth record β€” a misspelling, incorrect date, or other data issue. **Record at the start:** Registered **In plain terms:** A Registration Officer requests a correction on the registered record, specifying the field(s) to change and providing supporting documentation. The correction request is reviewed and approved (or rejected) by a Registrar. While the correction is pending, the certificate cannot be reprinted. Once approved, the record is updated and a corrected certificate can be issued. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | ---------------------------------- | | Registration Officer | Registration Officer | Requests the correction | | Registrar | Local Registrar | Approves or rejects the correction | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | -------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | 1 | Registration Officer | Requests a correction on the registered record, specifying fields and providing supporting evidence | District registration office | Correction request submitted β†’ `flag:correction-requested` added. Print disabled. | | 2 | Registrar | Reviews the correction request. Approves or rejects. | District registration office | If approved: record updated, flag cleared, Print re-enabled. If rejected: flag cleared, original record unchanged. | | 3 | Registrar | Prints corrected certificate (if approved) | District registration office | Corrected certificate issued | **Key decisions:** * If the correction involves the child's date of birth β†’ Provincial Registrar approval required (elevated approval) * If the correction involves biographical data (name, DOB, sex) β†’ MOSIP update triggered (see N11 for MOSIP-related corrections) **What the informant / family receives:** Corrected birth certificate (if approved). *** #### N11 β€” Correction to add MOSIP authentication for UIN creation (BIRTH-CORRECT-2-MOSIP) **Triggered when:** A correction adds eSignet authentication of a parent to a record where it was previously absent, satisfying the eligibility rules for UIN creation. **Record at the start:** Registered (without child UIN) **In plain terms:** A registered birth record did not trigger UIN creation at registration because no parent was authenticated. A correction is submitted that adds mother or father authentication via eSignet. Once the correction is approved, the system triggers deferred UIN creation for the child through MOSIP. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | -------------------- | ---------------------------------------------------- | | Registration Officer | Registration Officer | Requests the correction to add parent authentication | | Registrar | Local Registrar | Approves the correction | | MOSIP system | National ID system | Creates the child's UIN | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | -------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------- | | 1 | Registration Officer | Requests correction to add eSignet authentication of mother or father | District registration office | Correction request submitted | | 2 | Registrar | Approves the correction | District registration office | Record updated with parent authentication | | 3 | System | Evaluates eligibility β€” at least one citizen parent now authenticated. Triggers UIN creation via MOSIP. | Automated | Record enters *Awaiting external validation*. VID returned and stored. | **What the informant / family receives:** Child's UIN created in the national ID system. Updated certificate if needed. *** #### N12 β€” Revoke a registration (BIRTH-REVOKE-1) **Triggered when:** A registration is found to have been made in error or fraudulently. **Record at the start:** Registered **In plain terms:** The Registrar General revokes the birth registration, providing a legal reason and supporting documentation. The record is marked as revoked. The child's UIN in MOSIP is deactivated. Certificates can no longer be printed. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | ----------------- | ------------------------ | | Registrar General | Registrar General | Revokes the registration | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | ----------------- | ------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------- | | 1 | Registrar General | Revokes the registration with a reason, legal reference, and supporting documentation | CRA National HQ | `flag:revoked` added to the Registered record. Print disabled. | | 2 | System | Sends revocation to MOSIP β€” child's UIN deactivated | Automated | MOSIP identity flagged as inactive | **Key decisions:** * Can the revocation be reversed? Yes β€” see N13 **What the informant / family receives:** No further certificates can be issued. Notification to the family: Open Question. *** #### N13 β€” Reinstate revoked registration (BIRTH-REINSTATE\_REVOKED\_REGISTRATION-1) **Triggered when:** A previously revoked registration is determined to be valid after further investigation. **Record at the start:** Registered (with `flag:revoked`) **In plain terms:** The Registrar General reinstates a previously revoked birth registration, clearing the revocation flag. Certificates can be printed again. Open Question on whether MOSIP UIN is reactivated. **Who's involved:** | Role in this journey | Country title | Responsibility | | -------------------- | ----------------- | ----------------------------------- | | Registrar General | Registrar General | Reinstates the revoked registration | **Step by step:** | # | Who | What happens | Where | Output / handoff | | - | ----------------- | ----------------------------------------------- | --------------- | ----------------------------------------- | | 1 | Registrar General | Reinstates the registration with a reason | CRA National HQ | `flag:revoked` cleared. Print re-enabled. | | 2 | System | Open Question: whether MOSIP UIN is reactivated | β€” | β€” | **What the informant / family receives:** Certificates can be printed again. Registration restored. *** ### Open Questions | ID | Question | Domain | Decision-maker | Target date | Status | | ---- | ---------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------- | ----------- | ------ | | JQ-1 | Does the Registrar have `record.edit` + `record.register` to register-with-edits after rejection (bypassing re-declaration)? | registration | Country team | β€” | Open | | JQ-2 | Do late registration rules apply to embassy declarations? | declaration | Country team | β€” | Open | | JQ-3 | Is there a further "delayed" tier beyond 365 days? | declaration | Country team | β€” | Open | | JQ-4 | Can archived records be reinstated? (Not supported in v2.0) | archive | Country team / OpenCRVS Core | β€” | Open | | JQ-5 | Is MOSIP UIN reactivated when a revoked registration is reinstated? | integration | Country team | β€” | Open | | JQ-6 | Is notification of rejection sent to the informant? Via what channel? | notification | Country team | β€” | Open | | JQ-7 | Escalation response time expectations? | escalation | Country team | β€” | Open | | JQ-8 | Does the escalation use a single branching action (Recipe 2) or separate actions per destination? | escalation | Country team / Technical lead | β€” | Open | *** ### Version History | Version | Date | Status | Sections changed | Summary | | ------- | ---------- | ------ | ---------------- | ---------------------------------------------------------------------------------------------- | | 0.1 | 2026-05-07 | Draft | All | Initial draft β€” all journeys from BIRTH-REG-1 through BIRTH-REINSTATE\_REVOKED\_REGISTRATION-1 | # Demo # Your OpenCRVS Project ### 1. Introduction This section is your guide to implementing OpenCRVS in your country β€” from the first planning conversations through to running and improving the system in production. It is organised as a sequence of stages. If you are at the start of your journey, work through them in order; if you are already underway, jump to the stage you are in. Each stage page explains what it involves, what you need to begin, and what it produces for the next stage. {% hint style="info" %} **Where to start:** if you are beginning a new implementation, start with [Project planning](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/project-planning) and [Establish project & team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team). Everything else builds on those foundations. {% endhint %} *** ### 2. The implementation journey A typical OpenCRVS implementation moves through five broad phases: **plan and prepare**, **understand and design**, **build**, **launch**, and **run and improve**. **Plan and prepare** * [Project planning](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/project-planning) β€” agree the scope, timeline, budget and approach for the implementation. * [Establish project & team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team) β€” identify the roles and skills needed to set up, configure, run and sustain OpenCRVS. **Understand and design** * [Gathering requirements](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements) β€” collect and prepare the inputs for an optimal configuration, through desk research, field research, co-design and design & specification. * [Solution architecture](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/solution-architecture) β€” decide how OpenCRVS fits into your country's wider, interoperable digital ecosystem. **Build** * [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration) β€” turn the signed-off configuration inputs into a working system. **Launch** * [Deployment](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/deployment) β€” set up the servers and environments and deploy OpenCRVS. * [Migrate legacy data](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/migrate-legacy-data) β€” bring existing civil registration records into OpenCRVS. * [Quality assurance](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/quality-assurance) β€” test the configured system against the requirements before go-live. * [Go-live](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/go-live) β€” launch OpenCRVS into production use. **Run and improve** * [Operational support](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/operational-support) β€” keep the system running and support users day to day. * [Monitoring](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/monitoring) β€” track performance, usage and registration outcomes. * [Upgrading](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/upgrading) β€” keep OpenCRVS up to date with new releases. *** ### 3. Who you need Implementing OpenCRVS is led by a small, multidisciplinary team that grows with the scope of your work β€” a proof of concept may need only a couple of core roles, while a national programme draws in technical, design, change-management, training and monitoring roles. See [Establish project & team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team) for the full set of roles and how to size your team. {% hint style="info" %} **Embed your own people.** Wherever an implementing partner supports the work, include government staff throughout. Their knowledge keeps the implementation grounded, and their involvement is what makes the system sustainable after handover. {% endhint %} # Project planning ### 1. Introduction β€œFailing to prepare is preparing to fail.” Before configuring OpenCRVS for a country, it is important to plan the overall digital transformation journey. Pre‑configuration activities help to: * Build shared understanding of goals and constraints. * Align stakeholders around a realistic implementation roadmap. * Reduce rework during configuration by clarifying priorities early. * Identify risks, dependencies, and data considerations in advance. These activities sit **before** full configuration and pilot work, and make later phases faster and more effective. *** ### 2. Implementation phases A typical OpenCRVS programme is organised into three main implementation phases, plus a pre‑transformation phase that can secure buy‑in and super‑charge business analysis. 1. **Proof of Concept (PoC)** – configure the core product with basic country inputs to prove OpenCRVS’ applicability and identify additional requirements. 2. **Pilot** – test OpenCRVS in a range of real‑world settings to prove that it works, improve the configuration, and refine a scalable, integrated rollout plan. 3. **Scale‑up** – expand digital services across the country using the integrated components tested in the pilot. 4. **Operational support** – manage and maintain the solution for the long term, including regular product upgrades and hot fixes. Pre‑configuration activities prepare the country to move through these phases efficiently. *** ### 3. Roles and responsibilities A successful OpenCRVS project needs clear ownership. The country owns the legal, operational and policy decisions that shape the system. The OpenCRVS team, an implementation partner, or another delivery team may provide product expertise, implementation guidance, configuration support, technical delivery and project coordination, depending on the agreed project approach. The exact split between the OpenCRVS team, implementation partners, suppliers and local technical teams should be confirmed in the project scope, workplan or terms of reference. | Activity | Country / government team | OpenCRVS team, implementation partner or delivery team | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Project governance | Appoint sponsor, decision-makers and working groups; approve scope, risks and milestones. | Advise on recommended governance and implementation approach; coordinate governance meetings, action logs and delivery reporting where agreed. | | Vision, scope and roadmap | Define country objectives, event types, locations, service channels and rollout priorities. | Explain OpenCRVS capabilities, constraints and typical implementation pathways; help translate objectives into a practical roadmap and workplan. | | Stakeholder engagement | Convene civil registration, health, statistics, identity, legal, ICT and local service stakeholders. | Advise on which stakeholder groups are usually needed; facilitate workshops, document decisions and follow up actions where agreed. | | Business analysis | Confirm current processes, pain points, legal rules, future workflows and user needs. | Lead or support analysis, process mapping and requirements documentation; provide product and CRVS domain guidance; challenge requirements that may add unnecessary complexity. | | Legal and policy decisions | Decide registration authority, legal source of truth, fees, certificate rules, privacy, data sharing and delegations. | Identify where legal or policy decisions affect configuration; provide examples from other implementations where appropriate; track unresolved decisions and dependencies. | | Configuration decisions | Approve forms, workflows, roles, scopes, workqueues, certificates, notifications and reporting requirements. | Advise how requirements map to OpenCRVS configuration; prepare configuration specifications; configure the country instance where agreed; identify where custom development should be avoided. | | Technical environments | Provide or approve hosting, domains, VPN/access, security requirements, backup expectations and production ownership. | Provide deployment guidance, reference architecture and product release information; install, configure or operate environments where agreed. | | Data migration / digitisation | Own source data; approve migration scope, mapping rules, legal status of records and exception handling. | Advise on OpenCRVS data model, API approach, migration constraints and readiness criteria; build or run migration/digitisation tools, test loads, reconciliation and exception reports where agreed. | | Integrations | Approve integration scope, data-sharing agreements, security model and operational ownership. | Explain available APIs, action triggers and product integration patterns; design, build, test and document integrations where agreed. | | Testing and UAT | Provide users, test scenarios, acceptance criteria and sign-off decisions. | Prepare test plans, run QA, support UAT, advise on expected product behaviour, support issue triage and manage defect tracking where agreed. | | Training and change management | Own user readiness, communication, policy updates and adoption across offices. | Provide product knowledge and examples of role-based training needs; develop training materials, train users and support change activities where agreed. | | Deployment and rollout | Approve rollout sequence, site readiness, go-live decision and local support arrangements. | Advise on readiness gates, product release considerations and support escalation routes; coordinate deployment logistics, site activation and go-live support where agreed. | | Operational support | Own day-to-day service operation, user administration, incident management and long-term sustainability. | Provide product-level support routes, upgrades and fixes according to agreed support arrangements; provide L1-L3 support or managed service responsibilities where agreed. | {% hint style="info" %} The OpenCRVS team, implementation partners and suppliers should not be treated as the owners of country policy, legal interpretation, data ownership or operational sign-off. Those decisions must be made by the country registration authority and relevant government stakeholders. Delivery teams support those decisions by explaining product capabilities, risks, dependencies and good-practice implementation patterns. {% endhint %} *** ### 4. Proof of Concept (PoC) OpenCRVS can be quickly configured to meet the basic civil registration needs of a country. A **Proof of Concept** uses this capability to test the product and learn more about specific business needs and system requirements before committing to full implementation. #### 4.1 What a PoC is * A quick way to see how OpenCRVS can enable digital CRVS in your country. * Use of existing functionality in the core product, applied to country‑specific data and workflows. * An opportunity to learn what works and what does not, and to identify additional system requirements. * Small‑scale field‑testing to gather user feedback and better understand requirements. * A way to inform the development of a long‑term digitisation and investment strategy. #### 4.2 What a PoC is not * Not a full requirements‑gathering process (that happens once the country confirms it wants to use OpenCRVS). * Not customisation of OpenCRVS with new features; no new functionality is built during the PoC. * Not live registration of vital events; only mock data is used, so data sovereignty questions (such as in‑country hosting) do not affect the exercise. #### 4.3 Outputs of a PoC A typical PoC produces: 1. **Configured OpenCRVS instance** – a basic configuration for the country, hosted in the cloud. 2. **Analysis document** – including β€œas‑is” and β€œto‑be” process maps for key workflows. 3. **Requirements backlog** – a structured list of requirements identified during analysis that can be used for subsequent work (this is the start of a backlog, not a complete one). 4. **Pilot plan** – a high‑level plan for piloting the solution to inform a national‑scale CRVS digitisation effort. These outputs feed directly into more detailed configuration and pilot planning. During a PoC, the OpenCRVS team may support rapid product configuration, product demonstrations, technical guidance and analysis of product fit. The country team should provide the business context, confirm whether the PoC reflects real operational needs, and decide whether to proceed to a pilot. A PoC should not transfer ownership of future legal, policy or operational decisions to the OpenCRVS team. *** ### 5. Pilot A **pilot** is a small‑scale, real‑world implementation used to test feasibility, viability, and effectiveness before full‑scale roll‑out. The purpose of a pilot is to **learn and inform scale‑up plans**, not to deliver a final, nationwide solution. #### 5.1 Why pilot * Validate that OpenCRVS works in different environments (urban, rural, health facilities, stand‑alone offices). * Refine configuration (forms, workflows, roles, workqueues, communications) based on real usage. * Test integrations with other systems (for example, health or ID systems) in a controlled way. * Identify training, change‑management, and support needs for national roll‑out. #### 5.2 Integrated pilot workstreams A successful pilot is an **integrated programme**, not just a technology exercise. Each workstream should have a named country owner and, where relevant, an implementation partner or OpenCRVS team support role. Typical workstreams include: * **Business analysis** – refine business and system requirements to help the country achieve its CRVS objectives. * **Product configuration & testing** – design, configure, and test the country instance of OpenCRVS against agreed requirements. * **Change management** – design and deliver activities that secure buy‑in from leadership and staff, and support behavioural change. * **Training** – develop and implement scalable training that equips users to work effectively with OpenCRVS. * **Monitoring & evaluation** – define key performance indicators (KPIs) and a continuous improvement approach that uses data from the pilot to adjust product, service design, and deployment. * **Operational support** – establish tier 0–4 support (self‑help, helpdesk, technical support, vendor support) so services remain operational during the pilot. Before the pilot starts, agree who leads each workstream, who provides input, who signs off outputs, and how issues are escalated. The OpenCRVS team should normally support product and technical questions, while the country team owns operational decisions and acceptance of the pilot model. Findings from these workstreams directly shape the design of the national scale‑up. *** ### 6. Establish project and team OpenCRVS is designed to minimise technical effort for setup and configuration, but a small, well‑structured team is still essential for a successful implementation. At a minimum, countries should identify **two core roles**: * **Technical System Administrator** – responsible for installing, running, and maintaining the OpenCRVS infrastructure * **Business Analyst / National System Administrator** – responsible for configuring application details, forms, workflows, and vital event certificates For a full digitisation programme, additional skills are usually required, including designers, developers, QA engineers, and programme management roles. These roles may sit within government, an implementation partner, or another delivery organisation, but ownership must be explicit. The OpenCRVS team can advise and support, but the project should not assume that the OpenCRVS team will perform all business analysis, configuration, migration, training, deployment or operational support activities unless this is agreed in the project scope. For detailed guidance on roles, skills, and team composition, see [Establish project & team](/implementation/your-opencrvs-project/establish-project-and-team) *** ### 7. Pre‑configuration checklist Before starting detailed OpenCRVS configuration, countries should consider: * **Vision and scope** – which event types, geographies, and service channels will be included in the PoC or pilot. * **Governance, ownership and responsibilities** – who is responsible for decision‑making, sign‑off, day‑to‑day coordination, and each major activity across business analysis, configuration, infrastructure, migration, integrations, testing, training, deployment and support. * **Data and integration landscape** – existing systems (for example, health, ID), data standards, and integration priorities. * **Change readiness** – current processes, capacity, and any legal or policy changes required to support digital CRVS. * **Resource planning** – availability of business analysts, implementers, trainers, and support staff to run the programme. * **OpenCRVS team involvement** – what support is expected from the OpenCRVS team, what is expected from the country team, and what will be delivered by any implementation partner or supplier. Clarifying these elements early helps ensure that subsequent configuration work across Events, Records, Workflows, Access, and Aggregate Data modules is grounded in a realistic, well‑understood plan. # Establish project & team Create a team that has the skills to be able to setup, implement, manage and maintain your OpenCRVS instance. ### 1. Introduction Before any technical configuration begins, it's important to establish a clear project structure, define business objectives, and assemble a multidisciplinary team capable of delivering a successful CRVS digital transformation. OpenCRVS implementations are not simply software deployments β€” they are national transformation initiatives requiring alignment between policy, operations, technology, and change management. Investing time upfront to define objectives and identify the right team significantly reduces implementation risk. *** ### 2. **Define the Project Initiation Document (PID)** The first step is developing a PID that gives all stakeholders a shared understanding of the programme. It should define: * **Business objectives** β€” the strategic outcomes the country expects, such as increasing registration coverage, reducing delays, improving citizen experience, or strengthening data quality. Objectives should be measurable where possible. * **Project scope** β€” which vital events will be implemented, geographic coverage (pilot, phased, national), systems requiring integration, and infrastructure hosting approach. * **Governance structure** β€” executive sponsors, a steering committee, a project manager, and clear decision-making and escalation processes. * **Success criteria** β€” key milestones, timelines, adoption targets, and service quality expectations. ### 3. **Establish the implementation team** Successful OpenCRVS programmes require a multidisciplinary team with expertise spanning policy, operations, technology, user experience, deployment, and service improvement. The exact size of the team will depend on the country context, implementation scope, and available resources. In smaller programmes, individuals may perform multiple roles. #### 3.1 **Core project leadership** **Project Manager**\ Provides overall coordination and oversight of the programme.\ Responsible for: * Managing scope, timelines, budget, risks, and dependencies * Coordinating activities across all workstreams * Tracking delivery against objectives * Managing stakeholder communication * Reporting progress to governance bodies #### **3.2 Business Analysis and Service Design** This workstream ensures that OpenCRVS is configured and implemented in a way that reflects national laws, policies, and operational realities. **Business Analyst(s)**\ Responsible for: * Mapping existing registration processes * Identifying inefficiencies and improvement opportunities * Gathering functional and non-functional requirements * Documenting business rules and workflows * Ensuring requirements are translated into implementable solutions **Design Researchers / Qualitative Researchers**\ Responsible for: * Understanding the experiences of registrars, health workers, courts, communities, and citizens * Conducting interviews, workshops, and field observations * Identifying user needs, pain points, and service barriers * Supporting user-centred service design #### **3.3 Infrastructure and Platform Management** **Technical System Administrator / DevOps Engineer**\ Responsible for: * Infrastructure provisioning * OpenCRVS installation and configuration * Managing cloud or on-premise environments * Security and access management * Monitoring system performance and availability * Backup and disaster recovery planning * Ongoing maintenance and operational support #### **3.4 Design and Development** Where additional localisation or feature development is required, a dedicated design and development team should be established. **UX/UI Designer**\ Responsible for: * Translating requirements into intuitive user experiences * Designing interfaces consistent with OpenCRVS design standards * Supporting usability testing and design validation **Technical Architect**\ Responsible for: * Defining technical solution architecture * Reviewing integrations and interoperability requirements * Ensuring scalability, maintainability, and compliance with OpenCRVS architecture principles **Software Developers**\ Responsible for: * Developing additional features and integrations * Implementing country-specific customisations * Maintaining locally developed components #### **3.5 Quality Assurance** **Test Lead / Quality Assurance Engineers**\ Responsible for: * Defining testing strategy and planning functional and non-functional testing activities * Executing test cases and performing regression testing * Validating configurations and localisations * Managing defect resolution processes * Supporting user acceptance testing (UAT) * Determining deployment readiness Comprehensive testing is critical before pilot and production deployments. #### **3.6 Training and Capacity Building** **Training Lead / Trainers**\ Responsible for: * Developing the national training strategy and designing training materials * Defining training-of-trainers approaches * Delivering training to end users and supporting onboarding activities * Monitoring training effectiveness and gathering feedback to improve materials Training should account for varying levels of digital literacy and operational experience. #### **3.7 Deployment and Rollout** **Deployment Team**\ Responsible for: * Developing deployment strategies and rollout plans * Coordinating pilot and national deployment activities * Preparing implementation sites and ensuring site readiness * Supporting training activities and assisting users during rollout * Coordinating deployment resources and validating operational readiness #### **3.8 Change Management** Technology alone does not transform civil registration services. Sustainable adoption requires structured change management. **Change Management Lead**\ Responsible for: * Developing a change management strategy and conducting stakeholder analysis * Designing communication and engagement activities * Managing organisational readiness and monitoring user adoption * Promoting the programme and supporting colleagues during transition * Gathering feedback from users and encouraging adoption of new ways of working #### **3.9 Monitoring, Evaluation and Continuous Improvement** **Monitoring & Evaluation Lead**\ Responsible for: * Defining programme indicators and success metrics * Establishing monitoring frameworks * Measuring operational performance * Conducting periodic reviews * Supporting continuous improvement initiatives Indicators may include: registration coverage, registration timeliness, system utilisation, service turnaround times, data quality measures, and user satisfaction. *** ### 4. Resources and support For broader guidance on skills and roles in CRVS digitisation, see the [CRVS Digitisation Guidebook](http://www.crvs-dgb.org/en/skills-required/). For any questions about establishing a team to configure, further develop, or manage and maintain OpenCRVS effectively, contact [**team@opencrvs.org**](mailto:team@opencrvs.org). {% hint style="info" %} **Team sizing guidance:** The size and composition of your team should reflect the scope of your implementation. A Proof of Concept may only require the two core roles, while a national-scale digitisation programme typically requires all programme and change management roles in addition to technical staff. {% endhint %} # Gathering requirements Collect and prepare all the inputs required for optimal product configuration. ## Gathering requirements ### 1. Introduction Before you configure OpenCRVS for your country, you need to understand your civil registration reality β€” the law, the day-to-day processes, the people who run them, and the citizens they serve. This stage is where you gather that understanding and turn it into the concrete inputs an OpenCRVS configuration is built from. Investing properly here pays off later. A configuration grounded in how registration actually works means less friction, less rework, and fewer surprises once you reach build, testing and roll-out. {% hint style="info" %} **What this stage produces:** a validated set of requirements and design artefacts β€” process maps, business rules, a prioritised feature scope, user roles and office hierarchy, integration use-cases, and configuration templates β€” ready to hand to the [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration) stage. {% endhint %} *** ### 2. The four stages Requirements gathering runs in four stages. Each one consumes the output of the stage before it, and the final stage hands its output to Configuration. | Stage | What you do | Key output | Indicative duration\* | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------- | | **1.** [**Desk research & planning**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/preparation-and-foundation) | Collect and analyse the law, forms, certificates and procedures; plan the fieldwork | A fieldwork plan and a baseline understanding of the country's CRVS context | 2–4 weeks | | **2.** [**Field Research & Discovery**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/field-research-and-discovery) | Interview, observe and shadow; map how registration really works | Validated "as-is" process maps and a business-rules register | 1–3 weeks in country | | **3.** [**Co-Design & Validation**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/co-design-and-validation) | Run workshops to validate findings, agree scope and shape the future service model | Prioritised features, user roles and office hierarchy, integration use-cases | 1–2 weeks | | **4.** [**Design & Specification**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification) | Turn the agreed scope into mock-ups, prototypes and configuration templates | Approved configuration templates ready for build | 2–4 weeks | \*Indicative only. Effort scales with the number of events in scope, the geographic spread, and whether you are running a proof of concept or a national programme. The handoff chain, end to end: > **Desk research & planning** β†’ fieldwork plan β†’ **Field Research** β†’ validated as-is maps + business rules β†’ **Co-Design** β†’ prioritised scope, roles, integrations β†’ **Design & Specification** β†’ configuration templates β†’ **Configuration** *** ### 3. Where this sits in the implementation Gathering requirements comes after you have done your [project planning](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/project-planning) and [established a core team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team), and before [Solution architecture](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/solution-architecture) and [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration). **You are ready to start when:** * a project sponsor is identified and the core team is in place β€” at minimum a Business Analyst and a Technical System Administrator (see [Establish project & team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team)) * you have government agreement to engage registry, health and statistics stakeholders. **You are ready to move on when:** you hold validated process maps, a business-rules register, a prioritised feature scope, finalised user roles and office hierarchy, integration use-cases, and approved configuration templates. *** ### 4. Who you need and how long it takes Requirements gathering is led by a small, multidisciplinary team. The disciplines most specific to this stage are: * **Business / process analysts** β€” to map processes and capture business rules * **Qualitative researchers / designers** β€” to run interviews, observation and workshops * **Discovery or product managers** β€” to drive prioritisation and scope * **Local legal and civil-registration experts** β€” to interpret the legal framework and validate findings * **Technical / systems analysts** β€” to assess existing systems and integration needs For the full set of roles across the whole implementation β€” including the change management, training, deployment and monitoring roles you will need later β€” see [Establish project & team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team). {% hint style="info" %} **Sizing guidance:** A focused discovery for a proof of concept or single-province pilot β€” one or two vital events, a handful of sites β€” typically takes **6–12 weeks** end to end. A national programme covering all vital events, multiple administrative tiers and several integrations takes considerably longer and usually runs some activities (for example, desk research and fieldwork logistics) in parallel. Plan the stages to overlap where it is safe to do so, but do not start **Co-Design** before your field findings are validated. {% endhint %} {% hint style="info" %} **Embed your own people.** Wherever an implementing partner leads this work, include government staff (registrars, statisticians, IT) in the team throughout. They hold the contextual knowledge that makes findings accurate, and their involvement is what makes the resulting system sustainable after handover. {% endhint %} *** ### 5. Principles to carry through every stage * **Evidence-based.** Decisions are grounded in what you observe and validate in the field, not in assumptions or policy documents alone. * **Inclusive.** Universal registration is the goal, so actively investigate barriers for under-served groups β€” rural and hard-to-reach populations, women, persons with disabilities, and displaced, stateless or undocumented people β€” and design for them, not around them. * **Privacy by design.** OpenCRVS will hold sensitive personal data on the whole population. Capture data-protection, retention and access requirements from the outset; they shape user roles, access control and integrations. * **Co-designed with government.** The future service model has to be one the government will commit to and run, so validate every major finding and decision with the people who own and operate the system. *** ### 6. Resources and support For broader guidance on CRVS digitisation, including requirements and process mapping, see the [CRVS Digitisation Guidebook](http://www.crvs-dgb.org/). For any questions about gathering requirements or configuring OpenCRVS, contact [**team@opencrvs.org**](mailto:team@opencrvs.org). # Desk research & planning Desktop research and planning before any fieldwork ### 1. Introduction Before you can configure OpenCRVS for your country, you need a working knowledge of how civil registration and vital statistics (CRVS) are supposed to work β€” in law and in procedure. This page covers the first stage of [Gathering requirements](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements): the **desk research** that builds that knowledge, and the **planning** that turns it into a fieldwork plan. Doing this well means your time with registrars, health workers and citizens is spent validating and probing the things documents cannot tell you β€” not on basic discovery. The result is targeted, efficient fieldwork and far better use of your stakeholders' time. {% hint style="info" %} **What this stage produces:** a baseline understanding of the country's CRVS context, and a ready-to-execute fieldwork plan. Both feed directly into [Field Research & Discovery](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/field-research-and-discovery). {% endhint %} **When:** This is the first stage of requirements gathering and is mostly desk-based. It can begin as soon as your core team is in place. Indicative duration: **2–4 weeks**, depending on the number of vital events in scope and how readily the source documents can be obtained. **Before you start, you should have:** * a project sponsor and the core team in place β€” at minimum a Business Analyst and a Technical System Administrator (see [Establish project & team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team)) * the list of vital events the implementation will cover (for example: birth, death, marriage β€” and possibly divorce, adoption or stillbirth) * government agreement to request documents from, and later engage, registry, health and statistics bodies.

Registration Agent sharing examples of vital event records, declaration forms and certificate templates.

*** ### 2. Desk research Build your understanding from the documents that define how registration works today, then read them with configuration in mind. #### 2.1 Collect the existing materials Gather the official documents listed below. Log anything you cannot obtain so the gap can be filled during fieldwork. | Document | What to extract from it | Likely source | Collected? | | ------------------------------------------------ | ----------------------------------------------------------------------------- | -------------------------------------- | ---------- | | Civil Code / Vital Statistics Act | Legal mandate, event definitions, registration time limits, who must register | Ministry of Justice / Attorney General | ☐ | | Subsidiary regulations, decrees, circulars | Detailed procedures, fees, late-registration rules | Registrar General's office | ☐ | | Blank declaration/registration forms (per event) | Data fields collected, ordering, complexity | Registry / health facilities | ☐ | | Sample certificates (per event) | Legal content, security features, languages | Registry | ☐ | | Standard Operating Procedures (SOPs) / manuals | The intended workflow, actors and handoffs | Registry | ☐ | | Data-protection law and regulations | Lawful basis, data residency, retention, access rules | Data Protection Authority / Justice | ☐ | | Existing data-sharing agreements | Current or planned integrations (National ID, health, statistics) | Relevant ministries | ☐ | | Fee schedule | Registration, certification and late-registration fees, and any waivers | Registrar General's office | ☐ | | Administrative-boundary and office list | Jurisdictions and office hierarchy | Statistics office / interior ministry | ☐ | #### 2.2 Analyse the legal and procedural framework Collecting the law is not the same as knowing what it requires. Read the documents with one question in mind: **which legal parameters will shape the OpenCRVS configuration?** Capture each one, and where the answer is unclear or contested, mark it as something to confirm in the field. The table below maps the parameters that most often drive configuration decisions to the configuration work they feed. Use it as your extraction checklist. | Legal / policy parameter | Question to answer | Feeds (downstream configuration) | | ------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Registrable events in scope | Which events are legally registered? | [Event configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration/guides/guide-event-configuration) | | Registration time limit | What is the on-time window per event (for example, 30 days for a birth)? | Workflow branches; late/delayed logic | | Late & delayed registration | What evidence, approval or fees apply after the window? When is a court order required? | Conditional fields, scopes, fees | | Eligible informants | Who may declare each event? | [Form configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration/guides/guide-form-configuration); declaration roles | | Required vs optional data | What is the legal minimum data set per event? | Form configuration / validation | | Supporting documents | What evidence must accompany a declaration? | Form (document upload) requirements | | Who may register, approve and certify | Which roles validate, register and sign records? | User roles & scopes; certificate signing | | Correction & amendment | Administrative vs court-ordered correction; who approves? | Correction flows; scopes | | Certified-copy content & security | What must a certificate show? What security features and languages are required? | [Certificate configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration/guides/guide-certificate-configuration) | | Fees & waivers | What is charged, to whom, and who is exempt? | Business rules / configuration | | Jurisdiction & hierarchy | Which office serves which area, and what are the reporting lines? | [Mapping offices and users](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration/guides/guide-mapping-offices-and-users) | | Identifiers | Is a national ID issued at birth? What is the registration-number format? | Integrations; number generation | | Languages & scripts | What are the official languages? Are any right-to-left? | Localisation | | Notification obligations | Who must be notified of an event (National ID, health, statistics, electoral)? | Integration use-cases | | Data protection & retention | What is the lawful basis, residency, retention period, access and audit expectation? | Roles/scopes; non-functional requirements; audit | #### 2.3 Draft a preliminary "as-is" picture From the SOPs and process documents, sketch a first draft of how each in-scope event is registered today β€” the main steps, the actors, and the forms used. This is a starting hypothesis, not the truth: you will test and correct it in the field. Capturing it now means you arrive with specific things to verify rather than a blank page. *** ### 3. Fieldwork planning Turn your understanding and your open questions into a concrete plan: who to see, when, and what to ask. #### 3.1 Map your stakeholders You cannot plan fieldwork without knowing who to see and why. Build a stakeholder map covering everyone from national policymakers to facility staff and citizens. For each stakeholder, record: **name / role**, **organisation**, **level** (national, sub-national, facility, citizen), **their interest**, **their influence**, **what you need from them**, **engagement priority** (high / medium / low), and **contact details**. Plotting interest against influence helps you decide who to engage, and how deeply. #### 3.2 Plan the schedule and logistics Turn the stakeholder map into a concrete itinerary: * **Itinerary** β€” specific dates, sites (central registry, regional offices, health facilities) and people to meet. * **Site selection** β€” deliberately include contrasting contexts: urban and rural, high- and low-volume offices, well-connected and offline locations. Note your reasoning so the research is defensible. * **Objectives per visit** β€” what each meeting or site visit needs to confirm or uncover, based on the gaps from section 2. * **Logistics** β€” travel, permissions, equipment, and (for workshops) venues, invitations and materials. #### 3.3 Prepare the discussion guides Write a short, tailored guide for each audience rather than one generic list. Suggested starting points: * **Policymakers / CRVS officials** β€” mandate, priorities, known pain points, and what success looks like. * **Registrars** β€” the real day-to-day steps, exceptions, workarounds, volumes, and what slows them down. * **Health-facility staff** β€” how births and deaths are notified, and what data they hold. * **IT / systems staff** β€” current systems, connectivity, integration appetite, and security. * **Citizens** β€” how they register an event, what it costs them in time, money and travel, and what gets in the way. {% hint style="info" %} **Build in the inclusion lens.** In every guide, include prompts about under-served groups: how do rural or hard-to-reach families register? Are there gender-related barriers? How are persons with disabilities, or displaced, stateless or undocumented people served? Are there customary or religious practices the formal system does not capture? These questions are easy to omit and hard to retrofit. {% endhint %} *** ### 4. Outputs and definition of done **Key outputs:** by the end of this stage you should have: * a collection of source materials (laws, forms, certificates, SOPs, fee schedules, boundary lists), with gaps explicitly logged * a legal-parameter register β€” the completed analysis from section 2.2, flagging what still needs field validation * a preliminary as-is sketch for each in-scope event * a stakeholder map with engagement priorities * a fieldwork plan and schedule with site-selection rationale * a set of tailored discussion guides, one per audience. **Definition of done:** you are ready to move to [Field Research & Discovery](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/field-research-and-discovery) when: * \[ ] all priority documents are collected, or their absence is logged as a field question * \[ ] the legal-parameter register is drafted, with open questions flagged * \[ ] the stakeholder map is agreed * \[ ] the fieldwork schedule is confirmed with named contacts * \[ ] a discussion guide exists for each audience you plan to meet. *** ### 5. Resources and support For broader guidance on requirements gathering and process mapping for CRVS, see the [CRVS Digitisation Guidebook](http://www.crvs-dgb.org/). For any questions about gathering requirements or configuring OpenCRVS, contact [**team@opencrvs.org**](mailto:team@opencrvs.org). {% hint style="info" %} **Next:** the fieldwork plan and baseline understanding produced here are the inputs to [Field Research & Discovery](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/field-research-and-discovery), where you validate and correct them on the ground. {% endhint %} # Field Research & discovery Context immersion and primary research ### 1. Introduction This is the second stage of [Gathering requirements](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements), and it is where you find out how civil registration actually works β€” not how it is supposed to work on paper. You go into registry offices, health facilities and communities to see the process in action: who does what, where it slows down, and the workarounds people rely on to get the job done. The goal is to document the gaps between formal policy and day-to-day reality. That practical insight is what makes the difference between a configuration that fits the country and one that fights it. {% hint style="info" %} **What this stage produces:** validated "as-is" process maps, a business-rules register, and a prioritised list of the problems worth solving. These are the evidence base for [Co-Design & Validation](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/co-design-and-validation). {% endhint %} **When:** This stage is carried out in country, after [Desk research & planning](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/preparation-and-foundation). Indicative duration: **1–3 weeks** of fieldwork, plus time to synthesise afterwards. It scales with the number of events in scope and the geographic spread. **Before you start, you should have** the outputs of Desk research & planning: * a fieldwork plan and confirmed schedule * a baseline understanding of the CRVS context, including a preliminary "as-is" sketch per event * a legal-parameter register, with open questions flagged for the field * a stakeholder map and a discussion guide for each audience.

In-office observation and interviews with civil registration agents to gain real qualitative insights on how vital events are registered, challenges and opportunities for improvement.

*** ### 2. Conduct the research Use a mix of methods. Interviews tell you what people believe happens; observation shows you what actually happens; tracing an event end to end reveals the gaps between the two. #### 2.1 Interview stakeholders Run structured and semi-structured interviews across the full range of people in your stakeholder map: national CRVS officials and policymakers, sub-national administrators, local registrars, health-facility staff who initiate birth and death notifications, and citizens who use the service. Use the tailored discussion guides, and focus on perspectives, pain points and the workarounds people have invented to cope. #### 2.2 Observe and shadow Spend time in registration offices and facilities watching the process happen. Note the things documents never mention: infrastructure and connectivity limitations, how complex the forms really are, data-quality issues, queue lengths, and resource constraints. Shadowing a registrar through a normal day surfaces more than any interview. #### 2.3 Trace each event end to end For each in-scope event, physically follow the full lifecycle from the triggering event to the issued certificate. Record every step, the forms used, the responsible actor, the time taken, and each point where the case is handed off between people or offices. This is the raw material for your process maps. {% hint style="info" %} **How much is enough?** Aim for coverage rather than volume. Deliberately include contrasting contexts β€” urban and rural, high- and low-volume offices, well-connected and offline sites β€” and actively seek out under-served groups: rural and hard-to-reach families, women facing specific barriers, persons with disabilities, and displaced, stateless or undocumented people. Note your site-selection reasoning so the research is defensible. You have enough when new visits stop surfacing new problems. {% endhint %} *** ### 3. Synthesise the findings Turn raw observations into the validated artefacts the next stage depends on. Check everything against the baseline you built during desk research, and resolve the open questions you carried into the field. #### 3.1 Build the "as-is" process maps Produce one validated set of process maps for each in-scope event. Capture the flow on site as you trace it (section 2.3), then clean it up into a clear diagram and confirm it with the people who do the work. {% hint style="info" %} **Process-mapping convention.** Use swim-lane diagrams or Business Process Model and Notation (BPMN). Keep it consistent so maps from different team members can be compared: * one lane per actor (citizen, registrar, health worker, system) * for each step, capture the actor, the input/output document, the system used, and the time taken * mark every decision point and handoff * flag bottlenecks, redundant steps and unofficial workarounds with a consistent visual key. {% endhint %} #### 3.2 Compile the business-rules register Document the rules that govern how registration works: policies, constraints, calculations and conditional logic β€” for example age requirements, registration time limits, who may act as an informant, and what evidence is required. These are core **business and functional rules**, and they become authoritative references that keep the configured system consistent and compliant. Cross-check each rule against the legal-parameter register from desk research, and record where field reality diverges from the written law. Capture genuine **non-functional requirements** separately β€” for example expected performance and availability, offline working and intermittent connectivity, security, and data-protection and retention obligations. These shape the solution architecture and the user roles and scopes, and are easy to lose if they are mixed in with business rules. #### 3.3 Identify and prioritise the key problems Synthesise the findings into a shortlist of the top 5–10 challenges, each backed by evidence (a quote, a photo, a point on a process map). For each, note an initial idea for a technological or procedural intervention. This shortlist becomes the design mandate that Co-Design works from, so be clear about what the problem is, why it matters, and who it affects. #### 3.4 Prepare the findings readout Pull the above into a concise findings readout for stakeholders β€” a short report or presentation, led by field observations and made vivid with visuals, quotes and process maps. Its job is to build a shared, evidence-based understanding, make the case for change, and set the strategic direction going into the workshops. *** ### 4. Outputs and definition of done **Key outputs:** by the end of this stage you should have: * a validated "as-is" process map for each in-scope event * a business-rules register, cross-checked against the legal-parameter analysis * a documented set of non-functional requirements * a prioritised list of the top 5–10 problems, each with supporting evidence * a findings readout for stakeholders. **Definition of done:** you are ready to move to [Co-Design & Validation](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/co-design-and-validation) when: * \[ ] as-is maps are validated with frontline staff for every in-scope event * \[ ] the business-rules register is compiled and reconciled with the legal-parameter register * \[ ] non-functional requirements are captured separately * \[ ] open questions carried from desk research are resolved or escalated * \[ ] the top 5–10 problems are agreed and evidenced * \[ ] the findings readout is ready for the Co-Design workshops. *** ### 5. Resources and support For broader guidance on field research and process mapping for CRVS, see the [CRVS Digitisation Guidebook](http://www.crvs-dgb.org/). For any questions about gathering requirements or configuring OpenCRVS, contact [**team@opencrvs.org**](mailto:team@opencrvs.org). {% hint style="info" %} **Next:** the validated as-is maps, business rules and prioritised problems produced here are the inputs to [Co-Design & Validation](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/co-design-and-validation), where stakeholders turn them into an agreed scope and a future service model. {% endhint %} # Co-Design & validation Collaborative workshops for alignment in solution development ### 1. Introduction This is the third stage of [Gathering requirements](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements). Here you bring stakeholders together β€” government, service providers, technical partners and, where possible, citizens β€” to validate what you found in the field, agree what matters most, and co-create the future service. The work is workshop-driven. By the end you should have a shared, evidence-backed vision that the government will commit to: a clear scope, a prioritised set of features, and the technical groundwork (roles, office hierarchy and integrations) that the build depends on. {% hint style="info" %} **What this stage produces:** an agreed scope and a future service model, with prioritised features, finalised user roles and office hierarchy, and integration use-cases. These are the inputs to [Design & Specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification). {% endhint %} **When:** This stage follows [Field Research & Discovery](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/field-research-and-discovery). Indicative duration: **1–2 weeks** of workshops, plus preparation and write-up. It scales with the number of events in scope and the number of stakeholder groups to align. **Before you start, you should have** the outputs of Field Research & Discovery: * validated "as-is" process maps for each in-scope event * a business-rules register and a set of non-functional requirements * a prioritised shortlist of the top 5–10 problems, with evidence * a findings readout to anchor the workshops * confirmed availability of the stakeholders you need in the room.

Multiple national stakeholders during co-design workshops to align on priorities for future service delivery models.

*** ### 2. Validate and align Start by confirming the evidence with the people who own and run the system, so that everything downstream rests on a shared understanding rather than the project team's interpretation. #### 2.1 Agree the CRVS business objectives Run a workshop to review, co-create and prioritise the objectives for the programme β€” linking specific improvements (such as digitisation) to outcomes that matter: better services, greater inclusion, and more reliable vital statistics. **Output:** a short statement of agreed objectives, endorsed by leadership, that commits the organisation and guides later decisions. #### 2.2 Validate the as-is processes Walk the field-derived process maps through with a diverse group of stakeholders to confirm they are accurate and to build a shared view of where the current system fails β€” inefficiencies, inequities and access barriers. **Output:** validated as-is maps and an agreed list of bottlenecks and barriers, ready to prioritise. #### 2.3 Agree the priority problems to solve Turn the discovery findings into a set of concise problem statements that decision-makers sign up to. Synthesise the evidence into themes, share the stories behind them, and agree what the project will and will not try to fix. **Output:** an agreed set of problem statements β€” the design mandate for the rest of the stage. *** ### 3. Define the future service and scope With problems agreed, co-design the future service, check what OpenCRVS already supports, and decide what to build first. #### **3.1 Shape the future Service Delivery Model (SDM)** A Service Delivery Model describes how the future service works end to end: the roles involved, the channels citizens use to interact (in person, online, mobile), and the process steps for each event. Aim beyond incremental fixes β€” design a model that adapts to demographic and technological change and is organised around life events. Useful techniques include scenario planning (for example, mobile-first), service design (journey maps) and rapid prototyping, blending global good practice with local realities. **Output:** an agreed future SDM for each in-scope event.
#### **3.2 Map requirements to OpenCRVS use cases** Before prioritising, check what OpenCRVS already does. Break each future SDM down into the features and requirements it implies, then map each one against the [Use case inventory](https://documentation.opencrvs.org/v2.0/releases/editor) β€” the canonical list of capabilities OpenCRVS supports. This fit-gap analysis tells you, for every requirement, whether the route to delivering it is configuration or new design work, which is what makes the effort scoring in 3.3 reliable rather than a guess. Tag each requirement one of three ways: * **Supported** β€” covered by a current use case; the route is configuration. Effort is low and knowable. * **Partially supported** β€” achievable through configuration plus a workaround (for example a custom action, a flag, or a process change). The workaround still has to be designed, so effort is medium. * **Not supported** β€” no current use case covers it. This is a genuine gap that needs a deliberate decision in 3.4. | Requirement / feature | Maps to OpenCRVS use case | Support level | Route to deliver | Notes | | ---------------------------------------- | --------------------------------- | --------------------- | ------------------------------------- | ----------------------------------- | | *Health-facility birth notification* | *Notify (incomplete declaration)* | *Supported* | *Configure role scopes + workqueue* | *Standard pattern in Farajaland* | | *Approve late registration above 1 year* | *Custom action + flag* | *Partially supported* | *Custom action, escalation workqueue* | *Workaround to design and validate* | | *Offline biometric deduplication* | *β€”* | *Not supported* | *Decide route in 3.4* | *Raise as a gap* | | | | | | | {% hint style="info" %} **Prefer configuration.** When a requirement is not met out of the box, work through the options in this order: configure an existing capability, design a configuration workaround, commission custom development, or raise the need with the OpenCRVS team as a core-roadmap request. A gap in the platform is a roadmap conversation, not an assumption β€” do not plan as though unreleased capabilities will be available. {% endhint %} **Output:** a requirements list tagged Supported / Partially supported / Not supported, each with its route to delivery. #### **3.3 Prioritise the OpenCRVS scope and features** You cannot build everything at once, so prioritise collaboratively against agreed criteria. Score each candidate feature on three value lenses and on effort β€” using the support level from 3.2 to ground the effort estimate (supported features are low effort; partial and unsupported features carry the cost of their workaround or development route): * **Citizen value** β€” does it remove a real barrier for the public? * **Government and legal value** β€” is it required by law, or does it materially improve operations? * **Statistical value** β€” does it improve the completeness or quality of vital statistics? * **Effort** β€” relative cost and complexity to deliver, informed by the support level. Then place each feature into a MoSCoW category β€” **Must**, **Should**, **Could**, or **Won't (this time)** β€” recording the rationale so the result is reproducible rather than opinion-led. | Feature / epic | Problem it solves | Support level | Value (citizen / gov & legal / statistical) | Effort | MoSCoW | Rationale | | ----------------------------------------- | ------------------------------------- | ------------- | ------------------------------------------- | ------ | ------ | ---------------------------------------------- | | *e.g. Health-facility birth notification* | *Late and missed birth registrations* | *Supported* | *High / High / High* | *Low* | *Must* | *Legal duty + closes biggest completeness gap* | | | | | | | | | **Output:** a prioritised feature list with a clear, evidenced rationale and milestones. #### **3.4 Capture service-concept epics** For each priority service, write a one-page concept that gives stakeholders a high-level view of the new service: the problem it addresses, the main use cases, the current challenges, a short epic statement, and the initial design and development principles. For any feature tagged **Partially supported** or **Not supported** in 3.2, the epic must also record its **resolution route** β€” how the gap will be closed β€” and the consequence for timeline, cost and supportability. Choose one: * **Configuration workaround** β€” met by combining existing capabilities (custom actions, flags, process design). * **Custom development** β€” requires bespoke build; note the ownership, cost and long-term maintenance implication. * **Core-roadmap request** β€” raised with the OpenCRVS team as a candidate platform feature; cannot be assumed available for this implementation. * **Descope or defer** β€” not delivered this time; record the decision and revisit in a later phase. This keeps a single artefact type β€” every priority service has a concept epic β€” while making sure no gap is carried into design without an agreed way of closing it. **Output:** a set of service-concept epics, with a resolution route recorded for every partial or unsupported feature, ready to take into design. *** ### 4. Establish the technical groundwork Define the administrative and technical foundations the configuration will be built on. #### 4.1 Confirm the office hierarchy and user roles Catalogue the registration offices, the user roles, and the reporting lines, and validate them with stakeholders β€” clarifying who is responsible for which decisions, data and reports. Capture this in the format expected by the [Mapping offices and users](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration/guides/guide-mapping-offices-and-users) configuration guide. **Output:** a validated office hierarchy and a user-role and scope list. #### 4.2 Define the integration use-cases A digital CRVS rarely stands alone β€” it exchanges data with systems such as National ID, health and statistics. Map those systems, identify the connection points, and define each exchange as a use-case, validated with the owning systems' teams and their security requirements. Document one row per integration: | Use case | Source system | Target system | Trigger | Data exchanged | Direction | Frequency / volume | Security & consent | Owner | Priority | | ------------------------------------------ | ------------- | ------------- | ------------------------ | ---------------------------- | ---------- | ------------------ | -------------------------- | ---------- | -------- | | *Notify National ID on birth registration* | *OpenCRVS* | *National ID* | *Registration completed* | *Child + parent identifiers* | *Outbound* | *Real-time* | *Encrypted; legal basis X* | *NID team* | *Must* | | | | | | | | | | | | **Output:** a set of agreed integration use-cases, prioritised and owned. *** ### 5. Outputs and definition of done **Key outputs:** by the end of this stage you should have: * endorsed CRVS business objectives * validated as-is processes, with agreed bottlenecks and barriers * an agreed set of problem statements * a future Service Delivery Model for each in-scope event * a requirements-to-use-case mapping (fit-gap), with each requirement tagged by support level and given a route to delivery * a prioritised feature list (MoSCoW), with rationale * a set of service-concept epics, with a resolution route recorded for every partial or unsupported feature * a validated office hierarchy and user-role/scope list * a set of prioritised, owned integration use-cases. **Definition of done:** you are ready to move to [Design & Specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification) when: * [ ] business objectives are endorsed by leadership * [ ] as-is processes are validated with stakeholders * [ ] problem statements are agreed * [ ] a future SDM is agreed for each in-scope event * [ ] requirements are mapped to the Use case inventory, and every gap has an agreed resolution route * [ ] the feature list is prioritised with a recorded rationale * [ ] the office hierarchy and user roles are validated * [ ] integration use-cases are agreed with the owning systems' teams. *** ### 6. Resources and support For broader guidance on co-design, service design and prioritisation for CRVS, see the [CRVS Digitisation Guidebook](http://www.crvs-dgb.org/). For any questions about gathering requirements or configuring OpenCRVS, contact [**team@opencrvs.org**](mailto:team@opencrvs.org). {% hint style="info" %} **Next:** the agreed scope, future SDM, prioritised features, roles and integration use-cases produced here are the inputs to [Design & Specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification), where they become mock-ups, prototypes and configuration templates ready for build. {% endhint %} # Design & specification Creating implementation-ready deliverables ### 1. Introduction This is the final stage of [Gathering requirements](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements). It turns the validated scope, roles and workflows from [Co-Design & Validation](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/co-design-and-validation) into your **to-be design** β€” tangible artefacts and configuration inputs that a team can build from with minimal ambiguity. The **configuration guides** that sit under this stage are your main reference. Each one documents what OpenCRVS supports and includes recommendations, so you use them to shape the to-be requirements rather than designing in the abstract. Working through design before build also lets you validate the solution with stakeholders before any intensive coding. {% hint style="info" %} **What this stage produces:** approved mock-ups and prototypes, and a complete set of **configuration inputs** that capture the to-be (the full list is in section 3). These are then applied in the [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration) stage. {% endhint %} **When:** This stage follows Co-Design & Validation and closes out requirements gathering. Indicative duration: **2–4 weeks**, depending on the number of events in scope and how much is configured with defaults versus designed afresh. **Before you start, you should have** the outputs of Co-Design & Validation β€” a prioritised feature list and service-concept epics, a future Service Delivery Model (SDM) per event, a validated office hierarchy and user roles, and agreed integration use-cases β€” plus the business-rules register and non-functional requirements from earlier stages to design against. You will also draw on the **configuration guides below**, which tell you what OpenCRVS supports and recommend good-practice defaults. *** ### 2. Design the experience Produce visual mock-ups and interactive prototypes so stakeholders can see and validate the to-be solution before it is built. Trace every screen back to the business rules and legal parameters captured earlier, and check what is configurable against the relevant guide, so design decisions are grounded rather than invented. #### 2.1 Registration form mock-ups For each in-scope event, mock up the registration form: the fields, their order, conditional logic, and validation. Each field and rule should trace to a business rule or legal parameter. Use the [Form configuration guide](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-form-configuration) to see what is supported and recommended. #### 2.2 Correction and print/record flow mock-ups Mock up how corrections and record printing behave β€” including the difference between administrative and court-ordered corrections, and how a certified copy is printed and reissued β€” so the workflow rules are concrete before configuration. #### 2.3 Vital-event certificate mock-ups Design the certified copy for each event: layout, the legally required content, security features, and any languages or scripts. Use the [Certificate configuration guide](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-certificate-configuration). #### 2.4 Integration UI component mock-ups Where an integration surfaces in the interface β€” for example a National ID lookup or a health-facility notification intake β€” mock up the components so the interaction and the data shown are agreed before build. #### 2.5 Prototypes of new features For anything beyond OpenCRVS default behaviour, build an interactive prototype. Prototypes are the cheapest way to test a new idea with stakeholders and surface problems while they are still easy to change. *** ### 3. Configuration guides and inputs The guides below sit under this stage as your inputs. Each documents what OpenCRVS supports and includes recommendations, so you use them to shape the to-be design. Work through them to produce the **configuration inputs** β€” the artefacts that define your OpenCRVS configuration and are handed to the [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration) stage to build. **The guides:** * [**Event configuration**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-event-configuration) β€” designing the end-to-end business process for each event: steps, statuses, actions and workqueues (includes a worked [Name change](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-event-configuration/name-change) example). * [**Form configuration**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-form-configuration) β€” defining the declaration and action form fields, validation and conditional logic. * [**Certificate configuration**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-certificate-configuration) β€” defining certified-copy content, layout and security. * [**Mapping offices and users**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-mapping-offices-and-users) β€” defining the administrative structure, offices, user roles and scopes. * [**Dashboard**](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-dashboard) β€” defining the analytics and vital-statistics dashboards. **The configuration inputs** you produce, and the guide that supports each: | Configuration input | What it defines | Guide | | ------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------- | | **Administrative structure and locations** | The jurisdictional hierarchy, registration offices and health facilities | Mapping offices and users | | **Event business process flows** | The workflow and statuses each event moves through | Event configuration | | **Event business rules and requirements** | The rules governing each event β€” time limits, eligibility, validation | Event configuration | | **User roles and scopes** | Roles, permissions and scope-based access | Mapping offices and users | | **Workqueues** | The queues of records users work from, by status and role | Event configuration | | **Event record actions** (actions and flag config) | The actions available on a record, and flag configuration | Event configuration | | **Event form definitions** (declaration, action forms) | Fields, ordering, validation and conditional logic | Form configuration | | **Certified-copy templates** | Certificate layout, legal content, security features and languages | Certificate configuration | | **Analytics and vital statistics dashboards** | The dashboards and reporting outputs | Dashboard | {% hint style="info" %} **Start from the defaults.** OpenCRVS ships with the Farajaland reference configuration. Use it as your worked example: configure against it and adapt, rather than starting from a blank set of inputs. It shows you the shape of the target artefact for each input above. {% endhint %} *** ### 4. Outputs and definition of done **Key outputs:** by the end of this stage you should have: * approved mock-ups for registration forms, correction and print/record flows, vital-event certificates, and integration UI components * interactive prototypes for any new features * the completed configuration inputs listed in section 3. **Definition of done:** you are ready to move to the [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration) stage when: * \[ ] mock-ups and prototypes are signed off by stakeholders * \[ ] each form field and rule traces back to a business rule or legal parameter * \[ ] configuration inputs are complete and checked against the legal-parameter register, using the guides above * \[ ] the completed configuration inputs are ready to apply in the Configuration stage. *** ### 5. Resources and support The guides under this stage β€” [Event configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-event-configuration), [Form configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-form-configuration), [Certificate configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-certificate-configuration), [Mapping offices and users](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-mapping-offices-and-users) and [Dashboard](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification/guides/guide-dashboard) β€” are the working references for this stage. For broader guidance on CRVS digitisation, see the [CRVS Digitisation Guidebook](http://www.crvs-dgb.org/). For any questions, contact [**team@opencrvs.org**](mailto:team@opencrvs.org). {% hint style="info" %} **Next:** this is the last stage of requirements gathering. With approved designs and completed configuration inputs in hand, you move on to [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration) to build the system. {% endhint %} # Guides # Guide: Event configuration ### 1. Introduction The role of OpenCRVS is to enable **efficient, high‑quality civil registration services**. That starts with smart business processes that make the most of what digital technology can offer, instead of simply copying existing paper workflows. Use this page when you are: * Reviewing current CRVS processes before introducing OpenCRVS. * Designing new or improved workflows (for example, late registration, corrections, certificate issuance). * Preparing material to support legal or policy updates. *** ### 2. Do’s and don’ts #### 2.1 Do 1. **Use technology to enhance processes and satisfaction** Design workflows that reduce travel, waiting time, and manual re‑entry of data. 2. **Explore digital options even if laws are not yet updated** Consider features such as **digital signatures**, QR‑code verification, and electronic notifications as target end‑states. 3. **Use process redesign to inform legal change** Let improved workflows and service standards guide future **legislative updates** rather than being constrained only by existing law. 4. **Design with real users** Co‑design with registrars, health workers, and community leaders. Validate each step against what they can realistically do. 5. **Design to improve service delivery and experience** Optimise for faster registration, fewer visits, clearer responsibilities, and better communication with families. #### 2.2 Don’t 1. **Do not simply digitise paper processes** Avoid 1:1 replicas of forms, signatures, and approval chains that were designed for a paper world. 2. **Do not design based on legislation alone** Start from real operational needs and pain points, then check what must change legally to support better service. 3. **Do not dismiss features just because they are not yet legal** Treat these as a **vision** to work towards and as input to law and policy reform. 4. **Do not ignore what you already know is broken** If something causes delays or confusion today, redesign it. Do not carry known issues into your digital system. *** ### 3. Key CRVS terms Get comfortable with core terms used in CRVS workflows. Countries sometimes use these words differently, so always confirm what each term means locally. * **Notification** The **minimal set of data** relating to a vital event, often created by someone close to where the event occurs (for example, a health facility or community leader). *Note: Some countries use β€œnotification” and β€œdeclaration” interchangeably. Clarify how each term is used in your context.* * **Declaration** The **complete set of data** required to register a vital event (for example, all fields in a birth or death registration form) plus supporting documents. * **Validation** The process of **checking the declaration** against rules and evidence. This includes verifying that data is complete, consistent, and supported by appropriate documents. * **Registration** The **legal act** of adding a validated event to the civil register. After registration, the event becomes an official record and can be referenced in certificates and extracts. * **Certificate issuance** The process of **generating, printing, and issuing a certificate or certified copy** from a registered record, following defined business rules and fees. *** ### 4. Designing the end‑to‑end process When mapping business processes that OpenCRVS will support, think about the **full journey** from the moment an event occurs to the final issuance of a certificate, including who does what, where, and using which device. Below is a simple example using the core CRVS steps. Adapt the actors and locations to your country context. #### 4.1 Example mapping **Step: Notification / Declaration** * **Who is best placed to complete this step?** Health administrator, health worker, or community leader close to where events occur. * **Where should this be done?** At or near the **place of occurrence** (for example, health facility, community meeting point, outreach visit). * **Why them?** They know when events occur and can notify promptly, reducing delays and under‑registration. * **Using what device?** Mobile phone or tablet (online or offline), or a simple web form if connectivity allows. **Step: Validation** * **Who is best placed to complete this step?** Registration clerk or registration agent. * **Where should this be done?** At the **registration office** or service point where documents can be checked. * **Why them?** They handle daily administrative work on behalf of the Registrar and can follow clear validation checklists. * **Using what device?** PC or laptop with access to OpenCRVS, supporting review of both data and uploaded documents. **Step: Registration** * **Who is best placed to complete this step?** Registrar (or a designated official with legal authority). * **Where should this be done?** Wherever the Registrar can securely access OpenCRVS (usually at the registration office, but potentially remote if allowed by policy). * **Why them?** They hold the **legal mandate** to register vital events and are accountable for the accuracy of the register. * **Using what device?** PC or laptop with secure access and appropriate scopes in OpenCRVS. **Step: Certificate issuance** * **Who is best placed to complete this step?** Registration clerk or front‑office staff. * **Where should this be done?** At the **registration office** or service point where citizens collect certificates. * **Why them?** They handle most day‑to‑day interactions, payments, and printing on behalf of the Registrar. * **Using what device?** PC or laptop connected to a printer, using OpenCRVS Print actions. *** ### 5. Questions to guide process design Use these prompts when mapping or refining your business processes: * **Access and proximity** * How close is the person completing each step to where events actually occur? * Can some steps move closer to the community (for example, outreach, health facility notification)? * **Roles and responsibilities** * Is the right level of staff doing the right work? * Can clerks and agents handle more of the routine tasks so Registrars focus on decisions? * **Timing and deadlines** * How will processes support legal time limits for registration? * Where can reminders, flags, or workqueues help staff prioritise cases? * **Channels and devices** * Which steps can safely be done on mobile devices, and which require office‑based PCs? * How will offline work be handled and synced? * **Quality and fraud prevention** * Where in the process should additional checks or approvals be added? * How will you use flags, deduplication, or audit trails to manage risk? * **Citizen experience** * How many visits, documents, and signatures does the citizen currently need? * Which of these can be reduced or removed with better process and digital tools? Use the answers to these questions to propose **simpler, more reliable workflows** before you begin detailed configuration in OpenCRVS. # Guide: Form configuration Designing good forms in OpenCRVS helps users complete registrations quickly and ensures that high‑quality data is captured at source. Use the guidelines below when designing or reviewing any form. #### 1. Be clear why you are capturing each data point For every input, ask: **Why do we need this?** * Is it required to complete the registration workflow? * Is it only needed for statistics or reporting? * How will it appear in dashboards, exports, or vital statistics reports? If you cannot explain how a field will be used, strongly question whether it should be on the form at all. #### 2. Organise questions into focused pages Keep users focused on one topic at a time by grouping fields into **pages** such as: * Child details * Mother details * Father details * Informant details * Event details (birth / death / marriage) Use **conditional logic** to show or hide whole pages when they are only relevant in some scenarios. For example, only show "Father details" if the user confirms that the father is legally recognised in the registration. #### 3. Use conditional fields to simplify the experience Make the form feel smart by only showing fields when they are genuinely needed. Examples: * Show the **Medically Certified Cause of Death** inputs only when the user confirms that a medical practitioner has established the cause of death. * Ask for **facility details** only when the place of occurrence is a health facility. * Reveal **late registration justification** fields only when the declaration is beyond a configured time limit. Always ask yourself: *What can the system infer from existing answers so that the user does not have to think about it or see irrelevant fields?* #### 4. Reuse and copy data so users do not type it twice Look for opportunities to re‑use information already captured. Examples: * If the **informant is the mother**, copy the mother’s name and contact details into the informant section automatically. * If the **mother and father share the same address**, provide a checkbox such as "Same address as mother" that copies the address fields in the background. * If the **declaration location** is the same as the **place of occurrence**, provide an option to copy that address instead of re‑entering it. Use conditional checkboxes and selects to trigger this copying behind the scenes so the user experiences fewer fields and less typing. #### 5. Prefer selects and reference lists for statistical data Where possible, avoid free‑text inputs for values that need to be analysed. Use **select** fields backed by well‑defined reference lists for things like: * Occupation * Birth attendant type * Place of occurrence * Cause of death groupings * Registration channel (facility, field agent, office, etc.) Free‑text answers quickly lead to inconsistent, messy data that is hard to aggregate and compare. Define and maintain a controlled list of options instead. #### 6. Validate entries to protect data quality For any free‑text or numeric field, define **validation rules** to catch obvious errors at the point of entry. Questions to ask: * Can this **date** be in the future? * What is the **minimum and maximum** time between the child’s date of birth and the mother’s date of birth? * What is the realistic **range for weight at birth**? * Are there formats we should enforce (for example, phone numbers, national IDs, certificate numbers)? Apply validation rules that are strict enough to prevent bad data, but not so strict that valid real‑world cases are blocked. #### 7. Separate registration data from supporting documents Keep the electronic declaration form focused on the **data needed for registration**. Anything that functions as evidence or proof should usually be uploaded as a **supporting document**, not captured as extra fields. Examples: * Proof of birth or death certificates signed by a health professional * Medically certified cause‑of‑death forms * Attestation letters from community leaders If, for example, the signature of the birth attendant is required on a legacy paper form, consider designing a dedicated **proof of birth** template that is uploaded as a supporting document instead of recreating the whole paper form in the digital declaration. #### 8. Minimise cognitive load and reading effort Beyond the individual fields, review the overall experience: * Use **simple, direct labels** and help text that frontline staff can easily understand. * Avoid long paragraphs inside the form; prefer short hints or tooltips. * Keep related fields close together and in a logical order that matches how the informant tells their story. * Remove any questions that are not strictly needed or that duplicate information captured elsewhere. #### 9. Test with real users and iterate Before finalising a form configuration: * Run through sample scenarios with registrars and health workers. * Ask them where they hesitate, guess, or feel that information is being requested twice. * Capture their feedback and adjust pages, conditional logic, wording, and validation rules accordingly. Forms should evolve as policies and practices change. Treat this guidance as a living checklist that you revisit whenever you add new data points or re‑design a workflow. # Guide: Certificate configuration ### 1. Introduction This page provides **design guidelines** for certificate and certified copy templates in OpenCRVS. It focuses only on how to design a good, digital‑first certificate layout. Use these guidelines when you are: * Designing a new certificate or extract template. * Redesigning a legacy paper certificate for use with OpenCRVS. * Reviewing certificate layouts before they are exported to SVG and configured. For how certificates work as a feature (templates, printing, workflows), see the parent **Certificates** page. *** ### 2. Digital‑first layout principles #### 2.1 Rethink legacy certificates Implementing a digital CRVS system is an opportunity to **simplify and modernise** certificate layouts. * Treat the **digital registry as the source of truth**; the paper certificate is a view of that data. * Remove elements that only exist to guide handwriting (for example, dotted lines and boxes). * Avoid trying to mimic very flexible handwritten spaces; instead, design fixed areas that work well for typical values. * If the existing certificate was created in tools like **Microsoft Word**, plan to **recreate** it in a proper design tool rather than importing it directly. Aim for a clean, official design that is easy to read and easy to configure. #### 2.2 Visual hierarchy Make it easy for someone to quickly verify the certificate. * Start with a clear **title** (for example, "Birth Certificate"). * Surface key identifiers prominently (for example, registration number, UIN, date of registration). * Group related information: * Event details (date, place, type). * Person details (for example, child / deceased / spouses). * Parents or informant details. * Registration and issuing details. * Use headings, spacing, and subtle lines to separate sections. #### 2.3 Page size and orientation * Prefer **A4** or **A5** so that printing and preview behave consistently. * Choose portrait or landscape based on legal expectations and content density. * If you need multiple pages, design them together so that margins, headings, and section ordering are consistent.
OpenCRVS also supports **multi-page certificates**. This is achieved by configuring the SVG template so that it defines multiple pages within a single design (for example, by setting explicit page dimensions and adding additional page frames or artboards). At a high level, implementers: * Design the full certificate layout across the required number of pages. * Mark where each page should start and end inside the SVG (using separate layers, groups, or artboards, depending on the design tool). * Place each data field once in the correct position on the relevant page. When the template is rendered, OpenCRVS interprets this configuration, splits the SVG into multiple pages, and exports them as a multi-page PDF ready for printing. *** ### 3. Text, fonts, and readability #### 3.1 Font choice * Use clear, legible fonts suitable for official documents. * Avoid overly decorative typefaces except in small areas (for example, headings or seals). * Ensure fonts support all required character sets and languages. #### 3.2 Font size * Use **at least 12pt** for key data. * Reserve smaller sizes only for secondary information (for example, footnotes or references). * Use larger sizes for the certificate title and major section headings. #### 3.3 Long names and text Design with the **worst case** in mind. * Consider the longest realistic names, places, or addresses that might appear. * Prefer layouts where most fields can fit on a single line. * If text must wrap, ensure there is enough vertical space and that wrapping will not collide with other fields or graphics. * Avoid squeezing text tightly around seals, logos, or borders. #### 3.4 Language and labels * Use clear, unambiguous labels that match legal terminology. * If multiple languages are required, decide whether to: * Show both languages inline (for example, label and value shown twice), or * Provide separate template variants per language. * Keep wording concise so that labels do not dominate the layout. *** ### 4. Use of graphics, security elements, and images #### 4.1 Security paper If you print onto **pre‑printed security paper**: * Add the security paper design to your svg template certificate design so it shows in preview. Add << >> to exclude it in export to pdf. * Align text, seals, and signatures to the fixed elements of the security paper. * Keep margins consistent so that printing aligns reliably across different printers. #### 4.2 Logos, seals, and emblems * Use high‑resolution **PNG** or SVG for logos and seals. * Place key symbols (for example, coat of arms, ministry logo) prominently but without overwhelming the text. * Ensure there is strong contrast between any overlaid text and the background. #### 4.3 Digital signatures * Reserve a clear area for each **digital signature** and printed name. * Choose a consistent aspect ratio (for example, **2:1** width to height) for signature boxes. * Leave enough white space around the signature so it remains legible when printed. #### 4.4 Verification QR code * Reserve a **square** area (1:1 aspect ratio) for the verification QR code. * Place it where it is easy to scan but does not dominate the design (for example, bottom corner). * Keep a quiet zone (clear space) around the code so scanners can read it reliably. *** ### 5. Practical tips for working in design tools #### 5.1 Use realistic dummy data * Populate the layout with realistic example values (long names, complex addresses, long place names). * Check that the layout still looks good with this dummy data. #### 5.2 Layers and grouping * Use **layers and groups** to separate background graphics, section headings, labels, and data areas. * Name groups meaningfully (for example, "Child details", "Registration block") to make later configuration easier. #### 5.3 Alignment and spacing * Use consistent margins and alignment (for example, align all labels in a column). * Use baseline grids or layout grids in your design tool to keep spacing tidy. * Avoid placing important text too close to page edges where printers may clip. #### 5.4 Preparing for SVG export Although configuration happens later, some export‑related choices affect design: * Avoid effects that do not export cleanly to SVG (for example, complex shadows or raster effects). * Keep the number of fonts and weights manageable. * Ensure any text that will later be replaced by data remains as editable text (not outlines). *** ### 6. Review checklist Before handing a design over for SVG export and configuration, check: * \[ ] All legally required fields are present and clearly labelled. * \[ ] The layout is readable with long names and addresses. * \[ ] Font sizes meet accessibility and legibility expectations. * \[ ] Logos, seals, and security elements are clear and not obstructing data. * \[ ] Signature and QR code areas are well placed and have enough space. * \[ ] The design works in black‑and‑white printing if colour printers are not guaranteed. * \[ ] The page size, orientation, and margins are agreed with the implementation team. If the design passes this checklist, it is ready to be exported to SVG and configured as a certificate template in OpenCRVS. # Guide: Mapping offices and users ### 1. Introduction This guide helps you turn the validated office hierarchy and user roles from **Co-Design & Validation** into the configuration inputs that the build team needs. Working through it produces two of the inputs listed in [Design & specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/gathering-requirements/design-and-specification): * **Administrative structure and locations** β€” the jurisdictional hierarchy, registration offices and health facilities. * **User roles and scopes** β€” the roles your staff perform, and the scope-based permissions and jurisdictions that govern them. Use this page when you are deciding how your country's administrative geography, offices and user roles should be modelled in OpenCRVS. It explains *what to decide and why*; the full reference for how the concepts behave lives in the functional docs, linked throughout. {% hint style="info" %} **Start from the defaults.** OpenCRVS ships with the Farajaland reference configuration. Configure against it and adapt, rather than starting from a blank page β€” it shows you the shape of each artefact you need to produce. {% endhint %} *** ### 2. What's different in 2.0 If you are coming from earlier versions, three shifts change how you do this mapping: * **Custom roles replace fixed system roles.** You are no longer mapping staff onto a fixed set of standard roles with fixed privileges. You define as many custom roles as you need and compose each one from **scopes**. * **Offices can sit at any level of the hierarchy.** They are no longer always pinned to the lowest administrative level. A user's reach is *computed* from where their office sits in the hierarchy. * **Jurisdiction lives on the scope.** Each scope carries its own qualifier deciding *where* the user can act, so one role can reach differently for different actions, and two users with the same role get different reach from their office location. For the full model β€” the scope catalogue, jurisdiction qualifiers and values, and how routing works β€” see [Users](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/users) and [Administrative structure](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/administrative-structure). *** ### 3. The key principle: offices carry no behaviour, users do This is the idea country teams most often need to unlearn: > **Being called an "office" gives a location no registration capability of its own. What happens at a location is determined entirely by the roles, scopes and jurisdictions of the users assigned to it.** A "Registration Office" staffed only by users with notify scopes is a notification point. A "Health Facility" staffed by users with register scopes can register. The location type is descriptive β€” it labels the place for people and for reporting; it does not grant permissions. So when stakeholders draw "this office sends records to that office", that flow is the *result* of how the users at each office are scoped and where their jurisdictions overlap β€” not something configured on the offices. Your task is to capture the offices and the scoped roles that, together, produce the flow they describe. *** ### 4. Do's and don'ts #### **4.1 Do** 1. **Model the administrative hierarchy on the country's real geography.** It drives address capture and the aggregation of vital statistics, not just registration β€” so it must match the official structure and the levels at which you need to report. 2. **Place offices at the level they genuinely operate.** National, provincial, district or sub-district β€” or directly under the country (for an HQ or embassy). Let jurisdiction follow from the hierarchy. 3. **Start roles from real job functions.** Field Agent, Registration Agent, Registrar, Provincial Officer, National Administrator, and any country-specific role β€” then translate what each needs to do into scopes. 4. **Choose the narrowest jurisdiction each scope needs.** Tune jurisdiction per scope: a Registrar might search across a province but register only in their own district. 5. **Assign every participating user to one location and one role.** Anyone who performs an OpenCRVS action β€” including a health administrator or court clerk acting as a field agent β€” is a user assigned to a location. #### **4.2 Don't** 1. **Don't try to give an office permissions.** Capability comes from users' roles and scopes, never from the office itself. 2. **Don't force staff into generic roles.** With unlimited custom roles, model the role that matches the real job rather than approximating it. 3. **Don't default every scope to the same jurisdiction.** Decide deliberately, per scope, between the user's exact office, their whole area and its children, only records they personally touched, or unrestricted. 4. **Don't leave routing gaps.** Every record state that needs human attention must surface in a queue for the right role; check there are none that a role can create but not progress. 5. **Don't assume 1.x terms still exist.** `record.reinstate` and `record.assign` are not 2.0 scopes, and there is no `notified_in` jurisdiction qualifier yet β€” design around these. *** ### 5. How to approach the mapping Work through these in order with your stakeholders. Each step produces part of the input set. 1. **Model the administrative hierarchy** β€” every administrative tier and area, with each area's parent. Branches can be uneven; not every level need appear everywhere. 2. **Place the locations** β€” every office, health facility, community point, court or embassy that takes part in registration, its type, and the administrative area it sits in. 3. **List the roles** β€” the real job functions in your to-be Service Delivery Model. 4. **Translate each role into scopes** β€” list the actions each role performs, for which events, and set the jurisdiction qualifier on each scope. Keep the create / notify / declare scopes aligned for jurisdiction-limited roles. 5. **Attach workqueues** β€” only the queues each role needs, named from the user's perspective. 6. **Assign users** β€” one location and one role each; reach follows automatically from the office location. 7. **Trace the routing end to end** β€” for each event, confirm every state needing attention surfaces in exactly one queue for exactly the right role. *** ### 6. Questions to guide your mapping * **Hierarchy** β€” Does the structure match the country's real geography *and* the levels at which vital statistics must aggregate? * **Offices** β€” At which level does each office genuinely operate? Are any best placed directly under the country? * **Roles** β€” Are you starting from real job functions rather than forcing staff into generic roles? * **Scopes and jurisdiction** β€” For each scope, is the jurisdiction the narrowest that still lets the role do its job? Are create, notify and declare aligned for jurisdiction-limited roles? * **Workqueues** β€” Does every role see only the queues it needs, named from its own perspective? * **Routing** β€” Trace each event end to end: exactly one queue for every state needing attention, behind exactly the right role, with no record a role can create but not progress? *** #### Related pages * [Administrative structure](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/administrative-structure) β€” functional reference for the hierarchy, offices and routing. * [Users](https://documentation.opencrvs.org/v2.0/functional/markdown/workflows/users) β€” functional reference for roles, scopes, jurisdiction and workqueues. * [Administrative hierarchy](https://documentation.opencrvs.org/v2.0/technical/guides/configuration/administrative-hierarchy) and [Roles and scopes](https://documentation.opencrvs.org/v2.0/technical/guides/configuration/users/roles-and-scopes) β€” technical configuration. * [Guide: Event configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs-project/gathering-requirements/design-and-specification/guides/guide-event-configuration) β€” the sibling design guide for workflows and workqueues. # Solution architecture ### 1. Introduction OpenCRVS is a core component of a country's Digital Public Infrastructure (DPI), designed as an internal, staff-facing civil registration system used by registrars and government officials to record vital events such as births and deaths. Civil registration is not an isolated system β€” it sits at the centre of a broader government ecosystem, exchanging trusted data with identity, health, statistics and social-protection systems. OpenCRVS should therefore be implemented as part of a wider, interoperable architecture that enables secure, scalable and sustainable service delivery.
{% hint style="info" %} **Where this sits:** Solution architecture follows [Gathering requirements](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements) and informs [Configuration](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/configuration). It is where you decide how OpenCRVS fits into your country's wider systems landscape before you build. {% endhint %} *** ### 2. Civil registration as foundational DPI OpenCRVS is more than a sectoral system β€” it functions as foundational infrastructure by providing a country's **single source of legal, trusted life-events data**. This data underpins: * Identity systems (for example, birth β†’ ID creation, death β†’ deactivation) * Public service delivery (for example, healthcare, education, social protection) * National statistics and planning * Legal identity and individual rights By establishing authoritative records of life events, civil registration enables both government operations and inclusive service delivery across the public and private sectors. *** ### 3. System architecture and integration OpenCRVS is designed to integrate with other systems through **APIs and open standards**. It supports both direct integrations and integration via a **data exchange layer** (recommended β€” see section 4). **Incoming data flows** (receiving data into OpenCRVS): * **Health systems:** birth and death notifications from hospitals, health facilities and health information systems * **Identity systems:** verification of parent identity during registration, and validation of informant credentials * **Address registries:** validation of locations, administrative hierarchies and facility codes * **Statistical offices:** master data on reference lists such as occupations, causes of death, or ethnicity classifications **Outgoing data flows** (sharing data from OpenCRVS): * **National ID systems:** birth and death registration data to trigger identity lifecycle events (for example, issuance of a national ID, deactivation of deceased persons) * **Statistical offices:** vital statistics for demographic analysis, policy planning and SDG monitoring * **Social protection systems:** eligibility verification for child grants, pensions or other entitlements * **Education systems:** school-enrolment planning based on birth cohorts * **Verifiable credentials platforms:** issuing digitally signed, verifiable certificates for birth, death, marriage and other events {% hint style="info" %} **More integration scenarios** are available at [opencrvs.org/product/interoperability](https://www.opencrvs.org/product/interoperability), including interoperability with other Digital Public Goods such as MOSIP (identity) and OpenSPP (social protection). {% endhint %} *** ### 4. Interoperability and data exchange layer While OpenCRVS exposes APIs, implementing a **dedicated interoperability layer** is strongly recommended. **Benefits:** * decouples systems and reduces integration complexity * enables data transformation and mapping * automates data-exchange workflows * provides audit trails and observability * improves scalability and maintainability **Recommended platforms:** OpenFN, X-Road and OpenHIM. These act as secure middleware for system-to-system communication and are themselves Digital Public Goods. *** ### 5. Verifiable credentials and PKI OpenCRVS can issue **Verifiable Credentials (VCs)** such as digital birth certificates, enabling individuals to prove life events digitally. {% hint style="info" %} **OpenCRVS is not a Public Key Infrastructure (PKI) solution.** It does not manage root certificate authorities, trust registries, or key lifecycle management β€” these must be provided separately. {% endhint %} To implement OpenCRVS VCs, countries must: * establish a national PKI strategy or partner with trusted providers * define governance, trust frameworks and key-management policies * adopt standards such as **W3C Verifiable Credentials** *** ### 6. How civil registration enables government services Civil registration data enables critical functions across government: * **Identity:** provides foundational data for unique digital identities * **Service delivery:** enables targeting of healthcare, education and social protection * **Consent-based data sharing:** supports controlled access to personal data * **Statistics and planning:** produces continuous, high-quality demographic data Effective implementation requires: * clear legal and data-governance frameworks * secure, consent-based data-sharing mechanisms * automated and standardised data-exchange pipelines *** ### 7. Summary OpenCRVS should be implemented as a **foundational component of national Digital Public Infrastructure**, not a standalone system. The key success factors are: * embedding OpenCRVS within a broader interoperable ecosystem * using a dedicated data exchange layer for integrations * establishing PKI and governance frameworks for digital credentials * designing for security, scalability and sustainability from the outset A well-architected implementation enables trusted data flows across government, supports digital identity, and ensures civil registration becomes a powerful enabler of inclusive, efficient public services. *** ### 8. Resources and support * [Technical integration guide](https://documentation.opencrvs.org/v2.0/technical/guides/configuration/integrations) * [OpenCRVS APIs](https://documentation.opencrvs.org/v2.0/technical/apis) # Configuration ### 1. Introduction Configuration is where your **to-be design becomes a working system**. You take the configuration inputs that were defined and signed off in [Design & Specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification) and implement them, so that OpenCRVS reflects your country's events, forms, business rules, offices, roles, certificates and dashboards. This page is a high-level, non-technical overview of how configuration works and what it involves. The step-by-step technical instructions live in the [technical configuration guides](https://documentation.opencrvs.org/v2.0/technical/guides/configuration). {% hint style="info" %} **Where this sits:** Configuration follows [Gathering requirements](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements) β€” specifically [Design & Specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification), where the configuration inputs are created β€” and comes before [Deployment](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/deployment) and go-live. {% endhint %} *** ### 2. What goes into configuration Configuration starts from the **signed-off configuration inputs** produced in [Design & Specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification): * Administrative structure and locations * Event business process flows * Event business rules and requirements * User roles and scopes * Workqueues * Event form definitions (declaration, action forms) * Event record actions (actions and flag config) * Certified-copy templates * Analytics and vital statistics dashboards {% hint style="info" %} **Don't start before sign-off.** Configuration implements decisions that have already been agreed. If the requirements are not yet signed off, you risk building β€” and then rebuilding β€” against a moving target. Confirm sign-off first. {% endhint %} *** ### 3. How configuration works OpenCRVS separates the **core product** from a **country configuration**. The core software is the same for every country; everything specific to your country β€” its events, forms, rules, offices, roles, certificates and dashboards β€” lives in the country configuration, which your technical team sets up and maintains. This is what lets you tailor OpenCRVS without changing the core software. At a high level, completing the configuration means: 1. **Set up the country configuration** β€” establish the configuration and the environments (for example development, staging and production) it will be applied to. 2. **Implement each configuration input** β€” translate each signed-off input into the country configuration: the administrative structure and locations, the events and their process flows, business rules, form definitions, record actions and workqueues, user roles and scopes, certified-copy templates, and dashboards. 3. **Load the reference data** β€” import the supporting data the system needs, such as administrative locations, health facilities and initial users. 4. **Review against the signed-off requirements** β€” confirm the configured system matches what was agreed. Each of these steps has detailed instructions in the [technical configuration guides](https://documentation.opencrvs.org/v2.0/technical/guides/configuration). This work is led jointly by your Technical System Administrator and Business Analyst (see [Establish project & team](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/establish-project-and-team)): the analyst confirms the configuration matches the requirements, and the administrator implements and deploys it. *** ### 4. Validate and iterate Configuration is not finished when the inputs are loaded β€” it is finished when the system **behaves as the signed-off requirements describe**. Test the configured system against those requirements, fix any gaps, and validate with stakeholders. See [Quality assurance](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/quality-assurance) for how to test the configuration before go-live. *** ### 5. When configuration is complete Configuration is done when: * \[ ] every configuration input has been implemented in the country configuration * \[ ] the configured system matches the signed-off requirements * \[ ] the configuration has been tested and validated (see [Quality assurance](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/quality-assurance)) * \[ ] the configuration is ready to deploy (see [Deployment](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/deployment)). *** ### 6. Resources and support * [Technical configuration guides](https://documentation.opencrvs.org/v2.0/technical/guides/configuration) β€” step-by-step instructions for implementing each configuration input. * [Design & Specification](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/gathering-requirements/design-and-specification) β€” where the configuration inputs are defined and signed off. * [Quality assurance](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/quality-assurance) and [Deployment](https://documentation.opencrvs.org/v2.0/implementation/your-opencrvs/deployment) β€” the stages that follow configuration. # Deployment ### 1. Introduction Deployment is the process of making your configured OpenCRVS system available for users to access. It takes the validated country configuration and installs it into the environments where the system will operate, ensuring that the software, infrastructure, integrations and supporting services are ready for quality assurance and production use. This page is a high-level, non-technical overview of what deployment involves and the activities required before go-live. The detailed technical procedures for installing, upgrading and operating OpenCRVS are covered in the technical deployment guides. *** ### 2. What goes into deployment Deployment brings together everything needed to run and maintain OpenCRVS. This includes: * Infrastructure (cloud or on-premise server configuration) * Environments (Server installations for Development, QA, Staging (production mirror), Production & Backup) * Networking (VPN, DNS & TLS certification) * Continuous integration and deployment pipelines (e.g. Github Actions) * Communications method (Email, SMS) * Databases and storage * Integrations with external systems * Security configuration (secrets & secrets management, SSH access controls) * Monitoring, logging and alerting services *** ### 3. How deployment works OpenCRVS is deployed using containerised services that can run either in cloud infrastructure or on-premise environments. The deployment process installs the OpenCRVS platform together with the country's validated configuration and supporting services. At a high level, deployment consists of: **Prepare the supporting services & networking** β€” Confirm the hosting provider and/or data center meets the required specifications, set up code repositories, set up SMTP or communications APIs, define required environments, configure DNS networking for each environment following your desired URL pattern, purchase TLS certificates, select containerisation directory provider. **Prepare the infrastructure** β€” Provision the servers, networking, storage and security required for the target environment, whether development, QA, staging or production. **Deploy the OpenCRVS core and country configuration** β€” install the OpenCRVS services, databases and supporting infrastructure. Build & deploy the validated country configuration, including forms, business rules, workflows, certificates and dashboards. **Configure integrations** β€” connect OpenCRVS to any external services such as identity providers, authentication services, notification systems, health information systems or national data platforms. **Operationalise** β€” enable monitoring, logging, backups, disaster recovery and routine operational processes to support the live system. **Verify the deployment** β€” confirm that all services are running correctly, integrations are functioning and users can successfully access the system. Each of these activities is described in detail in the technical deployment guides. Deployment is typically led by a Technical System Administrator, working closely with infrastructure teams and any cloud or hosting providers to ensure the environment is correctly configured and operational. *** ### 4. Resources and support * [Technical installation guides](https://documentation.opencrvs.org/v2.0/technical/guides/configuration) β€” step-by-step instructions for installing OpenCRVS on servers * [Maintenance tasks](/technical/guides/installation/opencrvs-maintenance-tasks) β€” guides for backup, database seeding & disaster recovery * [Advanced topics](/technical/guides/installation/advanced-topics) β€” guides regarding networking and TLS * [Monitoring](/technical/guides/monitoring) β€” guides for monitoring & logging If you require assistance with deployment planning, infrastructure design or production operations, contact the OpenCRVS community or your implementation partner for guidance. # Migrate legacy data ### 1. Introduction Migrating legacy data is the project activity of preparing historical civil registration records for use in OpenCRVS. It includes deciding which sources are in scope, what legal status they have, how fields and identifiers will map, how exceptions will be handled, and how the migration will be tested and signed off. For the functional capability, see [Data migration](https://documentation.opencrvs.org/v2.0/functional/markdown/legacy-data/data-migration). For technical implementation guidance, see [Legacy data migration](https://documentation.opencrvs.org/v2.0/technical/guides/data-migration). *** ### 2. Source assessment For each legacy source, document: | Area | Questions to answer | | --------------------- | ------------------------------------------------------------------------------------------------------- | | Source owner | Who owns the data and can approve migration decisions? | | Legal status | Is this a legal civil register, notification source, index, statistics dataset, or supporting evidence? | | Event coverage | Which event types are included? | | Date range and volume | What period and how many records are covered? | | Field coverage | Which mandatory OpenCRVS fields are present or missing? | | Identifiers | What registration numbers, book/page references, PINs/UINs, National IDs, or legacy IDs exist? | | Locations | Can places of event and registration be mapped to configured locations? | | Attachments | Are scanned documents or evidence files available? | | Amendments | Are corrections, name changes, adoptions, or other amendments represented? | | Data quality | What duplicate, missing, inconsistent, or implausible data is known? | | Access constraints | Are there technical, legal, privacy, or vendor constraints on extraction? | | Migration decision | Migrate, migrate for review, quarantine, retain legacy access, or exclude? | *** ### 3. Target status decision The registration authority should approve the target status for each source before migration is built or tested. | Legacy source or record type | Usual treatment | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Legally completed civil registration record | Import as `Registered`, if the source is confirmed as legally authoritative. | | Incomplete record requiring staff review | Import as `Declared` or `Notified`, depending on completeness and workflow design. | | Health notification, hospital spreadsheet, or local notification list | Use for reconciliation, duplicate checking, or import as `Notified` only if approved. Do not import as `Registered` unless legally accepted as a completed registration. | | Uncertain, conflicting, or low-quality record | Quarantine, report as an exception, or retain in controlled legacy access until resolved. | | Source outside migration scope | Do not migrate; document the reason and how staff can access it if needed. | Target status may vary by source, event type, date range, location, or data-quality band. This is a business decision, not a technical one. *** ### 4. Mapping sign-off Before technical migration starts, sign off: * field-by-field mapping to the configured OpenCRVS event model * mandatory-field handling * registration number policy * legacy ID and source record ID handling * national ID or UIN handling * historical-to-current location mapping * attachment and source image handling * amendment and correction handling * unmapped fields and exclusion decisions *** ### 5. Data quality and exceptions Agree which systematic errors may be corrected during transformation and which records require review. Migration should not rewrite legally meaningful historical facts without an approved correction policy. Records that fail validation should have an owner, reason code, decision path and exception report. They should not be silently dropped. *** ### 6. Planning gates A migration plan should normally include: 1. Source assessment approved. 2. Migration scope approved. 3. Field, identifier and location mapping signed off. 4. Test migration completed in a non-production environment. 5. Reconciliation and exception report signed off. 6. Cutover rehearsal completed. 7. Final load or delta load completed. 8. Post-load verification completed. 9. Controlled legacy access plan confirmed. *** ### 7. Pilot and cutover The pilot sample should include clean records, messy records, duplicates, missing fields, old or renamed locations, records with amendments, records with attachments, and records used to print certificates. The cutover plan should define data freeze timing, final delta migration, rollback or contingency arrangements, staff instructions for using legacy systems, and how late-arriving records are handled after go-live. For low-connectivity settings, account for batch size, upload windows, support availability, service continuity, and whether records may be captured offline before synchronisation. # Quality assurance ### 1. Introduction Quality Assurance (QA) is the systematic process of ensuring that your OpenCRVS configuration is fully tested and ready for live use. While the OpenCRVS Core Product has been rigorously tested to ensure that all functionality is reliable across a variety of devices and connectivity levels, it is essential that you conduct your own testing prior to releasing the application to users. OpenCRVS has been thoroughly tested to ensure: * **Functional reliability** β€” all core features work as designed. * **Device compatibility** β€” the application works on a variety of devices and browsers. * **Connectivity resilience** β€” the application can handle various levels of connectivity, including offline scenarios. * **Performance** β€” the minimum server configuration has been successfully stress tested with loads of up to 200 birth declarations per minute, with multiple concurrent users experiencing response times consistently less than 5 seconds. * **Security** β€” independent cyber-security penetration tests have been carried out with no significant vulnerabilities found. This section provides guidance on testing types, test cases, and procedures to ensure your configured instance meets your quality standards. *** ### 2. Why testing is essential Although the OpenCRVS Core Product has been rigorously tested, your specific configuration or customisations require your own testing to ensure: * **Configuration correctness** β€” your forms, workflows, business rules, and certificates work as designed. * **Context-specific requirements** β€” the system meets your country's legal and operational requirements. * **Performance at scale** β€” the system can handle your expected user load and transaction volume. * **Security** β€” your deployment is protected against vulnerabilities in your specific environment. * **User readiness** β€” the system is usable and meets the needs of your frontline staff. Testing should be conducted in phases, from lab testing through field testing to wider rollout. *** ### 3. Testing types The following testing types should be considered as part of your quality assurance process. #### 3.1 Product test Product tests are systematic procedures conducted to evaluate the functionality, usability, and reliability of the deployed software. These tests aim to ensure that the product meets the specified requirements and functions as per the configuration design. **Steps:** 1. Identify test cases based on requirements and user stories. 2. Execute test cases to validate functionality, including inputs, outputs, and system behavior. 3. Document and report any defects found during testing. 4. Repeat testing iteratively as new features are added or changes are made. #### 3.2 User Acceptance Testing (UAT) UAT is the final phase of testing where end-users validate the software to ensure it meets their requirements and expectations before deployment. It focuses on confirming that the system behaves as intended in real-world scenarios. **Steps:** 1. Define acceptance criteria based on user requirements. 2. Invite stakeholders or representative users to perform testing. 3. Execute test cases covering typical user workflows and scenarios. 4. Gather feedback and address any issues or discrepancies identified. 5. Obtain formal approval from stakeholders to proceed with deployment. #### 3.3 Regression tests Regression tests verify that recent changes to the software have not adversely affected existing functionality. These tests help maintain product stability over time by ensuring that new features or bug fixes do not introduce unintended side effects. **Steps:** 1. Develop a comprehensive suite of regression test cases covering critical functionalities. 2. Execute regression tests after each software update or change. 3. Automate repetitive regression tests to streamline the testing process. 4. Investigate and address any failures, either due to regression issues or changes in requirements. #### 3.4 Smoke tests Smoke tests are preliminary tests performed to verify basic functionality and stability of the software build. They aim to quickly identify major issues that could prevent further testing or deployment. **Steps:** 1. Select a subset of essential test cases covering core features. 2. Execute smoke tests on each new build or deployment. 3. Verify basic functionalities such as login, navigation, and critical workflows. 4. If smoke tests pass, proceed with more extensive testing or deployment; otherwise, halt further testing and address issues. #### 3.5 Performance tests Performance tests evaluate the responsiveness, speed, and scalability of a software application under various load conditions. These tests help identify performance bottlenecks and optimize system resources. A set of non-functional requirements are defined which will need to be adapted to your country context. **Steps:** 1. Define performance metrics and objectives based on user expectations. 2. Create test scenarios simulating realistic usage patterns and load conditions. 3. Use load testing tools to simulate concurrent users, transactions, or data volume. 4. Measure and analyse system response times, throughput, and resource utilization. 5. Optimise resource usage to improve performance as needed. #### 3.6 Technical tests Technical tests, such as failover and backup procedures, ensure the reliability and availability of the software system in the event of hardware failures, disasters, or data loss. **Steps:** 1. Develop failover and disaster recovery plans detailing procedures for system recovery. 2. Test failover mechanisms by intentionally simulating hardware failures or network disruptions. 3. Verify backup procedures by regularly backing up critical data and restoring from backups. 4. Document and update technical tests and procedures based on system changes or improvements. 5. Conduct periodic drills or tabletop exercises to validate the effectiveness of failover and backup procedures. #### 3.7 Penetration testing Penetration testing involves simulating cyber-attacks on a software system and its infrastructure to identify vulnerabilities and assess its security posture. It is a mandatory testing phase before live use of OpenCRVS to mitigate risks that personally identifiable information (PII) could be accessed or misused. This testing should be organised with an accredited partner, for example with [CREST](https://www.crest-approved.org/) and [CyberEssentials](https://www.ncsc.gov.uk/cyberessentials/overview) certification. **Steps:** 1. Define objectives, scope, and rules of engagement for the test. 2. Gather information about target systems and potential vulnerabilities. 3. Assess identified weaknesses for potential exploitation. 4. Attempt to exploit vulnerabilities to gain unauthorized access. 5. Document findings and provide recommendations for strengthening security. {% hint style="warning" %} **Mandatory before go-live** β€” Penetration testing is mandatory before launching OpenCRVS for live use. This protects citizen data and ensures regulatory compliance. {% endhint %} *** ### 4. Test case repository The OpenCRVS testing team has developed a set of testing assets that can be used to support your own testing needs. #### Test case resources * [**OpenCRVS Test Case Repository**](https://docs.google.com/spreadsheets/d/1ifIdSu7z3DKs1PPI2H28Qab8tY1Fnn78QCYsuBQWqDw/edit?gid=0#gid=0) β€” contains all of the test cases used for testing the core product, which can be reused or modified for your own testing purposes. * [**Regression Test Report**](https://docs.google.com/spreadsheets/d/1hoFtm6ZesYDX_weGsd48HyCfwtaSsbDsifZScz6dQAA/edit?gid=0#gid=0) β€” regression test results on web-online and sanity tests on mobile-offline. These resources provide a comprehensive starting point for developing your own test suites. *** ### 5. Configuration and release notes OpenCRVS publishes configuration template files and release notes to help you configure your instance and stay up to date with the latest version. Check out the [Configuration, testing and technical configuration files](https://github.com/opencrvs/documentation/tree/master/v1.9.0/general/releases/README.md) for detailed guidance on configuration and version-specific documentation. *** ### 6. Raising OpenCRVS defects If you suspect that you have discovered a defect in the OpenCRVS Core Product, please share details with the OpenCRVS team using the following procedure. #### Where to report issues You can view existing issues and raise new ones at . #### How to prepare a defect report Your issue will be fixed much faster if you spend about half an hour preparing it, including the exact reproduction steps and a demo. **Steps to complete a detailed defect report:** 1. **Describe the bug** β€” a clear and concise description of what the bug is. 2. **Which feature of OpenCRVS does your bug concern?** β€” identify the module or feature affected. 3. **To reproduce** β€” steps required to reproduce the behavior, for example: * Login as a Registrar * Go to '...' * Click on '....' * Scroll down to '....' * See error 4. **Expected behavior** β€” a clear and concise description of what you expected to happen. 5. **Actual behavior** β€” describe what happened, including screenshots and video. 6. **OpenCRVS Core Version** β€” for example, v1.7.0 (Git branch: master / release-v1.7.0). 7. **Country Configuration Version** β€” for example, v1.7.0 (Git branch: master / release-v1.7.0). 8. **Device** β€” include: * OS (for example, iOS, Windows, Android) * Browser (for example, Chrome, Firefox, Safari) * Version (for example, 22) 9. **Possible fixes** β€” if you can, link to the line of code that might be responsible for the problem. Following this format ensures that the OpenCRVS team has all the information needed to investigate and resolve the issue efficiently. # Go-live ### 1. Introduction Go-live is the process of launching OpenCRVS for live vital event registration. This is a critical milestone in any implementation, marking the transition from development and testing to operational use. We recommend making go-live as small and low-key as possible, with initially just a few users testing the application at selected test sites. This gives you the possibility to provide feedback and adjust the solution before wider scale rollout. This section provides a comprehensive readiness checklist to ensure that your implementation is properly prepared for launch and subsequent nationwide rollout. *** ### 2. Go-live approach A phased approach to go-live reduces risk and allows for early feedback and adjustment. #### Recommended approach * **Start small** β€” begin with a limited number of users at selected test sites. * **Test in production** β€” validate that all processes work as expected in the live environment with real users. * **Gather feedback** β€” collect user feedback and monitor system performance during the initial phase. * **Adjust and iterate** β€” make necessary adjustments before expanding to additional sites. * **Scale gradually** β€” roll out to additional locations only when the initial sites are stable and successful. This approach minimizes disruption and allows you to identify and resolve issues before they affect a larger user base. *** ### 3. Go-live readiness checklist Before launching your solution for live vital event registration, ensure that all of the following areas have been properly prepared. #### 3.1 Office refurbishment Are registration offices and staff properly equipped to be able to use the new application? * **Equipment** β€” computers, printers, scanners, mobile devices, and accessories are in place and functioning. * **Connectivity** β€” reliable internet connectivity (or offline-capable infrastructure) is available. * **Power supply** β€” stable electricity or backup power solutions are in place. * **Physical security** β€” sufficient security measures are in place to ensure that equipment is safe. * **Work environment** β€” offices are set up to support efficient and secure registration processes. #### 3.2 Training Have the users been adequately trained, on the application but also on any new policies and processes? * **Application training** β€” users understand how to perform key tasks (declare, validate, register, print). * **Policy and process training** β€” users are familiar with new or updated civil registration policies and procedures. * **Role-specific training** β€” training is tailored to different user roles (Registration Agents, Registrars, Administrators). * **Training materials** β€” user guides, quick reference cards, and video tutorials are available. * **Refresher training** β€” plans are in place for ongoing training and support. #### 3.3 Change management Have the changes to processes and tools been properly communicated and are users ready to adopt the new application? * **Communication plan** β€” changes have been clearly communicated to all stakeholders. * **User readiness** β€” users understand why the change is happening and how it will benefit them. * **Leadership support** β€” managers and leaders are visibly supporting the transition. * **Feedback mechanisms** β€” channels are in place for users to provide feedback and ask questions. #### 3.4 Public communication Have the changes to vital event registration processes been properly communicated to the public so that they are aware of what to do? * **Public awareness campaign** β€” informants and the general public are aware of any changes to registration processes. * **Information materials** β€” posters, brochures, radio announcements, or other materials explain what is changing. * **Service locations** β€” the public knows where to go to register events. * **Requirements** β€” the public understands what documents and information they need to bring. #### 3.5 Data migration Has legacy digital data been migrated to the new application? Have historical paper-based records been digitised and uploaded into the new application? * **Legacy data migrated** β€” existing digital records have been successfully imported into OpenCRVS. * **Data quality** β€” migrated data has been validated and cleaned. * **Paper records digitised** β€” historical paper-based records have been digitised and uploaded (if required). * **Migration testing** β€” data migration has been tested and verified before go-live. #### 3.6 Testing Have all standard operating procedures been tested and proven to work as designed? Can the application support peak user load? Has the application and infrastructure passed cyber-security penetration tests? * **Functional testing** β€” all standard operating procedures have been tested end-to-end. * **User acceptance testing** β€” users have validated that the system meets their needs. * **Performance testing** β€” the application can support expected and peak user loads. * **Security testing** β€” the application and infrastructure have passed independent cyber-security penetration tests. * **Backup and recovery testing** β€” backup and disaster recovery procedures have been tested. #### 3.7 Service management Is there a team that can handle support requests and respond to the common queries and issues? Is it clear to users how to contact the support team? * **Support team in place** β€” a dedicated team is ready to handle user support requests. * **Support channels** β€” users know how to contact support (phone, email, in-person). * **Issue tracking** β€” a system is in place to log, track, and resolve support tickets. * **Common issues documented** β€” frequently asked questions and common issues are documented with solutions. * **Service level agreements** β€” response and resolution times are defined and communicated. #### 3.8 Application maintenance and support Are there support teams in place with the necessary SLAs to be able to support the service management team, including technical monitoring and maintenance of the application? * **Technical support team** β€” a team with the necessary skills is in place to maintain the application and infrastructure. * **Monitoring in place** β€” system health, performance, and security are actively monitored. * **Incident response** β€” procedures are in place to respond to and resolve incidents. * **Maintenance schedule** β€” planned maintenance windows are scheduled and communicated. * **SLAs defined** β€” service level agreements are in place for technical support and maintenance. #### 3.9 Rollout planning Is there a rollout plan with sufficient resources to scale up the use of the application nationwide? Are there checkpoints in place to help decide whether rollout should continue or should be paused? * **Rollout plan** β€” a phased plan is in place to expand from initial sites to nationwide coverage. * **Resource planning** β€” sufficient resources (staff, budget, equipment) are allocated for rollout. * **Checkpoints and milestones** β€” clear decision points are defined to assess whether to continue or pause rollout. * **Success criteria** β€” metrics are defined to measure success at each phase. * **Contingency plans** β€” plans are in place to address issues that may arise during rollout. *** #### 4. Pre-deployment checklist The [Pre-Deployment Checklist](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/3.3.4-set-up-an-smtp-server-for-opencrvs-monitoring-alerts) should be completed by the **production** environment server administrator before going live. This checklist covers technical infrastructure requirements including: * Server configuration and security * Database setup and backups * Monitoring and alerting * SSL certificates and encryption * Performance optimization Completing this checklist ensures that the technical infrastructure is properly configured and secured before launch. #### 5. Data security Upgrading OpenCRVS is only one part of maintaining a secure civil registration system. Project managers and operational teams must also understand the wider data security landscape in which OpenCRVS operates. Digitising civil registration introduces new risks alongside its many benefits. These include cyber attacks, social engineering, unauthorised access, malware, vulnerable infrastructure and data breaches. While OpenCRVS incorporates industry-standard security controls and is regularly penetration tested, no software can eliminate these risks on its own. Effective security also depends on robust infrastructure, operational procedures, staff awareness and good governance. {% file src="/files/YhQcCooPtJnc1NJWVyr8" %} All implementation teams should familiarise themselves with the **OpenCRVS Data Security Framework**, which explains: * the most common threats to digital civil registration systems * the technical security measures built into OpenCRVS * the responsibilities of governments and implementation teams * recommended policies and procedures for protecting citizen data * security considerations throughout implementation, operation and ongoing maintenance. Project managers do not need to become cybersecurity specialists, but they should understand the risks that exist, ensure that appropriate security policies are developed, and work with technical and operational teams to embed good security practices throughout the lifetime of the system. The Data Security Framework should be used alongside local government cybersecurity policies and recognised international guidance when planning and operating an OpenCRVS implementation. #### 6. Disaster recovery A disaster recovery plan helps ensure that civil registration services can be restored quickly following a major incident such as hardware failure, cyber attack, natural disaster or accidental data loss. Planning for disaster recovery is an essential part of operating a national digital civil registration system and should be considered from the start of an implementation. {% file src="/files/lnqiS0IZ0YIQU8OaC34D" %} Project managers should work with infrastructure and operational teams to define disaster recovery objectives, including how quickly services should be restored and how much data loss is acceptable. This should include documented backup procedures, recovery processes, regular testing of recovery plans and clearly defined operational responsibilities. OpenCRVS provides technical guidance for configuring backups and supporting disaster recovery, but each government is responsible for developing, maintaining and testing its own disaster recovery procedures to meet local policies and operational requirements. For technical guidance, see [Manual Restore / Disaster recovery](/technical/guides/installation/opencrvs-maintenance-tasks/backup-and-restore/manual-restore-disaster-recovery) # Operational support ### 1. Introduction Operational support is the ongoing management and maintenance of the OpenCRVS solution to ensure its continued successful operation. A well-structured support model ensures that users can resolve issues quickly, that common problems are identified and addressed, and that the system remains stable and available. This section describes a tiered support model that can be adapted to the country context, ensuring that issues are resolved at the appropriate level and escalated when necessary. *** ### 2. Support model overview A tiered support model provides clear pathways for issue resolution, from self-service options through to expert technical support. #### Benefits of a tiered support model * **Efficiency** β€” users can resolve simple issues themselves without waiting for support. * **Scalability** β€” first-line support can handle common issues, freeing expert resources for complex problems. * **Visibility** β€” issue tracking provides insight into common problems and training needs. * **Clear escalation** β€” issues are escalated to the appropriate level based on complexity. A typical support model includes four tiers, from self-service through to expert support. *** ### 3. Support tiers #### 3.1 Level 0: Self-service options Self-service options allow end-users to find answers to common questions and resolve simple issues without contacting support. **What to provide:** * **User guides and handbooks** β€” paper or digital guides covering common tasks and workflows. * **Online support materials** β€” searchable documentation and FAQs. * **Chatbots** β€” automated tools that answer simple questions. * **Country-specific materials** β€” update generic User Support Materials with details of your country configuration. **Benefits:** * Users can resolve issues immediately, any time of day. * Reduces the volume of support requests to first-line support. * Empowers users to find answers independently. #### 3.2 Level 1: First-line support First-line support provides a mechanism for users to raise issues or questions that they have not been able to resolve themselves. **What to provide:** * **Easy-to-use contact channels** β€” WhatsApp, email, phone, or other instant communication tools. * **Issue tracking system** β€” use a ticket tracking tool such as [GitHub](https://github.com/), Jira, or similar to log and track issues to resolution. * **Response and resolution targets** β€” define service level agreements for how quickly issues should be acknowledged and resolved. **Benefits:** * Users have a clear way to get help when they need it. * Issue tracking provides visibility into common problems and patterns. * Patterns in user issues can inform follow-up training or improvements to user support materials. **Example tools:** * GitHub Issues for tracking * Zendesk or Freshdesk for helpdesk management * WhatsApp Business for communication #### 3.3 Level 2: Technical support Technical support handles issues that cannot be resolved through first-line support, typically requiring deeper technical knowledge or configuration changes. **What to provide:** * **Management and maintenance team** β€” technical staff who can investigate and resolve issues that require system access or configuration changes. * **Access to production environments** β€” ability to review logs, check configurations, and make basic technical fixes. * **Escalation procedures** β€” clear criteria for when issues should be escalated to expert support. **Typical issues handled at this level:** * Configuration issues (forms, workflows, certificates). * User account management and permissions. * Performance or connectivity problems. * Data quality issues requiring investigation. #### 3.4 Level 3: Expert support Expert support provides resolution for issues that cannot be resolved by level 2 support, typically requiring fixes to the OpenCRVS Core Product or deep technical expertise. What to provide: * **Expert technical team** β€” core product developers or senior engineers with deep knowledge of the OpenCRVS codebase. * **Bug fixes and patches** β€” ability to diagnose and fix bugs in the core product. * **Upgrade management** β€” coordinated rollout of fixes and updates to all instances. **Typical issues handled at this level:** * Bugs in the OpenCRVS Core Product. * Security vulnerabilities. * Complex performance or scalability issues. * Core product feature requests or enhancements. *** ### 4. Escalation and issue tracking Clear escalation paths ensure that issues are resolved at the appropriate level and tracked to completion. #### 4.1 Escalation criteria Issues should be escalated when: * **Level 0 β†’ Level 1** β€” the user cannot find the answer in self-service materials. * **Level 1 β†’ Level 2** β€” the issue requires technical investigation or configuration changes. * **Level 2 β†’ Level 3** β€” the issue requires a fix to the core product or deep technical expertise. #### 4.2 Issue tracking best practices * **Log all issues** β€” use a ticket tracking tool to capture all issues reported to first-line support. * **Categorize issues** β€” tag issues by type (training, configuration, bug, etc.) to identify patterns. * **Track resolution time** β€” monitor how long issues take to resolve at each tier. * **Review regularly** β€” hold regular reviews of open issues and common problem areas. * **Update support materials** β€” use insights from issue tracking to improve self-service materials and training. *** ### 5. Getting support from OpenCRVS If you require support with any level of operational support, the OpenCRVS team can provide guidance and assistance. Please reach out to [**team@opencrvs.org**](mailto:team@opencrvs.org) to discuss how we can support you with: * Setting up support structures and processes. * Training your support teams. * Providing expert-level technical support. * Addressing core product issues. # Monitoring ### 1. Introduction Monitoring is an essential operational activity for every OpenCRVS implementation. Effective monitoring enables support teams to identify and resolve issues before they affect users, helping to maximise system availability and minimise service disruption. This page provides a high-level overview of monitoring and alerting within OpenCRVS. The [technical monitoring guidance](/technical/guides/monitoring) explains how to configure monitoring tools, create alerts and investigate operational issues. **Where this sits:** Monitoring begins immediately after Go-live and continues throughout the lifetime of the system as part of routine operations and support. *** ### 2. Why monitoring matters Operating a national civil registration system requires continuous oversight of both the application and the infrastructure on which it runs. Many operational issues develop gradually before users notice them. Examples include increasing disk usage, failing services, repeated authentication attempts or application errors. Monitoring allows support teams to detect these conditions early and take corrective action before they become service outages. Monitoring should therefore form part of the responsibilities of all operational support teams. *** ### 3. Monitoring OpenCRVS OpenCRVS provides monitoring capabilities that allow support teams to observe both system health and application behaviour. At a high level, monitoring consists of: **Monitor infrastructure health** β€” ensure that servers and supporting services remain healthy by monitoring system logs, resource utilisation, storage capacity and security-related events. **Monitor application behaviour** β€” identify application errors and exceptions as users experience them, allowing issues to be investigated before they become widespread. **Respond to alerts** β€” configure automated notifications so that operational teams are informed whenever predefined conditions are met, allowing timely investigation and resolution. **Investigate incidents** β€” use historical logs and diagnostic information to determine the cause of issues and verify that corrective actions have resolved them. *** ### 4. Monitoring tools OpenCRVS provides recommended tools to support operational monitoring. **Kibana** provides operational visibility into the infrastructure and OpenCRVS services. It can be configured to send automated email alerts for conditions such as: * server and application log events * failed SSH login attempts and other security events * disk space exhaustion * service failures * other infrastructure health indicators Kibana also provides searchable historical logs for each OpenCRVS service, allowing support teams to investigate incidents over a configurable retention period. **Sentry** monitors application errors from the user's perspective. It captures software exceptions and performance issues as they occur, enabling support teams to identify defects, understand their impact and prioritise corrective action. Together, these tools provide a comprehensive view of both infrastructure health and user experience. *** ### 5. Operational responsibilities Monitoring is only effective when alerts are acted upon. Project teams should establish operational procedures that define: * who receives alerts * how incidents are prioritised and escalated * expected response and resolution times * how incidents are investigated and documented * how recurring issues are analysed and permanently resolved Monitoring should be considered an integral part of the L1-L3 support process, helping teams detect problems early, maintain service availability and continually improve the reliability of the OpenCRVS deployment. *** ### 6. Resources and support Understand [operational support](/implementation/your-opencrvs-project/operational-support) service level expectations Technical [monitoring guides](/technical/guides/monitoring) # Version upgrades ### 1. Introduction Keeping OpenCRVS up to date ensures that your system remains secure, reliable and supported. Regular upgrades allow you to benefit from bug fixes, security patches, performance improvements and new functionality as the OpenCRVS platform evolves. This page provides a high-level overview of why regular upgrades are important and how to plan them. The detailed technical procedures for upgrading OpenCRVS are covered in the [version upgrade](/technical/guides/version-upgrades) guides. **Where this sits:** Maintaining your OpenCRVS deployment is an ongoing operational activity that begins after Go-live and continues throughout the lifetime of the system. *** ### 2. Why regular upgrades matter OpenCRVS is actively developed and improved. Each release may include: * Security updates and hotfixes * Bug fixes and performance improvements * New features and capabilities * Improvements to existing functionality * Platform and dependency updates Regular upgrades help ensure that your implementation continues to benefit from these improvements while remaining compatible with the supported OpenCRVS platform. **Don't wait too long between upgrades.** The further an implementation falls behind, the more complex and time-consuming future upgrades become. Keeping pace with releases makes maintenance simpler and reduces operational risk. *** ### 3. How upgrades are managed OpenCRVS follows a regular release process. Before planning an upgrade, review the release notes to understand what has changed and whether any preparation is required. At a high level, upgrading OpenCRVS consists of: **Monitor new releases** β€” review each OpenCRVS release to understand new features, bug fixes and any actions required for your implementation. **Plan the upgrade** β€” assess the changes, determine an appropriate upgrade window and identify any testing that will be required before deploying to production. **Test before production** β€” apply the upgrade to a non-production environment first (QA and staging) and verify that your country configuration, integrations and business processes continue to work as expected. **Deploy to production** β€” once validated, deploy the upgrade to the production environment using the documented upgrade procedures. *** ### 4. Stay informed To plan upgrades effectively, implementation teams should stay informed about the OpenCRVS roadmap and upcoming releases. We recommend that Technical System Administrators and implementation teams: * follow OpenCRVS communications and release announcements * attend community webinars and product update sessions * review the published release notes for every new version * monitor the OpenCRVS GitHub Releases page for newly published versions Understanding what is coming allows you to plan upgrades alongside your normal operational activities, rather than reacting only when support ends. *** ### 5. Supported versions OpenCRVS officially maintains support for the current minor release and the immediately preceding minor release. For example, if the current release is **2.0**, the supported versions are: * **2.0** (current) * **1.9** (previous minor release) Older minor versions are no longer actively maintained and will not receive new hotfixes or security updates. Keeping your implementation within the supported release window is essential to ensure you continue to receive maintenance updates and can obtain support from the OpenCRVS community. *** ### 6. When your system is up to date Your implementation is being maintained effectively when: * you regularly review new OpenCRVS releases * upgrades are planned as part of normal operational maintenance * new versions are tested before deployment to production * your production system remains within the supported release window * implementation teams stay informed through OpenCRVS communications and community updates *** ### 7. Resources and support The [version upgrade guides](/technical/guides/version-upgrades) provide detailed instructions for upgrading OpenCRVS between supported releases. To stay informed about upcoming changes: * Follow OpenCRVS product communications and community webinars. * Review the published roadmap and release announcements. * Monitor the GitHub Releases page for every new OpenCRVS release: . # Architecture ### 1. Introduction OpenCRVS is built using a **modular, event-driven microservices architecture** designed for scalability, configurability, and data sovereignty. The technical architecture enables countries to deploy OpenCRVS in on-premise private tier 2/3 data centres using included configurations, ensuring that civil registration data remains under national control. This section describes: * High-level core architectural principles and technology choices. * How OpenCRVS stores life events and other data * Infrastructure components (databases, orchestration, networking) * Client application architecture * Deployment and hosting considerations. *** ### 2. Architectural principles OpenCRVS architecture is designed to deliver a **low total cost of ownership** while meeting the unique requirements of civil registration systems in low-resource settings. **Core principles:** * **Modularity** β€” each component is independently scalable and replaceable. * **Data sovereignty** β€” all data can be hosted on-premise in national infrastructure. * **Offline capability** β€” frontline staff can work without connectivity and sync when online. * **Standards-based** β€” use of open standards for interoperability and integration. * **Single codebase** β€” TypeScript and JavaScript across backend and frontend reduce maintenance overhead. * **Configurability over customisation** β€” most country requirements can be met through configuration rather than code changes. *** ### 3. Infrastructure components #### 3.1 Container orchestration **Kubernetes available in OpenCRVS 2.0** From version 2.0, OpenCRVS can be deployed to any Kubernetes cluster. Our previous platform technology Docker Swarm will still remain supported, at least until OpenCRVS v2.1 is released. All OpenCRVS services and the deployment is defined as Helm charts, as defined in the [opencrvs-core](https://github.com/opencrvs/opencrvs-core/tree/develop/charts) repository. #### 3.2 Databases OpenCRVS uses multiple database technologies, each optimised for specific purposes: **PostgreSQL** * Stores event registration data. * Provides transactional integrity and relational queries. * Primary data store for all registered records. **Elasticsearch** * Industry-standard NoSQL document-oriented real-time search engine. * Enables lightning-fast, intelligent civil registration record searches. * Supports "fuzzy" search parameters for imprecise queries. * Powers de-duplication management to ensure data integrity. * Used with Kibana for application and server health monitoring. **Redis** * Used for storing quickly expiring data like 2FA codes. #### 3.3 Object storage **Minio** * Amazon S3-compatible object store. * Stores supporting documentation attachments (images, scanned documents). * Can be deployed on-premise for data sovereignty. #### 3.4 Business intelligence **Metabase** * Default BI tool for analytics and performance dashboards. * Can be substituted with any BI tool as long as there is a way to share data from the country config node.js process to the tool, typically via a country-operated database. * Provides pre-configured operational views (workload, timeliness, completion rates). #### 3.5 Security and networking **LetsEncrypt** * Automatic SSL certificate configuration and renewal. * Ensures encrypted communication between clients and servers. **SMS 2-Factor Authentication** * Built-in 2FA for all user authentication. * Configurable SMS gateway integration. **Monitoring** * Kibana for external server and application health monitoring. * Real-time visibility into system performance and errors. *** ### 4. Microservices architecture The core of OpenCRVS is a **monorepo** organised using **Lerna**. Each package represents a single Node.js microservice. Following the microservice model of one service per container, every package is independently scalable in a single Docker container. #### 4.1 Technology stack All microservices are written in **TypeScript** (a strictly typed superset of JavaScript that compiles to JavaScript). **Benefits of TypeScript:** * Type safety reduces runtime errors. * Improved developer experience with better tooling and autocomplete. * Easier refactoring and maintenance. * Single language across frontend and backend. #### 4.2 Microservice principles Each microservice in OpenCRVS: * Has **no knowledge** of other services or business requirements in the application. * Exposes its capabilities via **JWT-secured APIs**. * Can be **scaled independently** based on load. * Is **deployed in its own container** for isolation and resilience. This architecture enables continuous evolution of business requirements without tightly coupling components. #### 4.3 Inter-service communication Services communicate via: * **HTTP APIs** secured with JWT tokens. * **Event-driven messaging** for asynchronous workflows. * Well-defined contracts that enable independent service evolution. #### 4.4 Business logic extensibility **HTTP hooks** allow implementers to programmatically extend backend business logic without modifying core services. This supports country-specific requirements while preserving upgradeability. *** ### 5. Client application architecture OpenCRVS client applications are built using **React** and **Progressive Web Application (PWA)** technology. #### 5.1 Progressive Web Applications PWA technology enables: * **Offline functionality** β€” users can work without connectivity and sync later. * **Native mobile features** β€” camera access, push notifications, home screen installation. * **Single codebase** β€” no separate web and mobile codebases to maintain. * **No app store overhead** β€” updates deploy instantly without app store releases. #### 5.2 Offline capability In remote areas, registrars can save a configurable number of registrations offline on their mobile phone using Chrome's **IndexedDB**. Offline architecture uses **Workbox** to: * Cache application assets for offline access. * Queue record updates for later synchronisation. * Resolve conflicts when devices reconnect. #### 5.3 Technology stack **React** * Component-based UI framework. * Enables reusable, testable interface components. * Large ecosystem and community support. **TypeScript** * Type safety across frontend codebase. * Shared types with backend services. * Improved developer experience. *** ### 6. Content management OpenCRVS provides **standards-based multi-language content management** to support countries with multiple official languages. Features include: * Translation management for all user-facing text. * Language-specific formatting (dates, numbers, addresses). * Configurable default and fallback languages. *** ### 7. Automated testing and delivery OpenCRVS includes an **automated continuous integration, delivery, and testing suite** that enables: * Rapid identification of regressions. * Automated quality gates before deployment. * Repeatable, predictable releases. * Confidence in upgrades and configuration changes. *** ### 8. Deployment architecture #### 8.1 Hosting requirements OpenCRVS can be deployed: * **On-premise** in tier 2 or tier 3 data centres. * **Cloud-hosted** on any infrastructure provider (AWS, Azure, GCP, etc.). * **Hybrid** configurations combining on-premise and cloud components. For detailed server specifications and setup guidance, see the [installation documentation](https://github.com/opencrvs/documentation/tree/master/v1.9.0/setup/3.-installation/3.3-set-up-a-server-hosted-environment). #### 8.2 Scalability Each microservice can be scaled independently by: * Adding additional container instances. * Distributing load across multiple nodes. * Tuning resource allocation per service. #### 8.3 Network architecture The deployment includes: * Load balancing and reverse proxy. * Internal service mesh for inter-service communication. * External API gateway for integrations. * Firewall and network segmentation for security. *** ### 10. Related documentation For more detail on specific aspects of the OpenCRVS architecture, see: * **Functional Architecture** β€” the functional model, modules, and record lifecycle * **Security** β€” authentication, authorisation, and data protection * **Non-functional requirements** β€” performance targets and system quality attributes * **Integrations** β€” inbound and outbound APIs for interoperability # Technical stack ### 1. Introduction OpenCRVS is built as a TypeScript-first, microservices application running on Node.js. All services β€” frontend and backend β€” share a single language and a single monorepo, which reduces context-switching. *** ### 2. Language & runtime | | | | ------------ | -------------- | | **Language** | TypeScript 5.6 | | **Runtime** | Node.js 22 | TypeScript is used throughout: frontend applications, backend services, database migrations, and configuration tooling. This makes it possible to share types and schema definitions between services without duplication, and catches integration errors at compile time rather than at runtime. *** ### 3. Frontend The registration and administration interface is a **Progressive Web App (PWA)** built with **React 18**. It is designed to work offline β€” field agents can continue registering vital events without an active internet connection, with data synchronised to the server once connectivity is restored. It connects to the backend exclusively through the API gateway. | Concern | Technology | | -------------------- | --------------------- | | UI framework | React 18 | | Build tool | Vite | | Server state | React Query | | Client state | Zustand | | Forms | Formik | | Form validation | JSON Schema (AJV) | | Internationalisation | React Intl (FormatJS) | | Styling | Styled Components | A shared component library (`@opencrvs/components`) provides the design system used across both the main client application and the login application. The component library is documented with Storybook. All user-facing strings are externalised through React Intl, which allows country configurations to provide translations without modifying application code. Form validations are defined as **JSON Schema** and evaluated at runtime using **AJV**. This keeps validation logic declarative and portable β€” the same schemas are enforced on both the client and the server. *** ### 4. Country configuration toolkit Country configurers work with the **`@opencrvs/toolkit`** npm package rather than directly with the application internals. The toolkit provides TypeScript helpers and higher-level constructors for the most common configuration tasks β€” defining forms, writing validation rules, configuring workflows, and more β€” without needing to understand the underlying implementation. For most implementing countries, the toolkit is the primary development surface. *** ### 5. Backend services OpenCRVS is composed of several focused services, each owning a specific domain: | Service | Responsibility | | ------------------- | --------------------------------------------------------------------------- | | **Gateway** | Single entry point for all client requests. Routes to downstream services. | | **Auth** | Issues and validates JWT tokens. Manages SMS-based login flow. | | **Events** | Core civil registration logic. Source of truth for all registration events. | | **User Management** | User accounts, roles, and permissions. | | **Documents** | Stores and retrieves supporting documents and attachments. | Each service is independently deployable and runs as a Docker container. #### 5.1 HTTP framework Backend services use **tRPC** as their primary HTTP framework. tRPC is a TypeScript-native RPC framework β€” because both the client and the server share TypeScript types, mismatches are caught at compile time rather than at runtime. The Events service, which contains the majority of the civil registration business logic, is built entirely on tRPC. Other microservices also use tRPC for their internal APIs. The same tRPC routes are exposed as OpenAPI-compatible REST endpoints for external integrating parties. Some supporting services still use **Hapi.js**, though this will be phased out over time in favour of tRPC. *** ### 6. Data layer OpenCRVS uses purpose-specific databases rather than a single general-purpose store. Each database is chosen for what it does well:
DatabaseWhat it storesVersion
PostgreSQLCivil registration events, user data, and metrics17
ElasticsearchSearch index for records and analytics queries8.16
RedisSession tokens, short-lived caches, rate limiting8
MinIOSupporting documents and attachments (S3-compatible object storage)β€”
PostgreSQL is the authoritative store for all registration data. Elasticsearch is a derived store β€” populated from PostgreSQL β€” that powers fast search and reporting queries without loading the primary database. *** ### 7. APIs OpenCRVS exposes a **REST/OpenAPI** interface for external integrations with national systems and third-party applications. The OpenAPI specification is generated automatically from the codebase and is the recommended integration point for country-level system integrations. *** ### 8. Architecture pattern OpenCRVS follows an **event-sourced microservices** architecture: * **Microservices** β€” each service owns its domain and database. There is no shared database between services. * **Event sourcing** β€” civil registration actions (declarations, validations, registrations, corrections) are stored as an immutable sequence of events in the Events service. The current state of any record is derived from its event history. * **API Gateway** β€” all external traffic enters through the Gateway service, which handles authentication verification and routes requests to the appropriate downstream service. This pattern means registration records have a full, tamper-evident audit trail by design. *** ### 9. Monorepo structure All services and packages live in a single repository managed with **Lerna** and **Yarn Workspaces**. This allows shared packages (`@opencrvs/commons`, `@opencrvs/components`) to be used across services without publishing them to a registry during development, and ensures that all services are always tested against compatible versions of shared code. *** ### 10. Required skills The skills required depend on what your team is doing. **Country configuration** β€” configuring and extending OpenCRVS for your country requires TypeScript knowledge only. The country configuration package is a TypeScript codebase that defines forms, workflows, business rules, and translations. Knowledge of React, databases, or infrastructure is not needed for this work. **Core development** β€” contributing new features to OpenCRVS core requires familiarity with the full stack: | Skill | Where it applies | | ------------------- | ----------------------------------------- | | TypeScript | All services and packages | | React | Frontend applications | | Node.js | Backend services | | PostgreSQL | Events data, migrations, queries | | Elasticsearch | Search configuration and index management | | Docker & Kubernetes | Container operation and deployment | | REST/OpenAPI | External system integration | # Data architecture ### 1. Introduction OpenCRVS treats every civil registry record as an **append-only sequence of actions** rather than a row you UPDATE. The current state of a record β€” what gets shown in search, on a certificate, in an analytics dashboard β€” is always *derived* by folding those actions in order. This shapes nearly every other decision in the platform, so it's worth understanding before evaluating the rest. *** ### 2. Life events are sequences of actions A birth registration is not a single database write. It is a sequence such as: ``` CREATE β†’ DECLARE β†’ REGISTER β†’ PRINT_CERTIFICATE β†’ REQUEST_CORRECTION β†’ APPROVE_CORRECTION ``` The record's current state at any point in time is the reduction of all actions from the first one onwards. All actions are immutable once written. #### 2.1 Why this shape? * **Full audit trail by construction.** There is no separate audit log to maintain in lockstep with the data β€” the data *is* the log. For a civil registry, where every change carries legal weight, this matters. * **Reproducible state.** All consumers of OpenCRVS data can fold the same actions and arrive at the same state without coordination. *** ### 3. PostgreSQL is the source of truth; Elasticsearch is a derived view Action records are stored in PostgreSQL with a strict schema. Action payloads are JSON (jsonb) but validated against a Zod discriminated union before being accepted, so every row in `event_actions` is one of the known action shapes. Elasticsearch holds the **current state** of every record β€” i.e. the reduced view β€” for search and listing screens. It is fully derivable from PostgreSQL: * The ES index is rebuilt on every deploy. * It can also be rebuilt manually at any time. * The reduction is a plain fold over an array of objects; there is no snapshotting, no checkpointing β€” it is always a full replay from action #1. Records are expected to accumulate well under 100 actions over their lifetime (typically around 20), which keeps the fold trivially fast both on the server and in the browser. The same reducer code runs in both places. PostgreSQL is backed up nightly to a separate server. *** ### 4. Concurrency: record assignment, not merge OpenCRVS avoids the offline-first conflict-resolution problem by **assigning** a record to one user at a time. Assignment is itself an action (`ASSIGN` / `UNASSIGN`), and only the currently assigned user can write further actions. Two system users cannot race; a second system user must wait for the first to release the record. This is intentional. Civil registry actions are deliberative β€” declaring a birth or approving a correction is not a write you want to silently merge with a competing write β€” and the assignment model keeps the data model simple while reflecting how registry offices actually work. *** ### 5. Offline-first clients hold actions until acknowledged The web client is designed for field work in low-connectivity environments. When a user submits an action, the client does not consider the action "delivered" until the backend has confirmed it was processed correctly: * The action sits in an **outbox** persisted to IndexedDB on the device. * It is retried until the backend acknowledges it. * Only then is it removed from the outbox. Because state is derived from actions, the same reducer used on the server can be run locally over the outbox to show the user what their record *will* look like once their pending actions sync. *** ### 6. Files are uploaded ahead of the action Attachments β€” supporting documents, photos, signatures β€” are not sent inside the action payload. Instead: 1. As soon as the user adds a file in the form, the client uploads it directly to S3-compatible static storage. 2. The storage layer returns a unique file path. 3. That path is embedded into the eventual action payload. This means uploads happen *while the user is still filling out the form*, not at submit time. By the time the form is submitted, the heavy work is already done and the action itself is small and fast. When an action is processed, the backend verifies that every referenced file path actually exists before accepting the action. It also **cleans up unreferenced files for the event in the same step**: any file uploaded under the event's prefix that is not referenced by the freshly-computed state is deleted. There is no scheduled GC job β€” orphan cleanup is reactive, on every action. *** ### 7. Country configuration receives every action OpenCRVS Core is event-agnostic. The concepts of "birth", "death", "marriage" do not exist inside core β€” they are defined entirely by a **country configuration server** that each implementing country runs and owns. The configuration defines event types, form fields, validation rules, certificate templates, business rules, and notification logic. On every action the core sends the **full event document** (the event metadata plus the complete raw action history) to the country configuration server. Country config can: * Handle the action **synchronously** β€” respond with 200 to confirm, or an error to reject and have it retried. * Handle it **asynchronously** β€” respond with 204 and call back later via APIs to confirm completion. If the country configuration server is unreachable or returns an error, the user-facing action **fails** and is retried until country config is back up. This is deliberate: country config often holds business rules that the core cannot validate on its own (e.g. legal eligibility), so accepting an action that country config would have rejected is worse than asking the user to wait. Delivery is **at-least-once**: a retried action after a country config 5xx may be delivered more than once, so country config integrations should be idempotent. This integration point is where countries typically wire in their analytics warehouses, downstream identity systems, statistical bureaus, and so on β€” by subscribing to the action stream rather than reaching into core's database. *** ### 8. What this means for adopters * **Configurability is per-country, not per-deploy.** Event types and payload schemas are owned by your country configuration server. Birth/death/marriage are not hardcoded in the core. * **The full history is non-negotiable.** Actions are immutable; corrections happen by appending new actions, not by editing past ones. Errors stay visible in the log but no longer affect the derived state. * **You can rebuild from Postgres alone.** Losing Elasticsearch is recoverable; losing Postgres is not. Backup strategy should focus there. # Integration architecture ### 1. Introduction OpenCRVS Core is designed to be country-agnostic. It does not know how a country sends SMS, which National ID system it uses, or what business rules apply when a birth is declared. Instead, Core is built to communicate with **one well-known peer**: the country configuration package (referred to here as *country config*). Country config is owned, maintained and customised by each country. It is the bridge between Core and: * Notification providers (SMS, email) * National ID and other government registries * Payment providers * Reporting and statistics systems * Any other third-party system the country needs to integrate with ```mermaid flowchart LR User[Field agent / Registrar] --> Core[OpenCRVS Core] Core <-->|HTTP webhooks| CountryConfig[Country config package] CountryConfig <--> SMS[SMS / Email provider] CountryConfig <--> NID[National ID system] CountryConfig <--> Other[Other 3rd-party systems] ThirdParty[External system] -.->|discouraged| Core ThirdParty -->|preferred| CountryConfig ``` > **Golden rule:** third-party systems should never call OpenCRVS Core APIs directly. They should always go through country config, which acts as the country's integration and policy layer. ### 2. How Core talks to country config For every meaningful event that happens inside Core, Core sends an HTTP request to country config. This covers two broad categories: #### 2.1 Notification and account events These are events where country config is given the opportunity to **act on behalf of the country** without changing the outcome of the event in Core. Examples include: * A user requests login and a 2FA code needs to be delivered * A user is created and needs to receive credentials * A registrar action needs to trigger an outbound notification Core does not know how to send an SMS or email. It simply emits the event to country config, and country config decides whether to send the code via SMS, email, a national notification gateway, or something else entirely. #### 2.2 Action triggers (interceptable events) These are events tied to the lifecycle of a record β€” for example, *birth declared*, *birth registered*, *death certified*. Country config may **intercept** these events, perform additional work (such as validating against a National ID database), and then approve or reject the original action. See #action-interception below. *** ### 3. Webhook reliability Integrations across government systems are rarely perfectly available, so Core treats every outbound call to country config as a request that **must eventually succeed**. * Core retries the request to country config until it receives a `2xx` response. Any other status code, or a network error, is treated as a transient failure and retried. * For requests originating from a user action in the UI, the request **does not leave the user's outbox** until Core has fully processed the event end-to-end. This means a field agent working offline, or one whose request is blocked behind a slow integration, will see the action remain in their outbox until it is durably accepted. * Country config endpoints should therefore be designed to be **idempotent**. Country config may receive the same event more than once and must produce the same outcome. ```mermaid sequenceDiagram participant User participant Core participant CC as Country config User->>Core: Submit action (from outbox) loop until 2xx Core->>CC: POST event CC-->>Core: non-2xx or network error end CC-->>Core: 2xx Core-->>User: Remove from outbox ``` ### 5. Action interception Some events β€” typically registration-lifecycle actions β€” can be intercepted by country config. Interception lets a country attach domain-specific validation or processing to an action without modifying Core. When Core dispatches an interceptable event, the action is recorded in Core as a **pending action** and held there until country config resolves it. While pending: * The action exists in Core but its effects are not yet applied * Core continues to be the source of truth for the action's state * Country config may take as long as it needs to coordinate with external systems Once country config acknowledges the event with a `2xx`, Core informs the user that the action has been safely received by the backend. From the user's point of view the submission is done β€” their outbox can clear. Whether and when the record reappears in a workqueue depends on how country config eventually resolves the pending action: * **Approve** β€” the action's effects are applied and the record moves forward in its lifecycle. * **Reject** β€” the action is marked rejected and the record returns to an appropriate workqueue for follow-up. ```mermaid sequenceDiagram participant User participant Core participant CC as Country config participant NID as External system (e.g. National ID) User->>Core: Trigger action (e.g. Declare birth) Core->>Core: Record pending action Core->>CC: POST event (interceptable) CC-->>Core: 2xx (acknowledged) Core-->>User: Acknowledged β€” safe to clear outbox CC->>NID: Validate / register NID-->>CC: Result alt Validation passes CC->>Core: Approve pending action Core->>Core: Apply action (record progresses) else Validation fails CC->>Core: Reject pending action Core->>Core: Mark rejected (returns to a workqueue) end ``` This pattern lets countries plug arbitrary business logic and external dependencies into the registration lifecycle without forking Core. ### 6. Country config calling back into Core Country config frequently needs to read or write data in Core β€” for example, to enrich a record before approving it, or to fetch contextual information before sending a notification. It does this through Core's standard APIs, authenticated in one of two ways: * **User JWT** β€” country config reuses the JWT of the human user who triggered the original event. The call is performed *as that user*, with that user's permissions. This is appropriate when country config is acting on behalf of a specific human action. * **System client token** β€” a service-to-service token issued through the OpenCRVS admin UI for a registered system client. This is appropriate for background work, scheduled jobs, or any flow where no human user is in the loop. *** ### 7. Why third parties should not call Core directly Country config is more than a webhook receiver β€” it is the **trust and policy boundary** for the country's deployment of OpenCRVS. Several things follow from this: * **Security boundary.** Core is designed to be generic and country-neutral. Country-specific authorization, allow-listing, audit, and data-shaping decisions belong in country config. Letting third parties hit Core directly bypasses all of that. * **Single integration surface.** When all external systems route through country config, the country has one place to upgrade contracts, swap providers, add logging, or respond to incidents. * **Decoupling from Core upgrades.** Core's internal APIs evolve. Country config insulates third parties from those changes by exposing a stable, country-owned contract. * **Consistent behaviour with interception.** Many third-party interactions correspond to interceptable events. Routing them through country config keeps the approve/reject lifecycle coherent. Even when a third party needs to read Core data, the recommended pattern is to expose a country-config endpoint that fetches from Core (using a system client token) and returns a shaped, authorised response. ```mermaid flowchart LR TP[3rd-party system] CC[Country config] Core[OpenCRVS Core] TP -->|country-defined API| CC CC -->|JWT or system token| Core TP -. discouraged direct call .-> Core ``` ### 8. Summary * Core's only integration peer is country config. * Every Core-side event is dispatched to country config over HTTP, with retries until a `2xx` response is received; user-originated actions stay in the outbox until fully processed. * Country config can extend behaviour (notifications, account events) and intercept registration actions, holding them as pending in Core until approved or rejected. * Country config calls Core using either the originating user's JWT or a system client token. * Third parties should always integrate through country config, never directly with Core. # Standards ### 1. Introduction OpenCRVS sits at the intersection of three standards landscapes β€” civil registration, Digital Public Infrastructure, and general web/software engineering. This page lists the standards the platform conforms to or aligns with, separated by domain so adopters can map them against national procurement and architecture requirements. *** ### 2. Civil registration & social protection * **UN Guidelines for Civil Registration.** OpenCRVS implements the civil registration process as set out in the UN guidelines. * **Digital Convergence Initiative (DCI).** OpenCRVS is a Standards Committee Member of the DCI and co-authored the *CRVS and SP-MIS Interfaces* standard. The platform interoperates with social protection systems such as OpenSPP via these interfaces. * **G2P Connect** (Centre for Digital Public Infrastructure). G2P Connect specifications are used in the interoperable middleware that delivers the DCI CRVS↔SP-MIS interfaces above. OpenCRVS is designed as a core component of Digital Public Infrastructure and is committed to adopting open digital government data standards as the DPI standards ecosystem matures. *** ### 3. APIs & data exchange * **REST** is the API style for all core APIs. OpenAPI documentation is published at [documentation.opencrvs.org/v2.0/technical/apis/core-apis](https://documentation.opencrvs.org/v2.0/technical/apis/core-apis). * **Webhook payloads** sent to country configuration and other downstream consumers are a bespoke OpenCRVS schema. * **Versioning.** Releases follow a semantic-versioning shape β€” `MAJOR.MINOR.PATCH` β€” with the following guarantees: | Bump | Backwards-compatible to country config? | Manual data migration? | Cadence | | ----- | --------------------------------------- | ---------------------- | -------- | | Patch | Yes | Never | Frequent | | Minor | May break country-config contracts | Never | Regular | | Major | May break country-config contracts | Possible | Rare | Minor versions can require country configuration updates, but data migrations are reserved for major versions only. This lets implementing teams plan country-config changes against minors and reserve heavier engineering capacity for the rarer majors. *** ### 4. Data formats | Concern | Standard | | -------------- | ------------------------------------- | | Date-time | ISO 8601 | | Plain dates | `YYYY-MM-DD` (ISO 8601 calendar date) | | Languages | BCP 47 language tags, e.g. `fi-FI` | | Currency codes | ISO 4217 | | Translations | ICU MessageFormat | *** ### 5. Authentication & authorisation * **JWT** is used for session tokens, signed with **RS256** (RSA + SHA-256). The signing key is loaded from the filesystem at service startup, and the matching public key is published at the `/.well-known` endpoint so downstream services can verify tokens without sharing secrets. * **Two-factor authentication** is required for sign-in. The 2FA delivery channel is country-configurable β€” SMS, email, or any transport the country wishes to wire up. * **Role-based access control.** Roles and the actions they may perform are defined by country configuration; the core enforces them on every action. *** ### 6. Password storage * **bcrypt** with a work factor of **10 rounds**. *** ### 7. Audit logging OpenCRVS maintains two complementary audit trails: * **Event action log.** Every change to a civil registry record is itself an immutable action persisted to PostgreSQL. This is the journal of record for births, deaths, marriages and any other country-configured event. See the [data architecture page](https://documentation.opencrvs.org/v2.0/technical/architecture/data-architecture) for details. * **User and administrative audit log.** A separate audit stream captures user-lifecycle and administrative events that are not record changes β€” user creation, deactivation and reactivation, profile edits, login and logout, password changes (self-service, reset, admin-initiated), email and phone number changes, invitation resends and username reminders. These records are persisted to PostgreSQL alongside the event log. Tamper-evident hashing of audit entries is on the roadmap rather than in the current release. *** ### 8. Transport & at-rest encryption OpenCRVS treats transport security and at-rest encryption as **deployment-layer concerns**. The platform does not pin specific TLS versions or key-management systems in code; it expects the operator to terminate TLS at the ingress, enforce encrypted connections to managed PostgreSQL, MongoDB and S3-compatible storage, and configure disk/volume encryption and KMS-managed keys according to local policy. This is a deliberate choice: it keeps OpenCRVS portable across the cloud and on-premise environments that different country deployments require, and lets each country meet its own data-residency and key-custody mandates. Recommended deployment configurations are covered in the operations documentation. *** ### 9. Internationalisation * **Translation framework:** [react-intl](https://formatjs.io/docs/react-intl/) (part of FormatJS) on the web client. * **Message syntax:** ICU MessageFormat, supporting pluralisation, gender, and nested formatting. * **Translation source:** strings live in the country configuration repository as CSV and are loaded by the client. This keeps localisation fully in the hands of the implementing country, alongside form definitions and other country-specific configuration. *** ### 10. Licensing & governance * **Licence:** [Mozilla Public License 2.0 (MPL-2.0)](https://www.mozilla.org/MPL/2.0/) for the core codebase. # Infrastructure ### Introduction OpenCRVS is designed to run on **Kubernetes** and is typically deployed within **government-owned or government-approved infrastructure**. This deployment model supports **data sovereignty**, allowing countries to retain full control over sensitive civil registration data while meeting national security and compliance requirements. The infrastructure used to deploy OpenCRVS is maintained separately from the application code in the **OpenCRVS Infrastructure** repository: **Repository:** This repository contains the automation, deployment templates, and operational tooling required to provision, configure, upgrade, and maintain OpenCRVS environments. *** ### Infrastructure philosophy Deploying and operating Kubernetes clusters consistently is a complex task. Rather than requiring every implementation partner to build and maintain their own deployment tooling, OpenCRVS provides a fully automated deployment framework. The infrastructure has been designed around the principles of: * Infrastructure as Code * Repeatable, automated deployments * Continuous Integration and Continuous Deployment (CI/CD) * Standardised environments across all countries * Minimal manual intervention We strongly recommend using the provided automation rather than performing manual deployments or customising the deployment process unless absolutely necessary. *** ### Deployment automation OpenCRVS infrastructure is deployed using a combination of modern DevOps technologies including: * **GitHub Actions** for CI/CD pipelines * **GitHub Self-Hosted Runners** for executing deployments within secure government networks * **Ansible** for server provisioning and configuration * **Helm** for Kubernetes application deployment and upgrades * Kubernetes manifests and supporting automation scripts Together these components provide automated provisioning, upgrades, application deployment, backup operations, certificate management, and many day-to-day operational tasks. Our deployment scripts are designed to be executed from **GitHub Actions workflows** and assume this operating model. *** ### Deployment architecture OpenCRVS provides a **reference deployment architecture** that enables countries to get up and running quickly using a standard set of components. This architecture has been used across multiple country implementations and is fully supported by the deployment automation. A typical reference deployment includes: * Kubernetes cluster * GitHub Self-Hosted Runner * Container registry * PostgreSQL * Elasticsearch * Object storage * Monitoring and logging components This reference architecture is suitable for most initial deployments and provides a solid foundation for production use. *** #### Scaling over time As adoption grows and operational requirements become more demanding, countries may choose to increase disk space, decouple or replace individual infrastructure components. Examples include: * Moving databases onto dedicated high-availability database clusters * Using an enterprise container registry instead of Dockerhub * Replacing object storage with an existing government storage platform * Scaling Kubernetes worker nodes independently to meet increasing demand The OpenCRVS deployment automation supports this evolution, allowing infrastructure to mature without requiring changes to the application itself. The exact production architecture should be determined according to the country's requirements for availability, scalability, security, disaster recovery, and operational support. The reference architecture provides a supported starting point, while larger deployments can progressively adopt more enterprise-grade infrastructure as needed. *** ### Country responsibilities While OpenCRVS provides the deployment automation and application infrastructure, several external dependencies must be provided by the country implementation team before deployment can begin. These typically include: * Network infrastructure * [VPN](https://documentation.opencrvs.org/technical/guides/installation/advanced-topics/why-vpn) * DNS configuration * TLS certificates * SMTP email service These services are considered prerequisites for a successful implementation and are outside the scope of the OpenCRVS infrastructure repository. Read more: [Preparation steps](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps) *** ### Use the automation The infrastructure repository has been developed and tested across multiple country deployments and continues to evolve as new features and operational improvements are added. Implementation partners should use the supplied automation wherever possible. Following the standard deployment approach ensures: * Faster deployments * Easier upgrades * Reduced operational risk * Consistent environments across countries * Better support from the OpenCRVS community Manual deployments or significant modifications to the automation should only be undertaken where there is a clear technical or organisational requirement, as they may complicate future upgrades and support. *** ### Further reading: * [Deploy: Set-up a server hosted environment](/technical/guides/installation/deploy-set-up-a-server-hosted-environment) * [Advanced topics: Firewall config, TLS, disk space & SSH management](/technical/guides/installation/advanced-topics) * [Preparation steps, including network diagram](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps) * [Automation to configure a Github environment](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/create-a-github-environment) * [Ansible automations to provision servers](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/provisioning-servers) * [Github self-hosted runners used when deploying](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/deploy) * [Advanced topics: Why VPN?](https://documentation.opencrvs.org/technical/guides/installation/advanced-topics/why-vpn) # Security ### 1. Introduction OpenCRVS treats the security of the application and the personally identifiable information (PII) it stores with utmost care. Security is critical for protecting citizen data and maintaining public trust in the civil registration system. Every release of the OpenCRVS application and infrastructure has been security penetration tested by an independent, [CREST](https://www.crest-approved.org/) and [CyberEssentials](https://www.ncsc.gov.uk/cyberessentials/overview) certified 3rd party to UK government standards. Penetration tests of OpenCRVS have been performed by [MDSec](https://www.mdsec.co.uk/), [The Guardian Project](https://guardianproject.info/code/) on behalf of UNICEF, and [Gofore](https://gofore.com/)- [NORAD's](https://www.norad.no/) preferred security testing provider. *** ### 2. Feature overview OpenCRVS provides a comprehensive security model to protect citizen data and system infrastructure. #### Core capabilities With security features, OpenCRVS supports: * **Two-factor authentication** (2FA) for user login and server access, using SMS or Google Authenticator. * **Role-based access controls** that segregate personally identifiable data to only users who need it. * **Full audit trails** of all access to declarations and registrations, tracking who viewed what data and when. * **Encrypted data in transit** via TLS certificates, automatically provisioned and rotated. * **Encrypted data at rest** using Docker Secrets and Github Secrets, never stored in plain text. * **Rate limiting** to prevent denial of service and brute force attacks. * **Firewall and SSH protection** automatically provisioned on each node. * **Infrastructure monitoring** with automated alerting for security-relevant events. Security in OpenCRVS is: * **Tested** β€” every release is independently penetration tested to industry standards. * **Layered** β€” multiple controls protect data at different levels (authentication, access control, encryption, monitoring). * **Auditable** β€” all access to records and infrastructure is logged immutably. {% hint style="info" %} **Security posture** β€” As Gofore's Cyber Security Consultant noted: *"Already from the results of the first assessment, it was evident that the OpenCRVS web application had a good security posture. The web application security fundamentals were sound."* {% endhint %} *** ### 3. Penetration testing OpenCRVS undergoes regular security assessments by independent, certified third-party security firms. #### Testing providers Penetration tests have been performed by: * [**MDSec**](https://www.mdsec.co.uk/) β€” CREST certified security testing firm. * [**The Guardian Project**](https://guardianproject.info/code/) β€” on behalf of UNICEF. * [**Gofore**](https://gofore.com/) β€” NORAD's preferred security testing provider, CyberEssentials certified. * [**Orange Cyberdefense**](https://www.orangecyberdefense.com/) β€” -- a leading European cybersecurity company providing managed security, threat intelligence and cyber defence services. #### Testing methodology Security assessments typically include: * **Code review** β€” manual review of application source code for vulnerabilities. * **Automated enumeration scans** β€” scanning via the public internet to identify exposed services and potential weaknesses. * **Fuzzing with diverse input** β€” testing how the system handles unexpected or malicious input. * **Manual penetration testing** β€” simulating an adversary attacking the system to identify exploitable vulnerabilities. Testing is conducted in two rounds: 1. **Initial assessment** β€” identify and report vulnerabilities. 2. **Reassessment** β€” verify that reported vulnerabilities have been resolved. All tests are conducted to UK government standards and follow proven ethical hacking methodologies. {% hint style="warning" %} You should always conduct your own penetration test of your configuration and installation before going live. Penetration testing demonstrates that a system was secure against a defined set of tests at a point in timeβ€”it does not eliminate future vulnerabilities, configuration mistakes or supply chain risks. {% endhint %} *** ### 4. Authentication and access control OpenCRVS uses multiple layers of authentication and access control to ensure that only authorized users can access the system and view sensitive data. #### 4.1 Two-factor authentication All user authentication requires two factors: * **Something you know** β€” username and password. * **Something you have** β€” 2FA code sent to the user's mobile device via SMS or Google Authenticator. This ensures that only users with access to authenticated hardware can log in to OpenCRVS, even if their password is compromised. #### 4.2 Role-based access controls User types and access controls are managed to segregate personally identifiable data to only the users who need it. * **Roles and scopes** define what actions users can perform and what data they can access. * **Jurisdictional constraints** restrict users to records from specific administrative areas. * **Team management** is handled via the Team GUI, accessible by National and Local System Administrators. #### 4.3 Audit trail Every access to a specific declaration or registration is audited, tracking: * Who viewed the data. * When they viewed it. * What actions they performed. This protects citizen rights and provides accountability for all system access. *** ### 5. Infrastructure security OpenCRVS automatically provisions secure infrastructure with multiple layers of protection. #### 5.1 Firewall and SSH access * **Firewall** β€” OpenCRVS automatically provisions a secure firewall on each node using Ansible. * **SSH 2FA** β€” SSH users are configured to use Google Authenticator 2FA when connecting via a Terminal. * **Automated alerts** β€” every SSH access prompts an automated alert to technical teams via Slack. {% hint style="warning" %} **VPN requirement** β€” OpenCRVS should only be installed behind a separately configured and managed, government-owned VPN. {% endhint %} #### 5.2 TLS certificate OpenCRVS data is encrypted in transit via an SSL certificate that can be automatically provisioned and rotated by [Traefik](https://traefik.io/), signed by [LetsEncrypt](https://letsencrypt.org/), depending on DNS and VPN configuration. #### 5.3 Database encryption Encryption keys to the databases, API keys, and sensitive environment secrets are never stored in `.env` files. Instead, they are stored in RAM in inaccessible locations: * [**Docker Secrets**](https://docs.docker.com/engine/swarm/secrets/) β€” secrets are provided to deployment in encrypted form. * [**Github Secrets**](https://docs.github.com/en/actions/security-guides/encrypted-secrets/) β€” deployment secrets are stored encrypted in Github. #### 5.4 Infrastructure monitoring All access to OpenCRVS servers and infrastructure health is logged and monitored in [Kibana](https://www.elastic.co/observability/infrastructure-monitoring). *** ### 6. Rate limiting OpenCRVS authentication and API gateway is rate limited to prevent abusive attacks such as: * **Denial of Service (DoS)** β€” overwhelming the system with requests to make it unavailable. * **Brute Force attacks** β€” repeatedly attempting to guess passwords or access tokens. Rate limiting controls the number of requests a user or system can make to an API or service within a specified timeframe, preventing abuse and ensuring fair resource distribution. *** ### 7. Data Security Framework OpenCRVS is designed to digitally store and process personally identifiable information (PII) and create copies of official documentation including unique identifiers for citizens. While OpenCRVS is regularly penetration tested and provides technical solutions to mitigate common threats, it is used within the context of human day-to-day work and interaction with the outside world. #### 7.1 The evolving threat landscape Criminals continually adapt and attempt to gain access to valuable citizen data. The constantly evolving cyber-security landscape includes: * **Social engineering methods** β€” manipulating staff to gain access. * **Machine learning and artificial intelligence** β€” automated techniques to exploit vulnerabilities. * **Insider threats** β€” staff who misuse their access to the system. Reacting to such threats often falls outside the scope of what a technical system is capable of independently defending against. #### 7.2 The need for policies and procedures Data security policies and procedures must be developed and adhered to by implementing project teams and operational staff when setting up and using OpenCRVS. These policies and procedures should be: * **Context-specific** β€” appropriate to the government's specific needs and threat environment. * **Comprehensive** β€” covering design, implementation, monitoring, maintenance, and day-to-day usage. * **Informed by best practice** β€” drawing on publicly available data security guidance, not exclusively from this document. #### 7.3 Data Security Framework document OpenCRVS provides a **Data Security Framework** document to support governments in developing their own policies and procedures. This document is available in the [**Pre-Deployment Checklist**](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/3.3.4-set-up-an-smtp-server-for-opencrvs-monitoring-alerts) page. The purpose of this document is to provide organizations with: * An understanding of data security and privacy risks. * An understanding of the technical steps taken in OpenCRVS to mitigate against these risks. * A guidance framework for the development of context-specific data security policies and procedures. * Security guidance for project managers and all staff involved on a temporary or continual basis in the following stages of an OpenCRVS project: * Design and implementation * Monitoring and maintenance * Day-to-day usage of OpenCRVS Data security policies and procedures must be defined, implemented, and updated by governments appropriate to their own contextual needs. Example reference links are provided in the appendix of the Data Security Framework document. # Performance ### 1. Introduction OpenCRVS is built to run national-scale civil registration systems. This page explains what that means in practice: how many people can use it, how fast it responds, and how it handles pressure.\ \ All numbers on this page come from load tests run against a database of **1.2 million records** on a modest two-server (primary + secondary) setup. A larger deployment would perform even better. *** ### 2. At a glance | | | | ------------------------- | --------------------------------------------------- | | **Simultaneous users** | 1,000+ logged-in users at the same time | | **Registration speed** | Under 350 ms to process a birth registration | | **Search speed** | Under 60 ms to return search results | | **Error rate under load** | 0.00% | | **Spike recovery** | Returns to normal within seconds of a traffic surge | *** ### 3. How many people can use it at once? In testing, OpenCRVS handled over 1,000 users working at the same time: registrars filling in forms, staff searching for records, and supervisors monitoring workqueues. Every operation completed well within acceptable time limits. For context, even in a country the size of the Philippines (\~117 million people), it's rare for more than a few hundred staff to be submitting registrations at the same moment. The system has plenty of room beyond typical peak demand. The tests simulated realistic behaviour, including the time people spend reading screens and filling in forms, plus the background polling the OpenCRVS client does automatically. The number of virtual users in the test maps directly to the number of real people who could be logged in and working at once. *** ### 4. How fast is it? Response times are measured server-side: the time the server takes to process a request, not counting network travel between the user's device and the server. | What a user does | How long the server takes | | --------------------------- | ------------------------- | | Log in | \~130 ms | | Submit a birth registration | \~150 ms | | Complete a registration | \~170 ms | | Search for a record | \~25 ms | | Open a record | \~75 ms | | Load the workqueue | \~30 ms | A typical web page takes 1 to 3 seconds to load. These server processing times are a small fraction of that, so most operations feel instant. *** ### 5. What happens during a traffic spike? We tested a sudden jump to five times the normal load, the kind of thing you might see on a Monday morning, after a public holiday, or during a registration campaign. The system handled it with no crashes, errors, or data loss. Once the spike passed, response times returned to normal within seconds, with no lingering effects: nothing got stuck, and later users saw no slowdown. *** ### 6. How big can the database get? The test database held **1.2 million event records**, roughly six months of registration data for a country of 100 to 120 million people. At that scale, searches still returned in under 60 ms and registrations completed in under 350 ms. For reference, a country registering 10,000 events a day builds up about 3.6 million records a year. Maintenance strategies like indexing and archival are available to keep performance steady as the dataset grows over the years. *** ### 7. What infrastructure does it need? The test results above were achieved on a deliberately modest setup: | Server | Specification | | --------- | ------------------------- | | Primary | 8 CPU cores, 16 GB memory | | Secondary | 4 CPU cores, 8 GB memory | This is a baseline configuration. National deployments can scale infrastructure up or horizontally to increase capacity further. Even on this small setup, the system never used more than half its available memory and experienced zero crashes or restarts. *** ### 8. What about the user's device? The numbers above measure server-side speed only. The actual experience on someone's device also depends on their internet connection, browser, and hardware. One area we're still working on is how the browser handles large location datasets. In countries with tens of thousands of administrative areas (the Philippines has over 42,000 barangays), the client-side code that processes location data can make page interactions slower. It's a known optimisation target and doesn't affect server performance or data integrity. *** {% hint style="info" %} **Want the full details?** The complete performance test report β€” including methodology, per-operation breakdowns, infrastructure health metrics, and spike recovery analysis β€” is available on request. Contact the OpenCRVS team for a copy. {% endhint %} # Guides # Installation # Quick Start ### Create a country configuration ``` npm create @opencrvs/countryconfig ``` This command creates a country configuration package with a minimal example configuration. ### Run local development environment Make sure all prerequisites are installed, see [opencrvs-countryconfig](https://github.com/opencrvs/opencrvs-countryconfig/#prerequisites) Navigate to `-countryconfig` Start development environemnt: ``` tilt up ``` Open the Tilt UI: ``` http://localhost:10350 ``` Wait until the main resources are running. Then run the data seed task from the Tilt UI: 1. Open 2. Find the `2.Data-tasks` section 3. Run the `data-seed` or `clean-&-seed` resource 4. Wait until the job completes Open OpenCRVS: Thats it! πŸŽ‰ # Set up Github and Dockerhub accounts In the previous step you set up a country configuration package with a minimal example configuration. Next, you want to commit all changes to a repo and build your countryconfig Docker image using the Github Actions and a [**Dockerhub**](https://hub.docker.com/) account. #### 1. Use a GitHub Organisation The country configuration repository should be stored into a **GitHub Organisation**, not a personal GitHub account. Your organisation should: * use a **Github Team** or **Enterprise** plan (required for branch protection rules and Github Actions minutes) * grant you **Administrator** permissions on the repository Using an organisation simplifies collaboration, governance and access management throughout the lifetime of the project. #### 2. Choose a repository name Rename the repo to represent your own country implementation. E.G. ``` opencrvs- ``` #### 3. Plan your branching strategy We recommend adopting a Gitflow-style branching strategy to separate development, testing and production releases. | Branch | Purpose | | -------------------- | ------------------------- | | `main` (or `master`) | Deployment configuration | | `develop` | Development configuration | This allows configuration changes to be developed independently, tested in the `develop` branch and promoted to `main` only when approved. #### 4. Define repository governance Before development begins, configure your repository permissions. This typically includes: * adding implementation team members * assigning code reviewers * identifying repository administrators * granting DevOps engineers appropriate deployment permissions #### 5. Configure branch protection To protect your production configuration and enforce code review, configure branch protection rules for your repository. Navigate to: **Settings β†’ Branches β†’ Add Branch Protection Rule** Create a protection rule for the `main` branch (and optionally `develop`) with the following recommended settings: * Require pull request reviews before merging * Require status checks to pass before merging (when CI is configured) * Require signed commits (recommended) * Restrict who can push directly to protected branches Once configured, test the protection rules by creating and merging a test pull request. Branch protection helps ensure that all configuration changes are reviewed, validated and traceable before they are deployed. #### 6. Set up an individual and an organisation account on Dockerhub You will also need a container registry to store your country configuration Docker image. OpenCRVS is configured to use **Docker Hub** by default, although you can modify the infrastructure to use another container registry if preferred. Create a **Docker Hub Organisation** and add all developers as members so they can publish and access images. Then create a **single private repository** to store your country configuration image. This repository will be accessed by both your development team and your OpenCRVS servers during deployment. Docker Hub's free plan includes one private repository, which is sufficient for a typical OpenCRVS implementation. Creating a private Dockerhub repository for a countryconfig forked container:
Ensure that the Dockerhub members have permissions to write to the repository:
You will need your Dockerhub **username** and a personal Dockerhub account **access token**. Our scripts use these credentials to login to Dockerhub programmatically. This is how you create a Dockerhub access token: #### 7. Ensure your Docker image can be built successfully When you create a [Github environment](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/create-a-github-environment), you enter these Dockerhub login values, and they are saved into Github repository secrets. When you merge any pull request into the "main", "master" or "develop" branch, or if you explicitly run the "Publish image to Dockerhub" Gthub Action, a docker container image will be built and pushed to Dockerhub for your **countryconfig** microservice. {% hint style="info" %} The image will automatically be tagged with the Git commit hash. You will use this hash when deploying. {% endhint %} In [Github repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets), you can also manually set the following values and the above will occur.
# Deploy: Set-up a server-hosted environment In this chapter, you will learn how to create and configure the infrastructure and all required components for an OpenCRVS deployment using GitHub Actions workflows. These workflows guide you through the installation and configuration of OpenCRVS on servers The **essential** [**preparation steps**](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps) guide you through the following: * Provision servers (virtual machines) & VPN. * Configure DNS and obtain SSL certificates. * Set up an SMTP server. * Create the required accounts: * GitHub organisation * Docker Hub * 1Password (or another secrets manager) * Optional: other services such as Slack and Sentry #### Fork the required repositories If you have not already done so in the [Quick Start](/technical/guides/installation/quick-start), fork the [countryconfig](https://github.com/opencrvs/opencrvs-countryconfig) repository and configure its CI process to push images to your container registry. See [**Fork and build the countryconfig repo**](/technical/guides/installation/set-up-github-and-dockerhub-accounts) Fork the [infrastructure](https://github.com/opencrvs/infrastructure) repository. {% hint style="info" %} The country configuration repository contains an [infrastructure](https://github.com/opencrvs/opencrvs-countryconfig/tree/develop/infrastructure) folder which supports: **Backwards compatibility for OpenCRVS versions 1.9 and below still using DockerSwarm. Docker Swarm will be deprecated in 2.1.** [**MIGRATE TO KUBERNETES IN TIME!**](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/migration-from-docker-swarm-guide) {% endhint %} All steps are described in detail in this chapter. **Once the preparation steps are complete,** proceed with the installation steps **in order, starting with creating a Github environment**. # Preparation steps #### Before you begin Before running any scripts, you must complete the following **essential preparation steps**. Please carefully consider the information in these pages. This section describes the environments, servers and network requirements that countries are required to prepare in order to install OpenCRVS. We have an automated scripts to generate [Github environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) for you along with all the application secrets that Github needs to run the continuous provisioning and deployment scripts. Github Actions use environment secrets and variables when installing software on servers and deploying OpenCRVS. These secrets and variables are entirely dependant on the [prerequisite accounts and repositories](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/create-prerequisite-accounts-and-repositories). #### Further reading The [Advanced topics](/technical/guides/installation/advanced-topics) section gives you important detail on the various configurations related to servers, TLS, SSH access (to comply with internal procedures), Kubernetes cluster management and disk space. The [OpenCRVS maintenance tasks](/technical/guides/installation/opencrvs-maintenance-tasks) section explains how to manage data and disaster recovery. The [Monitoring](/technical/guides/monitoring) section explains how to use the ELK stack to track server and application health and respond to issues. This further reading guides you through how to configure, provision, deploy and maintain OpenCRVS server deployments technically. # Setup infrastructure ### Data Center OpenCRVS should only be provisioned on servers located in an equivalent minimum of a [certified Tier 2 or 3 Datacenter](https://uptimeinstitute.com/tier-certification/tier-certification-list). Implementers should refer to the β€œUptime Institute” design documents for specific requirements associated with Tier 2 & 3 certification. At a high-level, the datacenter should have: * Uninterrupted power supply with independent, backup power generation * Air conditioning * 24/7 security access for authorised technical staff only * Automatic server backup off-site * Failsafe internet connectivity * Security policies and procedures in place * Network administrator staff capable of configuring and maintaining a scalable VPN solution We appreciate that connectivity is a challenge in many countries where we work. The data centre should have **an absolute minimum of a 10Mbps internet connection** to the servers otherwise deploying to the servers will be unworkable. ### Server environments Before proceeding to discuss server specifications, it is important to understand the following server environment glossary that we will be referring to in our example countryconfig reference implementation and further sections. | Environment | Description | Authentication | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **production** | A live environment containing citizen data e.g: personally identifiable information (PII). | 2FA codes generated for production user access | | **staging** (pre-production / mirror) | A mirror of a live environment, used for final Quality Assurance of a production deployment containing a daily restored backup of citizen data (PII) from the previous day. | 2FA codes generated for production user access | | **qa** | A quality assurance environment for tester, trainer & developer use supporting the Quality Assurance of releases, training staff. | Test 2FA codes of 6 zeros allow test user access. | | **backup** | A low specification environment that simply stores encrypted backups from production for long term recovery. | Not applicable. OpenCRVS software does not run on this environment. | | **development** | An environment you can use for training and development purposes only. NOT FOR PRODUCTION USE!! | Test 2FA codes of 6 zeros allow test user access. | Before proceeding to discuss network specifications, it is important to understand the following other concepts: * **vpn:** All servers must be protected behind a government virtual private network (VPN). [*Learn why a VPN is important.*](https://documentation.opencrvs.org/technical/guides/installation/advanced-topics/why-vpn) Users must authenticate via the VPN to access OpenCRVS in a browser. The country should provide and operate the VPN. When using self-hosted GitHub Actions runners, place those runners inside the VPN or on the internal network so they can reach servers directly; no VPN tunnel from GitHub-hosted services is required. * **Continuous provisioning & deployment via GitHub Actions:** OpenCRVS provides GitHub Actions workflows for automated provisioning and deployment. A GitHub organisation is required. Self-hosted runners deployed within your VPN/internal network (recommended). * **bastion** or **jump:** An optional bastion (jump) host can consolidate and control SSH access to servers behind the VPN without distributing VPN credentials. Bastions are useful for administrative SSH access, auditing and as an alternative deployment hop even when using self-hosted runners inside the VPN. ### Server specifications Refer to these minimum server specifications for the above environments. Note that the hard-disk space specifications are illustrative. Depending on the population size, number of records to migrate and number of supporting documents that are required to be captured during civil registration business processes, you may require more RAM / disk-space. These are **absolute minimum specifications**. Regardless your system administrators must be capable of monitoring and increasing server disk-space on demand. : ### Minimum server specifications | Environment (use) | Minimum specification | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | development (learning / proof-of-concept) / qa | 16 GB RAM Β· 4 vCPU Β· 320 GB disk Β· Ubuntu 24.04 LTS x64 (headless) | | production / staging | 32 GB RAM Β· 8 vCPU Β· disk space calculated using formula above Β· Ubuntu 24.04 LTS x64 (headless) | | backup | 1 GB RAM Β· 2 vCPU Β· disk space calculated using formula above (recommend 2Γ— application server size) Β· Ubuntu 24.04 LTS x64 (headless) | Notes: * Disk-space values are minimums and illustrative; adjust based on population, attachments and retention needs. * Ensure administrators can monitor and expand disk capacity on demand. * Production clusters should follow recommendations in the "Server clusters by project" section for HA and scalability. ### Ubuntu version First, login as root, or if you only have sudoer access, do `sudo -i`. ``` riku@farajaland-prod:~$ lsb_release -a No LSB modules are available. Distributor ID: Ubuntu Description: Ubuntu 24.04 LTS Release: 24.04 ... ``` If you are not using the correct version of Ubuntu, either recreate the server or upgrade Ubuntu. ### Production / staging / backup disk space requirements {% hint style="info" %} Calculated disk space doesn't include space for monitoring and logs. Please check "Monitoring disk space requirements" for more details. {% endhint %} Required disk space for production, staging and backup environments is calculated using the expected number of records per year and the estimated average number of attachments. The number of participating locations should be taken into account. Please use the following formula:\ \ \&#xNAN;*attachments\_per\_year = number of births, deaths.. records per year \* average number of attachments \* 0.4MB* *record\_data\_per\_year = number of births, deaths.. records per year \* 18.33kB*\ \&#xNAN;*operating\_system\_requirements = 100GB* *minimum\_required\_disk\_space = operating\_system\_requirements + record\_data\_per\_year + attachments\_per\_year* Using an average size country with population of 30M, crude birth rate of 17.299 births per 1000 people and crude death rate of 7.7 per 1000 we can calculate an estimate of records submitted every year\ \ Births per year: 518 970 Deaths per year: 231 000 Number of records per year: 749 970 per year Choosing an average number of attachments of 3 we can calculate the total space needed per year Attachments: 749 970 \* 3 \* 0.4 = 899 964 MB or 899 GB Record data: 749 970 \* 18.33 = 13 746 950 kB or 13.74 GB Combining that with the minimum disk space reserved for the system, we conclude the minimum required disk space for application servers in this example is 1012.47 GB. For backup servers, we recommend storage size twice the size of application servers so in this case 2024.94 Gb. Work is ongoing in OpenCRVS to optimise storage in future versions. ### Monitoring disk space requirements In default configuration monitoring data is stored for 30 days. Monitoring data size depends on filebeat configuration (scrape frequency, collected metrics, labels, tags). OpenCRVS is using custom filebeat configuration file, optimised to store only valuable data. Average disk size for monitoring data is 200Mb host/day. In general value can be calculated by formula: ``` Total space = 200Mb * * + 1Gb * ``` * `200Mb`: disk size per day * `days`: number of days to store logs * `hosts`: number of hosts to store logs * `1Gb`: is minimal extra-space for each VM For single VM at least 7Gb of additional disk space is needed to store monitoring data for 30 days: ``` Total space = 200Mb * 30 * 1 + 1Gb * 1 = 7Gb ``` For Kubernetes cluster with 2 VMs at least 14Gb of additional disk space will be needed: ``` Total space = 200Mb * 30 * 2 + 1Gb * 2 = 14Gb ``` If scrape frequency, collected metrics, labels, tags were adjust then make sure disk size per day value is up to date. ### Logging disk space requirements Logging data is stored as Elasticsearch index and can be accessed any time in Kibana. Logging data is generated by few different sources: * Elastic APM agents installed within critical OpenCRVS components * OpenCRVS application and datastores logs * Operating system logs By default OpenCRVS monitoring helm chart is configured to store data for 1 week only. There is no way to estimate logging data usage, but it's recommended to keep at least 10Gb of disk space for logs. ### Disk layout requirements By default OpenCRVS stores citizens records, monitoring and logging in `/data` folder. There are few options available to define disk partitioning: * **Single disk partition**: disk partition mounted as `/` has sufficient space to store all data produced by OpenCRVS. At provision time `/data` folder is created by ansible scripts. * **Single disk partition with encryption**: same as previous, with encryption enabled OpenCRVS will create encrypted file on disk `/cryptfs_file_sparse.img`, allocate proper file size and mount file as `/data` partition. {% hint style="warning" %} If your datacentre is physically secure we do not recommend encryption. If your data cerntre is insecure and you wish to enable encryption, pay close attention to the **optional disk encryption for lower security data centres section below** {% endhint %} * **Dedicated disk partition for data**: System administrator may decide to use dedicated disk partition (e/g LVM, NAS) to store citizens data. * **Other layouts** are possible, but not supported by OpenCRVS installation scripts. OpenCRVS Dependencies helm chart allows to define other ways to store files by using Kubernetes storage classes. **Verify the disk has been partitioned correctly** We want to ensure the partition mounted to / has enough disk space. OpenCRVS citizen data will be stored in the following location: ``` /data ``` Here is example of disk layout: ``` root@yourserver:~$ df -h Filesystem Size Used Avail Use% Mounted on /dev/vda1 311G 32G 280G 67% / /dev/vda15 105M 6.1M 99M 6% /boot/efi ``` This server has 280GB available after the operating system has been deployed. You should set aside a further 50-75GB for Docker images. So only 205GB - 230GB is available. It is important to remember this value if you plan to configure disk encryption. **Regarding optional disk encryption for lower security data centres** {% hint style="info" %} Only use encryption if your data centre is equivalent to a Tier 2 or lower, where physical security may not be at its optimum. If your data centre tier is higher, and extremely secure, there should be no need to encrypt the disk. {% endhint %} To use 200GB, you would enter "200g" when prompted. It is optional to LUKS encrypt this location so that your data is encrypted at rest. You will be asked if you wish to encrypt and how much server space you should apply to the encrypted disk. The secret ENCRYPTION\_KEY is used on reboot to decrypt and mount this folder. To take advantage of this feature, amend the location of the key to a secure location in `infrastructure/server_setup/group_vars/all.yml`: ```yaml # Disk Encryption key location as an example (in production use a hardware security module) disk_encryption_key_path: /root/disk-encryption-key.txt ``` {% hint style="success" %} All the secrets are explained in more detail in the section [Environment secrets and variables explained.](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/create-a-github-environment/environment-secrets-and-variables-explained) {% endhint %} ### Server clusters by project The number of servers required in a load balanced cluster is configurable depending on the project and population size. Please take note of these recommendations. #### Proof-of-concept (P.O.C.) For a proof-of-concept (P.O.C.) of OpenCRVS, we use 1 **qa** server with **no backup**, operating under the condition that no live citizen data is captured during a P.O.C: **qa** x 1 #### Pilot A total of 4 servers are required for pilot implementations that capture citizen data. One for each environment: **qa** x 1, **production** x 1, **staging** x 1 & **backup** x 1. #### National scale For national scale implementations, we recommend deploying to a production server cluster of 2 - 5 production servers depending on population size. {% hint style="warning" %} It is recommended to deploy the production environment on a cluster of at least 2 servers. This ensures high availability and prevents downtime or data loss in the event of a server failure. {% endhint %} | Population size | Servers required | | --------------- | ---------------------------------------------------------------- | | < 30M | **qa** x 1, **production** x 2, **staging** x 1 & **backup** x 1 | | 30M - 60M | **qa** x 1, **production** x 3, **staging** x 1 & **backup** x 1 | | 60M+ | **qa** x 1, **production** x 5, **staging** x 1 & **backup** x 1 | ### Network Refer to the following network diagram as a reference example of how to network your server cluster.
### Server administrator SSH access & permissions: During provisioning, the server administrator requires SSH access through the provided VPN to all servers with **sudo** permissions. During installation of OpenCRVS, SSH config to all servers will be modified, blocking password based SSH authentication, root user access, configuring 2FA authentication and alerting for all future SSH access. Once provisioned, there should be no need for technical staff to ever SSH into a server during day-to-day operations. Every SSH access going forward is audited via a Slack notification to all technical staff thanks to these provisioned alerts. ### User access The following users will access 3 of the environments: **qa**, **production** & **staging**, via a VPN client: 1. Existing Civil Registration staff that access the OpenCRVS client using the Chrome browser on desktops/laptops/mobile devices. 2. 3rd party approved government staff (e.g. Healthcare staff in hospitals) that access the OpenCRVS client using the Chrome browser on desktops/mobile devices. 3. Your development and QA team that access the OpenCRVS client using the Chrome browser on desktops/laptops/mobile devices. 4. Potential future automated integrations from approved healthcare services using our [APIs](https://documentation.opencrvs.org/technology/interoperability/event-notification-clients) with VPN access 5. Potential future automated integrations external gov services using our [APIs](https://documentation.opencrvs.org/technology/interoperability/event-notification-clients) with VPN access 6. Automated continuous deployment scripts from a private Github code repository. {% hint style="info" %} All user workstations / tablets / smartphones and integrating APIs will require compatible VPN clients and accounts. {% endhint %} ### Egress (outbound) internet access In addition to serving user traffic the OpenCRVS infrastructure needs to be able to communicate outbound. This egress traffic includes things like pulling in latest updates, monitoring and emails. Check that the servers have internet connectivity. The servers must be able to access Dockerhub, Sentry and other internet services such as Ubuntu update repositories, Email & SMS apis for example. Therefore check if you can ping google.com from inside the servers. If your VPN requires a whitelist of allowed domains, the following are the known domains which the servers require access to: ``` archive.ubuntu.com changelogs.ubuntu.com hub.docker.com auth.docker.io registry-1.docker.io download.docker.com sentry.io fonts.gstatic.com storage.googleapis.com fonts.googleapis.com github.com acme-v02.api.letsencrypt.org (if using LetsEncrypt TLS certs) registry.npmjs.org registry.yarnpkg.com eu.ui-avatars.com ... Other domains may be required depending on your configuration ``` ### Email (SMTP) server You must have a working SMTP server and SMTP user details to deploy OpenCRVS. Staff onboarding and monitoring requires an Email service. Following variables are required to successfully deploy OpenCRVS on server environment * `SMTP_HOST`: Hostname or IP address of your smtp server * `SMTP_PORT`: Port where smtp server is listening * `SMTP_SECURE`: Use TLS for connection * `SMTP_USERNAME`: Username or email used to authenticate as a email client on smtp server * `SMTP_PASSWORD`: Password or API token depend on your email provider * `SENDER_EMAIL_ADDRESS`: All emails will be send with this email in sender field * `ALERT_EMAIL`: Email address for alerting, this field is often used to integrate with Slack, Google Chart or any other corporate communication tool. # Configure DNS #### Setup Domain A records Using your domain management system, A records will need to be created for all the services which are publicly exposed for **qa, production & staging** environments. Either use a wildcard or create individual A records for your chosen environment's domain name, with a TTL of 1 hour that forwards the URL to your **manager server node's** external IP address. **Option 1: Wildcard required A Records:** {% hint style="info" %} A total of 6 A Records are required for this option, 2 for each environment's domain: **qa, production & staging** {% endhint %} *\* *\*.\* **Option 2: Individual A Records:** {% hint style="info" %} A total of 27 A Records are required for this option, 9 for each environment's domain: **qa, production & staging** {% endhint %} *\* *countryconfig.\* *metabase.\* *minio.\* *minio-console.\* *gateway.\* *kibana.\* *login.\* *register.\* # Issue SSL Certificates There are a number of ways you can configure TLS / SSL certificates for OpenCRVS. The options are explained in detail in the [Advance topics > TLS/SSL Configuration for traefik](/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik) section. All methods must be compatible with [Traefik](https://doc.traefik.io/traefik/https/overview/). At a high-level, here is a brief intro to the subject. **Free LetsEncrypt certificates** A free approach is to use LetsEncrypt. However LetsEncrypt certificates must validate and refresh every 3 months. {% hint style="info" %} The OpenCRVS installation script will automatically configure Traefik to obtain and use dynamic Let's Encrypt SSL certificates for you that automatically refresh. **This automated option is available for testing and demonstration purposes, and not for production environments.** The server must be accessible from the public internet for this automated process to work. Therefore, as the server is not behind a VPN, the approach isnt suitable in production. {% endhint %} When installing OpenCRVS behind a VPN, **required for production and staging environments**, it's technically possible to create and refresh static LetsEncrypt certs every 3 months, with different approaches for certifcate validation via your DNS server. For more information see official documentation **Purchasing long term certificates** Most government networks require you to purchase or use a long term SSL certificate per environment, and manually replacing the static .crt & .key files every 1, 2 or 3 years depending on it's lifetime. Some governments have their own public key infrastructure to issue these static certs. The SSL certificates that you obtain must support the [DNS](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/configure-dns) subdomains for each environment's individual domain: **qa, production & staging.** You may opt for a single, wildcard SSL certificate for each domain. **Technical guide** For detailed technical guidance on how to configure the various options in helm charts read [Advance topics > TLS/SSL Configuration for traefik](/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik) # Create prerequisite accounts and repositories ### 1. Ongoing costs of additional services OpenCRVS is hardcoded to use the following 3rd party services which require subscriptions. The cost of these services is negligible, industry standard and promotes best practice developer operations experience. 1. A docker container registry [**organisation**](https://docs.docker.com/admin/organization/orgs/) account on [Dockerhub](https://hub.docker.com/) for hosting OpenCRVS Country config images. 2. An organisation Github account in a minimum of a ["Team"](https://github.com/pricing) plan to configure automated provisioning and CI/CD for the require repositories explained below. 3. System alerts can be broadcast to an email address. It's usually important that alert notifications are not silo-ed to a single individual for auditing purposes, therefore it is optional, but recommended to have a team messaging system such as Slack to receive these notifications: A Slack Pro account 4. Application bug reports can be delivered to a [Sentry](https://sentry.io/welcome/) Team account. A free plan is fine for development / proof-of-concept, or if you are less worried about report volume and longevity. 5. Critical server secrets and passwords are created when initialising an environment and creating National System Admin users. A password manager such as 1Password Team or Bitwarden Team is an industry standard location to store such secrets safely, providing sufficient governance. ### 2. Set up an individual and an organisation account on Dockerhub {% hint style="info" %} A DockerHub account is required as the registry for the countryconfig docker image. {% endhint %} You will need your DockerHub **username** and a personal DockerHub account **access tokens** as secrets. Our scripts use these credentials to login to DockerHub programmatically. This is how you create a DockerHub access token: ### 3. Create companion service accounts for monitoring and notifications {% hint style="info" %} This step is optional, but recommended {% endhint %} Our code includes optional integration with [Sentry](https://www.sentry.io) for error tracking. To take advantage, create a NodeJS project in Sentry for the environment you want to monitor. In the Sentry project settings, select "Client Keys", and **copy the DSN property**. You will use this as the `SENTRY_DSN` secret later. Any service error whether caught or uncaught will be visible in application logs that you can monitor in Kibana. Any hardware alert will be broadcast via elastalert to an email account configured using the `ALERT_EMAIL` environment secret. If you wish to collate service and hardware errors into a single location you can configure Sentry Alert Rules and email forwarding from `ALERT_EMAIL` to the same location, such as a Slack or GChat Channel via an email re-direct. The benefits of using a shared messaging platform like Slack, are that your entire development and quality assurance team can receive these notifications without a single individual becoming a bottleneck. Notifications are sent by email by default, so you should configure SMTP settings. The `SENDER_EMAIL_ADDRESS` environment secret stores the email address used as the sender for automated system emails. Notification gateways via SMS or other platform such as WhatsApp are configurable in countryconfig code. ### 4. Enforce two-factor authentication and PR approvals on your GitHub organisation The GitHub organisation hosting your opencrvs-countryconfig fork holds the keys to your production deployment: CI/CD workflows, environment secrets, infrastructure-as-code, and the ability to deploy. Treat compromise of a single member account as compromise of your production environment, and apply organisation-level controls accordingly. #### 4.1 Require two-factor authentication for every member Enable organisation-wide 2FA enforcement so that no member, outside collaborator, or owner can access the org without a second factor. Existing members who do not have 2FA configured will be removed when enforcement is enabled, so plan a short grace period and notify the team first. GitHub's documentation: [Requiring two-factor authentication in your organization](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). #### 4.2 Require reviewed pull requests on protected branches Configure a branch protection rule (or repository ruleset) on the default branch β€” typically main β€” and on any branch used to deploy to a production environment, with at least the following: * Require a pull request before merging β€” direct pushes to the protected branch are disallowed. * Require at least 2 approving reviews from organisation members before a PR can be merged. * Require status checks to pass before merging β€” at minimum the CI test suite. GitHub's documentation: [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) and [Managing rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). # Create a Github environment #### Before you begin In this section you will run the `yarn environment:init` script in **your forked infrastructure repository** which will help you to configure OpenCRVS environments. This command: * Creates GitHub environments * Drafts commands to bootstrap new servers * Prepare inventory files for ansible for environment provision * Prepares Helm chart values for deployment GitHub environments will host all secrets and variables required for successful infrastructure configuration (users, filesystem, kubernetes cluster, etc) and OpenCRVS deployment. Make sure you completed environment preparation steps and have all required information: | Property | Description | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GitHub Organisation | Own GitHub organisation with Team subscription. | | Country config repository | Refer to [Quick Start](/technical/guides/installation/quick-start) | | Virtual machines (servers) created | [Preparation steps: ](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps)Verify you have IP addresses or DNS names for each environment and you are able to login on those VMs | | Domain names are registered | Verify [DNS](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/configure-dns) names are pointed to appropriate IP addresses of VMs. | | SSL Certificates issued or one of the available Let’s Encrypt is considered to be used | [Advanced Topics > TLS/SSL Config for Traefik](/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik) | | Infrastructure repository forked | Refer to [Quick Start](/technical/guides/installation/quick-start) | | GitHub Token with full code access and workflow permissions created | Personal access token (Fine grained token) with access to Country config and Infrastructure repositories. Refer to [Quick Start](/technical/guides/installation/quick-start) | | DockerHub Account, token and repository are created | Make sure Country config image was built and pushed to DockerHub | | Users with their public keys to grant remote access to the servers | Refer to [Advanced Topics > SSH access](/technical/guides/installation/advanced-topics/ssh-access) | | SMTP server configured | Refer to [Setup Infrastructure](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/setup-infrastructure) | | Optionally Third-party accounts created (sentry, slack, etc) | Refer to [prerequisite accounts](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/create-prerequisite-accounts-and-repositories) | ### Create github environments Environments are managed by `yarn environment:init` script. The script will create files that must be pushed to Git, so it is **advisable to run the script in a new branch in order to open a pull request.** Re-run script for each environment: * development and (or) qa * staging * production {% hint style="info" %} *Migrating from an earlier version? ... Read the* [*Migration from Docker swarm guide.*](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/migration-from-docker-swarm-guide) Configuring a **staging** or **prodution** Github environment requires you to have a **backup server** environment in place. No explicit **backup** *Github* environment is created by this script anymore as of OpenCRVS v2.0. {% endhint %} To run the script, open terminal window and cd into your **forked infrastructure repository** and run the following command to start the configuration wizard: 
yarn install
yarn environment:init
{% hint style="info" icon="triangle-exclamation" %} You may notice that the same commands exist in an **infrastructure** folder in **forked countryconfig repo** but these exist only for backwards compatibility, e.g. OpenCRVS v1.8 or below and **should no longer be used**. Older installations should follow the [*Migration from Docker swarm guide*](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/migration-from-docker-swarm-guide) {% endhint %} You will be asked to provide values to configure key OpenCRVS components. Some actions can be automated and the script will guide you to the next steps. ### Environments init script questions #### Intro questions **Purpose for the environment?** The script will ask you to select the type of environment that you wish to create: ``` ? Choose a name and purpose for the environment? ❯ Development Quality assurance (no PII data) Staging (hosts PII data, no backups) Production (hosts PII data, requires frequent backups) Other... ``` Depending on your anwer different logic will be executed and some features might be not available. For example Approval workflow work only on environments with PII data. **What is the name of your environment?** Environment name is used later to create Kubernetes namespaces and other configuration objects like backup and restore folders. Environment name is read only property. We recommend you use following pre-configured environment names: * development * qa * staging * production #### GitHub **What is the name of your Github organisation?** Type your organisation. *Note that for personal repositories organisation is your GitHub login.* **What is your Github infrastructure repository?** Repository name where your infrastructure code lives. **What is your Github token?** Classic or Fine-grained token with access to infrastructure workflows and code. Once you provide answers to the questions script will connect GitHub: * If environment doesn't exist, script will continue it's execution

GitHub environment doesn't exist

* If environment exists, script will fetch information about existing secrets and variables for particular environment and repository.

GitHub environment already exists

* The script will fail if it cannot connect to Github for whatever reason. For environments with PII data script will ask you to answer additional questions: * `GH_APPROVERS`: Comma separated list of GitHub accounts responsible for Reviews and Approvals on OpenCRVS GitHub Actions workflows. This variable is defined at repository level. * `APPROVAL_REQUIRED`: Require approval for particular environment. This variable is defined at environment level. **It is strongly recommended to Approval requirement in production environments to mitigate the risk of accidental deployments or environment resets, which may lead to the deletion of citizen data.**

Configure production environment with required approval

#### Docker Hub The script will ask for your Dockerhub credentials or skip if they already exist. GitHub doesn't allow you to fetch secret values so you will not be able to check the current value, only updating the value is possible.

DockerHub credentials were created earlier

#### Kubernetes & Runtime The script will ask you to provide Kubernetes and Runtime options: * `DOMAIN`: Domain name to expose the OpenCRVS application frontend and APIs. It will be the domain after the subdomains that you configured when setting DNS. * `KUBE_API_HOST`: IP address or domain address for the Kubernetes master node. Provision script will generate Kubernetes config files for each user defined in users section of inventory file. Leave empty to use the default address of the provisioned master node. * `KUBE_API_ALLOWED_CIDRS` : Comma-separated list of CIDR ranges allowed to access the Kubernetes API. Default: `KUBE_API_HOST` (Allow connections from master node only). * `KUBE_WORKER_NODES`: Comma separated list of additional Kubernetes cluster members (Virtual Machines). Leave empty for a single node setup. Worker nodes can be added later. Default: no worker nodes. {% hint style="info" %} The values of `KUBE_API_HOST` , `KUBE_API_ALLOWED_CIDRS` and `KUBE_WORKER_NODES` are used to generate the firewall configuration during provisioning, check [Ubuntu Firewall configuration](/technical/guides/installation/advanced-topics/ubuntu-firewall-configuration) {% endhint %}

On screenshot access to Kubernetes API is limited to master node only.

#### SSH Users Script will ask you to create users with remote SSH access, answer following questions: * User name: Remote user name to login * Public ssh keys: Add public key(s) for remote login. Login by password is disabled by default, keys must be provided * Role: User role on remote system Check documentation for more examples and detailed instructions how to manage remote access: [Advanced topics > SSH Access](/technical/guides/installation/advanced-topics/ssh-access) Once all the users are added, select **"Save & Exit"** in order to continue with the script.
#### Traefik SSL Certificate Installation script does configuration for traefik helm deployment. Following options are available at configuration time: 1. **Lets Encrypt certificate:** No additional input is required. The installation script will automatically configure Traefik to obtain and use Let’s Encrypt SSL certificates for you.\ **NOTE:** Your server must be accessible from the public internet for this process to work.\ This option is recommended only for testing and demonstration purposes, not for production environments. 2. **Static SSL certificate:** The script will prompt you to provide an SSL certificate and key for the frontend. The provided values will be securely stored as GitHub secrets. 3. **Custom configuration:** No additional questions will be asked. A preconfigured file (without the Let’s Encrypt section) is used, and Traefik will use its default certificate. Choose this option if you plan to configure Traefik yourself later using Helm chart values. Questions for **Static SSL certificate** * `SSL_CRT`: SSL Certificate or Certificate chain * `SSL_KEY`: SSL Certificate private keys Full documentation about traefik configuration can be found at: * Official documentation page: * [Advanced Topics > TLS/SSL Configuration for Traefik](/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik) #### Storage {% hint style="info" %} **Only enable disk encryption if your data centre is equivalent to a Tier 2 or lower, where physical security may not be at its optimum.** If your data centre tier is higher, and extremely secure, there should be no need to encrypt the disk. **It is vital to safely store the encryption key** that is generated by the script to avoid loss of data. **Losing the encryption password is not recoverable.** {% endhint %} Disk Encryption: If disk encryption is enabled, provision GitHub Actions workflow will create encrypted file in the root (`/`) directory and mount it as `/data`. Disk encryption is optional. **Disk encryption can't be enabled later.** * `DISK_SPACE`: Amount of disk space that should be dedicated to OpenCRVS data (logs, monitoring and citizens crvs records). Specified value will become the size of an encrypted cryptfs `/data` directory. Specified disk space will be allocated on each cluster node for multi-node kubernetes cluster and this behaviour may change in the future. #### Backup Its possible for this environment to back up its data to another server e.g. backup every night. **It is strongly recommended if you are provisioning a production environment to enable backup.** * `BACKUP_HOST`: Backup server IP address or hostname. * `BACKUP_SERVER_USER`: User to connect to backup server. At this point you may choose any username, provision script will create user for you. E/g If you would like to use shared server to store backups from qa and production, you may want to have separate users for security reasons. Script will add backup host to ansible inventory files and configure appropriate values for helm release. Script will create private/public key-pair for backup server user. By default backup is configured to run at 01:00 AM by UTC, if you need to adjust backup schedule, update configuration manually at `environments//dependencies/values.yaml`

Backup configuration

More information about backup server configuration can be found at [Backup and Restore](https://github.com/opencrvs/documentation/tree/master/v2.0.0/setup/3.-installation/4.4-opencrvs-maintenance-tasks/4.3.7-backup-and-restore) section. #### Restore Its possible for this environment to restore backed-up data from another environment every night. **It is strongly recommended if you are provisioning a staging (pre-prod/mirror) environment to enable restore.** Restore configuration will ask you to provide the restore environment name from the existing environment list. **If the environment doesn't exist and will be created later, feel free to type future environment name here, but don't forget to create that environment BEFORE running OpenCRVS** [**dependencies**](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/deploy/running-a-dependencies-deployment) **deployment.** By default restore is configured to run at 00:00 AM by UTC, if you need to adjust the restore schedule, update configuration manually at `environments//dependencies/values.yaml`

Restore configuration

#### Databases & monitoring The script will proceed to ask you to set database and monitoring passwords. Strong passwords are suggested. It is advisable to accept the defaults presented to you. * `KIBANA_USERNAME`: (Default: opencrvs-admin): Kibana user name * `KIBANA_PASSWORD`: (Default: random value): Kibana password

Database and monitoring sections. In this example disk encryption is already enabled

#### Sentry `SENTRY_DSN`: The DSN tells the SDK where to send bug events to. OpenCRVS application has built-in Sentry support.
#### Metabase admin Metabase provides a public web interface to access an analytics editor. * `OPENCRVS_METABASE_ADMIN_EMAIL`: Metabase Admin user (only emails are allowed) * `OPENCRVS_METABASE_ADMIN_PASSWORD`: Metabase Admin password

Metabase configuratiob section

#### SMTP At this point smtp server should be configured. If you are using third-party email providers like Sendgrid, please make sure that your OpenCRVS domain is in whitelist and issued credentials are correct. * `SMTP_HOST`: Hostname or IP address of your smtp server * `SMTP_PORT`: Port where smtp server is listening * `SMTP_SECURE`: Use TLS for connection * `SMTP_USERNAME`: Username or email used to authenticate as a email client on smtp server * `SMTP_PASSWORD`: Password or API token depend on your email provider * `SENDER_EMAIL_ADDRESS`: All emails will be sent with this email in sender field * `ALERT_EMAIL`: Email address for alerting, this field is often used to integrate with Slack, Google Chart or any other corporate communication tool.

Email configuration

#### Review step Once all questions are answered, the script will generate strong database passwords for all the database technologies used in OpenCRVS. It will display all the secrets that the script will create and ask you if you want to continue to create the environment on Github. The script will slowly create the Github environment and upload all the secrets OpenCRVS requires to provision and deploy OpenCRVS from Github Actions. It will create Helm chart and values files ready for committing to your repository. On the final step the script will provide a command to bootstrap a self-hosted runner on your server. **Save the command from script output to a temporal file, you will need it later**. This is explained in the section [Bootstrap servers](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/bootstrap-servers): {% code title="Bootstrap command is automatically created ... " %} ``` curl -sfL https://raw.githubusercontent.com/opencrvs/infrastructure/refs/heads/develop/scripts/bootstrap/opencrvs-bootstrap.sh \ -o opencrvs-bootstrap.sh && \ bash opencrvs-bootstrap.sh --owner opencrvs \ --repo my-custom-infrastructure \ --env qa \ --token gh_PARSONAL_ACCESS_TOKEN \ --enable-runner ``` {% endcode %}

Command to bootstrap self-hosted runner on newly created virtual machine. Script will provide additional commands and hints for multi-node Kubernetes cluster and for configuration with backup server

Run following command on your infrastructure repository: ``` git status ``` You should get a number of files modified: ``` Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git restore ..." to discard changes in working directory) modified: .github/workflows/deploy-dependencies.yml modified: .github/workflows/deploy-opencrvs.yml modified: .github/workflows/github-to-k8s-sync-env.yml modified: .github/workflows/k8s-reindex.yml modified: .github/workflows/k8s-reset-data.yml modified: .github/workflows/k8s-seed-data.yml modified: .github/workflows/provision.yml modified: .github/workflows/reset-2fa.yml Untracked files: (use "git add ..." to include in what will be committed) environments/development/ infrastructure/server-setup/inventory/development.yml ``` Usually review is not required for files under the `.github` folder. Review modified files: * `infrastructure/server-setup/inventory/.yml`: Configuration file for Ansible playbook responsible for server provision. For more information please follow hints inside file and [SSH Access](/technical/guides/installation/advanced-topics/ssh-access) section. * `environments/`: Folder with `values,yaml` files for helm charts: * `environments//traefik/values.yaml`: Update this file with proper configuration to handle SSL certificate. Please follow documentation under [TLS / SSL & DNS](/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik) * `environments//opencrvs-services/values.yaml`: Review configuration and adjust according to your needs, **usually defaults are good for initial deployment** * `environments//dependencies/values.yaml`: Review configuration and adjust according to your needs, **usually defaults are good for initial deployment**. ### Final notice {% hint style="danger" %} The later [provision](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/provisioning-servers) script will disable password SSH access for all users on the server and create new users from the `infrastructure/server-setup/inventory/.yml` file. After provisioning, SSH will only be possible using public/private key pairs. {% endhint %} {% hint style="success" %} Users will be required to use Google Authenticator to SSH in after [provisioning](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/provisioning-servers). This 2FA approach is an important step to secure your infrastructure. {% endhint %} {% hint style="danger" %} If any user is utilising the 1000 group, the script will fail. Modify your available user groups on the server to ensure this one is available. {% endhint %} {% hint style="danger" %} The .env.\ file outputted by this script contains sensitive information about your environment configuration. Copy the content of this file into a secure place or password manager such as [Bitwarden](https://bitwarden.com/) or [1Password](https://1password.com/) and delete this file. **YOU MUST NEVER SHARE THIS FILE, NOR COMMIT IT TO GIT!!!** This file is not required by OpenCRVS. {% endhint %} You will notice that an environment now exists in your Github repo containing all the secrets required. {% hint style="info" %} If you made a mistake and wish to run the script for this environment again, you must delete the environment on Github by clicking the trash icon first. **The environment and all secrets will be deleted and recreated, enforcing you to start over.** {% endhint %} **Repeat the process for all your required environments, e.g. qa, production, staging ...** Once all environments are setup, feel free to continue. # Approval Process for Production Environments To provide System Administrators and DevOps teams with an additional layer of protection against human error and unauthorized access, an approval process should be configured for production environments. The list of individuals eligible to approve GitHub workflows is defined by the repository-level variable `GH_APPROVERS`. Each approver must be a valid GitHub account holder and added as a collaborator to the infrastructure repository. Approval can be enabled for specific environments by setting the `APPROVAL_REQUIRED` variable to `true`. It is strongly recommended to enforce this requirement in production environments to mitigate the risk of accidental deployments or environment resets, which may lead to the deletion of citizen data. The infrastructure repository should have issues enabled to facilitate the approval process. **Workflow execution** As demonstrated in the screenshot below, when approval is enabled for an environment, workflow execution will be paused. An issue will be automatically created within the infrastructure repository, and a link to this issue will appear in the workflow log.
The GitHub issue will contain a detailed description outlining exactly what needs approval. Once the necessary approvals have been received, the workflow execution will resume.
{% hint style="danger" %} For workflows that involve cleaning up environments and potentially wiping all citizen data, at least three approvals are required. This ensures that a minimum of three team members review and approve such critical actions. {% endhint %} # Environment secrets and variables explained #### **Global repository secrets**
ParameterDescription
DOCKER_USERNAME

Your Dockerhub username to access the container registry. If you are using a different container registry, you will need to manually edit the deploy.yml at OpenCRVS Countryconfig repository appropriately.

NOTE: Dockerhub is used to store only OpenCRVS Countryconfig docker images. All Core images are stored in GitHub Packages

DOCKER_TOKENYour Dockerhub access token.
DOCKERHUB_ACCOUNTThe name of your Dockerhub account or organisation that forms the URL to your country config docker image on Dockerhub before the slash. e.g: opencrvs
DOCKERHUB_REPOThe name of your Dockerhub repository that forms the URL to your country config docker image on Dockerhub after the slash.. e.g. ocrvs-farajaland
GH_TOKENThe personal Github Token used in all Action runners.
GH_ENCRYPTION_PASSWORDUsing the Github Token, a password is created that allows automated actions to access the secrets from other environments. This occurs during provisioning so that the production, backup and staging environments use the same BACKUP_ENCRYPTION_PASSPHRASE.
#### **Global repository variables** | Variable | Description | | ------------- | -------------------------------------------------------------------------------- | | GH\_APPROVERS | List of valid GitHub accounts to approve deployments for particular environment. | #### **Environment secrets** | Secret | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ENCRYPTION\_KEY | A password used to LUKS encrypt the `/data` folder containing OpenCRVS data. | | ELASTICSEARCH\_SUPERUSER\_PASSWORD | The Elasticsearch superuser password. You can also use this to login to Kibana with the username "**elastic**" and you have superuser Elastic privileges. Kibana URL: \ | | KIBANA\_USERNAME | A username for a regular Kibana user to login and monitor OpenCRVS stack health. Useful for developers as this user will have no superuser privileges. | | KIBANA\_PASSWORD | A password for a regular Kibana user to login and monitor OpenCRVS stack health | | MONGODB\_ADMIN\_USER | The MongoDB superuser admin username. A powerful account that has all rights to OpenCRVS data | | MONGODB\_ADMIN\_PASSWORD | The MongoDB superuser admin password. | | MINIO\_ROOT\_USER | A username for a Minio superuser admin to login to the Minio console to view supporting document attachments submitted during registrations. \ | | MINIO\_ROOT\_PASSWORD | A password for a Minio superuser admin | | SMTP\_HOST | | | SMTP\_PORT | | | SMTP\_USERNAME | | | SMTP\_PASSWORD | | | SMTP\_SECURE | Whether or not your SMTP port requires TLS | | ALERT\_EMAIL | Email address or Slack channel address to send system technical alerts to. | | SENDER\_EMAIL\_ADDRESS | The sender email address that appears in all emails will need to be configured. | | OPENCRVS\_METABASE\_ADMIN\_EMAIL | Email address for metabase admin panel login | | OPENCRVS\_METABASE\_ADMIN\_PASSWORD | Password for metabase admin panel login | #### Environment variables | Variable | Description | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DOMAIN | The host **domain name** (without www!) for your environment. | | SELF\_HOSTED\_RUNNER\_ADDITIONAL\_LABELS | Additional labels for self-hosted runner, useful to deploy multiple OpenCRVS instances on shared Kubernetes cluster | | CONTENT\_SECURITY\_POLICY\_WILDCARD | This string is supplied to the clients and nginx config and ensures that the format of your domain above can be configurable for CORS purposes. | | ACTIVATE\_USERS | When users are seeded, are they immediately active using a test password and six zeros as a 2-Factor auth code. Always false in production and staging. | | AUTH\_HOST, CLIENT\_APP\_URL, COUNTRY\_CONFIG\_HOST, GATEWAY\_HOST, LOGIN\_URL | **DEPRECATED**: URLs passed to docker-compose to support internal micro-service communications. | | DISK\_SPACE | The amount of disk space set aside for encrypted PII data stored by OpenCRVS | | NOTIFICATION\_TRANSPORT | **DEPRECATED**: A prop which can be used to configure either Email or SMS for staff and beneficiary comms or potentially both. | | KUBE\_API\_HOST | Kubernetes API host domain name or IP address | | KUBE\_API\_ALLOWED\_CIDRS | Allowed CIDRs for Kubernetes API access. Access is not restricted by default | | KUBE\_CLUSTER\_NODE\_CIDR | Kubernetes cluster network CIDR, used to restrict communication between internal Kubernetes tools. No restriction by default | | WORKER\_NODES | Comma separated list of Kubernetes workers nodes, in case you are planning to setup Kubernetes cluster with multiple nodes. This property could be left empty for single node setup or you can add worker nodes later. | | APPROVAL\_REQUIRED | Make approval required for this particular environment. If set to true all GitHub workflows will ask for approval, otherwise approval process will be optional even with defined `GH_APPROVERS` list. **NOTE:** "Reset environment" workflow required 3 approvals to proceed, that additional requirement was made for security reasons. Single person is not able to take decision for environment reset. | #### **Optional environment secrets**
ParameterDescription
BACKUP_SERVER_USERUser used to upload backups, users home directory is used as default path for backup. Is used by Kubernetes backup jobs
BACKUP_ENCRYPTION_PASSPHRASEBackup encryption passphrase, used only if backup is enabled. This is the password that is used to encrypt all the backups that OpenCRVS creates from a production server and that are stored on the backup server. Use this passphrase to decrypt the backups.
BACKUP_HOST_PUBLIC_KEYssh public key for BACKUP_SERVER_USER , used to authenticate Kubernetes backup jobs on backup server
SENTRY_DSNOpenCRVS can report application errors to Sentry in order to help you debug any issues in production.
BACKUP_HOST_PRIVATE_KEYssh private key for BACKUP_SERVER_USER is used for authentication by Kubernetes backup jobs
#### **Optional environment variables** | Parameter | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | BACKUP\_HOST | Backup server, define this property if you would like to manage backup server as part of your environment. Check Backup and restore section for more information how to use configure backup server. Used by Kubernetes backup jobs | | BACKUP\_ENVIRONMENT\_MODE | Backup environment mode (full or differential). | | RESTORE\_ENVIRONMENT\_NAME | GitHub environment name used to configure restore on staging line environments. | | Parameter | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | BACKUP\_HOST | Backup server, define this property if you would like to manage backup server as part of your environment. Check Backup and restore section for more information how to use configure backup server. Used by kubernetes backup jobs | | BACKUP\_ENVIRONMENT\_MODE | Backup environment mode (full or differential). | | RESTORE\_ENVIRONMENT\_NAME | GitHub environment name used to configure restore on staging line environments. | # Bootstrap servers ## General information These are the steps you need to perform after receiving a server IP address and an SSH user before you can run the provisioning scripts for any given environment. E.G: **qa, backup, staging, production (1, 2, 3 or 5 server cluster).** Use command produced by create environment script (\`yarn environment:init) to bootstrap servers: * [#bootstrap-kubernetes-single-node-master-node](#bootstrap-kubernetes-single-node-master-node "mention") * [#bootstrap-kubernetes-worker-nodes-backup-server](#bootstrap-kubernetes-worker-nodes-backup-server "mention") ## Bootstrap Kubernetes single node / master node {% hint style="info" %} Use code snippet generated by the `yarn environment:init` script in the [Create a GitHub environment step](/technical/guides/installation/deploy-set-up-a-server-hosted-environment/create-a-github-environment) {% endhint %} 1. SSH into your server as a user with sudo access or as root 2. Run the following command on the VM: ```bash curl -sfL https://raw.githubusercontent.com/opencrvs/infrastructure/refs/heads/develop/scripts/bootstrap/opencrvs-bootstrap.sh \ -o opencrvs-bootstrap.sh && \ bash opencrvs-bootstrap.sh --owner \ --repo \ --env \ --token \ --enable-runner ``` {% hint style="info" %} The script will install a self-hosted Github runner and set up a user on your server called **provision**. At the end of this process the script will display that provision user's public SSH key, which you will need to use in the next step if you are setting up a backup integration (required for a PII - staging / production environment) or a cluster. Example output: ``` βœ… Runner 'prod-runner' is installed and started! ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ Store the following public key for later usage ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ βš™οΈ provision SSH key pair public key (add on worker nodes if needed): ssh-ed25519 AAAAC3NzaC....F5uYOPl+ provision@prod1 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ βœ… Node bootstrap complete for tmp-prod1. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` {% endhint %} **Checklist for script execution** 1. Verify `provision` user was created: ``` su - provision whoami ``` Example output: ``` provision$ whoami provision ``` 2. In your GitHub repository, navigate to **Settings β†’ Actions β†’ Runners** and verify that the runner appears as a self-hosted runner. ## Bootstrap Kubernetes worker nodes / backup server 1. SSH into your server as a user with sudo access or as root 2. Run following command to bootstrap server ``` curl -sfL https://raw.githubusercontent.com/opencrvs/infrastructure/refs/heads/develop/scripts/bootstrap/opencrvs-bootstrap.sh -o opencrvs-bootstrap.sh && \ bash opencrvs-bootstrap.sh --ssh-public-key "" ``` --- [Next Page](/llms-full.txt/1)