From 5b1c3eda63cec84e2be7d20f63ae4f9b66cbd80e Mon Sep 17 00:00:00 2001
From: Tejas Mahajan <141305477+mahajantejas@users.noreply.github.com>
Date: Mon, 7 Apr 2025 15:26:06 +0530
Subject: [PATCH] Create Custom Certificates.md
added the documentation for using certificates feature,
---
.../Custom Certificates.md | 169 ++++++++++++++++++
1 file changed, 169 insertions(+)
create mode 100644 docs/3. Product Features/Custom Certificates.md
diff --git a/docs/3. Product Features/Custom Certificates.md b/docs/3. Product Features/Custom Certificates.md
new file mode 100644
index 000000000..c5425b301
--- /dev/null
+++ b/docs/3. Product Features/Custom Certificates.md
@@ -0,0 +1,169 @@
+### **7 minute read `Advanced`**
+
+## Overview
+This feature enables the organization using Glific to provide personalized certificates and/or badges to the contacts upon completion of a certain task or action or a desired behaviour recorded through the flows.
+
+Using this feature organizations can upload multiple certificate or badge templates, and share these for the contacts having their personalized information such as "name", or "course participation", "course completion" details or any other such contact specific details be printed on the certificates and have the certificate shared with the contacts through the flows.
+
+## Pre-requisites
+Custom certificates feature is released as a trial feature and as a result cannot be accessed by all orgs using Glific out of the box. For being part of the beta program and trying out this feature, please write to tejas@glific.org. The feature has to be enabled for a particular account in order to access the screens where certificate templates can be added in the Glific platform.
+
+### Google Cloud Studio Setup
+1. Enable Slides API
+Use this [wizard](https://console.developers.google.com/start/api?id=slides.googleapis.com) on the selected project in the Google Developers Console. This will automatically turn on the Slides API.
+
+
+
+2. Enable Drive API
+Use this [wizard](https://console.developers.google.com/start/api?id=drive.googleapis.com) on the selected project in the Google Developers Console. This will automatically turn on the Drive API.
+
+
+
+3. Create a new service account on the Google Cloud which has the “editor” permission to the Google Cloud Studio. Go to Google Cloud Console, and ensure that you’re in the right project. (same project which has the BigQuery and Google Cloud Storage bucket linked to your Glific account)
+
+- a. Go to API and Services.
+- b. Go to `Credentials` -> `Create Credentials` -> Select `Service Account`
+
+
+
+
+- c. Give the service account an appropriate name.
+- d. Give the the “editor” access and complete the creation.
+
+
+
+- e. Once the service account is created, new keys need to be generated.
+- f. Go to `manage keys` -> `Create new key` -> select `json`.
+- g. This downloads the json file
+
+
+
+- h. These JSON needs to be copied into the `Google Slides` provider on the `Settings` page
+
+
+
+### Setup on Glific
+Go to `Settings` -> `Google Slides` -> Activate this setting and enter the json key that was generated in the earlier step.
+
+
+
+## Aspect Ratios
+### For best results:
+- **Landscape certificates**: Use a resolution of 2550 x 3300 px.
+- **Portrait certificates**: Use resolution of 816 x 1056 px
+- **Badges**: Use a square format, resolution of 600 x 600 px.
+
+
+
+
+To change the page dimensions for a google slide
+1. Go to `file` -> `page setup` -> `custom`.
+2. This provides the menu to alter the dimensions of the page
+3. It is advised to research on your own behalf for the most suitable aspect ratio of the base template that suits your use case.
+
+## Sending the certificates/badges to contacts
+
+### 1. Create/ Import template design in Google Slides
+1. For certificates created on canva or other softwares, export the designs as “ppt” and save it on your computer
+2. The design template should have placeholders where the personalized information for the Glific contacts will be populated.
+
+
+
+3. Create the new slide file
+4. Go to “import slides” in “files”
+5. Select “upload” and “browse” to get the ppt file
+6. Import the file and see it as slide 2 on your ppt.
+7. Copy the url on the 2nd slide. This url will be used to create the certificate template on Glific.
+
+
+
+
+8. Certificate url is the link to the google slide template taken by copying the link on the template
+- Ensure that the slide template does not end with “...slide=id.p1”
+- Ensure that the slide template is saved on the Google Drive linked to organization email id.
+
+9. Provide editor access to the google service account’s client email address.
+
+
+
+### 2. Save the certificate template in Glific
+
+1. On the Glific platform, go to `Flows` -> `Certificates` -> `Create` to add a new certificate template
+
+
+2. Add a title, description (optional), and the certificate url (see step 6 in above section
+3. The design template is now saved.
+4. The placeholders need to be added as {1} or {2}. In single curly braces with the numbers.
+5. Ensure that the placeholders have a large enough text field to accommodate the information for contact being sent
+
+### 3. Use the certificate template in the flow
+1. Call the webhook with `function` name as `create_certificate` and give it an appropriate result name.
+
+2. Go to `Function Body` and ensure that the following parameters are passed to the webhook
+```
+{
+ "certificate_id": 5,
+ "contact": "@contact",
+ "replace_texts": {
+ "{1}": "@contact.name"
+ }
+}
+```
+
+
+
+3. Here the `certificate_id` has to be taken from the certificate list page by using the `copy id` button for the certificate generated.
+4. `”contact”: “@contact”` has to be kept as it is. This enables the webhook to have access to all the contact variables being referenced in the webhook.
+5. `”replace_texts”` parameter should contain the placeholders that should be replaced in the design template. The format for replace text has to be following
+
+```
+“replace_texts”: {
+“{1}” : “@contact.fields.preferred_name” ,
+ “{2}” : “@results…” }
+```
+
+6. Ensure that the placeholders on the template are the same as the placeholder replacement texts being referred in the webhook function body are matching.
+7. The certificate url being generated can be used in the next `Send a message` node by going to the `attachments` and calling the `Expression`
+8. Based on the webhook result name defined, the Google Cloud media url is can be called by `@results.webhookresult.certificate_url`
+
+## Error Handling
+
+
+
+#### 1. Use the following validation before the `create_certificate` webhook call to ensure that the certificates are not generated for contacts for whom the placeholder parameters value is not present
+
+- a. Use the below expression to check if the variables being sent in the webhook indeed have a value for the given contact and do not end up printing a certificate like error 1 shared above.
+`<%= ["@contact.name", "@contact.abcd"] |> Enum.any?(&String.starts_with?(&1, "@")) %>`
+
+- b. For more than 2 variables, add further commas in the first list and add the variable names in double quotes.
+- c. For just one variable, use split by custom expression and plainly enter the name of the variable and check for the condition “has only the phrase” and the variable name as shown in the screenshot.
+- d. The above expression returns the value true if any of the variables start with “@..” which indicates that the variable is empty.
+- c. This method can be used to avoid sending certificates for contacts where the variable is not present.
+
+#### 2. To catch certificates non-generation due to api level problems.
+
+
+
+- a. Insert the following split by expression right after the webhook. Use `@results.webhookresultname.success` contains `true` when the certificate url is generated.
+- b. Use this condition to share a relevant message to inform the contact of certificate generation
+
+#### 3. “Error 1: URL ending with slide=id.p”
+
+This error happens because the id after slide indicates the location of the slide in the google drive and if the location is not present, then the code is not able to perform the steps like create a copy and replace the placeholder text with the variables from the webhook.
+
+**Steps to resolve**
+- a. Copy the root slide as slide 2 and slide 3
+- b. Delete the slide 1 and 3
+- c. Refresh the page
+- d. See the slide url is now changed.
+- e. Use this new url
+
+#### 4. “Error 2: Permission Issues”
+
+**Steps to resolve**
+- a. Ensure that the design template is created in the google drive account linked to the org’s email id.
+- b. Try by storing the template in a different location on the drive or on a different shared drive
+
+
+
+