4.2.6.3 Configure certificate templates

⚠️ Important: Changes to Certificate Configuration in OpenCRVS 1.9

OpenCRVS v1.9 introduces a completely new certificate configuration framework.

Designed your certificate template? Once you have designed your certificate templates you are ready to configure the SVG. Please refer to our guidance on designing a certificate here: 3.5 Designing a certified copy

Step 1. Configuring certificate SVG files

The next step is for you to design and configure your certificate template SVG files. You can have as many different certificates as you like, represented as different SVG files, for each vital event.

From OpenCRVS v1.9 onwards, you use $lookup object syntax to mark where in the SVG you wish the citizen data to be rendered from the available $declaration prop using form field ids to access variables and $metadata properties related to the EventMetadata.

Other helper functions and props are available to you within your certificates, such as:

# Variables & functions

## Available top-level variables

- `$state`: Event record in it's current state
- `$declaration`: Raw declaration data
- review: used to show that the certificate is in a preview state before printing so you can render a pre-printed watermark, common in official certificate paper stock

## Available top-level functions

### `$lookup`
Used for direct property lookup within objects.
- `$lookup $state "modifiedAt"`
- `$lookup $state "updatedAtLocation"`
- `$lookup $state "createdAtLocation"`
- `$lookup $state "assignedTo"`
- `$lookup $declaration "child.firstname"`
- `$lookup $declaration "child.surname"`
- `$lookup $declaration "child.gender"`

### `$intl`
Looks up i18n translation strings.
- `$intl 'constants' ($lookup $declaration "child.gender")`
- `$intl 'v2.constants.informant' ($lookup 'informant.relation')`

### `$or`
Returns the first non-undefined value among two expressions.
- `$or ($lookup 'child.address.other.district') ($lookup 'child.address.other.district2')`

### `$formatDate`
Formats a date using a given format string.
- `$formatDate ($lookup $state "modifiedAt") "dd MMMM yyyy"`
- `$formatDate ($lookup $state "createdAt") "dd MMMM yyyy"`

Entirely custom helper functions can be written to manipulate the SVG elements and your data to create virtually any design you want for your event.

This custom helper functions capability is retained from OpenCRVS 1.8 and will not be deprecated.

All your SVGs should be placed in the src/api/certificates/source folder.

Notice that OpenCRVS v1.9~ compatble certificates have a V2 prefix in the naming convention.

To get an idea of what we mean, take a look at the Farajaland example certificates and available handlebars for each event:

Event	Certificate template SVG
V2 Birth	Birth Certificate Birth Certified Copy
V2 Death	Death Certificate Death Certified Copy

Step 2: Add custom font files

Any fonts can be used in your certificate provided you have permission and are prepared to accept the client load time required to render the font file.

Drop your custom font files (.ttf) in this directory: https://github.com/opencrvs/opencrvs-countryconfig/tree/develop/src/api/fonts

Step 3: Serve certificates to the application

To set-up your SVG files, fonts and fees to be served to the client, you must configure the certificateConfigs TypeScript object here.

An example v2 certificate config looks like this:

{
  id: 'v2.birth-certificate',
  event: Event.Birth,
  isV2Template: true, // Must be set for V2 certificates.  Will be deprecated in OpenCRVS 2.0
  label: {
    id: 'certificates.birth.certificate',
    defaultMessage: 'Birth Certificate copy',
    description: 'The label for a birth certificate'
  },
  isDefault: true, 
  fee: {
    onTime: 7, // Fees assocaited with the certificate
    late: 10.6,
    delayed: 18
  },
  svgUrl: '/api/countryconfig/certificates/v2.birth-certificate.svg',
  fonts: {
    'Libre Baskerville': {
      normal: '/api/countryconfig/fonts/LibreBaskerville-Regular.ttf',
      bold: '/api/countryconfig/fonts/LibreBaskerville-Bold.ttf',
      italics: '/api/countryconfig/fonts/LibreBaskerville-Italic.ttf',
      bolditalics: '/api/countryconfig/fonts/LibreBaskerville-Regular.ttf'
    }
  },
  conditionals: [
    {
      type: 'SHOW', // Optional business functional conditionals deciding when this cert should be available
      conditional: not(event.hasAction(ActionType.PRINT_CERTIFICATE))
    }
  ]
}

• The id property must be unique.

• isV2Template must be set to true

• The event property must be set to the supported Event.<prop> provided to you by TypeScript.

• The label property must be a react-intl formatjs object with a translation for the visible label that you wish to apply to this certificate in the select field that is available to the user. Appropriate translations must exist in your client.csv file for the label.id where necessary. You can learn about how to configure OpenCRVS content translation in the section: Managing Language Content.

• The isDefault property can only be applied to one item per event. Its the first item users will see in the select UI form field when choosing a certificate.

• The fee property allows you to configure unique fees for the certificate type. Defaults are applied from applcation-config.ts

• The svgUrl property is self explanatory. The SVG file must exist in this location.

• The fonts property, as above, must point to ttf font files that exist in the referenced location.

• conditionals allow you to set visibility conditionals to configure the business logic from metadata, deciding when and how often this template should be available for printing. In some countries, legal requirements state that certain templates should only be printed once, and only then certified copies should be printed.