All Collections
Badges
Awarding a badge using specific criteria
Awarding a badge using specific criteria

Want to award a badge outside of the set parameters? You can achieve this with the use of the Event Hub and an automation tool.

Paulene Crook avatar
Written by Paulene Crook
Updated over a week ago

By using the Event hub and an automation tool such as Zapier, you can create a custom set of rules to award a badge for your iQualify course activation.

Before you start

The following items will need to be setup prior to creating the automation:

  • Create a course activation (note all learners do not need to be added at this point).

  • Make sure a badge has been enabled for this activation.

Setup

To get started you'll need to create a Zapier account. Please note that zaps you will be creating will require you to have a paid Zapier account.

You will also need a Google account.  If you have a gmail address you already have a Google account.  If you don't have a Google account you can easily set one up - Create your Google Account

You will also need someone with account owner access, as this automation requires the API token and access to the event hub, both of which are found under iQualify settings.

How to

  1. First, you will need to create a new Google Spreadsheet. Give your spreadsheet a name and enter the following column headers in the first row:
    first name  last name  email  case study  and badge awarded

  2. If you are setting this up for more than one activation, you can use the same spreadsheet and set each activation up on a different worksheet. Each worksheet will need the headers from step 1 (see image below).

Image showing Google Sheet with 3 worksheets

3. Give your Google Sheet a title so it is easy to identify.  Otherwise it will automatically save as Untitled spreadsheet. 

Zaps

In this example, the zap set up looks at the learner's progress % through the course, where 60% or higher is the threshold for being awarded a badge, and whether a certain assessment (for this example it is named case study) has been submitted. There are two separate zaps required for this automation. The instructions below act as a step by step guide on how to set them both up.

Zap 1

This zap will capture and inspect all event data for submitting an assessment, and we'll write that information onto a spreadsheet if the event relates to the course activation and assessment that we're interested in. If the learner has met badge requirements for the course, they'll be awarded a badge and a congratulatory email will be sent to them.

  1. First, we need to set up a trigger. For our trigger, we'll select 'Webhooks by Zapier'. 

  2. Select the 'Catch Hook' option and press continue.

  3. You will then be given a custom webhook URL to add to the required endpoint in the Event Hub. To capture a submitted assessment, the webhook URL will need to be added as an endpoint to the corresponding event. For this zap we'll add the endpoint to the 'Submitted an assessment' event, under the 'Assessments' category in the Event Hub.

Image showing the Event hub menu to add endpoint

Once you have added the custom endpoint to the corresponding event, click the Save  and Update buttons to save your changes. 

In Zapier, you will need to test this step. To do this you will need to complete the iQualify action that triggers the event, i.e. submitting an assessment in a course activation. Once you've done this, you'll see one or more sets of sample data available, depending on the number of times the event has been triggered. Select the sample data that you just triggered and click 'Done Editing'.

Image showing the Zapier sample for data collection

4. Next, we'll add a filter step. Select 'Filter by Zapier' as your action step. In the filter settings, select Offering ID  in the first box, (Text) is in box two and in box three paste the offering ID of the course activation you set up earlier. If you aren't sure how to find the offering ID for your course, you can read our help article here.

Press Test & Continue once you've finished the above step.

5. In this step we'll add an action for Lookup Spreadsheet Row  using Google Sheets. Select the Google Sheets option and choose Lookup Spreadsheet Row  as the action event. Select your Google Account to provide Zapier with access to the spreadsheet created earlier, and click 'Continue'.

6. In the Customize Spreadsheet Row section, the following fields need to be populated:

  • Spreadsheet - select the spreadsheet that you have set up for this zap

  • Worksheet - select the worksheet related to this zap, i.e. 'activation 1'.

  • Lookup column - select email

  • Lookup value - from the drop down menu, select 'Step One (Catch Hook)', then select Actor Email

Image showing the Zappier trigger sample
  • Select the Create Google Sheets Spreadsheet Row if it doesn't exist yet checkbox. On each drop down menu, select 'Step One (Catch Hook)' to populate the following fields: first name, last name and email.

Image showing the Zappier trigger sample

Click 'Continue' once you've finished this step, then select 'Test & Continue' to run a test on this action step. If successful, a new row of data should be populated in your spreadsheet.

7. In this next step, we'll add another action  to update spreadsheet row in Google Sheets. We'll use this action to add data to the 'case study' column in our spreadsheet, indicating that the assessment has been submitted by the learner.
Select Update Spreadsheet Row as the action event, then click 'Continue'.  Like in the previous step, connect your Google Account and continue.

In the Customize Spreadsheet Row section, the following fields need to be populated:

  • Spreadsheet - select the spreadsheet that you have set up for this zap

  • Worksheet - select the worksheet related to this zap

  • Row -  select Use a Custom Value (advanced) 

In Custom Value for Row ID, select 'Step Three (Find or Create Row)' from the drop down, then select Row

In the case study  field, select 'Step One (Catch Hook)' from the drop down, then select Event Timestamp.

Image showing the Zappier trigger sample

Click 'Continue' once you've finished this step, then select 'Test & Continue' to run a test on this action step. If successful, the 'case study' column should be populated on the second row of data in your spreadsheet, where you already have the first name, last name and email of the corresponding learner.

8. Next, we'll query the iQualify API to find out the current progress percentage of the learner. If the learner's progress percentage is at 60% or higher, they've met the badge requirements for the course.

Select 'Webhooks by Zapier' as the app and 'GET' as the action event. Once you've done this, click 'Continue'.

In the Customize GET section, the following fields need to be populated:

  • URL -  add the following URL: https://api.iqualify.com/v1/users/{userEmail}/offerings/{offeringId}/progress
    Note: From the drop down menu, select 'Step One (Catch Hook)' and add 'Actor Email' in place of {userEmail}. Paste the 'Offering ID' of your course activation (like in Step 4) in place of {offeringId}.

  • Send As JSON - Set this value to Yes 

  • Headers -  In the left box, type Authorization. In the right box, copy and paste your API access token.

Image showing the Zappier GET API sample


9. Next, we'll add another filter step as we're only interested in instances where the learner's progress % is 60% or higher.

Select 'Filter by Zapier' as your action step. In the filter settings, add the following two statements:

  • Select 'Step 5 (GET)' then add Completion to the first box. In the second box, select '(Number) Greater than'. In the third box, type 59%

  • Click +AND  to add another statement field. 

  • Select 'Step 3 (Find or Create Row)' then add Completion to the first box. In the second box, select '(Text) Does not exactly match'. In the third box, type TRUE

Image showing the Zappier Filters

Click 'Continue' once you've finished this step. Zaier will inform you whether your current test data would have passed this filter step or not. Click 'Done Editing' once you've finished this step.

10. Now we are ready to award a badge to a learner that has submitted their assessment and has a progress percentage of 60% or higher.

Select 'Webhooks by Zapier' as the app and 'POST' as the action event. Once you've done this, click 'Continue'.

In the Customize POST section, the following fields need to be populated:

  • URL -  add the following URL: https://api.iqualify.com/v1/offerings/{offeringID}/users/{userEmail}/badges/award
    Note: From the drop down menu, select 'Step One (Catch Hook)' and add 'Actor Email' in place of {userEmail} . Paste the 'Offering ID' of your course activation (like in Step 4) in place of {offeringId}.

  • Payload Type - Set this value to json  

  • Headers -  In the left box, type Authorization. In the right box, copy and paste your API access token.

Image showing the Zappier API call setup

Click 'Continue' once you've finished this step, then select 'Test & Continue' to send the API request. If the request sends successfully, click 'Done Editing'.

11. We'll add another action for Lookup Spreadsheet Row  using Google Sheets. This is to add a value to the spreadsheet to indicate that the badge has been awarded. Select the Google Sheets option and choose Lookup Spreadsheet Row  as the action event. Select your Google Account to provide Zapier with access to the spreadsheet created earlier, and click 'Continue'.

In the Customize Spreadsheet Row section, the following fields need to be populated:

  • Spreadsheet - select the spreadsheet that you have set up for this zap

  • Worksheet - select the worksheet related to this zap, i.e. 'activation 1'.

  • Lookup column - select email

  • Lookup value - from the drop down menu, select 'Step One (Catch Hook)', then select Actor Email . 

Image showing the Zappier Customised spreadsheet row

Click 'Continue' once you've finished this step, then select 'Test & Continue' to run a test on this action step.

12. Now we need an action  to update spreadsheet row in Google Sheets. We'll use this action to add data to the 'badge awarded' column in our spreadsheet.
Select Update Spreadsheet Row as the action event, then click 'Continue'.  Like in the previous step, connect your Google Account and continue.

In the Customize Spreadsheet Row section, the following fields need to be populated:

  • Spreadsheet - select the spreadsheet that you have set up for this zap

  • Worksheet - select the worksheet related to this zap

  • Row -  select Use a Custom Value (advanced) 

In Custom Value for Row ID, select 'Step Eight (Lookup Spreadsheet Row)' from the drop down, then select Row

In the badge awarded  field, type TRUE .

Image showing the Custom Value for Row in Zappier

Click 'Continue' once you've finished this step, then select 'Test & Continue' to run a test on this action step. If successful, the 'badge awarded' column should be populated on the second row of data in your spreadsheet, where you already have the first name, last name and email of the corresponding learner.

13. This zap is now ready to go! You can give it a name and turn it on. When naming this zap it is helpful to indicate within the title that this is the first of the two zaps in the automation.

Zap 2:

The second zap will trigger each time a learner increases their progress % in the course activation. It'll validate whether a learner has met the badge requirements for the course, and if so, the learner will be awarded with the course badge and a congratulatory email will be sent to them.

  1. First, we need to set up a trigger. For our trigger, we'll use 'Webhooks by Zapier'.

  2. Select the 'Catch Hook' option and press continue.

  3.  You will then be given a custom webhook URL to add to the required endpoint in the Event Hub. In this zap, we want to capture any event where the learner's progress percentage will increase. Each event needed can be found under the 'Content' category in the Event Hub. The events are listed below:

  • Viewed a unit

  • Submitted a MCQ activity

  • Submitted an open response activity

  • Submitted a task activity

  • Submitted a fill in the blanks activity

Image showing the Event hub menu to add endpoint

Once you have added the custom endpoint to the corresponding events, click the Save  and Update buttons to save your changes. 

In Zapier, you will need to test this step. To do this you will need to complete the iQualify action that triggers the event, i.e. viewing a unit in a course activation. Once you've done this, you'll see one or more sets of sample data available, depending on the number of times the events have been triggered. Select the sample data that you just triggered and click 'Done Editing'.

Image showing the Zapier sample for data collection

4. Next, we'll add a filter step. Select 'Filter by Zapier' as your action step. In the filter settings, add the following two statements:

  • In the filter settings, Select 'Step 1 (Catch Hook)', then add Offering ID  in the first box. Add (Text) is in into box two and in box three paste the offering ID of the course activation.

  • Click +AND  to add another statement field. 

  • Select 'Step 1 (Catch Hook)' then add Event Event Properties Offering Progress to the first box. In the second box, select '(Number) Greater than'. In the third box, type 0.59

Press Test & Continue once you've finished the above step.

5. In this step we'll add an action for Lookup Spreadsheet Row  using Google Sheets. Select the Google Sheets option and choose Lookup Spreadsheet Row  as the action event. Select your Google Account to provide Zapier with access to the spreadsheet created earlier, and click 'Continue'.

6. In the Customize Spreadsheet Row section, the following fields need to be populated:

  • Spreadsheet - select the spreadsheet that you have set up for this zap

  • Worksheet - select the worksheet related to this zap, i.e. 'activation 1'.

  • Lookup column - select email

  • Lookup value - from the drop down menu, select 'Step One (Catch Hook)', then select Actor Email . 

Click 'Continue' once you've finished this step, then select 'Test & Continue' to run a test on this action step.

7. Next, we'll add another filter step. Select 'Filter by Zapier' as your action step. In the filter settings, add the following two statements:

  • In the filter settings, Select 'Step Three (Lookup Spreadsheet Row)', then add badge awarded  in the first box. Add (Text) does not exactly match  into box two and in box three type TRUE.

  • Click +AND  to add another statement field. 

  • Select 'Step Three (Lookup Spreadsheet Row)' then add case study  into the first box. In the second box, select exists .

Image showing the Zappier Filters

Press Test & Continue once you've finished the above step. Your zap will tell you whether or not the process would continue with your current set of test data, depending on the filter parameter. Click 'Done Editing'.

8. Now we are ready to award a badge to a learner that has submitted their assessment and has a progress percentage of 60% or higher.

Select 'Webhooks by Zapier' as the app and 'POST' as the action event. Once you've done this, click 'Continue'.

In the Customize POST section, the following fields need to be populated:

  • URL -  add the following URL: https://api.iqualify.com/v1/offerings/{offeringID}/users/{userEmail}/badges/award
    Note: From the drop down menu, select 'Step One (Catch Hook)' and add 'Actor Email' in place of {userEmail}. Paste the 'Offering ID' of your course activation (like in Step 4) in place of {offeringId} .

  • Payload Type - Set this value to json  

  • Headers -  In the left box, type Authorization. In the right box, copy and paste your API access token.

Image showing the Zappier API call setup

Click 'Continue' once you've finished this step, then select 'Test & Continue' to send the API request. If the request sends successfully, click 'Done Editing'.

9. Now we need an action  to update spreadsheet row in Google Sheets. We'll use this action to add data to the 'badge awarded' column in our spreadsheet.

Select Update Spreadsheet Row as the action event, then click 'Continue'.  Like in the previous step, connect your Google Account and continue.

In the Customize Spreadsheet Row section, the following fields need to be populated:

  • Spreadsheet - select the spreadsheet that you have set up for this zap

  • Worksheet - select the worksheet related to this zap

  • Row -  select Use a Custom Value (advanced) 

In Custom Value for Row ID, select 'Step Three (Lookup Spreadsheet Row)' from the drop down, then select Row

In the badge awarded  field, type TRUE .

Image showing the Custom Value for Row ID in Zappier

Click 'Continue' once you've finished this step, then select 'Test & Continue' to run a test on this action step. If successful, the 'badge awarded' column should be populated on the second row of data in your spreadsheet, where you already have the first name, last name and email of the corresponding learner.

10. The final step! For the final step we are adding is an action  to send an email. Select the gmail icon as shown in the image below:

Image of Gmail logo

Connect your Google Account and click 'Continue'.
In the edit options  for the spreadsheet, the following fields need to be completed:

  • To - from the drop down, select step one (google sheet) and select email 

  • From - enter the gmail address the email is being sent from

  • Subject - Congratulations! You’ve earned a badge.

  • Body type - Html

Below is what should be entered as the body of the image, take careful note of highlighted spots where you will need to enter specific information:

/start

<p>Hi from the drop down, select step one (google sheet) and select first name,<br />

You’ve been awarded a badge for the Name of course </p>

<h3>View your badge</h3>
<p>You can view your badge on your <a href="https://your environment name .iqualify.com/course/offering ID /#/overview">overview page</a>.</p>

<h3>Get sharing</h3>
<p>Why not share your badge and showcase your achievement? You can share your badge anywhere you can share a URL, for example on LinkedIn, Facebook, Twitter or on a CV. Check out our <a href="https://intercom.help/iqualify/learning-with-iqualify/digital-badges/how-to-see-and-share-your-digital-badge">knowledgebase article</a> for more information.</p>

<p>This email was sent by iQualify.</p>

<p>To find out more about iQualify visit <a href="https://www.iqualify.com">www.iqualify.com</a> or follow us on <a href="https://twitter.com/iqualify_lms">Twitter</a>.</p>

end/

Click 'Continue' once you've finished this step, then select 'Test & Continue' to run a test on this action step. This zap is now ready to go! You can give it a name and turn it on. When naming this zap it is helpful to indicate within the title that this is the second of the two zaps in the automation.

Did this answer your question?