2A/and you

From Leapspecs

Guide to explaining and documenting mappings to Leap2A March 2010

The objectives of a mapping are twofold:

to note for yourself how you have decided to map things, to guide those who implement Leap2A for your system
to explain to others how you have decided to map things.

The second may well be more challenging. You will need to make explicit things which may not be obvious to others.

Diagrammatic guides can be very helpful and illustrative, but principally, for ease of reference, as well as construction, a tabular format is suggested. However, the mapping is often not one-to-one between system elements and Leap2A elements. So be prepared to use more than one line for a mapping, either several of your elements mapping onto one Leap2A element, or, more likely, one of your elements mapping onto several Leap2A elements.

On your side, you may want to document any or all of (perhaps in columns)

name of field
data type
database table
field name in database table
web page(s) appearing in demo system on which information appears
example content, or (if long) typical length of content

If you have good reasons not to make your database structure public, the essential details (which cannot be kept secret in any case) are

web page(s) appearing in demo system on which information appears, allowing people to refer to the interface
any heading appearing on the page, indicating the nature of the content
example content, or (if long) typical length of content

On the Leap2A side, to be as clear as possible, any of these following may need to be detailed. Remember that there may be more than one Leap2A entity involved in representing something you think of as one entity. If you are mapping to a whole Leap2A item, you need to know:

rdf:type of Leap2A item used to represent this information
title of that item (what do you use for the title?)
what is in the content of that item
any required categories of that item
what links are needed from that item
- the relationship
- the object of the relationship

If you are mapping to a part of an item, you need to know the Leap2A "path", along with any significant types, etc. along the way.

Exactly how you display and document these is a matter of personal choice and style. However, you will only have completed the mapping task when all of this information is decided -- and checked with me and others -- so it really needs to be able to be understood by us.

The mapping task is to some extent iterative. You cannot expect to get it "right" at the first attempt, or to make it communicate perfectly. Therefore, the sooner you start to share and check your mappings, the sooner you will approach something that will actually work for export and import.

Ideally, you would also then document the Leap2A XML to be (or actually) generated for this information. (If you have your own proprietary XML format, this should be shown alongside.)

One further consideration. When you import Leap2A, you will be looking out for patterns matching the patterns you have generated on export. Therefore, make sure that the mapped patterns of each of your different elements are distinguishable. Even just one different category may be sufficient to distinguish two different patterns; or the presence of a particular kind of link to a particular other kind of item. Try to find other systems that have similar information, and be sure to use the same ways of doing the same things as other people have used.

You are welcome to discuss your mappings with me at any convenient time. Then you should also check with other PIOP partner projects. Then implement your export, and give examples of the resulting Leap2A XML (or zip files) to established partners to see what they make of it on import.

Please keep the latest version of your mappings available on your PIOP 3 web page. Remember that this is publicly available, so please don't put confidential information anywhere on your PIOP 3 page. Look at other people's mappings, and look at your own from other people's point of view. Feel free to ask questions about other projects' mappings.

Principles

The first task before exporting or importing information is to map the information on your system to Leap2A in a way that will be most comprehensible to others using the specification.

First, a few general principles which might help orient you to the recommended approaches.

Focus on what constitutes a Leap2A item - each item is represented as an Atom entry. Remember that the preferred view of Leap2A information consists of portfolio items linked by meaningful relationships.
If there is a choice of using one or two items, one is preferred. Unnecessary items are generally liable to be confusing.
If Atom does things a certain way, we try to go with that. See elements. E.g. a title means just a title or heading; content should be just content or description.
Hierarchical structure is discouraged unless necessary.
- Meaningful relationships and/or categories are preferred.
- Use selections only when there is no better way.
- In particular, try to avoid selections of type Grouping or Folder unless they are very clearly justified.

Mapping

This section is intended to help you think about the portfolio information in your system in a way that will be easiest to map onto this specification, and then to identify the right types, relationships and categories for each item. Mapping is very unlikely to be completely obvious, because with information as soft and complex as this, there will often be several ways of mapping the same thing. The purpose of the guidance here is to help people to find the same way.

Finding the right granularity of item

In the page on structures some ideas were given about how portfolio information is understood in terms of this specification. Taking this forward, let us consider any "chunk" of information that may be recorded in a portfolio or related system, and find the right granularity to fit properly with this specification.

Firstly, can parts of the chunk be reused separately and independently? For example, perhaps you have a structure where a number of actions or activities are listed. If the list is simply one piece of text, you cannot easily break it up and it will have to remain as a whole. But if the actions are stored separately, it is possible that each action could be thought of separately, one action could be changed, replaced, or left out independently of the others. In these latter cases, your original chunk is too large, and needs to be split into its parts.

Now it may be that the large chunk simply consists of smaller chunks, with nothing left over. More likely, perhaps, is that there are a set of smaller chunks, and something in the middle that holds them together. This is fine: there are structures in this specification that allow you to handle that case well, including the selection entry type.

Secondly, and conversely, does your chunk of information mean anything by itself? A date, by itself, means nothing. A title is lost without being attached to the thing it is the title of. If your chunk means nothing by itself, it is probably too small, and needs to be bound together with enough other things so that the set of information has independent meaning.

But this is not quite always true, and this is the exception. Often, perhaps in personal development planning, there will be a set of related questions with text answers. For example, your system may invite learners to reflect on different aspects of a particular experience. Because of the way that the questions are introduced, the resulting short pieces of text - perhaps down to one sentence, or even just a phrase - may make no sense out of context. In order to convey as much as possible of the structure of these answers, each answer needs to be represented by itself, with relationships and categories put in to clarify as much as commonly possible the role of each piece of text in context.

As a rule, one portfolio item, in terms of this specification, can only have at most one piece of independent text, which is its main content or description. All other pieces of text that are stored separately need to be represented as independent portfolio items.

When you have broken down, or lumped together, the portfolio information in the ways described, you will be left with a set of related portfolio items that can be represented in terms of this specification. An attached file is a special case. A file by itself may be referred to by portfolio items, but to integrate best into the rest of the portfolio information, a file really needs to have some information about it recorded in a format which fits in with the rest of the portfolio information. Information about a file will normally be a resource in terms of this specification, unless the file stands in for the content of another item. The file and this resource information can be thought of together: in fact for the rest of the process here the file itself need not be considered, as it will be the resource (or other item) information which will have type, relationships and categories.

Which type of portfolio item is it?

If it is information about a digital artefact - that is, effectively, a file - the type will usually be resource. The only exception to this may be that a file is simply the content of another item, and these are discussed now.

If the item is a piece of text that is not the (main) description of some particular thing, then the item will be represented as an entry. This will become clear only after considering whether it fits into any of the other types.

At this point, you can refer to the page on types and see which type fits best. You will want to consider the relationships which the item has with other items, and the categories which may fit it. However, there are some tricky cases where some guidance may be of help.

Achievement, activity, or plan?

These types can be easily confused. If I want to walk up a hill, is that a planned activity or an actual plan? If I walked up a hill, was that an achievement or a past activity? It is particularly difficult to distinguish when the item is described, as here, by a short phrase or sentence.

But there are clear logical distinctions that can be made. Activities take time; achievements are states of the world that have been reached; plans include a goal to achieve in the future. That is, activities have two associated dates, for a start and for a finish, while achievements have only one, the time at which they were achieved.

In that something has distinct start and finish times, it must be an activity or plan of some kind. The walk itself, if planned, is a planned activity, which could be part of a plan. Clearly it could be planned to start at a certain time, and expected to finish at a certain time. If in the past, it will have definite start and finish times. The related goal could be reaching the top of the hill (and return safely). If the goal is just to walk up the hill nearby, that may not need much of an explicit plan, but if it is climbing a Himalayan peak, it will need a plan, which may comprise many activities, and when it is achieved, you may well want to count it as an achievement.

Plans, which are very significant in much portfolio-related practice (e.g. in personal development planning) do complicate matters slightly. Because a plan is associated with a goal, it may have a target date for completion. On the other hand, the execution of plans takes time, and involves several activities that take time, and these activities will have an overall start and finish date, which can be associated with the plan.

The important thing is to try to distinguish these types in a clear way that is likely to be the same as the way other people distinguish them. If something is going to count as an achievement, then it is likely to deserve a plan. In this version of Leap2A, the goal of a plan is represented by an entry which expresses the goal, as a desired state. This is (hopefully) similar to the way in which the achievement would be described when it is achieved. Anything that is not, or is not going to be, counted as an achievement may safely be regarded just as an activity or action. Small action points, or steps if you like, may just look like sub-goals, particularly if they have no times attached to them, but as they may actually have start and finish times, it will work to represent them as activities.

Ability

One of the confusing things about abilities is the many terms that can be used, including skill, competence, and competency. Though distinctions may be made, all of these are about what someone may be able to do, possibly in certain circumstances. Qualifications are also related, but perhaps slightly more complex. A qualification is evidence that a person has demonstrated certain knowledge or abilities in certain defined situations, assessed in a particular way.

There are two positive ways a person may relate to an ability. Someone may aim to acquire or achieve an ability, or they may claim to have (or not to have) that ability. These are clearly closely related, but equally clearly opposite in meaning! For representation of portfolio information, it is essential to distinguish these two unambiguously.

A safe way that is the basis of representation for this specification is to represent the ability as an impersonal definition. Thus, an ability as such is not the statement "I can ride a bicycle", but something more like "able to ride a bicycle (along a road safely)".

The statement "I can ride a bicycle" is a claim, which is represented in this specification as an entry. This claim may have evidence attached. Obvious things to attach as evidence would be a video of you riding, or a statement from a reliable witness. However, it is also common practice, which can be represented in this specification, to skip the claim itself, and simply to record as evidence things that are evidence of the ability, with the tacit assumption that the portfolio holder is claiming that ability.

Structured questions

Particularly with materials that are more guided, perhaps for younger people, often one sees much material entered by a user that is essentially in answer to some questions. Each answer may not make much sense by itself. Sometimes the answers are short one-liner pieces of text; sometimes they are not text at all, but check boxes or selections, as in some questionnaire responses.

Examples may help: try looking at the Leap2A case study 1.

In Atom there is no smaller unit for a text answer than the atom:entry, so for text questions/answers, create a separate entry for each question/answer. Put the question, if less than about 80 characters, in the atom:title element. If the question is longer, put a short version in the title.

If the question/answer pairs are understandable on their own, and they relate to a substantial item such as an activity, just have them as separate entries, with a link rel="leap2:supports" to the main item. This is a very general idea of supports, in that the questions and answers support the understanding of the activity.

Alternatively, if there is more context that is needed to allow understanding of the answer, or if the questions are long and involved, if there is more than one answer on a page, and if there is no main item to relate them to, create a selection with a category of Grouping. Put contextual material in the selection content, and have each separate question/answer as "part of" the Grouping selection.

Non-text answers can be handled in a similar way, with a separate entry for each answer. The title of the entry can be the question, and in the content, put a text representation of the answer. Each answer entry can additionally have a category, which makes the answer unambiguous, and is more likely to map onto the answer to a similar question than plain text.

There is another pattern that could be considered for more complex questions. The question itself can be given as a separate entry, with care being taken to ensure that the author of that entry is not the portfolio holder, but rather the system, the host institution, or someone with authority in the host institution. The answer can then be given "in reply to" the question. This could even be used for questionnaire-type sets of questions with non-text answers. The questionnaire could be given as the question entry, and the answer entry could have one category for each answer. The categories would have to be specially constructed for each question and answer.

Should the information be exported at all?

However, having given ways of representing this kind of information, people implementing this specification are also advised to consider whether or not it might be acceptable not to include such information in an export. A good test of this is to ask yourself, about the information in question

can it be recreated fairly easily in a new setting
would it be difficult to reuse in any way in a new setting.

If the answer to both these question is, yes, then it is probably not worth exporting the information in the first place. This is not the only test. You may want to consider other criteria for whether certain information should ever be exported as Leap2A.

Exporting Leap2A

Adding literal metadata

Once you have established the type of a given item, you need to add required sub-elements to it. Start with the literals applicable to all Leap2A/types. Atom's title is mandatory, as is id (guidance given elsewhere). Author must be given for an entry if it is not for the feed as a whole.

Then move on to the appropriate type in the type specifications where further guidance is given. This in turn links on to considering the Leap2A literals.

There are two special cases for literal metadata. The first are items of type person, which have a special set of personal data defined. Similarly, items of type organization have organizational data.

Usually, the content will be the main place where the textual information about an item is represented - perhaps its description. If you have a sophisticated e-portfolio system, you may allow your users to create pages which refer to other items of theirs. In this case, you will need to think about the structured content considerations.

Noting the relationships

After determining the literal metadata, you will need to add the relationships as atom:link sub-elements to the entry. Relationships are a vital part of portfolio information in general, and for this specification in particular they are fundamental, as the principle of splitting the information into small items removes much of the possibility for tacit relationships to be implicit in the information structure. So try to include as many relationships as are meaningful.

On the appropriate places in the types page you will see the expected relationships for each item type, and you can click through to see the relevant definition in the relationships page.

Now, there is an issue with whether the relationships are always defined at both ends, or not. Ideally, they would be, so if you can do this, so much the better. However, for an initial implementation, this may be simply too much hard work. In this case, you need to make it clear to partners that you are exporting at least some one-ended relationships. If you do have relationships represented at both ends, the one in one entry must be the correct inverse of the one in its related entry.

On the whole, it is advisable to start by considering whether you can apply the most specific relationships first. These are the ones for meetings, and for threads. Then consider whether one item is considered to be evidence of another. This may be implicit in your system, rather than explicit. If none of the more specific relationships holds, you may consider the support relationship and its inverse, which is relatively general but still directed, or the relation relationship which is completely general and non-directed.

For selection types, that is, anything which is essentially composed of parts, if the parts have a significant order, you may want to introduce the display_order and when_added attributes to part links. See the appropriate part of the relationships page.

Packaging exports with attachments

Where Leap2A exports have any attached files, the complete export shall be represented in one "zip" file.

There shall be exactly one Atom feed per zip file
The Atom feed shall be called "leap2a.xml" and shall be in the root directory
Relative URLs shall be used within the Atom feed to refer to any attached file
There is no further restriction on the file, folder or directory structure within the zip archive.

It was decided not to use IMS Content Packaging as the overhead was not justified.

Importing Leap2A

The overall task for systems importing Leap2A portfolio material is, for each set of related information, to identify the closest corresponding structure within their system, and then to populate it with the information presented.

For some Leap2A items, this will be fairly straightforward. For instance, if your system holds meetings as a particular type of thing, and if a Leap2A meeting is encountered, there is a good chance that the information relating to the Leap2A meeting will slot into your meeting structure. You will know roughly how much it does through you knowledge of exporting your meetings in Leap2A representation.

But for other items, particularly Leap2A entries, it may be less immediately clear where the information goes. You may need to take into account not only the type (in that case, an entry), but also some of the relationships and possibly categories.

Leap2A information does not have a defined order, and in any case, whatever order the information comes in, there can be no guarantee that all items will be defined before being referred to. Hence, before putting the information into your database, it will make sense to construct an overall map of the information, with a first pass through it, so that at a second pass, it will be clear what everything relates to and therefore where it should go.

For example, one could first build some temporary database tables.

One table would be the entry id and type table, where each atom:entry had noted

its ID (which would be unique)
its rdf:type

A second table could be a link table. For each atom:entry/link one could have

the relationship type
the source entry id
the destination entry id

Because the relationships can be noted at either end or both ends, it would be a good idea to go through at some point filtering out duplicate inverse relationships, where the same relationship between two entries has been noted using inverse relationships.

A third, category table may or may not also be needed, which would have

the entry id (not necessarily unique)
the category scheme-term, made up by concatenating the scheme and the term strings

Relationship directions

It was noted above that some systems may not export all the relationships bidirectionally. For these systems, there may be a relationship one way, but not the other way.

A superior, sophisticated importing capability will be able to handle unidirectional relationships. A simple one may not, or may be able to handle only some unidirectionality. Please ensure that this aspect of your import, as well as export, is fully tested and documented.

Importing information you cannot properly use

On import, it is quite possible that you might come across information in some form that you cannot use directly in your system. In this case, the general advice is that any information connected to an entry that is not used in the importing process or represented in the importing system may be appended to the content of the entry, so that it is readable by the user.

This clearly includes relevant start, end or target dates, if your system doesn't have them, but also may include the more subtle information from categories or relationship links. However, there is no general or algorithmic way of doing this: you should decide on how to serve your users most appropriately.

Individual approaches

These should be documented in, or linked from, the partner pages.