Contact Us Support Forum Get Email Updates
 
 

Thanks! Someone will be in touch with you shortly.

Rather just email us? Email us here.
Rather speak with someone in person?
Call any time with Tin Can questions:

866.497.2676

Sharing documents between courses or learners

This guide relates specifically to implementing Tin Can within traditional e-learning courses created using common authoring tools. Tin Can is also used in more innovative learning solutions. You can read more about documents here.

The Sharing statements between courses guide took you through the process of sending a Tin Can statement from one e-learning course to another. This guide builds on that, so make sure you’ve worked through that guide before attempting this one.

You should use the Sharing statements between courses guide in scenarios where learner actions, such as completing a task or making a particular choice need to have an impact on what happens in a subsequent course. The statements you generate can be used not just by the courses that pull in the data, but also in reports and analytics.

Statements are less appropriate when you want to store data such as settings, preferences or bookmarking data that is less likely to be reported on. For these, you can use documents. These documents might be stored in the Activity Profile API and shared by all learners completing a course, or in the Agent Profile API to be share between courses completed by a single learner. The State API is used where bookmarking data is relevant to a single course and learner; as this feature is covered by most authoring tools we’ll not cover it here.

Sharing between learners

Use the Activity Profile API where you want to store and retrieve data about a single course to be shared between learners. This is useful for team learning experiences to store shared bookmarking data, or competitive learning experiences, for example to store a high scores table. As in the previous guide, you’ll need to design the data you want to store and retrieve and include TinCanJS in your project.

Store the document from learner 1

To store a document to the Activity Profile API, use the following code:

var tincan = new TinCan ({url: window.location.href});

tincan.activity = {
    id: "http://your-organizations.website/tincanapi/activities/unique-id-for-activity"
}

var SomeBookmarkingDataToSave = {
    "customerStatisfactonIndex": 9,
    "budgetSpent": 423
};

saveActivityProfile(SomeBookmarkingDataToSave, "teamScenarioVariables");

function saveActivityProfile(dataToSave, key){
    tincan.getActivityProfile(key, {
        callback: function (err, profile) {
            var activityProfile = null;
            if (err === null && profile !== null && profile.contents !== null && profile.contents !== "") {
                activityProfile = profile;
            }

            tincan.setActivityProfile(
                key,
                JSON.stringify(dataToSave),
                {
                    lastSHA1: (activityProfile !== null ? activityProfile.etag : null),
                    callback: function (err, xhr) {
                        // If we hit a conflict just try this whole thing again...
                        if (xhr.status === 409 || xhr.status === 412) {
                            saveActivityProfile(dataToSave, key);
                        }
                    }
                }
            );
        }
    });  
}

You will need to customize the activity id to match that of your course, the data being saved, and the place that data is saved. You may wish to include the function in your html file rather than adding it within the authoring tool’s interface.

Note that in the event of a conflict (two learners save data at the same time), this code will simply save the data belonging to the last learner to save. More sophisticated approaches to conflicts are possible.

Retrieve the document for learner 2

Retrieving the document to use the data requires much less code:

var tincan = new TinCan ({url: window.location.href});

tincan.activity = {
    id: "http://your-organizations.website/tincanapi/activities/unique-id-for-activity"
}

tincan.getActivityProfile("teamScenarioVariables", {
    callback: function (err, profile) {
        if (err === null && profile !== null && profile.contents !== null && profile.contents !== "") {
            YourBookmarkingData = JSON.parse(profile.contents);

            //Insert authoring tool specific code here.
        }
    }
});

The bookmarking data is returned with the ‘YourBookmarkingData’ variable. You can replace this with a variable within the authoring tool.

Learner preferences and settings

As well as sharing data for a single course between learners, but can share data about a single learner between courses. This is useful for learner preferences and information such as language, volume setting or avatar choice, or for progress information such as points received. This data is saved in the Agent Profile API.

The code for the Agent Profile API is very similar to that for the Activity Profile API, except that we don’t need to specify the activity id. The data is stored against the learner experiencing the course.

Store the document in course 1

var tincan = new TinCan ({url: window.location.href});

var SomePreferenceDataToSave = {
    "AvatarChoice": "Susan",
    "volumeLevel": 11
};

saveAgentProfile(SomePreferenceDataToSave, "teamScenarioVariables");

function saveAgentProfile(dataToSave, key){
    tincan.getAgentProfile(key, {
        callback: function (err, profile) {
            var agentProfile = null;
            if (err === null && profile !== null && profile.contents !== null && profile.contents !== "") {
                agentProfile = profile;
            }

            tincan.setAgentProfile(
                key,
                JSON.stringify(dataToSave),
                {
                    lastSHA1: (agentProfile !== null ? agentProfile.etag : null),
                    callback: function (err, xhr) {
                        // If we hit a conflict just try this whole thing again...
                        if (xhr.status === 409 || xhr.status === 412) {
                            saveAgentProfile(dataToSave, key);
                        }
                    }
                }
            );
        }
    });
}

Retrieve the document in course 2

var tincan = new TinCan ({url: window.location.href});

tincan.getAgentProfile("teamScenarioVariables", {
    callback: function (err, profile) {
        var YourBookmarkingData = null;
        if (err === null && profile !== null && profile.contents !== null && profile.contents !== "") {
            YourPreferenceData = JSON.parse(profile.contents);

            //Insert authoring tool specific code here.
        }
    }
});

Getting help

If you run into any difficulties getting this example working in your authoring tool, please get in touch. Once you have a handle on how this works, you can take it further by pulling in data from other experiences beyond e-learning courses.

Note that to keep things simple, the code samples above don’t include any error handling in case connection to the LRS is lost. It might be helpful to add this in to give your learners a smoother experience in the event something goes wrong.

Having completed this tutorial, take a look at the developer section to diver deeper into Tin Can or go back to the Share statements between courses tutorial.

Questions?

Need a little extra help to implement this in your course?

Contact Us!


Tin Can API Email Updates

* indicates required

Tin Can API Email Updates

Thanks for signing up for the Tin Can API newsletter!

Make sure to follow us on Twitter @ProjectTinCan,
and tweet this page to let others know about the Tin Can API.

Close