GET /api/personcompetences

Description

Returns list of passed or missing competences for person.

Parameters

person_competence_id

Int. Optional. ID to specific PersonCompetence object. The distinction between using person_competence_id and calling /api/personcompetences/[competence_id] is that if you use competence_id, you may also have to define user_name to get the object you want. Also, when using competence_id, the system will always return the "current" PersonCompetence. In other words, it will give you the latest attempt at fulfilling a competence/ecourse/course/etc. When using person_competence_id, the system will return this object, regardless of cancellations, validity, if it has been replaced by a newer object, etc. Note that when person_competence_id is specified, all other parameters are disregarded.

start

DEPRECATED. Will be removed in future version. Use offset in stead.

limit

Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.

offset

Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.

state

String. Optional. ”passed”/”missing”/"expired". Whether to return passed competences, missing competences, or competences that have expired. Default: ”passed”.

user_name

String. Optional. Username identifying the person whose competences we want. If not given, will return competences for logged in person.

role_ids

List of ints. Optional. IDs of roles to restrict to. Will only yield competences mandatory for these roles.

requirement

String. Optional. None/”mandatory”/”optional”. If set to ”optional”, will return optional instead of mandatory competences. Default: None for state ”passed”, ”mandatory” for state ”missing” or if role_ids is defined

types

List of strings. Optional. Competence types to restrict to.

view

String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.

fields

String. Optional. See Field customization.

Return

Array of PersonCompetence objects.

Security

Superuser, person’s manager and self

GET /api/personcompetences/[competence_id]

Description

Returns details of competence for person.

Parameters

competence_id

Int. Parameter given in URL path. ID for competence to get. Mandatory, unless person_competence_id is given.

user_name

String. Optional. If not given, will get competence for logged in user. Only allowed for managers and superusers.

state

String. Optional. ”passed”/”missing”. Whether to return passed competence or competence that have expired. If there are no passed/expired competence, will return empty set. Default: not set, will yield current PersonCompetence object, regardless of passed/expired state.

fields

String. Optional. See Field customization.

Return

Array of one PersonCompetence object.

Security

Superuser, person’s manager and self

POST /api/personcompetences/

Description

Updates state of competence for person by creating a new PersonCompetence object. What it actually does, depends on the type of the competence:
Common for all types: Registers competence for person, sets dates (verified date and valid until date), stores a comment and file.
Checklist item: Sets the checklist’s state on or off
Signature: Signs digitally, only allowed for self
Formal competence: Sets competence and stores school/university and graduation year
Skill: Stores skill level

Parameters common for all competence types

user_name

String. Optional. If not given, will set competence for logged in user. Only allowed for managers and superusers.

competence_id

Int. Mandatory. ID for Competence to register for person.

passed

Int, 0-100. Optional, default: 100. Defines passed level for the competence, where 100 is fully passed and 0 is not at all. Mostly for skills, other types should not provide this parameter, usually.

date

String, date on ISO format. Optional, default: now. The point in time from which the competence is valid for the person. 

valid_until

String, date on ISO format. Optional. The point in time where the competence is no longer valid.

comments

Text. Optional. Additional comment to the person’s competence.

file

File. Optional. File to store with the person’s competence. Typically documentation for the competence. NOT IMPLEMENTED.

fields

String. Optional. See Field customization.

Parameters applicable for specific competence types

action

String. ”on”/”off”. For checklist items. Determines which state to set the checklist item to. Note: If a person’s manager invokes this, and action is defined, the request is regarded as an attempt to check/uncheck the checklist item as per the item’s setting. However, if action is not defined, the request is regarded as an override to the check/uncheck status of the item, and the competence is set as passed for the person, regardless.

password

String. Person’s password. For signatures when user_name not given. Must be correct in order for the signature to be marked as signed.

show_course_diploma

Boolean. Optional. For courses, module courses, ecourses. If present (and any value), user will be able to download course diploma for the competence.

grade

Floating point number. Optional. For courses, module courses, ecourses. The grade given to the participant.

school

String. Optional. For formal competences. Name of school or university.

graduation_year

String, four digit year. Optional. For formal competences. Year of graduation. 

Return

Array of one PersonCompetence object.

Security

Superuser, person’s manager and/or self, but depending on type and how it is configured. 

PUT /api/personcompetences/[person_competence_id]

Description

Updates state of PersonCompetence object. What it actually does, depends on the type of the competence:
Common for all types: Updates, sets dates (verified date and valid until date), stores a comment and file.
Checklist item: Sets the checklist’s state on or off
Signature: Signs digitally, only allowed for self
Formal competence: Sets competence and stores school/university and graduation year
Skill: Stores skill level

Parameters common for all competence types

person_competence_id

Int. Mandatory. Parameter given in URL. ID for PersonCompetence object to update.

competence_id

Int. Optional. ID for competence, if you want to change which competence the PersonCompetence belongs to. Must be used with caution. If PersonCompetence belongs to an event that has not been registered manually (typically a classroom course), this parameter will be ignored. Consider doing a DELETE and POST in stead.

passed

Int, 0-100. Optional, default: 100. Defines passed level for the competence, where 100 is fully passed and 0 is not at all. Mostly for skills, other types should not provide this parameter, usually.

date

String, date on ISO format. Optional, default: now. The point in time from which the competence is valid for the person. 

valid_until

String, date on ISO format. Optional. The point in time where the competence is no longer valid.

comments

Text. Optional. Additional comment to the person’s competence.

file

File. Optional. File to store with the person’s competence. Typically documentation for the competence. NOT IMPLEMENTED.

fields

String. Optional. See Field customization.

Parameters applicable for specific competence types

action

String. ”on”/”off”. For checklist items. Determines which state to set the checklist item to. Note: If a person’s manager invokes this, and action is defined, the request is regarded as an attempt to check/uncheck the checklist item as per the item’s setting. However, if action is not defined, the request is regarded as an override to the check/uncheck status of the item, and the competence is set as passed for the person, regardless.

password

String. Person’s password. For signatures when user_name not given. Must be correct in order for the signature to be marked as signed.

show_course_diploma

Boolean. Optional. For courses, module courses, ecourses. If present (and any value), user will be able to download course diploma for the competence.

grade

Floating point number. Optional. For courses, module courses, ecourses. The grade given to the participant.

school

String. Optional. For formal competences. Name of school or university.

graduation_year

String, four digit year. Optional. For formal competences. Year of graduation. 

Return

Array of one PersonCompetence object.

Security

Superuser, person’s manager and/or self, but depending on type and how it is configured. 

DELETE /api/personcompetences/[person_competence_id]

Description

Removes a competence from a person, by setting the cancelled attribute on the PersonCompetence object.

Parameters

person_competence_id

Int. Mandatory (sort of). ID for PersonCompetence to remove. Parameter given in URL path.

competence_id

Int. ID for Competence. If given, will override person_competence_id and remove ALL PersonCompetence instances for Person/Competence. If given, person_competence_id is actually not mandatory.

user_name

String. Optional. Only required if person_competence_id is not given and we are looking up the current PersonCompetence object by competence_id. Will look up object for logged in user if not given. Only allowed for managers and superusers.

fields

String. Optional. See Field customization.

Return

Array of one PersonCompetence object.

Security

Superuser, person’s manager and/or self.

GET /api/personcompetences/search

Description

Returns list of passed or partially passed competences for persons. This is a search, not tied to any specific person.

Parameters

term

String. Search for competence with name containing this.

state

String. Optional. ”passed”/"missing"/”expired”. Whether to return passed competences, missing competences or expired competences. Default: ”passed”. State "missing" not supported yet.

role_ids

List of ints. Optional. IDs of roles to restrict to. Will only yield competences mandatory for these roles.

requirement

String. Optional. None/”mandatory”/”optional”. If set to ”optional”, will return optional instead of mandatory competences. Default: None for state ”passed”, ”mandatory” if role_ids is defined

types

List of strings. Optional. Competence types to restrict to.

competence_ids

List of ints. Restrict to these competences.

organisation_ids

List of ints. Restrict to competences defined in these organisations (or their children).

external_organisation_ids

List of ints. Same as for organisation_ids.

competence_group_ids

List of ints. Restrict to competences belonging to these groups.

external_competence_group_ids

List of ids. Restrict to competences belonging to these groups. Can be used together with competence_group_ids.

view

String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.

limit

Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.

offset

Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.

fields

String. Optional. See Field customization.

Return

Array of PersonCompetence objects.

Security

Superuser