11.9.4. Import a framework file

Administration menu → Extensions → SmartEvidence → Import

You can import a SmartEvidence framework by clicking the Import link in the SamrtEvidence navigation. The framework file must end in the extension .matrix to be recognized and interpreted by Mahara.

Upload a .matrix file that contains a competency framework

1. Click the Import link to go to the screen where you can upload a SmartEvidence file.

2. Click the Browse button to choose the matrix file that contains the framework that you want to use.

3. Click the Upload matrix button to upload the file.

The file is checked for issues in the structure of the file. It is rejected if problems are encountered. Most common issues are:

• The short name has more than 100 characters.

• The name of a standard element has more than 255 characters.

• Punctuation or parentheses are not correct.

A JSON validator such as JSON Formatter & Validator or JSON Formatter can usually unearth syntactical errors. Character length errors need to be sorted out manually.

11.9.4.1. Create a framework file

Get started with a SmartEvidence framework by downloading an existing file. You can then make any number of changes.

Notitie

If you created your own SmartEvidence framework files that you want to share with the community, please send them to us for review and inclusion in the download area.

You can use any text editor to create and edit your SmartEvidence framework files. If you have an edit that supports syntax highlighting for JSON files, you have an advantage as you can differentiate text that you can change from prompts that Mahara needs to interpret the file more easily.

You can also use a JSON editor, e.g. JSON Editor Online or JSONedit. These make it easy for you to edit the file because you can view it without much of the JSON syntax that is required.

Notitie

It is best to start your framework file with the help of one of the samples as you then know the structure and have all relevant elements in the file.

11.9.4.2. Start of the file

A framework file contains a number of parameters at the beginning that allow you to customise the framework to your needs.

The start of a matrix file

1. institution: The short name of the institution in which the framework should be used is entered here. If the framework is for all institutions, all is placed here.

   Notitie

   The institution short name can be seen by hovering over the institution name on the Institution overview page and looking at the end of the URL. The last parameter is the institution short name.

2. name: The title of the framework as it should be shown to authors.

3. description: The description of the framework is displayed on the SmartEvidence page in a collection. It can contain basic HTML code.

4. If the HTML code in the description field requires the use of quotation marks, these need to be escaped. Otherwise, they would be interpreted as commands. The escaping is done easily by placing a backslash right in front of the quotation mark: \".

5. selfassess: Determine whether people can self-assess their competencies or whether the competencies can only be assessed by somebody else. The following two values are allowed:

   • true: Authors can self-assess.

   • false: Authors cannot perform self-assessment.

6. evidencestatuses: Currently, there are four evidence statuses that can be used in an evidence map: begun, incomplete, partially complete, and completed. You can decide what words are used for these statuses in the framework that you set up. For example, this allows you to easily set up frameworks in different languages.

7. standards: The rest of the document holds the standards and sub-standards.

Notitie

Be careful when changing a matrix file. Make sure not to remove any commas, quotation marks, brackets, curly braces, or any other marks in sections that you use. They are required for the correct interpretation of the file.

You can check if your file contains all necessary syntax by pasting it into the JSON Formatter and Validator for example. If there are any issues and JSON cannot interpret your file, the validator specifies the places where the errors occur so you can track them down more easily and fix.

11.9.4.3. Standards section

You can define the standards after the initial information. They provide the heading level on the SmartEvidence overview page.

The standards in a matrix file

1. standards: Introduction of this section. You can define as many standards as you want. There is no limit.

2. shortname: Each standard needs a short name, e.g. a number or a summary of the full title. The short name is mandatory and a maximum of 100 characters long.

3. name: Title of the standard. It is mandatory and a maximum of 255 characters long.

4. description: The description is optional and is displayed when you hover over the name of the standard (touch-click on mobile).

5. standardid: Give each standard a natural number so they can be placed in the correct order and referred back to from the standard elements.

6. Do not place a comma after the closing curly brace of the last standard.

11.9.4.4. Standard elements section

Define all the standard elements, i.e. the individual sub-standards after the standards. They are the ones to which you can add evidence.

Notitie

Place all sub levels immediately after the higher level standard element so that the mapping is happening correctly.

The standard elements in a matrix file

1. standardelements: Introduction of this section. There is no limit on how many standard elements you can define.

2. shortname: The short name is displayed on the SmartEvidence overview page. It is mandatory and a maximum of 100 characters long.

3. name: Title of the standard element. It is mandatory and a maximum of 255 characters long.

4. description: The description is optional and is displayed when you hover over the name of the standard element (touch-click on mobile).

5. standardid: Provide the ID of the standard to which you want to associate a particular standard element.

6. elementid: Give your standard element an ID so you can refer to it when you have another sub level. The ID needs to be placed between quotation marks.

7. parentelementid: Provide the elementid of the parent standard element if the standard element that you set up is on a level lower. The ID needs to be placed between quotation marks.

   Notitie

   When a standard element has a lower level, it cannot be associated with evidence itself, but only the standard elements on the lower level.

11.9.4.5. The end of the file

When you defined all your standards and standard elements, you can end the file.

The end of a matrix file

1. Do not put a comma after the last curly brace of the last standard element.

2. Make sure to close all angular brackets and curly braces.

11.9.4.6. The result

Once you finished the file, you can import it into Mahara and start using it.

The finished result once uploaded

1. Title of the framework

2. Description of the framework

3. A standard. It cannot have evidence associated, only its lower levels.

4. A standard element.

5. A standard element with further lower level elements. It cannot have evidence associated, only its lower level.

6. A third level of elements.

   Notitie

   You can have more than 3 levels in your competency framework. The readability decreases though with many levels.