V2 VR Scenario – Integrating ChatMapper with Articulate Storyline and SCORM 1.2

Integrating ChatMapper in SCORM environments through Articulate Storyline is incredibly straightforward. Thanks to the deep extensibility that both ChatMapper and Storyline have been developed for, JavaScript can act as a bridge and pass information from one to the other, and then to the SCORM environment.

This brief guide will take the user through the process of correctly setting up a ChatMapper scenario, integrating it in Articulate Storyline, and then reporting back to a SCORM environment with a sample project.

Table of Contents

The ChatMapper scenario

1.1. Setting up the project

Autoplay

1.2. The scoring variables

1.3. Communicating with Storyline

1.4 Publishing

The Articulate Storyline story

2.1. Adding Variables

2.2. Exporting to SCORM

Appendix I: Adding Scenario to an existing .story

Appendix II: Sending a score from Storyline to Scenario

The Storyline side

The ChatMapper side

The Scenario side

Appendix III: Testing the SCORM integration

1. The ChatMapper scenario

Scenario creation in ChatMapper has been detailed in various places already, like the documentation, the introductory videos, and the helpdesk. For this reason, this guide will only cover the integration process to make ChatMapper communicate with Storyline and the SCORM environment.

1.1. Setting up the project

For the integration to work well, it is advised to use two Custom Asset Fields (which can be added by going to Project → Project Settings → Custom Asset Fields, and selecting the element we want to extend):

Fig 1. The Project Settings with CAFs already defined.

Autoplay

• Tab: Conversations
• Title: Autoplay
• Type: Boolean

This should be set to true in the conversation we want to automatically start, and false everywhere else.

1.2. The scoring variables

Since the aim of this guide is to also integrate with a SCORM environment (in this case SCORM Cloud), the need for score tracking presents itself. This is something done routinely with ChatMapper e-learning projects through variables.

In ChatMapper, create a new user variable (CTRL+SHIFT+U) with a name of your choosing and an initial value of 0.

Fig 2. Creating a user variable.

The same variable can also be created directly in code, by writing the following line in the Script Editor of the conversation’s first node.

Variable["CMScore"] = 0

The variable is thus declared and initialized (i.e. given an initial value), and can be then used during the scenario to record the learner’s progress, for instance by increasing it every time a correct answer is given.

Fig 3. Note how the CMScore variable is incremented by one in the Script editor of the “correct answer” node.

In this case, we’re increasing the CMScore variable by 1 for each correct answer, which can be done like so:

Variable["CMScore"] = Variable["CMScore"] + 1

Please keep in mind that any number of variables can be created for all sorts of purposes – this is just a proof of concept, and is for this reason kept simple.

1.3. Communicating with Storyline

There is one last step in ChatMapper, which is to communicate the scenario’s outcome to Storyline. This can be done as easily as anything else, by including the following two lines in the last node of the scenario:

var CMScore = Variable["CMScore"]

LB.Lms.submitScore(CMScore);

Where Variable["CMScore"] will of course be the name of your variable, if it is different.

1.4 Publishing

Now that the work on the scenario is done, it can be published. A series of video guides that go through the process step-by-step can be found here: https://hyperspace.mv/academy/building-microlearning-modules/ . On a high level, this process consists of :

1. Publish the scenario (will create a .json file)
2. Create a new Scenario (https://app.learnbrite.com/dashboard/scenarios/create ) and Upload the .json file
3. Create a new space (and select the Scenario created in the previous step during creation).
4. Visit the space (and copy the URL for the next section)

Fig. 4. Copying the URL

2. The Articulate Storyline story

For deploying your first Scenario as a SCORM we recommend you use our pre-built Storyline template, which you can download from here. To add a Scenario to an existing Storyline project please see appendix I.

2.1. Adding Variables

Now that the ChatMapper project is set up, open the provided template with Storyline. For the integration to work, it is required to add a variable to the Storyline project. This can be done by selecting a slide, then clicking on the “{x}” button on the top right of the “Triggers” panel.

Fig. 5. Opening the list of variables

A new window will open, containing the list of variables. Adding a new one is as simple as clicking on the blue “+” button in the lower left corner

Fig. 6. Creating a new variable

And then filling in the fields

Fig. 7. Just after opening the “Create variable” popup

These are the variables to be added, alongside the form fields.

• ScenarioURL: this is the only required variable for the integration to work. It will point to the Space you created.

• Name: ScenarioURL
• Type: Text
• Default value: the URL of a the space to embed

If you are going to keep your space up-to-date with our platform, a different URL is better suited for the task.

For spaces:

For worlds, the URL is similar. Note that in this case {SPACE_ID} is the ID of the space you want the user to “land” in.

• PassPoints: this variable is optional (the default value is 50); if the learner will take a quiz within Scenario, this should be the minimum score to achieve a passing grade in the quiz. The score is inclusive, meaning that if the variable is set to 70, and the learner achieves a score of 70, they will pass.

• Name: PassPoints
• Type: Number
• Default value: the score required for the learner to achieve a passing grade.
  

• MaxPoints: this variable is also optional (the default value is 100) and is the maximum score obtainable by the user. It is used to calculate whether a passing or failing grade will be submitted to the LMS.

• Name: MaxPoints
• Type: Number
• Default value: the maximum score achievable for the learner.

For reference, here are the variables after they’ve been added:

Fig. 8. The list of variables, filled in

When the score is submitted from Scenario, the Storyline wrapper will automatically pick up on it and submit it to the LMS.

2.2. Exporting to SCORM

The only thing left is to export the story so that it can be uploaded to the SCORM environment of choice. This can be done by going to the Home tab, and clicking on Publish on the far right of the bar.

This will open a new window, in which various fields and options can be selected. Here are the settings for the sample project. Note: you should export to SCORM 1.2.

Fig 9. The Publish window.

After this step is completed, be sure to click on the ZIP option in the new window that will pop up, and save that archive to a location you’ll remember – it is that archive that will be uploaded to the SCORM environment.

Fig 10. Saving the ZIP version.

That’s it! The project is now ready to be uploaded to your SCORM server!

Appendix I: Adding Scenario to an existing .story

Scenario can be included within any Storyline project. To do so requires following 3 steps.

1. First, create a new, empty slide where Scenario will be loaded, then single-click on it to select it.

Fig. 11. Selecting a slide

2. The “Triggers” panel should appear on the right. Click on the “New trigger” button

Fig. 12. Adding a new trigger

3. A new popup will show, with a few fields to fill in.

1. Action: Execute Javascript
2. When: Timeline Starts
3. Object: the slide (will be selected by default)

Fig. 13. Fields filled in to create the Scenario trigger

4. Next, click on the “…” button beside Script, and a textbox will appear. Paste the following code in the textbox, then click “OK”

5. The last step is to set the variables required to integrate Scenario and Storyline (there are instructions on how to do that in section 2.1 of this guide).

Appendix II: Sending a score from Storyline to Scenario

It is also possible to embed one or more Storyline modules within Scenario, and have Scenario receive a score from Storyline. This is useful when including multiple quizzes in a single room as mediaboards, to report back a unified score to the LMS.

The Storyline side

First, each quiz will need a variable in which to keep track of the score itself. One can be created by following section 2.1 of this guide. We will call the example variable “ExampleScore”.

Then, to send the score from Storyline to Scenario, a button that will trigger the following Javascript is required:

That’s it! You can publish the project (see section 2.2) and when the user clicks on the button just created a message will be sent to Scenario with the score.

The ChatMapper side

In ChatMapper, a listener is required to receive the score and trigger the appropriate actions. It is advisable to set this up in the first node of the first conversation the user goes through, to ensure the event listener is registered.

The code to add in the “Script editor” of that node follows; here is a handy image to show where the script editor is in relation to other ChatMapper interface elements (in the lower left).

Fig. 15.The ChatMapper Script Editor

And here is the script

A few things to note about this snippet:

• Note 1: eventName (“SCEscore” in the example) must match eventName in the snipper right before this one, in the “The Storyline side” section.
  
• Note 2: the actions to be triggered when the score is received (in the case of this example, to be triggered only if the score received is higher or equal to the passing grade score, set as 60) are arbitrary: a full list of actions can be found in our Scenario Actions guide.
  
• Note 3: “task_code” is the task’s shortcode, and can be found in Trophio. If you are not familiar with that part of the Hyperspace Metaverse Platform and wish to introduce gamification within your experiences, please refer to our guide to Trophio.

A note on scoring: if more than a single Storyline module is included in a Scenario, their score will need to be reduced to a single one (Scenario can only submit a single score to the LMS). It is therefore recommended to have a consistent scoring system (such as, for 5 different modules, having each of them contribute a maximum of 20 points to the score).

The Scenario side

For the last part of the integration, some sort of trigger to show the Storyline module is required within a space – usually clicking or tapping on a mediaboard. Including it is quite straightforward:

1. Go to the space that should include the module (make sure to be logged in and of having editing permissions – a crown 👑 will appear next to your avatar’s name, but it’s exact appearance will vary depending on the platform).

Fig. 16.Crown besides the avatar’s name

2. Click on the “Edit menu” button, and then on “Add mediaboard”

Fig. 17. The edit menu

3. Select “HTML”, and paste the following in the input box.
   Make sure to put the URL of your captivate module in the code where “YOUR_STORYLINE_MODULE” is

Fig. 18. Creating a mediaboard

4. Click the green “Embed” button in the popup: a mediaboard will be created in front of the avatar, and is movable by clicking and dragging over it.

And that’s it – any Storyline module can be integrated within Scenario in the same way.

Appendix III: Testing the SCORM integration

The easiest and quickest way to test that a score can be submitted by the platform to the chosen LMS is to create an object in the space, and call submitScore from it.

1. In the edit menu, select “Add content”, then add any model (for instance you can search for “cube”)
2. After the model loaded, enter edit mode, and click on the gear icon

3. In the onclick field, click on “Edit Action”

4. Click on “More” (the rightmost of the blue buttons at the bottom)
5. Select “Custom action” from the dropdown
6. Fill it with the following parameters:

1. Action Name: callFunction
2. name: LB.Lms.submitScore
3. parameter: 100

7. Then click or tap on “Save action”,  then “Save” at the bottom of the previous popup.
8. Exit edit mode.

By clicking on the item now, a score of 100 will be submitted, and you can check that it’s reported correctly in your LMS of choice.