eox-tagging 3.0.0

eox-tagging

Eox-tagging (A.K.A. Edunext Open extensions) is an openedx plugin, that adds the capability to tag edx-platform objects. These tags can be used to categorize, include extra information, and so on.

Installation

Open edX devstack

• Install a supported version of the Open edX devstack. See versions for more details.

• Clone the git repo:

cd ~/Documents/eoxstack/src/  # Assuming that devstack is in  ~/Documents/eoxstack/devstack/
sudo mkdir edxapp
cd edxapp
git clone [e-mail]:eduNEXT/eox-tagging.git

• Install plugin from your server (in this case the devstack docker lms shell):

cd ~/Documents/eoxstack/devstack  # Change for your devstack path (if you are using devstack)
make lms-shell  # Enter the devstack machine (or server where lms process lives)
cd /edx/src/edxapp/eox-tagging
pip install -e .
python manage.py lms migrate eox_tagging --settings=<your app settings>

Compatibility Notes

Open edX Release	Version
Ironwood	< 0.9
Juniper	>= 0.9
Koa	>= 2.2
Lilac	>= 2.2

The following changes to the plugin settings are necessary. If the release you are looking for is not listed, then the accumulation of changes from previous releases is enough.

Ironwood

EOX_TAGGING_GET_ENROLLMENT_OBJECT: "eox_tagging.edxapp_wrappers.backends.enrollment_i_v1"
EOX_TAGGING_GET_COURSE_OVERVIEW: "eox_tagging.edxapp_wrappers.backends.course_overview_i_v1"
EOX_TAGGING_BEARER_AUTHENTICATION: "eox_tagging.edxapp_wrappers.backends.bearer_authentication_i_v1"

Koa (optional)

EOX_TAGGING_GET_ENROLLMENT_OBJECT: "eox_tagging.edxapp_wrappers.backends.enrollment_l_v1"

Lilac

EOX_TAGGING_GET_ENROLLMENT_OBJECT: "eox_tagging.edxapp_wrappers.backends.enrollment_l_v1"

Those settings can be changed in eox_tagging/settings/common.py or, for example, in ansible configurations.

NOTE: the current common.py works with Open edX juniper version.

Usage

Important notes:

• All the comparison with string objects are case insensitive.

• validate_<FIELD_VALUE> meaning:

  • The FIELD_VALUE must be a Tag field, if not an exception will be raised.

  • If this is defined in EOX_TAGGING_DEFINITIONS as one of the tag definitions:

    validate_<FIELD_VALUE_1>: <VALIDATIONS>

    • The application will expect that <VALIDATIONS> is a dictionary of validations or a string.

    • This dictionary has for keys the validations you want to perform and for values, the values allowed for the field. In case it is a string, the field must be equal to that string.

    • If a key or value is not defined then an exception will be raised. In case that is a string, the field must be equal to that string.

  • If this is defined:

    <FIELD_VALUE>: <VALIDATIONS>

    • The application will expect just a string as a validation. This is also a way to define the required fields.

    • The settings for EOX_TAGGING_DEFINITIONS can be a combination of dictionary validations and strings.

  • If a key in the settings dictionary has as prefix validate it means that the <key, value> can have a dictionary of validations as value. If not, is assume that

    value is a string.

• force_<FIELD_VALUE> meaning:

  • This allows to set a value to a field without running validations or directly specifying it in the tag object.

• The validations available are:

Name	Description	Example
in	the field must be equal to one of the strings defined inside the array		validate_tag_value : {"in": ["tag_value_1", "tag_value_2"]}
exists	the field must be different to None		validate_tag_value : {"exists": true}
equals	the field must be equal to the dictionary value		validate_tag_value : {"equals": "tag_value"}
regex	the field must match the pattern defined		validate_tag_value : {"regex": ".+eduNEXT"}
opaque_key	the field must be an opaque key		validate_tag_value : {"opaque_key": "CourseKey"}
between	the field must be greater than the first member of the list and less than the last member. Or can be equal to one of the two. The list must be sorted.		validate_expiration_date : {"between": [DATE_1, DATE_2]}

• The available objects to tag and validate are: User, Site, CourseOverview, CourseEnrollment and GeneratedCertificate.

• If an owner is not defined, then it is assumed to be the site.

Examples

Example 1:

{
    "validate_tag_value":{
        "in":[
            "example_tag_value",
            "example_tag_value_1"
        ]
    },
    "validate_access":{
        "equals":"PRIVATE"
    },
    "validate_target_object":"OpaqueKeyProxyModel",
    "owner_object":"User",
    "tag_type":"tag_by_example"
}

This means that:

• Tag value must be in the array

• The field access must be equal to private

• The target type must be equal to CourseOverview

• The owner type must be equal to User

• Tag_type must be equal to tag_by_example

Example 2:

{
    "validate_tag_value":{
        "exist":true
    },
    "validate_access":"Public",
    "validate_target_object":"User",
    "tag_type":"tag_by_edunext"
}

This means that:

• The tag value must exist, it can take any value.

• The field access must be equal to public.

• The target type must be equal to User.

• Tag type must be equal to tag_by_edunext.

Example 3:

{
    "validate_tag_value":"tag_value",
    "validate_access":{
        "in":[
            "Private",
            "Public"
        ]
    },
    "validate_target_object":"CourseEnrollment",
    "tag_type":"tag_by_edunext",
    "validate_activation_date":{
        "exist":true,
        "in":[
            "Dec 04 2020 10:30:40",
            "Oct 19 2020 10:30:40"
        ]
    }
}

This means that:

• The tag value must be equal to tag_value.

• The field access can be private or public.

• The target type must be equal to CourseEnrollment

• Tag type must be equal to tag_by_edunext.

• The tag activation date must exist and be between the values defined in the array. This means: value_1 <= activation_date <= value_2. The array must be sorted or a validation error will be raised.

Tagging REST API

Get list of tags

Request

curl -H 'Accept: application/json' -H "Authorization: Bearer AUTHENTICATION_TOKEN" http://BASE_URL_SITE/eox_tagging/api/v1/tags/

Response

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "meta": {
                "created_at": "2020-07-10T13:25:54.057846Z",
                "target_id": 2,
                "target_type": "User",
                "inactivated_at": null,
                "owner_type": "User",
                "owner_id": 7
            },
            "key": "55a20579-ce8e-4f0b-830e-78fe79adac46",
            "tag_value": "tag_value",
            "tag_type": "tag_by_edunext",
            "access": "PUBLIC",
            "activation_date": "2020-12-04T15:20:30Z",
            "expiration_date": null,
            "status": "ACTIVE"
        },
        {
            "meta": {
                "created_at": "2020-07-10T13:33:44.277374Z",
                "target_id": 2,
                "target_type": "User",
                "inactivated_at": null,
                "owner_type": "Site",
                "owner_id": 1
            },
            "key": "2bec10f5-a9e0-4e42-9c24-f9643bb13537",
            "tag_value": "tag_value",
            "tag_type": "tag_by_edunext",
            "access": "PUBLIC",
            "activation_date": "2020-12-04T15:20:30Z",
            "expiration_date": null,
            "status": "ACTIVE"
        },
    ]
}

Create tag

Request

curl -H 'Accept: application/json' -H "Authorization: Bearer AUTHENTICATION_TOKEN" --data TAG_DATA http://BASE_URL_SITE/eox_tagging/api/v1/tags/

Where TAG_DATA:

{
    "tag_type": "tag_by_edunext",
    "tag_value": "tag_value",
    "target_type": "user",
    "target_id": "edx",
    "access": "public",
    "owner_type": "user",
    "activation_date": "2020-12-04 10:20:30"
}

Response:

Status 201 Created

{
    "meta": {
        "created_at": "2020-07-10T13:25:54.057846Z",
        "target_id": 2,
        "target_type": "User",
        "inactivated_at": null,
        "owner_type": "User",
        "owner_id": 7
    },
    "key": "55a20579-ce8e-4f0b-830e-78fe79adac46",
    "tag_value": "tag_value",
    "tag_type": "tag_by_edunext",
    "access": "PUBLIC",
    "activation_date": "2020-12-04T10:20:30-05:00",
    "expiration_date": null,
    "status": "ACTIVE"
}

Delete tag

Request

curl -X DELETE http://BASE_URL_SITE/eox_tagging/api/v1/tags/EXISTING_KEY_TAG/

Response

Status 204 No Content

Filters example usage:

/eox_tagging/api/v1/tags/?target_type=MODEL_TYPE

/eox_tagging/api/v1/tags/?course_id=COURSE_ID

/eox_tagging/api/v1/tags/?username=USERNAME

/eox_tagging/api/v1/tags/?access=ACCESS_TYPE

/eox_tagging/api/v1/tags/?enrollments=COURSE_ID

Auditing Django views

The majority of views in eox-tagging use an auditing decorator, defined in our custom library called eox-audit-model, that helps saving relevant information about non-idempotent operations. By default this functionality is turned on. To check your auditing records go to Django sysadmin and find DJANGO EDUNEXT AUDIT MODEL.

For more information, check the eox-audit-model documentation.

How to Contribute

Contributions are welcome! See our CONTRIBUTING file for more information – it also contains guidelines for how to maintain high code quality, which will make your contribution more likely to be accepted.