MoodleDocs - User contributions [en]

Competencies

2010-11-25T19:22:14Z

Janvh: /* "Add / edit competency depth" admin page */

{{Moodle 2.0}}'''Note''': This page outlines ideas for the Competencies feature planned for Moodle 2.0. It's a ''specification under construction''! If you have any comments or suggestions, please add them to the [[Development talk:Progress tracking|page comments]].''

* '''PROJECT STATE: Proposal'''
* '''MAIN TRACKER ISSUE''':
* '''DISCUSSION''': Not yet announced on Moodle.org
* '''COMMENTS''': [[Development_talk:Competencies]]
* '''AUTHOR''': [[User:Jonathan Newman|Jonathan Newman]] with help from [[Matt Clarkson|Matt Clarkson]] and others

=Overview=
To support the range of different types of competency frameworks used by organisations, competencies in Moodle 2.0 needs to expand on the 1.9 outcomes architecture.

==Goals==
# Measured amount of abstraction
#* Allow "admins" to organise competencies in a hierarchy
#* Allow "admins" to create unlimited hierarchical levels
#* Allow "admins" to map related competencies on a given depth level
#* Allow "admins" to define custom info fields on a given depth level
# Easy navigation
#* Allow "admins" to view the competency structure
#** Expanding/collapsing competencies
#** Sorting/searching/filtering by competency meta data
#* Allow "admins" to easily add new competencies and meta-data
# Linking competencies and evidence items
#* Allow "admins" to easily attach allowed evidence (course, activity, etc) to a competency (from a ''site-level competency view''):
#* Allow "course creators" to attach competencies to evidence ''within a course'':
# Portability
#* Allow "admins" to import competencies (using import plugins) into a Moodle install
#* Allow "admins" to export competencies (using export plugins) from a Moodle install
# Specifying expected proficiency levels
#* Allow "admins" to assign an expected proficiency level (i.e., competency scale value) to a competency and a competency evidence item
# Aggregating measured proficiency
#* Allow "admins" to specify aggregation methods for each competency
#* Reporting
#** Allow "admins" to view competency results for all students
#** Allow "teachers" to view student measured proficiencies related to evidence in his/her courses.
#** Allow "students" to view their own competency results (via either their personal profile or My Moodle).
# Specifying weights
#* Allow "admins" to assign weight to a competency or a competency evidence item
# Scalability
#* Store and retrieve data efficiently to allow the scalability to very large numbers of courses, users, competencies, evidence, etc
# Extensibility
#* Use a plugin architecture for evidence types

==General requirements==
# We'll need to access and use the existing site-wide Outcomes [https://docs.moodle.org/en/Development:Grades#grade_outcomes Outcomes tables]
# We'll need to use the tables that indicate completion status for courses (these are not yet in place) [https://docs.moodle.org/en/Development:Course_completion Course Completion]
# We need to get aggregate information about the course outcomes and aggregate grades for each user from the gradebook API

==Definitions==
'''Scale''': A way to measure a competency using scale values.

Example scales:
"Average-based scale"
"Competency-based scale"

'''Scale values''': Descriptor or numeric values that comprise a scale. A scale value can have a id number (code) and description.

Example scales values (with descriptors and numerical values) for the scale examples above:
"Below average [1], Average [2], Above average [3]
"Not yet competent [0], Competent [100]"

'''Competency''': A measurable knowledge, skill, ability, attitude or other learning-related characteristic which a student may have. Competencies can be organised into a hierarchy.

Example hierarchy of competencies:
top-level competency: "Literacy"
-> child competency: "Reading Comprehension"
-> child competency: "Responding to Text"
-> child competency: "Initial Understanding of Literary Text"
-> child competency: "Demonstrate initial understanding of elements of literary texts (including text read aloud, reading independently"

'''Competency evidence type''': A form of evidence that can be accepted as evidence that a competency has been achieved. Examples:
Activity grade
Activity completion
Activity outcome
Course completion
Course grade
File (diploma)

'''Competency evidence''': A competency can be measured by one or more competency evidence types. Evidence can be stated to include the evidence type, evidence date, and measured value. Examples:
"Quiz - 4:00pm May 28, 2009 - Grade 90% out of 100%"
"Certificate - Public Speaking Institute - 4:00pm May 28, 2009 - Passed."
"File - College Diploma - 4:00pm May 28, 2009 - Bachelor of Science Computer Science"

'''Expected proficiency level''': The expected (or required) rating (based on a scale descriptor or numerical value) for a competency. Examples:
"Average"
"5"
"50%"
"Passed"

'''Measured proficiency level''': A user's observed, scored, reported proficiency level for a competency.
"Above average"
"8"
"80%"
"Passed"

'''Competency weighting''': Child competencies can be assigned weights which can be used for aggregating either sums or averages of child competencies. Examples:

Example with percentage weights
-> top-level competency: "Communication"
-> child competency: "Written Communication" : weight: 60%
-> child competency: "Oral Communication" : weight: 40%

==Example frameworks==

'''Example 1:''' Competency hierarchy with activity outcomes as evidence

The example data below is based roughly on the [http://education.vermont.gov/ Department of Education for the State of Vermont]'s [http://education.vermont.gov/new/html/pgm_curriculum/literacy/gle.html Grade 1 Expectations for Literacy] for Reading.

{| border="1" cellpadding="2" cellspacing="0"
|'''Depth level'''
|'''Depth name'''
|'''Competency'''
'''full name'''
|'''Competency'''
'''evidence'''
|'''Competency'''
'''aggregation method'''
|'''Competency
'''weight'''
|'''Competency'''
'''proficiency expected'''

|-
|0
|"Curriculum"
|"Literacy"
|none
|all
|20%
|80%

|-
|1
|"Type"
|"Reading"
|none
|all
|20%
|100%

|-
|2
|"Standard"
|"Standard 1.1 Reading Strategies"
|none
|all
|20%
|80%

|-
|3
|"Strategy"
|"Early Reading Skills and Strategies: Phonological Awareness"
|none
|all
|100%
|80%

|-
|4
|"Code"
|"RK: 1 - Applies phonological knowledge and skills by..."
|activity outcome "Recognizing pairs of rhyming words and producing rhymes"

activity outcome "Blending and segmenting syllables and onset-rimes"

activity outcome "Isolating phonemes in single-syllable words (e.g., "tell me the first sound in 'mop' "; "tell me the last sound in 'mop,'" "tell me the middle sound in 'mop'")"
|all
|50%
|80%

|-
|3
|"Strategy"
|"Early Reading Skills and Strategies - Concepts of Print"
|none
|all
|50%
|80%

|-
|4
|"Code"
|"RK: 2 - Demonstrates understanding of concepts of print during shared or individual reading by..."
|activity outcome: "Distinguishing between printed letters and words"

activity outcome: "Following text with finger-pointing (e.g., charts, simple books), demonstrating left-to-right and top-to-bottom directionality"

activity outcome: "Identifying the first and last parts of a word (beginning/end of the word)"

activity outcome: "Identifying key parts of a book: front and back, print, illustrations"

|all
|50%
|80%
|}

See [https://docs.moodle.org/en/Development:Competencies_example here] for how the data above fits into the proposed schema.

=Settings=
==Site settings==
[https://docs.moodle.org/en/Development:Conditional_activities#Completion_tracking_2 Activity Completion] provides an "Enable outcomes" setting (found in the Site Administration block's Advanced features / optional subsystems settings page). We need to keep outcomes, however we will need to add competencies.

'''Proposed changes:'''
* Create a new setting named "Enable competencies" (the setting will allow competencies to be defined)

=User interface=

==Site Administration block==
When competencies are enabled, a "Competencies" menu item should appear in the Site Administration block. An "Add / edit competencies" option should appear when "Competencies" is clicked. The "Add / edit competencies" will point to the "Add / edit competencies" admin page.

=="Add/edit competencies" admin page==
[[Image:Competencies_add_edit_default.png|thumb|400px|Mockup of the Add/edit competencies admin page (default)]]

[[Image:Competencies_add_edit.png|thumb|400px|Mockup of the Add/edit competencies admin page (with competencies from Example 1 framework)]]

An "admin" can use this page to add and edit competencies and competency depth levels, using buttons and features available in a table.

'''Buttons'''
* An "Add a new competency" button will link to the "Add a competency" admin page.
* An "Add a new depth level" button will link to the "Add a depth level" admin page.

'''Table rows'''
* A "plus" / "minus" icon will appear on the right of each row in the table, allowing all child competencies to be shown or hidden.

'''Table columns'''
* A default, top-level competency depth named "Competency" will appear in a table as a column on the left. The default competency depth name can be changed (e.g., "Competency Area", "Standard", "Development Area", etc).
* When a new competency depth is added, it will appear as column to the right of the next highest competency depth level.
* Appearing to the right of the competency depth level columns will be the following "standard" interface columns: "Evidence items", "Edit", and "Move competency to".

Below are more specifics on the table columns and content:
* ''[Competency depth level 0 name]'', ''[Competency depth level 1 name]'', ''[Competency depth level 2 name]'', ... ''[Competency depth level n name]''
** Columns of depth levels will be ordered from highest/top-level (on the left) to the lowest (on the right).
** An edit icon will appear beside each competency depth name, and will link to the "Edit competency depth" page (which will allow an "admin" to change the name of the competency depth name).
** The competency name will be displayed, and will link to a page containing meta data and possibly summary proficiency achievement stats about the competency.
* ''Evidence item''
** By default the number of evidence items will be "0". The number shown will link to the "Add / edit evidence items" admin page for the given competency.
* ''Edit''
** Three icons appear providing the following functionality:
*** "edit" icon points to the "Edit competency" page for the competency
*** "delete" icon points to a confirmation page for deleting the competency
*** "up" / "down" icons will appear beside child competencies when a parent has two or more child competencies. A competency can only be moved up or down with respect to a parent competency.Only the down arrow will appear for the highest child competency, and only the up arrow will appear for the lowest child competency.
* ''Move competency to''
** A drop down menu appears containing all parent competencies at the next highest depth.
** Competencies can only be moved from one parent to another parent in the same depth level.

=="Add / edit a competency" admin page==
[[Image:Competencies_add.png|thumb|400px|Mockup of the Add competencies admin page]]

An "admin" will use this page to add or edit a new competency, with the following settings:

''General settings''
* Parent competency
* Competency full name
* Competency short name
* Competency ID number
* Description
* Aggregation method
* Scale
* Proficiency expected

''Custom depth level settings''
* Form elements based on custom fields for selected depth level (based on the parent competency)
* Changing the selected parent competency should update the custom fields shown, if the depth level of the parent changes

=="Add / edit competency depth" admin page==
[[Image:Competencies_depth_add.png|thumb|400px|Mockup of the Add competency depth admin page]]

An "admin" will use this page to add / edit a new competency depth, with the following settings:
* Depth full name
* Depth short name
* Description

Also, the depth level will be displayed

=="Add / edit competency evidence" admin page==
[[Image:Competencies_evidence_add_edit.png|thumb|400px|Mockup of the Add / edit competency evidence admin page with Example 1 competencies]]

An "admin" will be use this page to view / add / edit evidence for a competency. The top of the page should display the existing general data for the competency, the number of "students" who have achieved the competency, and a table showing data and functionality for each evidence item:
* The name of the competency evidence (which links to the evidence item in context, e.g., the course if course completion is specified, etc)
* The type of evidence
* The activity (if the evidence is an activity outcome or activity grade)
* The weight of the evidence
* Options to edit or remove the evidence
* The number of "students" who have achieved the evidence

An "Add new competency evidence" button should link to the "Add new competency evidence" admin page.

=="Competencies summary" user profile page==

[[Image:Competencies_user_profile_activity.png|thumb|400px|Mockup of user profile page with Example 1 competencies]]

An "student" or a user with permission to view a student's competencies will be able to view the proficiency status for each competency as a table with the following columns:
* Competency depth(s)
* Evidence items
* Proficiency
* Scale

Each competency name should link to a pop-up containing the competency details (full name, description, aggregation method, scale, and meta data) and list of evidence items.

Each number of competency items should link to a pop-up containing a list of evidence items.

=Data structures=

[[Image:Competency_data_model.png|thumb|400px|Competencies data model]]

===scale===
Scales (introduced in Moodle 1.9) give a scale value a single attribute: text (i.e., the name of the scale value like "below standard," "meets standard," "above standard"). Scale values can be particularly useful if given attributes including: numerical equivalent, idnumber (code id), and a description. The new attributes will require a new table.

''Proposed changes:'' Create a new table 'scale_values' that includes a foreign key to the 'scale' table, and migrate the 'scale' field values from the 'scale' table (as serialised text) to the 'scale_values' table (as separate records). A sort order field will be used to track ranking (starting with the lowest with a sortorder of 0).

Below is the proposed 'scale' table, and further below is the proposed 'scale_value' table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''courseid'''
|int(10)
|
|Id of the course, which the scale belongs to

|-
|'''userid'''
|int(10)
|
|Id of the user who last modified the scale

|-
|'''name'''
|varchar(255)
|
|Name of the scale value

|-
|'''description'''
|text
|
|Description of the scale value

|-
|'''timemodified'''
|int(10)
|
|Timestamp of when the scale was modified
|}

===scale_values===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''scaleid'''
|int(10)
|
|Id of the scale that the scale value describes

|-
|'''name'''
|varchar(255)
|
|Name of the scale value

|-
|'''idnumber'''
|varchar(100)
|
|Optional id, code number or local identifier for the scale value (used for reporting).

|-
|'''description'''
|text
|
|Description of the scale value

|-
|'''numeric'''
|number(8)
|
|Numerical value for the scale value

|-
|'''sortorder'''
|int(10)
|
|The order for the scale value

|-
|'''timemodified'''
|int(10)
|
|Timestamp of when the scale value was modified
|}

===competency===

A competency can be part of a hierarchy and can have evidence attached to it.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''shortname'''
|varchar(100)
|
|The shortname for the competency

|-
|'''fullname'''
|varchar(255)
|
|The full name for the competency

|-
|'''description'''
|text
|
|The description of the competency

|-
|'''idnumber'''
|int(10)
|
|The id, code number or local identifier for the competency used for reporting

|-
|'''parentid'''
|int(10)
|
|The id of the parent competency

|-
|'''sortorder'''
|int(10)
|
|The order number of this competency (useful for ordering competencies for viewing/navigation/reporting)

|-
|'''depthid'''
|int(10)
|
|The id of the depth level the competency belongs to

|-
|'''path'''
|varchar(255)
|
|The path to the competency

|-
|'''aggregationmethod'''
|int(10)
|
|A constant representation one of the competency aggregation methods (any, all, unit, fraction, sum of weighted, average of weighted)

|-
|'''scaleid'''
|int(10)
|
|The scale used to measure the competency

|-
|'''proficiencyexpected'''
|int(10)
|
|The expected proficiency for the competency, foreign key to the scale_value table's id

|-
|'''timecreated'''
|int(10)
|
|The time when the competency was created

|-
|'''timemodified'''
|int(10)
|
|The time when the competency was modified

|-
|'''usermodified'''
|int(10)
|
|The userid of the person who last modified the competency
|}

===competency_relations===

For tracking relations between competencies.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''description'''
|text
|
|Info about how competencies are related

|-
|'''competencyid1'''
|int(10)
|
|The id of a competency

|-
|'''competencyid2'''
|int(10)
|
|The id of a related competency
|}

===competency_depth===

Data for a competency depth level.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''shortname'''
|varchar(255)
|
|Shortname for the depth level

|-
|'''fullname'''
|varchar(255)
|
|Full name for the depth level

|-
|'''description'''
|text
|
|Description for the depth level

|-
|'''level'''
|int(2)
|
|The actual depth level, starting at 0
|}

===competency_depth_info_field===

Data for a competency depth level field.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''shortname'''
|varchar(255)
|
|Shortname for the field

|-
|'''fullname'''
|text
|
|Full name for the field

|-
|'''depthid'''
|int(10)
|
|The id of the competency depth for the field. Foreign key to the competency_depth table's id

|-
|'''datatype'''
|varchar(255)
|
|The type of field data

|-
|'''description'''
|text
|
|Description of the field

|-
|'''categoryid'''
|int(10)
|
|The id for the field category. Foreign key to the competency_depth_info_category table's id field
|-
|'''sortorder'''
|int(10)
|
|The sort order for the field within its category

|-
|'''hidden'''
|int(1)
|
|The field should be hidden

|-
|'''required'''
|int(1)
|
|The field required

|-
|'''defaultdata'''
|text
|
|Default text for the selected parameter

|-
|'''param1'''
|text
|
|Parameter text

|-
|'''param2'''
|text
|
|Parameter text

|-
|'''param3'''
|text
|
|Parameter text

|-
|'''param4'''
|text
|
|Parameter text

|-
|'''param5'''
|text
|
|Parameter text
|}

===competency_depth_info_category===

A competency's depth level can have categories for its fields.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''name'''
|varchar(255)
|
|Shortname for the depth level category

|-
|'''sortorder'''
|int(10)
|
|The order number for this category

|}

===competency_depth_info_data===

Data for a depth level field.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''fieldid'''
|int(10)
|
|The id for the field

|-
|'''competencyid'''
|int(10)
|
|The id for the competency

|-
|'''data'''
|text
|
|The actual data for the competency field
|}

===competency_evidence_items===

A competency can be achieved by one or more forms of evidence.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''competencyid'''
|int(10)
|
|The id for the competency that this evidence describes

|-
|'''itemtype'''
|varchar(30)
|
|The type of evidence 'course/outcome', 'mod/outcome', 'course/completion', 'mod/completion', 'course/grade', 'mod/grade', 'file'

|-
|'''itemmodule'''
|varchar(30)
|
|The type of evidence 'quiz', 'scorm', etc
|-

|'''iteminstance'''
|int(10)
|
|The id for the evidence instance (ie, grade_outcome id, course id, course_modules id, grade_item id, files id)

|-
|'''weight'''
|num(10)
|
|The weight applied to this evidence item (for aggregation)

|-
|'''timecreated'''
|int(10)
|
|The time when this competency evidence was allowed

|-
|'''timemodified'''
|int(10)
|
|The time when this competency evidence was last changed

|-
|'''usermodified'''
|int(10)
|
|The user who last modified this evidence
|}

===competency_evidence===

Track historical and current competency information for each user.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|auto-incrementing

|-
|'''userid'''
|int(10)
|
|The id of the user

|-
|'''competencyid'''
|int(10)
|
|The id of the competency

|-
|'''proficiencymeasured'''
|int(10)
|
|The measured/evaluated proficiency level for the user

|-
|'''timecreated'''
|int(10)
|
|The time when this competency evidence was started

|-
|'''timemodified'''
|int(10)
|
|The time when this competency evidence was last changed
|}

=Plugin architecture=
'''Competency evidence type plugins'''

Each type of evidence will need its own methods for interacting with the competency architecture and will need to interact via a base competency evidence API. Below are the item types.

* Course completion
* Course grade
* Course outcome
* Activity completion
* Activity grade
* Activity outcome
* File

'''Report plugins'''

Similar to the gradebook, we need to allow development of report plugins for competencies.

'''Import/Export plugins'''

We need to be able to import and export data related to competencies.

'''Competency framework import/export'''
A competency framework should be able to be exported using an appropriate format in either xml and csv file format. There are some standards on exchanging competencies including:
* IEEE P1484.20.1 Standard on Reusable Competency Definitions and the IEEE Draft Standard on Simple Reusable Competency Map
* ISO/IEC PDTR 24763 Conceptual Reference Model for Competencies and Related Objects

'''Competency evidence import/export'''

There are a variety of standards for exchanging competencies evidence including:
* IMS Reusable Definition of Competency or Educational Objectives Spec (RDCEO)
* IMS Learner Information Package Spec (LIP)
* HR-XML Competencies (Measurable Characteristics) Recommendation, 2007 April 15

IMS RDCEO and LIP recommend formats as shown in the examples below (more [http://www.imsglobal.org/competencies/index.html IMS RDCEO here] and [http://www.imsglobal.org/profiles/index.html IMS LIP home]). Special thanks to Sarveswaran Kengatharaiyer (GSOC 2008 student for the Moodle Progress Tracker project) who developed these examples.

rdceo.identifier = rdceo434323
rdceo.title = Identify verbs in simple sentences
rdceo.description = “Identify verbs in simple sentences”
rdceo.definition.statement.
statementid = 123
statementname = Always
statementtext = Scale
statementtoken = scl55435
rdceo.definition.statement.
statementid = 124
statementname = Never
statementtext = Scale
statementtoken = scl55436
rdceo.definition.statement.
statementid = 125
statementname = Sometimes
statementtext = Scale
statementtoken = scl55437

lip.contenttype.referencial.sourceid.id = jenney_profile
lip.identification.cotenttype.referential.indexid = id123
lip.identification.name.partname.typename=Jenny
lip.competency
cotenttype.referential.indexid = j123
exrefrecord = rdceo434323
description = Always

HR-XML recommends a format like shown below in an example which uses recursive competencies (more [http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/Competencies.html#_Toc127531664 here]).
<Competency name="Communication Skills">
<Competency name="Written Communication Skills">
<CompetencyEvidence name="WRITTENTEST1-A" dateOfIncident="1995-01-01" lastUsed="2000-01-01">
<NumericValue minValue="3" maxValue="5" description="SEP-equivalent Skill-Level Range">5</NumericValue>
</CompetencyEvidence>
<CompetencyWeight>
<NumericValue minValue="0" maxValue="100">35</NumericValue>
</CompetencyWeight>
</Competency>
<Competency name="Oral Communication Skills">
<CompetencyEvidence name="ManagerObservation" dateOfIncident="1996-01-01" lastUsed="2000-01-01">
<NumericValue minValue="1" maxValue="5" description="Company XYZ Skill Range">5</NumericValue>
</CompetencyEvidence>
<CompetencyWeight>
<NumericValue minValue="0" maxValue="100">65</NumericValue>
</CompetencyWeight>
</Competency>
</Competency>

=Logging=
All competency related changes should be logged in history tables.

=Role capabilities and permissions=

{| border="0" cellpadding="2" cellspacing="0"
|'''Description'''
|'''Capability'''

|-
|View competency competencies
|moodle/competency:viewcompetencies

|-
|View hidden competencies
|moodle/competency:viewhiddencompetencies

|-
|Manage competencies
|moodle/competency:managecompetencies
|}

=Ideas for the future=
# Allow competencies to be attached to an individual user (either by user profile field or by drag and drop).
# Allow competencies to be tagged (in a folksonomy) using Moodle's tag/lib.

[[Category:Project]]

Competencies

2010-11-25T19:21:33Z

Janvh: /* "Add / edit a competency" admin page */

{{Moodle 2.0}}'''Note''': This page outlines ideas for the Competencies feature planned for Moodle 2.0. It's a ''specification under construction''! If you have any comments or suggestions, please add them to the [[Development talk:Progress tracking|page comments]].''

* '''PROJECT STATE: Proposal'''
* '''MAIN TRACKER ISSUE''':
* '''DISCUSSION''': Not yet announced on Moodle.org
* '''COMMENTS''': [[Development_talk:Competencies]]
* '''AUTHOR''': [[User:Jonathan Newman|Jonathan Newman]] with help from [[Matt Clarkson|Matt Clarkson]] and others

=Overview=
To support the range of different types of competency frameworks used by organisations, competencies in Moodle 2.0 needs to expand on the 1.9 outcomes architecture.

==Goals==
# Measured amount of abstraction
#* Allow "admins" to organise competencies in a hierarchy
#* Allow "admins" to create unlimited hierarchical levels
#* Allow "admins" to map related competencies on a given depth level
#* Allow "admins" to define custom info fields on a given depth level
# Easy navigation
#* Allow "admins" to view the competency structure
#** Expanding/collapsing competencies
#** Sorting/searching/filtering by competency meta data
#* Allow "admins" to easily add new competencies and meta-data
# Linking competencies and evidence items
#* Allow "admins" to easily attach allowed evidence (course, activity, etc) to a competency (from a ''site-level competency view''):
#* Allow "course creators" to attach competencies to evidence ''within a course'':
# Portability
#* Allow "admins" to import competencies (using import plugins) into a Moodle install
#* Allow "admins" to export competencies (using export plugins) from a Moodle install
# Specifying expected proficiency levels
#* Allow "admins" to assign an expected proficiency level (i.e., competency scale value) to a competency and a competency evidence item
# Aggregating measured proficiency
#* Allow "admins" to specify aggregation methods for each competency
#* Reporting
#** Allow "admins" to view competency results for all students
#** Allow "teachers" to view student measured proficiencies related to evidence in his/her courses.
#** Allow "students" to view their own competency results (via either their personal profile or My Moodle).
# Specifying weights
#* Allow "admins" to assign weight to a competency or a competency evidence item
# Scalability
#* Store and retrieve data efficiently to allow the scalability to very large numbers of courses, users, competencies, evidence, etc
# Extensibility
#* Use a plugin architecture for evidence types

==General requirements==
# We'll need to access and use the existing site-wide Outcomes [https://docs.moodle.org/en/Development:Grades#grade_outcomes Outcomes tables]
# We'll need to use the tables that indicate completion status for courses (these are not yet in place) [https://docs.moodle.org/en/Development:Course_completion Course Completion]
# We need to get aggregate information about the course outcomes and aggregate grades for each user from the gradebook API

==Definitions==
'''Scale''': A way to measure a competency using scale values.

Example scales:
"Average-based scale"
"Competency-based scale"

'''Scale values''': Descriptor or numeric values that comprise a scale. A scale value can have a id number (code) and description.

Example scales values (with descriptors and numerical values) for the scale examples above:
"Below average [1], Average [2], Above average [3]
"Not yet competent [0], Competent [100]"

'''Competency''': A measurable knowledge, skill, ability, attitude or other learning-related characteristic which a student may have. Competencies can be organised into a hierarchy.

Example hierarchy of competencies:
top-level competency: "Literacy"
-> child competency: "Reading Comprehension"
-> child competency: "Responding to Text"
-> child competency: "Initial Understanding of Literary Text"
-> child competency: "Demonstrate initial understanding of elements of literary texts (including text read aloud, reading independently"

'''Competency evidence type''': A form of evidence that can be accepted as evidence that a competency has been achieved. Examples:
Activity grade
Activity completion
Activity outcome
Course completion
Course grade
File (diploma)

'''Competency evidence''': A competency can be measured by one or more competency evidence types. Evidence can be stated to include the evidence type, evidence date, and measured value. Examples:
"Quiz - 4:00pm May 28, 2009 - Grade 90% out of 100%"
"Certificate - Public Speaking Institute - 4:00pm May 28, 2009 - Passed."
"File - College Diploma - 4:00pm May 28, 2009 - Bachelor of Science Computer Science"

'''Expected proficiency level''': The expected (or required) rating (based on a scale descriptor or numerical value) for a competency. Examples:
"Average"
"5"
"50%"
"Passed"

'''Measured proficiency level''': A user's observed, scored, reported proficiency level for a competency.
"Above average"
"8"
"80%"
"Passed"

'''Competency weighting''': Child competencies can be assigned weights which can be used for aggregating either sums or averages of child competencies. Examples:

Example with percentage weights
-> top-level competency: "Communication"
-> child competency: "Written Communication" : weight: 60%
-> child competency: "Oral Communication" : weight: 40%

==Example frameworks==

'''Example 1:''' Competency hierarchy with activity outcomes as evidence

The example data below is based roughly on the [http://education.vermont.gov/ Department of Education for the State of Vermont]'s [http://education.vermont.gov/new/html/pgm_curriculum/literacy/gle.html Grade 1 Expectations for Literacy] for Reading.

{| border="1" cellpadding="2" cellspacing="0"
|'''Depth level'''
|'''Depth name'''
|'''Competency'''
'''full name'''
|'''Competency'''
'''evidence'''
|'''Competency'''
'''aggregation method'''
|'''Competency
'''weight'''
|'''Competency'''
'''proficiency expected'''

|-
|0
|"Curriculum"
|"Literacy"
|none
|all
|20%
|80%

|-
|1
|"Type"
|"Reading"
|none
|all
|20%
|100%

|-
|2
|"Standard"
|"Standard 1.1 Reading Strategies"
|none
|all
|20%
|80%

|-
|3
|"Strategy"
|"Early Reading Skills and Strategies: Phonological Awareness"
|none
|all
|100%
|80%

|-
|4
|"Code"
|"RK: 1 - Applies phonological knowledge and skills by..."
|activity outcome "Recognizing pairs of rhyming words and producing rhymes"

activity outcome "Blending and segmenting syllables and onset-rimes"

activity outcome "Isolating phonemes in single-syllable words (e.g., "tell me the first sound in 'mop' "; "tell me the last sound in 'mop,'" "tell me the middle sound in 'mop'")"
|all
|50%
|80%

|-
|3
|"Strategy"
|"Early Reading Skills and Strategies - Concepts of Print"
|none
|all
|50%
|80%

|-
|4
|"Code"
|"RK: 2 - Demonstrates understanding of concepts of print during shared or individual reading by..."
|activity outcome: "Distinguishing between printed letters and words"

activity outcome: "Following text with finger-pointing (e.g., charts, simple books), demonstrating left-to-right and top-to-bottom directionality"

activity outcome: "Identifying the first and last parts of a word (beginning/end of the word)"

activity outcome: "Identifying key parts of a book: front and back, print, illustrations"

|all
|50%
|80%
|}

See [https://docs.moodle.org/en/Development:Competencies_example here] for how the data above fits into the proposed schema.

=Settings=
==Site settings==
[https://docs.moodle.org/en/Development:Conditional_activities#Completion_tracking_2 Activity Completion] provides an "Enable outcomes" setting (found in the Site Administration block's Advanced features / optional subsystems settings page). We need to keep outcomes, however we will need to add competencies.

'''Proposed changes:'''
* Create a new setting named "Enable competencies" (the setting will allow competencies to be defined)

=User interface=

==Site Administration block==
When competencies are enabled, a "Competencies" menu item should appear in the Site Administration block. An "Add / edit competencies" option should appear when "Competencies" is clicked. The "Add / edit competencies" will point to the "Add / edit competencies" admin page.

=="Add/edit competencies" admin page==
[[Image:Competencies_add_edit_default.png|thumb|400px|Mockup of the Add/edit competencies admin page (default)]]

[[Image:Competencies_add_edit.png|thumb|400px|Mockup of the Add/edit competencies admin page (with competencies from Example 1 framework)]]

An "admin" can use this page to add and edit competencies and competency depth levels, using buttons and features available in a table.

'''Buttons'''
* An "Add a new competency" button will link to the "Add a competency" admin page.
* An "Add a new depth level" button will link to the "Add a depth level" admin page.

'''Table rows'''
* A "plus" / "minus" icon will appear on the right of each row in the table, allowing all child competencies to be shown or hidden.

'''Table columns'''
* A default, top-level competency depth named "Competency" will appear in a table as a column on the left. The default competency depth name can be changed (e.g., "Competency Area", "Standard", "Development Area", etc).
* When a new competency depth is added, it will appear as column to the right of the next highest competency depth level.
* Appearing to the right of the competency depth level columns will be the following "standard" interface columns: "Evidence items", "Edit", and "Move competency to".

Below are more specifics on the table columns and content:
* ''[Competency depth level 0 name]'', ''[Competency depth level 1 name]'', ''[Competency depth level 2 name]'', ... ''[Competency depth level n name]''
** Columns of depth levels will be ordered from highest/top-level (on the left) to the lowest (on the right).
** An edit icon will appear beside each competency depth name, and will link to the "Edit competency depth" page (which will allow an "admin" to change the name of the competency depth name).
** The competency name will be displayed, and will link to a page containing meta data and possibly summary proficiency achievement stats about the competency.
* ''Evidence item''
** By default the number of evidence items will be "0". The number shown will link to the "Add / edit evidence items" admin page for the given competency.
* ''Edit''
** Three icons appear providing the following functionality:
*** "edit" icon points to the "Edit competency" page for the competency
*** "delete" icon points to a confirmation page for deleting the competency
*** "up" / "down" icons will appear beside child competencies when a parent has two or more child competencies. A competency can only be moved up or down with respect to a parent competency.Only the down arrow will appear for the highest child competency, and only the up arrow will appear for the lowest child competency.
* ''Move competency to''
** A drop down menu appears containing all parent competencies at the next highest depth.
** Competencies can only be moved from one parent to another parent in the same depth level.

=="Add / edit a competency" admin page==
[[Image:Competencies_add.png|thumb|400px|Mockup of the Add competencies admin page]]

An "admin" will use this page to add or edit a new competency, with the following settings:

''General settings''
* Parent competency
* Competency full name
* Competency short name
* Competency ID number
* Description
* Aggregation method
* Scale
* Proficiency expected

''Custom depth level settings''
* Form elements based on custom fields for selected depth level (based on the parent competency)
* Changing the selected parent competency should update the custom fields shown, if the depth level of the parent changes

=="Add / edit competency depth" admin page==
[[Image:Competencies_depth_add.png|thumb|400px|Mockup of the Add competency depth admin page]]

An "admin" will be use this page to add / edit a new competency depth, with the following settings:
* Depth full name
* Depth short name
* Description

Also, the depth level will be displayed

=="Add / edit competency evidence" admin page==
[[Image:Competencies_evidence_add_edit.png|thumb|400px|Mockup of the Add / edit competency evidence admin page with Example 1 competencies]]

An "admin" will be use this page to view / add / edit evidence for a competency. The top of the page should display the existing general data for the competency, the number of "students" who have achieved the competency, and a table showing data and functionality for each evidence item:
* The name of the competency evidence (which links to the evidence item in context, e.g., the course if course completion is specified, etc)
* The type of evidence
* The activity (if the evidence is an activity outcome or activity grade)
* The weight of the evidence
* Options to edit or remove the evidence
* The number of "students" who have achieved the evidence

An "Add new competency evidence" button should link to the "Add new competency evidence" admin page.

=="Competencies summary" user profile page==

[[Image:Competencies_user_profile_activity.png|thumb|400px|Mockup of user profile page with Example 1 competencies]]

An "student" or a user with permission to view a student's competencies will be able to view the proficiency status for each competency as a table with the following columns:
* Competency depth(s)
* Evidence items
* Proficiency
* Scale

Each competency name should link to a pop-up containing the competency details (full name, description, aggregation method, scale, and meta data) and list of evidence items.

Each number of competency items should link to a pop-up containing a list of evidence items.

=Data structures=

[[Image:Competency_data_model.png|thumb|400px|Competencies data model]]

===scale===
Scales (introduced in Moodle 1.9) give a scale value a single attribute: text (i.e., the name of the scale value like "below standard," "meets standard," "above standard"). Scale values can be particularly useful if given attributes including: numerical equivalent, idnumber (code id), and a description. The new attributes will require a new table.

''Proposed changes:'' Create a new table 'scale_values' that includes a foreign key to the 'scale' table, and migrate the 'scale' field values from the 'scale' table (as serialised text) to the 'scale_values' table (as separate records). A sort order field will be used to track ranking (starting with the lowest with a sortorder of 0).

Below is the proposed 'scale' table, and further below is the proposed 'scale_value' table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''courseid'''
|int(10)
|
|Id of the course, which the scale belongs to

|-
|'''userid'''
|int(10)
|
|Id of the user who last modified the scale

|-
|'''name'''
|varchar(255)
|
|Name of the scale value

|-
|'''description'''
|text
|
|Description of the scale value

|-
|'''timemodified'''
|int(10)
|
|Timestamp of when the scale was modified
|}

===scale_values===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''scaleid'''
|int(10)
|
|Id of the scale that the scale value describes

|-
|'''name'''
|varchar(255)
|
|Name of the scale value

|-
|'''idnumber'''
|varchar(100)
|
|Optional id, code number or local identifier for the scale value (used for reporting).

|-
|'''description'''
|text
|
|Description of the scale value

|-
|'''numeric'''
|number(8)
|
|Numerical value for the scale value

|-
|'''sortorder'''
|int(10)
|
|The order for the scale value

|-
|'''timemodified'''
|int(10)
|
|Timestamp of when the scale value was modified
|}

===competency===

A competency can be part of a hierarchy and can have evidence attached to it.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''shortname'''
|varchar(100)
|
|The shortname for the competency

|-
|'''fullname'''
|varchar(255)
|
|The full name for the competency

|-
|'''description'''
|text
|
|The description of the competency

|-
|'''idnumber'''
|int(10)
|
|The id, code number or local identifier for the competency used for reporting

|-
|'''parentid'''
|int(10)
|
|The id of the parent competency

|-
|'''sortorder'''
|int(10)
|
|The order number of this competency (useful for ordering competencies for viewing/navigation/reporting)

|-
|'''depthid'''
|int(10)
|
|The id of the depth level the competency belongs to

|-
|'''path'''
|varchar(255)
|
|The path to the competency

|-
|'''aggregationmethod'''
|int(10)
|
|A constant representation one of the competency aggregation methods (any, all, unit, fraction, sum of weighted, average of weighted)

|-
|'''scaleid'''
|int(10)
|
|The scale used to measure the competency

|-
|'''proficiencyexpected'''
|int(10)
|
|The expected proficiency for the competency, foreign key to the scale_value table's id

|-
|'''timecreated'''
|int(10)
|
|The time when the competency was created

|-
|'''timemodified'''
|int(10)
|
|The time when the competency was modified

|-
|'''usermodified'''
|int(10)
|
|The userid of the person who last modified the competency
|}

===competency_relations===

For tracking relations between competencies.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''description'''
|text
|
|Info about how competencies are related

|-
|'''competencyid1'''
|int(10)
|
|The id of a competency

|-
|'''competencyid2'''
|int(10)
|
|The id of a related competency
|}

===competency_depth===

Data for a competency depth level.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''shortname'''
|varchar(255)
|
|Shortname for the depth level

|-
|'''fullname'''
|varchar(255)
|
|Full name for the depth level

|-
|'''description'''
|text
|
|Description for the depth level

|-
|'''level'''
|int(2)
|
|The actual depth level, starting at 0
|}

===competency_depth_info_field===

Data for a competency depth level field.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''shortname'''
|varchar(255)
|
|Shortname for the field

|-
|'''fullname'''
|text
|
|Full name for the field

|-
|'''depthid'''
|int(10)
|
|The id of the competency depth for the field. Foreign key to the competency_depth table's id

|-
|'''datatype'''
|varchar(255)
|
|The type of field data

|-
|'''description'''
|text
|
|Description of the field

|-
|'''categoryid'''
|int(10)
|
|The id for the field category. Foreign key to the competency_depth_info_category table's id field
|-
|'''sortorder'''
|int(10)
|
|The sort order for the field within its category

|-
|'''hidden'''
|int(1)
|
|The field should be hidden

|-
|'''required'''
|int(1)
|
|The field required

|-
|'''defaultdata'''
|text
|
|Default text for the selected parameter

|-
|'''param1'''
|text
|
|Parameter text

|-
|'''param2'''
|text
|
|Parameter text

|-
|'''param3'''
|text
|
|Parameter text

|-
|'''param4'''
|text
|
|Parameter text

|-
|'''param5'''
|text
|
|Parameter text
|}

===competency_depth_info_category===

A competency's depth level can have categories for its fields.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''name'''
|varchar(255)
|
|Shortname for the depth level category

|-
|'''sortorder'''
|int(10)
|
|The order number for this category

|}

===competency_depth_info_data===

Data for a depth level field.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''fieldid'''
|int(10)
|
|The id for the field

|-
|'''competencyid'''
|int(10)
|
|The id for the competency

|-
|'''data'''
|text
|
|The actual data for the competency field
|}

===competency_evidence_items===

A competency can be achieved by one or more forms of evidence.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|Auto incrementing

|-
|'''competencyid'''
|int(10)
|
|The id for the competency that this evidence describes

|-
|'''itemtype'''
|varchar(30)
|
|The type of evidence 'course/outcome', 'mod/outcome', 'course/completion', 'mod/completion', 'course/grade', 'mod/grade', 'file'

|-
|'''itemmodule'''
|varchar(30)
|
|The type of evidence 'quiz', 'scorm', etc
|-

|'''iteminstance'''
|int(10)
|
|The id for the evidence instance (ie, grade_outcome id, course id, course_modules id, grade_item id, files id)

|-
|'''weight'''
|num(10)
|
|The weight applied to this evidence item (for aggregation)

|-
|'''timecreated'''
|int(10)
|
|The time when this competency evidence was allowed

|-
|'''timemodified'''
|int(10)
|
|The time when this competency evidence was last changed

|-
|'''usermodified'''
|int(10)
|
|The user who last modified this evidence
|}

===competency_evidence===

Track historical and current competency information for each user.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|auto-incrementing

|-
|'''userid'''
|int(10)
|
|The id of the user

|-
|'''competencyid'''
|int(10)
|
|The id of the competency

|-
|'''proficiencymeasured'''
|int(10)
|
|The measured/evaluated proficiency level for the user

|-
|'''timecreated'''
|int(10)
|
|The time when this competency evidence was started

|-
|'''timemodified'''
|int(10)
|
|The time when this competency evidence was last changed
|}

=Plugin architecture=
'''Competency evidence type plugins'''

Each type of evidence will need its own methods for interacting with the competency architecture and will need to interact via a base competency evidence API. Below are the item types.

* Course completion
* Course grade
* Course outcome
* Activity completion
* Activity grade
* Activity outcome
* File

'''Report plugins'''

Similar to the gradebook, we need to allow development of report plugins for competencies.

'''Import/Export plugins'''

We need to be able to import and export data related to competencies.

'''Competency framework import/export'''
A competency framework should be able to be exported using an appropriate format in either xml and csv file format. There are some standards on exchanging competencies including:
* IEEE P1484.20.1 Standard on Reusable Competency Definitions and the IEEE Draft Standard on Simple Reusable Competency Map
* ISO/IEC PDTR 24763 Conceptual Reference Model for Competencies and Related Objects

'''Competency evidence import/export'''

There are a variety of standards for exchanging competencies evidence including:
* IMS Reusable Definition of Competency or Educational Objectives Spec (RDCEO)
* IMS Learner Information Package Spec (LIP)
* HR-XML Competencies (Measurable Characteristics) Recommendation, 2007 April 15

IMS RDCEO and LIP recommend formats as shown in the examples below (more [http://www.imsglobal.org/competencies/index.html IMS RDCEO here] and [http://www.imsglobal.org/profiles/index.html IMS LIP home]). Special thanks to Sarveswaran Kengatharaiyer (GSOC 2008 student for the Moodle Progress Tracker project) who developed these examples.

rdceo.identifier = rdceo434323
rdceo.title = Identify verbs in simple sentences
rdceo.description = “Identify verbs in simple sentences”
rdceo.definition.statement.
statementid = 123
statementname = Always
statementtext = Scale
statementtoken = scl55435
rdceo.definition.statement.
statementid = 124
statementname = Never
statementtext = Scale
statementtoken = scl55436
rdceo.definition.statement.
statementid = 125
statementname = Sometimes
statementtext = Scale
statementtoken = scl55437

lip.contenttype.referencial.sourceid.id = jenney_profile
lip.identification.cotenttype.referential.indexid = id123
lip.identification.name.partname.typename=Jenny
lip.competency
cotenttype.referential.indexid = j123
exrefrecord = rdceo434323
description = Always

HR-XML recommends a format like shown below in an example which uses recursive competencies (more [http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/Competencies.html#_Toc127531664 here]).
<Competency name="Communication Skills">
<Competency name="Written Communication Skills">
<CompetencyEvidence name="WRITTENTEST1-A" dateOfIncident="1995-01-01" lastUsed="2000-01-01">
<NumericValue minValue="3" maxValue="5" description="SEP-equivalent Skill-Level Range">5</NumericValue>
</CompetencyEvidence>
<CompetencyWeight>
<NumericValue minValue="0" maxValue="100">35</NumericValue>
</CompetencyWeight>
</Competency>
<Competency name="Oral Communication Skills">
<CompetencyEvidence name="ManagerObservation" dateOfIncident="1996-01-01" lastUsed="2000-01-01">
<NumericValue minValue="1" maxValue="5" description="Company XYZ Skill Range">5</NumericValue>
</CompetencyEvidence>
<CompetencyWeight>
<NumericValue minValue="0" maxValue="100">65</NumericValue>
</CompetencyWeight>
</Competency>
</Competency>

=Logging=
All competency related changes should be logged in history tables.

=Role capabilities and permissions=

{| border="0" cellpadding="2" cellspacing="0"
|'''Description'''
|'''Capability'''

|-
|View competency competencies
|moodle/competency:viewcompetencies

|-
|View hidden competencies
|moodle/competency:viewhiddencompetencies

|-
|Manage competencies
|moodle/competency:managecompetencies
|}

=Ideas for the future=
# Allow competencies to be attached to an individual user (either by user profile field or by drag and drop).
# Allow competencies to be tagged (in a folksonomy) using Moodle's tag/lib.

[[Category:Project]]

Creating a web service and a web service function

2010-10-29T06:34:11Z

Janvh: /* Test the web service function */

{{Moodle_2.0}}
In this document you will learn how to create a web service function.

This document expect that you first read the administration manual [[Setting_up_a_web_service]]. 
To explain how to write a new web service function, we will write a web service function ''create_groups($groups)''. This function create a group into a Moodle course. - actually the function already exists into Moodle. You'll be able to browse CVS to have a look to the actual code.

This function will take a list of group object as parameters and it will return the same groups with their newly created id. If ever one group creation fails, the function will throw an exception, and no creation will happen.

We'll finally add the web service function to a core web service.

== Preparation ==
We need to identify:
* '''the core functions''': for our case we will use ''groups_create_group()'' from [http://cvs.moodle.org/moodle/group/ /group/lib.php]. Of course not every core function exists and in some other cases you could have to write them.
* '''the parameter types''': for our case we'll send a list of object. This object are groups, with id/name/courseid.
* '''the returned value types''': for our case we want to send back a list of group object with their id.
* '''the user capabilities''': for our case the user will need the ''moodle/course:managegroups'' capability.

== Declare the web service function ==
Web service functions are declared into ''db/services.php'' of each component. In our case ''create_groups()'' is a core external function, so we will add the function to [http://cvs.moodle.org/moodle/lib/db/ /lib/db/services.php].

<code php>
$functions = array(
'moodle_group_create_groups' => array( //web service function name
'classname' => 'moodle_group_external', //class containing the external function
'methodname' => 'create_groups', //external function name
'classpath' => 'group/externallib.php', //file containing the class/external function
'description' => 'Creates new groups.', //human readable description of the web service function
'type' => 'write', //database rights of the web service function (read, write)
),
);
</code>

Here you should ask yourself what is the difference between a web service function and an external function. Web service function could be considered as a redirection to the external function. The web service function name is the name that is served by web service server to the client. By this way the client doesn't know about the external functions.

The web service function name is arbitrary, but it must be globally unique so we highly recommend using the component name as prefix (and "moodle" for core functions).

== Define the web service description ==
Some web service protocol need a full description of the web service function parameters and return value. For example we need to generate a full WSDL for SOAP if we expect a JAVA/.Net client to call our function. This WSDL need a complete and fully detailed description of the parameters. 
Moreover we implemented a web service parameters validation process that also require a full description of these parameters. 
In conclusion, you must write these descriptions. These descriptions are not applied on the web service function but the external function, remember that the web service function is just a kind of redirection. 

Descriptions are usually located into a class into an externallib.php in the component folder. You probably remember that we referenced this ''moodle_group_external'' class into [http://cvs.moodle.org/moodle/lib/db/ /lib/db/services.php]. Let's take a minuteto talk about the [http://cvs.moodle.org/moodle/group/ /group/externallib.php] that we need to create.

This file will contain all external functions. These functions are all related together. In our case the externallib.php file will contain all ''group'' related functions. For each external function, we will have:
* the external function, calling a core function.
* a function describing the parameters of the external function
* a function describing the return values of the external function

Now we'll have look to the description of the ''create_group($groups)'' parameters. All parameter descriptions are included into a function called ''externalfunctionname_parameters()''. In our case it will be ''create_groups_parameters()'' :

<code php>
require_once("$CFG->libdir/externallib.php");

class moodle_group_external extends external_api {

/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function create_groups_parameters() {
return new external_function_parameters(
array(
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'courseid' => new external_value(PARAM_INT, 'id of course'),
'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
'description' => new external_value(PARAM_RAW, 'group description text'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
)
)
)
)
);
}
</code>

Ok you are probably already here :) We have to understand this function very well. There is different approaches to understand this function, here is my personal one. 
The function ''xxx_parameters()'' always return an ''external_function_parameters'' object. This object is initialized with an associative array. This array contains the parameter descriptions. If the external function have three parameters, this array will have three elements, the keys being the paramters name.
Each of its element is a parameter description. A parameter can be a list (external_multiple_structure), an object (external_single_structure) or a primary type (external_value).

Our create_groups() function expect one parameter named ''groups'', so we will first write:

<code php>
/**
* Returns description of method parameters
* @return external_function_parameters
*/
public static function create_groups_parameters() {
return new external_function_parameters(
array(
'groups' => ...

)
);
}
</code>

This ''groups'' parameter is a list of group. So we will write :

<code php>
'groups' => new external_multiple_structure(
...
)
</code>

An external_multiple_structure object (list) can be initialized with external_single_structure (object), external_value (primary type) or another external_multiple_structure (list). You will respectively obtain a list of a unique object type, a list of a unique primary type, or a list of a list. These last case being probably bad design. 
In our case we want a list of group, a group being a object. Have a look on how would describe a group :

<code php>
new external_single_structure(
array(
'courseid' => ...,
'name' => ...,
'description' => ...,
'enrolmentkey' => ...,
)
)
</code>

From this code you can guess that a external_single_structure is initialize with an associative array. This array containing the object attibuts. 
Thus a list of group will be defined :

<code php>
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'courseid' => ...,
'name' => ...,
'description' => ...,
'enrolmentkey' => ...,
)
)
)
</code>

Every of the group attribut are primary type. ''courseid'' is an integer. ''name'' is a string, ''description'' is a string, and ''enrolmentkey'' is also a string. To define a primary type we use the ''external_value'' object. This ''external_value'' is initialize with a non associative array containing three elements:
# the primary type
# a human readable description
# is the parameter optional (if the parameter is mandatory we don't need this third element)

For example for the ''courseid'' and ''name'' attribut we would define:

<code php>
'courseid' => new external_value(PARAM_INT, 'id of course'),
'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
</code>

So our list of object description will be :

<code php>
'groups' => new external_multiple_structure(
new external_single_structure(
array(
'courseid' => new external_value(PARAM_INT, 'id of course'),
'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
'description' => new external_value(PARAM_RAW, 'group description text'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
)
)
)
</code>

Now you should be able to understand this parameter description function. You also should be able to deduce how to write the return value description function.

Return value function always return one primary or complex value, so we don't need to return external_function_parameters object. In our case we want to return the exact same list of groups. The only change being that we want the group to have an id attribut.

<code php>
public static function create_groups_returns() {
return new external_multiple_structure(
new external_single_structure(
array(
'id' => new external_value(PARAM_INT, 'group record id'),
'courseid' => new external_value(PARAM_INT, 'id of course'),
'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
'description' => new external_value(PARAM_RAW, 'group description text'),
'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
)
)
);
}
</code>

Here ends the most difficult part of the web service infrastructure implementation. Congratulation!

=== Mandatory, Optional or Default ===
An attribut can be defined MANDATORY, OPTIONAL, or DEFAULT.

<code php>
'yearofstudy' => new external_value(PARAM_INT, 'year of study',VALUE_DEFAULT, 1979),
</code>

The third parameter VALUE_DEFAULT indicates that 'yearofstudy' is set to a default value if the attribut is not supply. When you set VALUE_DEFAULT in the description, you must also write a default value as fourth parameter. Here the default value of 'yearofstudy' is 1979.

The three values can be understood like it:
* VALUE_REQUIRED - if the parameter is not supplied, then the server throw an exception
* VALUE_OPTIONAL - if the parameter is not supplied, then the param has no value
* VALUE_DEFAULT - if the parameter is not supplied, then the default value is used

== Define the external function ==
We declared our web service function and we defined the external function parameters and return values. We will now implement the external function. Let's have a full look to the external function.

<code php>
/**
* Create groups
* @param array $groups array of group description arrays (with keys groupname and courseid)
* @return array of newly created groups
*/
public static function create_groups($groups) { //Don't forget to set it as static
global $CFG, $DB;
require_once("$CFG->dirroot/group/lib.php");

$params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));

$transaction = $DB->start_delegated_transaction();

$groups = array();

foreach ($params['groups'] as $group) {
$group = (object)$group;

if (trim($group->name) == '') {
throw new invalid_parameter_exception('Invalid group name');
}
if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
throw new invalid_parameter_exception('Group with the same name already exists in the course');
}

// now security checks
$context = get_context_instance(CONTEXT_COURSE, $group->courseid);
self::validate_context($context);
require_capability('moodle/course:managegroups', $context);

// finally create the group
$group->id = groups_create_group($group, false);
$groups[] = (array)$group;
}

$transaction->allow_commit();

return $groups;
}
</code>

First let's have a look at
<code php>
$params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
</code>
This ''validate_parameters'' function validates the external function parameters against the description. It will return an exception if some required parameters are missing, if parameters are not well-formed, and check the parameters validity. The array('groups'=>$groups) take the expected parameters by the description function.

A very important point: the parameters of your external function (''$groups'' into ''public static function create_groups('''$groups''') {'') should be in the exact same order as the ones into your description function ('''return new external_function_parameters( array( ''''groups'''' => ... )'''). I agree that our example function doesn't give us a good example :)

Then we have the following line
<code php>
$transaction = $DB->start_delegated_transaction();
</code>
Our function has for goal to create multiple group. The function is calling multiple time the '''groups_create_group()''' core function. If ever one function fail and return an exception, we do not want to commit any change. It's why we declare this line that suspend any commit till we write the following line
<code php>
$transaction->allow_commit();
</code>

You will also notice that our function throws exception. It is automatically handle by Moodle web service servers.
<code php>
throw new invalid_parameter_exception('Group with the same name already exists in the course');
</code>

And yet again another important point: the context checking and capability checking happens into the external function. In a long term, in Moodle 2.0, all context/capability checks will disappear from the core functions and will be located into the external functions
<code php>
/// now security checks
$context = get_context_instance(CONTEXT_COURSE, $group->courseid);
self::validate_context($context);
require_capability('moodle/course:managegroups', $context);
</code>

Last point, the return values will be parsed by the Moodle web service servers. Only the required values describe into the function description will be returned. An error will be returned if the external function doesn't return some required values.

== Add the web service function into a service ==
In some specific case we could want to set a service by default, so the Moodle administrator doesn't need to set a new one. We can do that by writing the following code into [http://cvs.moodle.org/moodle/lib/db/ /lib/db/services.php]:

<code php>
$services = array(
'groupservice' => array( //the name of the web service
'functions' => array ('moodle_add_groups', 'moodle_create_groups'), //web service functions of this service
'requiredcapability' => 'some/capability:specified', //if set, the web service user need this capability to access
//any function of this service
'restrictedusers' = >1, //if enabled, the Moodle administrator must link some user to this service
//into the administration
'enabled'=>0, //if enabled, the service can be reachable on a default installation
)
);
</code>

In this code we created a service called ''groupservice''. This service contains two functions ''moodle_add_groups''/''moodle_create_groups''. 
This possibility to preset a service exists to facilitate the administrator life. He can easily enable a bunch of function. 
However it is not possible for an administrator to add/remove any function from preset service. For security purpose, it is not a recommended to preset a service.

== Test the web service function ==
Moodle is bundled with a test client that can be accessed into [http://cvs.moodle.org/moodle/webservice/ webservice/testclient.php]. You are more than adviced to run it before to look at the code as the client can be used for multiple protocols, and multiple functions. You will have a better understanding. 
In order to support our function we will need to add a form into [http://cvs.moodle.org/moodle/webservice/ webservice/testclient_forms.php].
<code php>
class moodle_group_create_groups_form extends moodleform {
public function definition() {
global $CFG;

$mform = $this->_form;

$mform->addElement('header', 'wstestclienthdr', get_string('testclient', 'webservice'));

//note: these element are intentionally text aera without validation - we want users to test any rubbish as parameters
$mform->addElement('text', 'wsusername', 'wsusername');
$mform->addElement('text', 'wspassword', 'wspassword');
$mform->addElement('text', 'courseid', 'courseid');
$mform->addElement('text', 'name', 'name');
$mform->addElement('text', 'description', 'description');
$mform->addElement('text', 'enrolmentkey', 'enrolmentkey');

$mform->addElement('hidden', 'function');
$mform->setType('function', PARAM_SAFEDIR);

$mform->addElement('hidden', 'protocol');
$mform->setType('protocol', PARAM_SAFEDIR);

$mform->addElement('static', 'warning', '', get_string('executewarnign', 'webservice'));

$this->add_action_buttons(true, get_string('execute', 'webservice'));
}

public function get_params() {
if (!$data = $this->get_data()) {
return null;
}
// remove unused from form data
unset($data->submitbutton);
unset($data->protocol);
unset($data->function);
unset($data->wsusername);
unset($data->wspassword);

$params = array();
$params['groups'] = array();
$params['groups'][] = (array)$data;

return $params;
}
}
</code>

That's all for our create_groups() function. We've been able to implement it and to test it. In [[Creating_a_web_service_client]] we will talk about web service client.

==See also==
* [[Web services]]
* [[External services security]]
* [[External services description]]
* [[Creating_a_web_service_client]]
* [[Setting_up_a_web_service]]

[[Category:Web Services]]