xAPI State

• xAPI State
  • Introduction
    • Simple
    • With Options
  • Save/Retrieve Variables
    • saveVariable
    • retrieveVariable
  • Save/Retrieve JSON Data
    • saveState
    • retrieveState

Introduction

xapi.ly has some utility functions to allow saving and retrieving authoring tool variables or JSON data within and across courses. This utilizes xAPI State, and in xapi.ly these State functions are tied to a particular actor and an activity.

For each type below, there is a Simple version and one With Options.

Simple

This is the minimum needed to use a particular function, and probably the one you'll use most.

Example use case: You want to save values in one course to retrieve in another.

With Options

This provides additional options for callback functions for you to further take action if needed.

Example use case: You want to save/retrieve values between courses, but need to process or handle the data or responses using JavaScript.

• cb(err, response) Function

• isGlobal Boolean

  • If true (default), the variables can be used across independent courses as long as the variables have the exact same name.
  • If false, the variables will use the course's activity ID to save, so it will be scoped only to that course activity. To retrieve elsewhere, you will need to know the activity ID and construct the request manually.

Note

You will want to make sure your variable names are globally unique to avoid conflicts with other courses.

For instance, something like choice1 is perhaps too simple and might be reused by another set of courses with the same audience. courseShortTitle_choice1 (or some other standard convention) is less likely to clash.

Save/Retrieve Variables

Simply supply the variable name used in your authoring tool to the functions. Sending and retrieving (and setting back to the course for use) are handled for you.

Note

You will need to create the variables for each course where you are using them, making sure the names and types match exactly.

saveVariable

Simple

xapily.saveVariable('myVariableName');

With Options

xapily.saveVariable('myVariableName', cb, isGlobal);

Show Full Example

xapily.saveVariable('myVariableName', function (err, response) {
	if (err) {
		// handle error
		return;
	}

	// handle successful response
	console.log('response:', response); // 'OK'
}, false);

retrieveVariable

Simple

xapily.retrieveVariable('myVariableName');

With Options

xapily.retrieveVariable('myVariableName', cb, isGlobal);

Show Full Example

xapily.retrieveVariable('myVariableName', function (err, response) {
	if (err) {
		// handle error
		return;
	}

	// handle response value
	console.log('response:', response);
}, false);

Note for Captivate

When retrieving a variable value which sets back to the course, it may not be saved to the course's new bookmark data immediately; there might need to be a user action (like navigation) to force a bookmark save.

In that case, the retrieveVariable function might be best placed as early as possible to ensure it's fully added to the course's save data.

Save/Retrieve JSON Data

You can use these functions for more sophisticated processing if needed. No authoring tool variables are involved; you will need to handle data manually.

To save you will need to construct your arbitrary data in proper JSON format, and to retrieve you will need to handle the response in the callback function. Currently, saving will overwrite the contents of a preexisting value.

The stateId property can be any valid string, and data any valid JSON structure.

saveState

Simple

const data = { firstName: 'Matt' };

xapily.saveState('myStateId', data);

With Options

const data = { firstName: 'Matt' };

xapily.saveState('myStateId', data, cb, isGlobal);

Show Full Example

const data = { firstName: 'Matt' };

xapily.saveState('myStateId', data, function (err, response) {
	if (err) {
		// handle error
		return;
	}

	// handle successful response
	console.log('response:', response); // 'OK'
}, false);

retrieveState

Simple

This requires a callback to handle the response.

xapily.retrieveState('myStateId', function (err, response) {
	if (err) {
		// handle error
		return;
	}

	// handle response data
	console.log('response:', response);
});

With Options

xapily.retrieveState('myStateId', cb, isGlobal);

Show Full Example

xapily.retrieveState('myStateId', function (err, response) {
	if (err) {
		// handle error
		return;
	}

	// handle response data
	console.log('response:', response);
}, false);