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 recognised 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.

Note

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 editor 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.

You can also use a JSON editor, e.g. JSON Editor Online. You can view your file without much of the JSON syntax.

Note

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 (version 1)

Note

SmartEvidence version 1 and version 2 differ only in the general setup, but not in the standards and standard elements.

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 for SmartEvidence version 1

  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.

    Note

    You can see the institution short name on the Institution overview page.

  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 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 set up frameworks in different languages.

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

Note

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 and fix.

11.9.4.3. new in Mahara 24.04 Start of the file (version 2)

The main differences between version 1 and version 2 of SmartEvidence for the setup are:

  • Self assessment can be mixed with external assessment.

  • A total of five assessors, including the learner themselves, can be defined. These can correspond to different roles in Mahara.

  • An assessor does not have to have the ‘Staff’ role any more.

Note

If you want to transform a file you created earlier into a SmartEvidence version 2 file, you only need to adjust this general section, in particular:

  • self-assess

  • version

  • evidencestatuses

The start of a matrix file for SmartEvidence version 2

  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.

    Note

    You can see the institution short name on the Institution overview page.

  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 by placing a backslash right in front of the quotation mark: \".

  5. selfassess: Determine whether people can self-assess their competencies alongside other assessors. The following two values are allowed:

    • true: Authors can self-assess.

    • false: Authors cannot perform self-assessment.

  6. evidencestatuses: This section contains the information about the different roles that can assess a SmartEvidence version 2 collection. You can have up to five assessors, including the portfolio author themselves. If you want to have fewer than five assessors, only put as many sections into the file as you need, ensuring that they all follow the correct formatting.

  7. Evidence status role section: Each section consists of the following:

    • title: Give your role a title.

    • mahara_roles: Decide, which system role or roles the person must have to perform the assessment. Possible are:

      • member: A regular account holder

      • institutionstaff: A person with the ‘Institution staff role’

      • institutionsupportadmin: A person with the ‘Institution support administrator role’

      • institutionadmin: A person with the ‘Institution administrator’ role

      • staff: A person with the ‘Site staff’ role

      • siteadmin: A person with the ‘Site administrator’ role

    • begun: The status that indicates that there is evidence mapped against this standard element. The text can be different for each role.

    • incomplete: The status that indicates that the evidence mapped against this standard element doesn’t meet the criteria. The text can be different for each role.

    • partialcomplete: The status that indicates that there is not sufficient evidence mapped against this standard element or that it only partially meets the criteria. The text can be different for each role.

    • completed: The status that indicates that the evidence mapped against this status element is sufficient to meet the standard. The text can be different for each role.

    • new in Mahara 24.04 merit: The status that indicates that there is more than enough evidence mapped against the standard element. The text can be different for each role.

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

Note

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 and fix.

11.9.4.4. 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.5. 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.

Note

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.

    Note

    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.6. 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.7. 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.

    Note

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