CSV Import Templates provide a mapping between the data in a CSV file and either xAPI statements or Watershed people, groups, and permissions. A template consists of JSON definitions of the objects being imported along with template expressions using Handlebars syntax. Template expressions are used to transform CSV values, to insert CSV values into the JSON definition, and to provide logic to modify the JSON definition using data from the CSV file.

CSV Import Templates are processed once for each row of data from the CSV file. xAPI statements and Watershed people objects are usually fully defined by a single row of CSV data.

CSV Import Templates are typically defined to create either xAPI statements, or People/Group/Permission objects. (All of these objects can technically be combined into a single template if the CSV data file contains both types of information, but it's generally best to have separate files and templates). Templates can include sections for any of these objects, as shown in the following examples. Each section is a list of object definitions for that type of object. The order of the object sections does not matter, but there can be only one section per object type.

{{!-- statement template structure --}}

{ 
    "statements": [
        ...
    ]
}

{{!-- people, groups, and permissions template structure --}}

{
    "people": [
        ...
    ],
    "groups": [
        ...
    ],
    "permissions": [
        ...
    ]
}}

{{!-- template with all object types --}}

{
    "people": [
        ...
    ],
    "groups": [
        ...
    ],
    "permissions": [
        ...
    ].
    "statements": [
        ...
    ]
}

CSV Data File Guidelines

In general, a single row of csv file data per statement or person being imported. Or more precisely, a single row of csv file data can define one or more statements, but data from multiple rows cannot be combined in one statement. The same is generally true for Watershed person objects; one row per person. There are cases where the definition of a person can be repeated on multiple rows of the csv file, but in general multiple rows of csv data are not easily combined into a single Watershed person object.

Watershed group memberships and permissions, on the other hand, can and usually are defined over multiple rows of people data. Typically, group memberships for a person are defined by values in specified columns. But looking at it from a group membership view, the definition of a group’s members is spread over many rows of data, one row for each member in the group.

xAPI Statements

xAPI statements are represented in templates exactly as they are defined in JSON. Various properties of the statement can be replaced by values from the CSV data and template logic expressions can be used to modify the structure of the statement based on values from the CSV file. For this reason, you'll need to have a basic understanding of xAPI statements before attempting to create an xAPI statement templates. xapi.com has a great introduction to xAPI statements including the following resources:

• Statements 101 takes you through the basics of statements that you need to know in order to get going with xAPI.
• Statement Explorer is an interactive example statement that explains the high level structure of the statement.
• xAPI Lab is a tool that supports you to build your a statement and send it to an LRS.
• Statements Deep Dive takes you beyond the basics to help you get the most out of xAPI.

Once you understand how to write xAPI statements, read more about xAPI statement templates.

People, Groups, and Permissions

People, groups, and permissions are defined using a simplified JSON version of the person, group and permission objects that are defined for the Watershed API.

Makes sure that you are familiar with the the Watershed concepts for personas, people, groups, group types and permissions before attempting to create a people, groups and permissions template.

Read more about people, groups and permissions templates

Handlebars Syntax

A CSV Import Template is written using a custom version of the Handlebars templating language that has been extended with functions, called “helpers”, that are specific to the needs of defining xAPI statements and Watershed people, groups, and permissions. In Handlebars, expressions are surrounded by double curly brackets, {{ and }}.

Read more about CSV template syntax.