Customize VC PDF Template

Configuring Credential Template

This guide help you customize and configuring credential templates using the Velocity Template Language (VTL) syntax. It explains how data from the mimoto service is passed into a template, how you can configure fields in the template, and how to retrieve and display the relevant data dynamically. This also includes a sample template to guide users in writing their own templates.

Overview

The mimoto service pass data to a Velocity Template for rendering, This allows the you to define which fields you want to display and how you want to structure the credential templates. You can customize the template with your own fields and data, making it flexible and easy to adapt.

Mimoto Service Flow

1. Data Preparation: The mimoto service gathers all the required display properties and field values for the credential from the issuer wellknown.

2. Template Retrieval: The user provides the issuerId and credentialType which are used to check if a custom template exists in the configuration service.

3. Field Mapping: The template is populated dynamically using field names and values passed from the backend.

Template Retrieval and Configuration

Template Retrieval Mechanism

The mimoto service checks if a specific template is available based on the issuerId and credentialType by querying the config service. If a template is found, it is used; otherwise, a default template is applied. A dynamic name for the template file which mimoto service search is made with this combination issuerId-credentialType-template.html. For example if issuerId is Mimoto and credentialType is MosipVerifiableCredential then service will search for Mosip-MosipVerifiableCredential-template.html file in the configuration service.

If the profile is local while running mimoto, the template is fetched from a local directory; else, it fetches from a configuration service.

Understanding available Data Fields in the template

Credential Issuer Information:

• titleName: The credential display name provided by the issuer (MOSIP Verifiable Credentials).

• logoUrl: The logo of the issuer (https://api.collab.mosip.net/inji/mosip-logo.png) which can be included in the template as part of the issuer's branding.

• backgroundColor: Background color for the credential provided by the issuer.

• backgroundImage: A background image URL (https://api.collab.mosip.net/inji/mosip-logo.png)which can be used to customize the appearance of the credential.

• textColor: The color of the text in the credential( #000000).

• qrCodeImage:

• face:If face is available as part of the credential.

Dynamic Fields

Data fields are dynamically fetched in the velocity template from the rowProperties object.

• If orderProperty is present: The rowProperties map will contain the fields from credentialSubject in the order specified by orderProperty of issuer wellknown. Each entry in rowProperties will map the field name (e.g., fullName, phone) to a Map with the display name as the key and the credential value as the value.

• If orderProperty is not present: All fields in credentialSubject of issuer wellknown will be included in rowProperties, and they will be picked in the order they appear in the redentialSubject. Each field will again be mapped to a Map with the corresponding display name and its value. The rowProperties map will look like this for example:

{
    "fullName": {
        "Full Name": "Some Name"
    },
    "phone": {
        "Phone Number": "[phone]"
    },
    "gender": {
        "Gender": "Male"
    }
}

Customizing the Template

Now that you understand the available properties, you can customize your template using these dynamic values. In your custom credential template (HTML file), you will use placeholders for each property to dynamically populate the content.

Example for rendering the Full Name field:

#foreach($field in ['fullName'])
    #set($data = $rowProperties.get($field))
    #if($data && $data.size() > 0)
        #foreach($entry in $data.entrySet())
            <div>
                <label>$entry.key</label>
                <div>$entry.value</div>
            </div>
        #end
    #end
#end

Example for logoUrl

<img src="../../../../unsegregated/$logoUrl" alt="Issuer Logo" class="logo" />

This pattern can be used for any other field such as Policy Number, Email, Gender, etc., by updating the $field name.

Sample Templates

StayProtected-InsuranceCredential-template.html

StayProtected-InsuranceCredential-template.html