1 of 4

Configuring certificates

Overview

This document will help an implementer configure a certificate (template and QR code) for a health event such as vaccination. This section includes configuring:

API

The DIVOC platform provides API services for generating digitally verifiable QR code-based vaccination certificates. The API for certificate generation has 6 sections:

PreEnrollmentCode: This section is linked to the 'dose' in the vaccination section to uniquely identify an event. For example, beneficiary registration number (R101) and dose number (1) as (R101-1) will be used to identify the first dose event uniquely. Similarly, beneficiary registration number (R101) and dose number (2) as (R101-2) will be used to identify the second dose event uniquely.
Recipient: It contains information about the beneficiary.
Vaccination: It contains details about the vaccination event such as name, batch, and vaccination date.
Vaccinator: It contains details about the vaccinator.
Facility: It contains details about the facility where beneficiaries will get vaccinated.
Meta: It contains additional information, which is not part of the QR code, such as the number of past doses taken.

Sample for default certificate generation request

You can refer to the API service call with sample data below:

Key Functionalities

Generate configured QR code
Generate configured certificate template

Prerequisite: Get details on API request and field validations

Making the changes

Click the following to see how you can make the changes:

Step 1: Create a certification generation request

Example

Include the beneficiary’s parent name in the certificate. The parent’s name is “Sam Mandosa.” This is a mandatory field.

Steps

Step 1: Create a certification generation request

a. Open this file: https://github.com/egovernments/DIVOC/blob/main/backend/vaccination_api/pkg/certify_handler.go

b. Add a parameter in the function “convertToCertifyUploadFields” called RecipientParentName.

func convertToCertifyUploadFields(data *Scanner) *db.CertifyUploadFields {
	return &db.CertifyUploadFields{
		PreEnrollmentCode:         data.Text("preEnrollmentCode"),
		RecipientName:             data.Text("recipientName"),
RecipientParentName:        data.Text("recipientParentName"),
		RecipientMobileNumber:  data.Text("recipientMobileNumber"),
		RecipientDOB:              data.Text("recipientDOB"),
		RecipientGender:           data.Text("recipientGender"),
		RecipientNationality:      data.Text("recipientNationality"),
		RecipientIdentity:         data.Text("recipientIdentity"),
		RecipientAge:              data.Text("recipientAge"),
		RecipientAddressLine1:  data.Text("recipientAddressLine1"),
		RecipientAddressLine2:  data.Text("recipientAddressLine2"),
		RecipientDistrict:         data.Text("recipientDistrict"),
		RecipientState:            data.Text("recipientState"),
		RecipientPincode:          data.Text("recipientPincode"),
		VaccinationBatch:          data.Text("vaccinationBatch"),
		VaccinationDate:           data.Text("vaccinationDate"),
		VaccinationDose:           data.Text("vaccinationDose"),
		VaccinationTotalDoses:   data.Text("vaccinationTotalDoses"),
	VaccinationEffectiveStart:data.Text("vaccinationEffectiveStart"),
	VaccinationEffectiveEnd:data.Text("vaccinationEffectiveEnd"),
	VaccinationManufacturer:   data.Text("vaccinationManufacturer"),
		VaccinationName:           data.Text("vaccinationName"),
		VaccinatorName:            data.Text("vaccinatorName"),
		FacilityName:              data.Text("facilityName"),
		FacilityAddressLine1:      data.Text("facilityAddressLine1"),
		FacilityAddressLine2:      data.Text("facilityAddressLine2"),
		FacilityDistrict:          data.Text("facilityDistrict"),
		FacilityState:             data.Text("facilityState"),
		FacilityPincode:           data.Text("facilityPincode"),
	}
}

c. Add RecipientParentName in the function “createCertificate” to make the field mandatory.

recipient := &models.CertificationRequestRecipient{
		Name: &certifyData.RecipientName,
		Age:  recipientAge,
		Address: &models.CertificationRequestRecipientAddress{
			AddressLine1: &certifyData.RecipientAddressLine1,
			AddressLine2: certifyData.RecipientAddressLine2,
			District:     &certifyData.RecipientDistrict,
			Pincode:      &certifyData.RecipientPincode,
			State:        &certifyData.RecipientState,
		},
		Contact:     contact,
		Dob:         dateAdr(strfmt.Date(dob)),
		Gender:      &certifyData.RecipientGender,
		Nationality: &certifyData.RecipientNationality,
		ParentName: &certifyData.RecipientParentName,
		Identity:    &certifyData.RecipientIdentity,
	}

d. If the data is uploaded via CSV, then add this column to the CSV template for this field. Open “application-default.yml” and update the certificate section in this file.

Note:

As a standard practice, we recommend you to update the informative files mentioned in step 1 of this section.
Make sure the name matches exactly with the name convertToCertifyUploadFields function that you edited in step 1.

Step 2: Configure the QR code content

The template for the QR code generation is provided here under vaccination-context. The QR code structure must match the vaccination-context. Any updates made in the QR code content must reflect in the vaccination-context.js file.

Steps:

a. Open the file main.js.

b. Go to the function transformW3 and add the fields according to your requirement. This function will read the data received from the certificate generation API call and convert it into QR code Json format.

function transformW3(cert, certificateId) {
  const certificateType = R.pathOr('', ['meta', 'certificateType'], cert);
  const namespace = certificateType === CERTIFICATE_TYPE_V3 ? CERTIFICATE_NAMESPACE_V2 : CERTIFICATE_NAMESPACE;
  const recipientIdentifier = R.pathOr('', ['recipient', 'identity'], cert);
  const preEnrollmentCode = R.pathOr('', ['preEnrollmentCode'], cert);
  const recipientName = R.pathOr('', ['recipient', 'name'], cert);
  const recipientGender = R.pathOr('', ['recipient', 'gender'], cert);
  const recipientNationality = R.pathOr('', ['recipient', 'nationality'], cert);
  const recipientParentName = R.pathOr('', ['recipient', 'parentName'], cert);

c. Add the newly-added field to the data variable

let data = {
    namespace, recipientIdentifier, preEnrollmentCode, recipientName, recipientGender, recipientDob, recipientAge, recipientNationality, recipientParentName, recipientAddressLine1, recipientAddressLine2, recipientAddressDistrict, recipientAddressCity, recipientAddressRegion, recipientAddressCountry, recipientAddressPostalCode,
    issuer, issuanceDate, evidenceId, InfoUrl, feedbackUrl,
    certificateId, batch, vaccine, icd11Code,  prophylaxis, manufacturer, vaccinationDate, effectiveStart, effectiveUntil, dose, totalDoses,
    verifierName,
    facilityName, facilityAddressLine1, facilityAddressLine2, facilityAddressDistrict, facilityAddressCity, facilityAddressRegion, facilityAddressCountry, facilityAddressPostalCode
  };

Note:

Certain constant values are also listed in the main.js. If you want to update any of the constant values such as “certificate controller,” please refer to the DockerFile.

Step 3: Configure the certificate template

Each country will have a separate certificate template with country-specific branding, and language.

Steps:

a. The DIVOC certificate template has been designed in the HTML format. To configure the HTML-based certificate template according to your country’s requirement, open certificate_template.html and map the dynamic fields in the certificate template.

<tr>
        <td><span class="d-flex pt-1 pb-1 font-bold">Beneficiary Name</span></td>
        <td><span class="d-flex pt-1 pb-1 font-bold">Beneficiary Parent Name</span></td>
    </tr>
    <tr>
        <td><span class="d-flex">{{name}}</span></td>
        <td><span class="d-flex">{{parentName}}</span></td>
    </tr>

b. Any modifications that you make (such as combining address fields as a single string) to the address value must be performed in controller.js. The dynamic values will be sent from controller.js.

function prepareDataForVaccineCertificateTemplate(certificateRaw, dataURL) {
    certificateRaw.certificate = JSON.parse(certificateRaw.certificate);
    const {certificate: {credentialSubject, evidence}} = certificateRaw;
    const certificateData = {
        name: credentialSubject.name,
        parentName: credentialSubject.parentName,
        age: credentialSubject.age,
        gender: credentialSubject.gender,
        identity: formatId(credentialSubject.id),
        beneficiaryId: credentialSubject.refId,
        recipientAddress: formatRecipientAddress(credentialSubject.address),
        vaccine: evidence[0].vaccine,
        vaccinationDate: formatDate(evidence[0].date) + ` (Batch no. ${evidence[0].batch} )`,
        vaccineValidDays: `after ${getVaccineValidDays(evidence[0].effectiveStart, evidence[0].effectiveUntil)} days`,
        vaccinatedBy: evidence[0].verifier.name,
        vaccinatedAt: formatFacilityAddress(evidence[0]),
        qrCode: dataURL,
        dose: evidence[0].dose,
        totalDoses: evidence[0].totalDoses,
        isFinalDose: evidence[0].dose === evidence[0].totalDoses,
        currentDoseText: `(${getNumberWithOrdinal(evidence[0].dose)} Dose)`
    };

    return certificateData;
}

Note:

To check the PDF/print version, which will be generated after an update, open the HTML file in the browser and check for the print preview.
The page size should be A4 as the HTML is developed according to A4 dimensions.

Step 2: Configure the QR code content

Steps:

a. Open the file main.js.

function transformW3(cert, certificateId) {
  const certificateType = R.pathOr('', ['meta', 'certificateType'], cert);
  const namespace = certificateType === CERTIFICATE_TYPE_V3 ? CERTIFICATE_NAMESPACE_V2 : CERTIFICATE_NAMESPACE;
  const recipientIdentifier = R.pathOr('', ['recipient', 'identity'], cert);
  const preEnrollmentCode = R.pathOr('', ['preEnrollmentCode'], cert);
  const recipientName = R.pathOr('', ['recipient', 'name'], cert);
  const recipientGender = R.pathOr('', ['recipient', 'gender'], cert);
  const recipientNationality = R.pathOr('', ['recipient', 'nationality'], cert);
  const recipientParentName = R.pathOr('', ['recipient', 'parentName'], cert);

c. Add the newly-added field to the data variable

let data = {
    namespace, recipientIdentifier, preEnrollmentCode, recipientName, recipientGender, recipientDob, recipientAge, recipientNationality, recipientParentName, recipientAddressLine1, recipientAddressLine2, recipientAddressDistrict, recipientAddressCity, recipientAddressRegion, recipientAddressCountry, recipientAddressPostalCode,
    issuer, issuanceDate, evidenceId, InfoUrl, feedbackUrl,
    certificateId, batch, vaccine, icd11Code,  prophylaxis, manufacturer, vaccinationDate, effectiveStart, effectiveUntil, dose, totalDoses,
    verifierName,
    facilityName, facilityAddressLine1, facilityAddressLine2, facilityAddressDistrict, facilityAddressCity, facilityAddressRegion, facilityAddressCountry, facilityAddressPostalCode
  };

Note:

Certain constant values are also listed in the main.js. If you want to update any of the constant values such as “certificate controller,” please refer to the DockerFile.

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Step 1: Create a certification generation request

Example

Include the beneficiary’s parent name in the certificate. The parent’s name is “Sam Mandosa.” This is a mandatory field.

Steps

Step 1: Create a certification generation request

a. Open this file: https://github.com/egovernments/DIVOC/blob/main/backend/vaccination_api/pkg/certify_handler.go

b. Add a parameter in the function “convertToCertifyUploadFields” called RecipientParentName.

func convertToCertifyUploadFields(data *Scanner) *db.CertifyUploadFields {
	return &db.CertifyUploadFields{
		PreEnrollmentCode:         data.Text("preEnrollmentCode"),
		RecipientName:             data.Text("recipientName"),
RecipientParentName:        data.Text("recipientParentName"),
		RecipientMobileNumber:  data.Text("recipientMobileNumber"),
		RecipientDOB:              data.Text("recipientDOB"),
		RecipientGender:           data.Text("recipientGender"),
		RecipientNationality:      data.Text("recipientNationality"),
		RecipientIdentity:         data.Text("recipientIdentity"),
		RecipientAge:              data.Text("recipientAge"),
		RecipientAddressLine1:  data.Text("recipientAddressLine1"),
		RecipientAddressLine2:  data.Text("recipientAddressLine2"),
		RecipientDistrict:         data.Text("recipientDistrict"),
		RecipientState:            data.Text("recipientState"),
		RecipientPincode:          data.Text("recipientPincode"),
		VaccinationBatch:          data.Text("vaccinationBatch"),
		VaccinationDate:           data.Text("vaccinationDate"),
		VaccinationDose:           data.Text("vaccinationDose"),
		VaccinationTotalDoses:   data.Text("vaccinationTotalDoses"),
	VaccinationEffectiveStart:data.Text("vaccinationEffectiveStart"),
	VaccinationEffectiveEnd:data.Text("vaccinationEffectiveEnd"),
	VaccinationManufacturer:   data.Text("vaccinationManufacturer"),
		VaccinationName:           data.Text("vaccinationName"),
		VaccinatorName:            data.Text("vaccinatorName"),
		FacilityName:              data.Text("facilityName"),
		FacilityAddressLine1:      data.Text("facilityAddressLine1"),
		FacilityAddressLine2:      data.Text("facilityAddressLine2"),
		FacilityDistrict:          data.Text("facilityDistrict"),
		FacilityState:             data.Text("facilityState"),
		FacilityPincode:           data.Text("facilityPincode"),
	}
}

c. Add RecipientParentName in the function “createCertificate” to make the field mandatory.

recipient := &models.CertificationRequestRecipient{
		Name: &certifyData.RecipientName,
		Age:  recipientAge,
		Address: &models.CertificationRequestRecipientAddress{
			AddressLine1: &certifyData.RecipientAddressLine1,
			AddressLine2: certifyData.RecipientAddressLine2,
			District:     &certifyData.RecipientDistrict,
			Pincode:      &certifyData.RecipientPincode,
			State:        &certifyData.RecipientState,
		},
		Contact:     contact,
		Dob:         dateAdr(strfmt.Date(dob)),
		Gender:      &certifyData.RecipientGender,
		Nationality: &certifyData.RecipientNationality,
		ParentName: &certifyData.RecipientParentName,
		Identity:    &certifyData.RecipientIdentity,
	}

d. If the data is uploaded via CSV, then add this column to the CSV template for this field. Open “application-default.yml” and update the certificate section in this file.

Note:

As a standard practice, we recommend you to update the informative files mentioned in step 1 of this section.
Make sure the name matches exactly with the name convertToCertifyUploadFields function that you edited in step 1.

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

Configuring certificates

Overview

This document will help an implementer configure a certificate (template and QR code) for a health event such as vaccination. This section includes configuring:

API

The DIVOC platform provides API services for generating digitally verifiable QR code-based vaccination certificates. The API for certificate generation has 6 sections:

PreEnrollmentCode: This section is linked to the 'dose' in the vaccination section to uniquely identify an event. For example, beneficiary registration number (R101) and dose number (1) as (R101-1) will be used to identify the first dose event uniquely. Similarly, beneficiary registration number (R101) and dose number (2) as (R101-2) will be used to identify the second dose event uniquely.
Recipient: It contains information about the beneficiary.
Vaccination: It contains details about the vaccination event such as name, batch, and vaccination date.
Vaccinator: It contains details about the vaccinator.
Facility: It contains details about the facility where beneficiaries will get vaccinated.
Meta: It contains additional information, which is not part of the QR code, such as the number of past doses taken.

Sample for default certificate generation request

You can refer to the API service call with sample data below:

[
    {
        "preEnrollmentCode": "62",
        "recipient": {
            "name": "Sam",
            "uhid": "abc2232",
            "dob": "1990-09-14",
            "age": "31",
            "gender": "Male",
            "nationality": "India",
            "identity": "did:in.gov.uidai.aadhaar:11112222334",
            "contact": [
                "tel:1111111313"
            ],
            "address": {
                "addressLine1": "123, Koramangala",
                "addressLine2": "",
                "district": "Bengaluru South",
                "state": "bihar",
                "pincode": "560033"
            }
        },
        "vaccination": {
            "name": "covaxin",
            "batch": "AB348FS",
            "manufacturer": "Bharat Biotech",
            "date": "2021-07-12T19:21:19.646Z",
            "effectiveStart": "2021-07-12",
            "effectiveUntil": "2021-08-12",
            "dose": 2,
            "totalDoses": 2
        },
        "vaccinator": {
            "name": "Sooraj Singh"
        },
        "facility": {
            "name": "ABCD Medical Center",
            "address": {
                "addressLine1": "123, Koramangala",
                "addressLine2": "",
                "district": "Bengaluru South",
                "state": "Karnataka",
                "pincode": "560033"
            }
        },
        "programId": "6ce74c0f-b1b5-4b20-9fa2-084acbbd857a",
        "meta": { //Meta section stored as an Object and it can contain information in    Key value pair
        }
    }
]\

Refer to the /v3/certify service for details.
Click if you want to understand the mandatory and non-mandatory information that should be there in a vaccination certificate, according to global standards.

Key Functionalities

Generate configured QR code
Generate configured certificate template

Prerequisite: Get details on API request and field validations

a. Please refer to the existing service details in the ‘certification’ section (/v3/certify):

b. The detailed field validations are mentioned here:

// /v3/certify:
    post:
      tags:
        - certification
      summary: Certify the one or more vaccination
      description: >-
        Certification happens asynchronously, this requires vaccinator
        authorization and vaccinator should be trained for the vaccination that
        is being certified. The payload for this API is compliant with DDCC core
        data set prescribed by WHO
      operationId: certifyV3
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/CertificationRequestV2' //Refer Line 722 in same file 
      responses:
        '200':
          description: OK
        '400':
          description: Invalid input
          schema:
            $ref: '#/definitions/Error'

Making the changes

Click the following to see how you can make the changes:

All content on this page by is licensed under a .

Step 3: Configure the certificate template

Each country will have a separate certificate template with country-specific branding, and language.

Steps:

<tr>
        <td><span class="d-flex pt-1 pb-1 font-bold">Beneficiary Name</span></td>
        <td><span class="d-flex pt-1 pb-1 font-bold">Beneficiary Parent Name</span></td>
    </tr>
    <tr>
        <td><span class="d-flex">{{name}}</span></td>
        <td><span class="d-flex">{{parentName}}</span></td>
    </tr>

b. Any modifications that you make (such as combining address fields as a single string) to the address value must be performed in controller.js. The dynamic values will be sent from controller.js.

function prepareDataForVaccineCertificateTemplate(certificateRaw, dataURL) {
    certificateRaw.certificate = JSON.parse(certificateRaw.certificate);
    const {certificate: {credentialSubject, evidence}} = certificateRaw;
    const certificateData = {
        name: credentialSubject.name,
        parentName: credentialSubject.parentName,
        age: credentialSubject.age,
        gender: credentialSubject.gender,
        identity: formatId(credentialSubject.id),
        beneficiaryId: credentialSubject.refId,
        recipientAddress: formatRecipientAddress(credentialSubject.address),
        vaccine: evidence[0].vaccine,
        vaccinationDate: formatDate(evidence[0].date) + ` (Batch no. ${evidence[0].batch} )`,
        vaccineValidDays: `after ${getVaccineValidDays(evidence[0].effectiveStart, evidence[0].effectiveUntil)} days`,
        vaccinatedBy: evidence[0].verifier.name,
        vaccinatedAt: formatFacilityAddress(evidence[0]),
        qrCode: dataURL,
        dose: evidence[0].dose,
        totalDoses: evidence[0].totalDoses,
        isFinalDose: evidence[0].dose === evidence[0].totalDoses,
        currentDoseText: `(${getNumberWithOrdinal(evidence[0].dose)} Dose)`
    };

    return certificateData;
}

Note:

To check the PDF/print version, which will be generated after an update, open the HTML file in the browser and check for the print preview.
The page size should be A4 as the HTML is developed according to A4 dimensions.

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.