How to create a PDF template

Design a template

Bundle the following template components into a .zip file:

• template.pdf: This is a required PDF file used as the PDF template.
• config.json: This is a required JSON file used for field mappings.
• fonts : This is an optional folder that includes any custom fonts being used in the template in .otf or .ttf format.
  The template .zip file cannot be larger than 700kb.

template.pdf

• Maximum size of template.pdf is 700kb.
• The template must have a qrCode button field. The QR code is generated from the payload and there is no value mapping required for this field.
• All other fields in the template should be plain text fields
  • Other field types (e.g. checkboxes, radio buttons, list boxes, dropdown boxes) are not supported.
  • No macros, rules, formulation or calculations are supported.
• It is possible to have identical claims in the same PDF. The field names be suffixed (e.g. firstName#1, firstName#2).
• Multi-page templates are supported as long as the qrCode field is on the first page.
• Reading order for each field should be specified to support accessibility. Unselect Display like elements in a single block.

config.json

This JSON file should be structured as follows:

{
  "name": "SamplePDF_WorkingAtHights",
  "fileName": "{{ vc.credentialSubject.code }}_{{ vc.credentialSubject.name }}",
  "metadata": {
    "title": "{{ vc.credentialSubject.certificationName }} Certification – {{ vc.credentialSubject.name }}"
  },
  "fonts": [
    {
      "name": "PublicSans-Regular",
      "fileName": "PublicSans-Regular.ttf"
    },
    {
      "name": "PublicSans-Bold",
      "fileName": "PublicSans-Bold.ttf"
    }
  ],
  "fields": [
    {
      "key": "name",
      "value": "{{ vc.credentialSubject.name }}",
      "isRequired": true,
      "alternativeText": "{{ vc.credentialSubject.name }}",
      "fontName": "PublicSans-Regular"
    },
    {
      "key": "code",
      "value": "{{ vc.credentialSubject.code }}",
      "isRequired": true,
      "alternativeText": "{{ vc.credentialSubject.code }}",
      "fontName": "PublicSans-Bold"
    }
  ]
}

• name : Template name.
• fileName : Use values from your template.pdf to set the generated PDF file name.
• metadata : Use values from your template.pdf to set the generated PDF metadata.
• fonts : This array includes custom fonts that are used in your PDF template. Note that these custom fonts must be included in a fonts folder in your template.zip bundle for the template to be valid.
  • name : The name of the font to be referenced by fields using it.
  • fileName : The name of the font .otf/.ttf file in the fonts folder.
• fields : This array includes fields that are defined in your template.pdf file: - key : Field name in the template.pdf file. - value : Mapped claim from the credential payload. - isRequired : When set to true, the value must be provided in the credential payload to generate a valid PDF. If it is not provided, an error would occur. - alternativeText : Alternative text to support accessibility. Must be specified for every field except for qrCode. If the value is defined in both template.pdf and config.json, the value from config.json is used. - fontName : Custom font name to display the field. When no font is specified Helvetica is used by default. Note that this default font only supports Windows-1252 encoding character sets. Refer to Internationalization implementation considerations for more information.

Create a MATTR VII template

Make a request of the following structure with the template .zip file included as a binary file to create a CWT credential PDF template:

POST /v2/credentials/compact/pdf/templates
Header: Content-Type: application/zip

You can make a similar request to a different endpoint to create a Semantic CWT credential PDF template:

POST /v2/credentials/compact-semantic/pdf/templates
Header: Content-Type: application/zip

Response

{
  "id": "682f203a-f5bd-4304-95e3-c8c708e90d26", 
  "name": "SamplePDF_WorkingAtHights",
  "fileName": "{{ vc.credentialSubject.code }}_{{ vc.credentialSubject.name }}",
  "fonts": [
    {
      "name": "PublicSans-Regular",
      "fileName": "PublicSans-Regular.ttf"
    },
    {
      "name": "PublicSans-Bold",
      "fileName": "PublicSans-Bold.ttf"
    }
  ],
  "fields": [
    {
      "key": "name",
      "value": "{{ vc.credentialSubject.name }}",
      "isRequired": true,
      "alternativeText": "{{ vc.credentialSubject.name }}",
      "fontName": "PublicSans-Regular"
    },
    {
      "key": "code",
      "value": "{{ vc.credentialSubject.code }}",
      "isRequired": true,
      "alternativeText": "{{ vc.credentialSubject.code }}",
      "fontName": "PublicSans-Bold"
    },
    {
      "key": "certificationName",
      "value": "{{ vc.credentialSubject.certificationName }}",
      "isRequired": true,
      "alternativeText": "{{ vc.credentialSubject.certificationName }}",
      "fontName": "PublicSans-Bold"
    },
    {
      "key": "certificationLevel",
      "value": "{{ vc.credentialSubject.certificationLevel }}",
      "isRequired": true,
      "alternativeText": "{{ vc.credentialSubject.certificationLevel }}",
      "fontName": "PublicSans-Regular"
    },
    {
      "key": "expiry",
      "value": "{{ date vc.credentialSubject.expiry 'dd MMM yyyy' }}",
      "isRequired": true,
      "alternativeText": "{{ date vc.credentialSubject.expiry 'PPP' }}",
      "fontName": "PublicSans-Regular"
    }
  ],
  "metadata": {
    "title": "{{ vc.credentialSubject.certificationName }} Certification – {{ vc.credentialSubject.name }}"
  }
}

• id : This is a unique identifier for this PDF template. You will use it as the templateId when formatting a CWT credential as a PDF.
• All other fields in the response include information retrieved from your PDF template.

Troubleshooting

Errors may occur in the following scenarios:

• Unable to decompress the template .zip file.
• Either template.pdf or config.json are missing from the bundle.
• Either template.pdf or config.json are malformed.
• Custom fonts are used but not provided in template.zip.
• Either the template .zip file or template.pdf exceed the maximum allowed file size (700kb).
• Fields set as required in config.json are not available in template.pdf.