Ten Steps to Plan & Communicate Your xAPI Design to a Web Developer

If you are an instructional designer beginning to work withthe Experience API (xAPI), you may be wondering how to go about designing anddeveloping an xAPI solution. Some of the authoring tools you use may supportthe xAPI. But the only activities some of these tools track are the samebookmarking, scoring, and completion data that SCORM handles.

To realize the full activity-tracking potential of the xAPIin your design, you will need to collaborate with a web developer who knows howto program and who can manually code the xAPI statements. This article outlines10 steps you can take to plan and communicate your xAPI design to a webdeveloper.

Step 1: Make sure that your technicalpartners understand the Experience API

The first step is to provide your web-development partnerwith information on how to develop xAPI statements. Point your partner to ourcompanion article, Five Things a Web Developer Needs to Know About the xAPI, which provides a technical briefing on what the xAPI is and how it worksas well as more detailed information about the syntax along with some tools andexamples. (Editor’s Note: We also recommend The eLearning Guild’s researchreport The Experience API—Liberating Learning Design, which provides an in-depthexploration of the xAPI’s potential.)

One of the nice things about xAPI statements is that theyare formatted in JavaScript Object Notation (JSON). Your development partnerwill need to know how JSON works, but all you need to know is that it is ahuman-readable programming method—that is, a non-programmer should not have muchtrouble designing xAPI statements.

Step 2: Make sure you have therequired technology in place

First, thoroughly examine the kind of data that yourinstructional design calls for, and then see if you have the right technology to pull itoff. You and your developer must answer the following questions:

• Does your LMSsupport the xAPI?

  If your LMS does not support the xAPI, check with yourLMS vendor to find out whether you can upgrade to a version with xAPI support.If not, then next time your organization upgrades its LMS, make sure xAPIsupport is on your requirements list. Meanwhile, you can acquire a third-partyLearning Record Store (LRS). The addition of an LRS will enable you toimplement your xAPI solution. (Editor’sNote: You can find information about some of the third-party LRS solutionsby opening this link.)

• What types ofreporting and analytics will you need?

  Define your reporting and analyticsrequirements and check your LMS or LRS to make sure it provides the reportingor analytics you have designed for your xAPI solution.

• Are there any ITpolicies or constraints that impact your design?

  Communicate with your IT departmentto ensure that your design aligns with security policies and standards relatedto the use of devices (especially if you plan to support smartphones ortablets.)

Step 3: Develop a communication methodfor your course’s data tracking needs

The sub-steps are as follows:

1. Meet with your web developer to discuss overall goals.While you know best what you are trying to accomplish through your design, yourweb developer may have ideas on how to implement the xAPI statements. There aremany ways to formulate statements and one xAPI verb may have advantages overanother. By approaching the xAPI part of your design collaboratively, yourdeveloper will become better acclimated to your goals and may have some greatideas on how to make them happen.
2. Meet with your developer to agree on a method andformat for documenting and communicating your design. Table 1 below isrecommended. It is an example from the eLearning Guild Research Report, The Experience API — Liberating Learning Design.

   Table 1: (Example) Documenting and formatting an xAPI design

   The Situation column can be used to describe the learneraction that triggers the xAPI statement. The Purpose column describes what isbeing tracked and why. The Actor, Verb, and Object columns are the threecomponents that make up an xAPI statement. This table format will document yourdesign and provide the information your web developer will need to code theJSON version of the statement, place it in the proper location, and ensure theright information is being recorded.

3. Try communicating a sample of your tracking statementsusing this method. Hand it off to your developer and verify that he or sheunderstands your intent and can develop the code to implement it.

As you design your xAPIstatements, be consistent. It is best to use the same verbs to record similaractivities. Establish and document your statement conventions. Using a formatlike the table above is an important step in maintaining and applyingconventions consistently. As you develop more xAPI solutions, your organizationmay benefit from a “data dictionary” that documents your xAPI standards. Thismay seem like a lot of effort, but it may be worth it if you or your enterprisewill be creating many more learning experiences like this one.

Step 4:Discuss verbs you will need

It is important for you to consider the verbs and theirrelationship to objects as you use them in your xAPI statements. Statementsthat convey context are easier to interpret and analyze in reports thanstatements that have none. For example, within an exam taken using a web form,statements like “Jane selected radio button 4” are difficult to interpret. Amore meaningful statement would be “Jane chose assessment option d” because thetype of object is an assessment as opposed to a generic form.

To add even more meaning, you can enter information into thestatement’s context property as in “Jane chose assessment option d (PH), onquestion 3 (What is a measure of the acidity or basicity of an aqueoussolution?) as a part of Chemistry 101 Quiz #1.” When you run LRS reports, youcannot see the labels for the text fields or radio buttons so embedding contextmakes your statements easier to interpret.

As you decide how to buildmeaning into your statements, it is important to define and document your verbsand make sure they are not ambiguous. For instance, the verb “fired” may mean “dismissedsomeone from employment” or “launched a projectile.” You and your web developershould agree on how you will use and define the verbs you use in your xAPIstatements.

Step 5:Pilot test a selection of xAPI calls

Use the table you created inStep 3 to conduct some preliminary testing of the communication between yourxAPI solution and the LRS. Trigger some of the events that send xAPI calls andlook at the resulting statements that the LRS has stored. Don’t wait until theentire solution is developed. Ask your web developer to create a quickprototype for testing.

This preliminary testing willanswer some critical questions. Did the triggers work? Was the data recorded properlyin the LRS? Will you be able to use the LRS data to generate the reports andanalytics you need? Early testing helps ensure that your LRS configuration isworking properly and the design of your xAPI statements is effective so thatyou won’t risk having to backtrack when something goes wrong.

Step 6:Design activity size and flow of your learning experience

Finally, it’s time to sit downand design the full range of xAPI statements. There are now several key areasfor you and your developer to explore.

Activitygranularity and hierarchy

Deciding on the level of granularity is important. You mustconsider the entire context of each activity. Take, for example, the activityof cooking French toast, which consists of several sub-activities:Understanding a recipe, dry versus wet ingredients, beating an egg, dipping thebread, cooking techniques, serving sizes, etc. Is it important to track eachsub-activity in the process or just the final milestone? Think about yourreporting needs. Will it be useful to report on other activities that requirethe same sub-activity (beating an egg) such as making eggnog, scrambled eggs,and egg salad?  If the answer is yes,then you may need to track each sub-activity in the process.

xAPI statements can include an optional context property tohelp tie together higher-level activities with the more granular activitiesthat comprise them. Statements can use context in many ways, but the mostuseful is to reference related activities. Using context within statementsallows your LRS reporting and visualization services to build an “activity tree”of the activities you are recording. For example, the “beating an egg” activitymay be used in thousands of recipes, but by setting its context to referencethe “parent” activity, “Cooking French Toast,” the entire activity of cooking Frenchtoast could be pulled in a report, along with its associated sub-activities.

Granularity and context can work together to move further upthe chain. Let’s say this French toast activity was a part of Cooking 101 at The Culinary Academy. Let’s also say a particular student is in the Fall 2014, Session3 of this class. Creating a specific activity for Cooking 101, Fall 2014,Session 3 may be useful to find all statements within that particular class,but it would be harder to look across all French toast activities at The Culinary Academy. It is important tothink about your reporting requirements as you make decisions about granularityand context.

Does yourdesign require branching?

Clearly, you can use xAPIstatements to collect data about activities the learner performs. Another way youcan use xAPI statements is to trigger adaptive behavior such as branching toelaborate or remediate. Using xAPI statements this way may require two-waycommunication between your solution and the LRS. In other words, your solutionmay need to retrieve information from the LRS to control branching, such aslearner responses to the last few questions. To plan for adaptive use of xAPIstatements, consider working with your web developer to create flow charts likeFigure 1 below.

Figure 1: This flow chart is an exampleof one that would help an instructional designer communicate with a webdeveloper when planning for adaptive use of xAPI statements

Does yourdesign require personalization?

Your design may call forcontent personalization, for example to present cases or scenarios that arespecifically relevant to the user’s role, function, or location. This mayrequire retrieval of LRS information about the user’s profile so that you canadapt, personalize, or localize the solution. To do this, you will need todefine “agents” in your statements. An agent is a user account in an LRS. Theagent account allows you to collect and retrieve user-profile information onspecific users. This information may be used to customize the learningexperience for the individual user.

Step 7:Complete the learning-experience design

As you finish the remainingaspects of your design, you and your web developer should think about two keyquestions when deciding on the placement of xAPI statements:

1. At what pointin the learning process should the information and xAPI statement begenerated? For example, some of your statements may be generated before the learning experience tocollect agent information and recommend a specific path to the user. Somestatements will clearly be generated duringthe learning experience to track the user’s learning results. Other statementsmay be generated after the learningexperience to compare your performance to the performance of other users whohave completed the learning activity.
2. Who or what is generating the activitystatement? Most of the time, the information will result from actions taken bythe learner. It may also result from environmental factors such as yourlocation, the retail season, or economic factors. Other actors such as amentor, coach, or observer may also generate activity statements.

It is important to emphasize that, unlike SCORM, xAPI is notpredicated on being used with asynchronous eLearning. xAPI-instrumented eventscan occur within the context of any type of learning experience. Any actor cangenerate them: a system, the learner (or a group of them), an instructor, amentor, a training administrator, etc. For instance, many informal andconstructivist learning scenarios rely on learners self-reporting theiractivities, and self-rating their progress. This can be done through a browserwidget that learners use to record YouTube videos they have watched; an appthat allows users to record that they have visited a certain location (asindicated to them by GPS location detection, for instance); a web form thatallows mentors to record a successful mentoring session; and in other ways. Thelist of possibilities is endless. You and your programmer should work togetherto plan all relevant aspects of the learning experience to get the data youneed.

Step 8:Develop the learning experience

Your developer should now be ready to start working on creatingthe solution, including xAPI calls, if he or she has not already. Once thesolution is completed, be sure to fully test it before deployment.

Step 9:Deploy or implement the learning experience

Deploy the learning experience, including all of thenecessary parts to make the xAPI elements work: LRS and associated dashboards,analytics engines, etc.

Step 10:Learning experience improvement

Congratulations! You havesuccessfully created your solution. From a technical standpoint, you and your collaboratorshave achieved success. However, as an instructional designer your work is notdone.

After you have implemented yourdesign—either as an extension of pilot testing or in the “real world”—you willfinally have data to analyze. What does detailed, aggregated learning-experienceinformation regarding your course’s instructional video tell you about yourdesign? Are learners watching the entire video? Are they re-watching a specificportion? If the video is embedded in a player (e.g., YouTube, Vimeo, etc.) arelearners hitting the “Watch Later” button? Are they sharing the video?

Thinking about the patterns thatemerge from interaction with your designs enables you to improve your students’learning experiences, workplace performance, and, ultimately, contribute to theorganization’s well-being. Additionally, it allows you as a learningprofessional to articulate the return on investment for your interventions.

Conclusion

At this point in the early lifeof the xAPI spec, there are not many tools that automate or de-skill theprocess of planning and creating xAPI calls, especially calls that go beyondscoring and completion data to realize its full activity-tracking potential. Totake full advantage of the xAPI, you will need to work with a web developer whocan write statements and embed them in your learning and performance supportsolutions. We hope that this document will help you and your web developer worktogether effectively to plan and communicate these coding requirements. This 10-stepprocess will help you make important strategic decisions for using xAPI,putting you on the path towards a data-driven learning ecosystem.

From the Editor: Want more? Explore the xAPI at DevLearn!

At DevLearn 2014 later this month there will be two xAPIhighlights. The first is xAPI Hyperdrive, a new competition designed to showcase thebest examples of innovation using the Experience API; it takes place Tuesday,October 28 at 3:30 PM, the afternoon before the conference begins.

During the conferenceitself, October 29 – 31, we offer a brand-new featured track—xAPI in Practice—that is included with conference registration. The xAPI inPractice program consists of a group of sessions that run throughout theconference, offering you the chance to explore real-world case studies showinghow xAPI is being used in organizations today. Learn about the business valueof xAPI and the opportunities it presents to improve your practice.