What They Are

A Persona represents an actual person with a combination of zero or more identifiers and attributes, although there should always be at least one identifier. This results in the following structure.

persona-diagram

  • The _id field is a unique Mongo id for an entity.
  • The organisation field references the _id field of an organisation and determines which organisation the persona belongs to.
  • The persona field on the identifier entity and the personaId field on the attribute entity reference the _id field of the persona and determines which persona the identifier/attribute belong to.
  • The name field on the persona entity is usually the name of the actual person.
  • The key field on the attribute entity determines the name of the attribute (e.g. “hair colour”).
  • The value field on the attribute entity determines the value of the attribute (e.g. “brown” when the key is “hair colour”).
  • Finally, the ifi field on the identifier entity references the inverse functional identifier used in statements (such as the actor’s mbox, account, etc).

Why we need them

Firstly, although it’s possible to store attributes within xAPI statements, statements can’t be changed, but attributes can often change over time. Attributes such as “Team”, “Department” or “Role” could easily change as a learner moves within your organisation, so these can’t be stored in xAPI statements. Personas allow these attributes to be added/changed/deleted over time. Using these attributes in Learning Locker, you can include and exclude certain teams in queries and dashboards, that you wouldn’t otherwise be able to do.

Secondly, if you have multiple data sources to your LRS, it’s likely that your learners have multiple identifiers. For example, in one statement from one source they might be identified by an account id (actor.account), but from another source in another statement they might be identified by an email address (actor.mbox). This is often a symptom of systems being adopted at different stages, but it does cause a problem when querying a single source of record like Learning Locker. Personas provide a way to link these identifiers, allowing you to include or exclude all of the statements for a person in your queries, no matter how they’re identified in statements from different sources.

How to use them

Learning Locker provides three interfaces for updating personas, these are the API, the “manage” personas UI, and the “import” personas UI. Our help centre can guide you through the UI, but if it’s a more automated solution that you’re looking for via our API you can view our technical documentation. However, I appreciate that the API can be trickier, so I’ll walk you through some example requests below. Before we begin, it’s worth pointing out that when a new identifier is found in an incoming statement, Learning Locker automatically creates the identifier and links it to a new persona, therefore the first two requests below are usually unnecessary.

So, say we want to create a new persona for one of our learners called John Smith. Simple, we make the POST request below, then Learning Locker creates a persona without any attributes or identifiers, and finally Learning Locker responds with the full persona entity containing an _id for John (see the response below the request)

Request

POST http://www.example.org/api/v2/persona
Authorization: Basic YOUR_BASIC_AUTH
Content-Type: application/json

{
“name”: “John Smith”
}

Response

{
"_id": "PERSONA_ID_FOR_JOHN",
"organisation": "YOUR_ORG_ID",
"name": "John Smith",
"createdAt": "2018-03-05T09:30:04.230Z",
"updatedAt": "2018-03-05T09:30:04.230Z"
}

At this point John won’t have any statements because we haven’t told Learning Locker how John is identified in statements. Let’s imagine that statements are identifying John by their email address (actor.mbox) which is [email protected]. Using this email address and the _id for John we can create an identifier using the POST request below. Learning Locker can then link John with all of their past and future statements. Note that you cannot create identifiers without a persona.

POST http://www.example.org/api/v2/personaidentifier
Authorization: Basic YOUR_BASIC_AUTH
Content-Type: application/json

{
“persona”: “PERSONA_ID_FOR_JOHN”,
“ifi”: {
“key”: “mbox”,
“value”: “mailto:[email protected]
}
}

 

Now we have John linked to some statements, we might want provide some attributes that tell us a bit more about them to group them with other learners. Let’s say John is part of the sales team, using this information and the _id for John we can create an attribute using the POST request below. This will allow us to include or exclude John as part of the sales team in our queries in Learning Locker.

POST http://www.example.org/api/v2/personaattribute
Authorization: Basic YOUR_BASIC_AUTH
Content-Type: application/json

{
“personaId”: “PERSONA_ID_FOR_JOHN”,
“key”: “team”,
“value”: “sales”
}

 

This is great, John is all setup with his attributes and identifiers, but what if we want to add some attributes or identifiers later and can’t remember the _id for John. Well we knew John’s email address, so we can make the GET request below to find the identifier for John’s email address, and from that identifier we can get their persona id (as shown in the response below the request).

GET http://www.example.org/api/connection/personaidentifier?filter={"ifi.value": "mailto:[email protected]", "ifi,key": "mbox"}
Authorization: Basic YOUR_BASIC_AUTH
Content-Type: application/json

{
“edges”: [
{
“cursor”: “EXAMPLE_CURSOR”,
“node”: {
“_id”: “ATTRIBUTE_ID_FOR_JOHN”,
“organisation”: “YOUR_ORGANISATION_ID”,
“persona”: “PERSONA_ID_FOR_JOHN”,
“ifi”: {
“key”: “mbox”,
“value”: “mailto:[email protected]
}
}
}
],
“pageInfo”: {
“endCursor”: “EXAMPLE_CURSOR”,
“hasNextPage”: false,
“hasPreviousPage”: false,
“startCursor”: “EXAMPLE_CURSOR”
}
}

There is a quick overview to get started on making some simple calls to the new interface, we have a Postman collection that contains some more examples for “GET”, “DELETE”, “PUT” and “PATCH”. I hope this encourages you to try to take advantage of this powerful tool and that it opens up new possibilities for your learning analytics.