====== Updating the system's taxonomy ======

===== Who is this guide for =====

  * System administrators mantaining ODM's system
  * Content editors which are requesting new elements in the taxonomy
  * ODM Staff working on translating the system's resources

===== What this guide teaches =====

  * How to edit the data structure representing the taxonomy.
  * How upload the new taxonomy to transifex in order to be localized.
  * How implement the new taxonomy into the CKAN instance.
  * How implement the new taxonomy into the Wordpress multi-site instance

===== Things to know in forehand =====

==== Universal Taxonomy for ODM ====

Since the system is composed by several country sites plus the datahub (CKAN Instance). There is the need for a common taxonomy which should be used for categorizing the contents exposed in the system.

==== Taxonomy is stored in the odm-localization github repository ====

A data structure describing the taxonomy is stored under https://github.com/OpenDevelopmentMekong/odm-internal. This is the central repository for administering the taxonomy and its translations.
In this repository the taxonomy folder is present, which contains files with the current version of the taxonomy and its translations plus other folders with each of the different versions (i.e 0.9)

<WRAP center round important 90%>Please mind that the filenames and folder structure should be respected. Otheriwse import scripts could fail.</WRAP>

==== Taxonomy visualization tool ====

Under https://github.com/OpenDevelopmentMekong/OpenDevelopmentMekong.github.io there is a tool for visualizing the different values of the taxonomy in the different languages. This tool needs to be kept up-to-date in case the taxonomy changes.

===== How to update the Universal Taxonomy for ODM =====

==== Review and versioning ====

Every update of taxonomy should be considered as a milestone and each modification of the taxonomy will get a version number. This will help differentiating between different states.

==== Translating new version on Transifex ====

The final taxonomy should be uploaded to transifex https://www.transifex.com/projects/p/odm-taxonomy/ as a new resource in order to be translated into the other languages. Once it is translated to the other languages being used in the system, it can be used.

==== Uploading new version into odm-localization ====

In order to keep record of the different versions and facilitate the access to the taxonomy by Staff and scripts, everytime a new version is defined, following steps need to be undertaken in the odm-localization github repository:
  - Upload a new folder with the new version into odm-localization/taxonomy (i.e odm-localization/taxonomy/1.0)
  - Replace the json files of the current taxonomy in the odm-localization/taxonomy folder with those with the newest ones.

==== Re-running import scripts in order to apply the changes on the CKAN instance ====

In order to apply the new taxonomy into any CKAN instance, it is necessary to run the import scripts specified in the GUIDE: [[migrating_from_previous_system|Migrating from previous System]]

==== Applying the new taxonomy into the Wordpress multi-site instance ====

The categories of the ODI Universal Taxonomy for Development are implemented in Wordpress by the [[https://en.support.wordpress.com/posts/categories/ | post category system]]. New country instances will have the most current version of the taxonomy implemented, but updates to the hierarchy and categories should be carried out manually through the Wordpress interface. These should not need to be updated frequently. WordPress manages these categories based on a system of IDs, not the category names -- the IDs are created automatically whenever either of new tags, categories, and custom taxonomies are added. 

==== Add new taxonomy category====
  * First, log in to the WordPress dashboard. 
  * On the left hand menu bar, hover on "Post", and then click the "Categories" in the dropdown menu that appears
  * The screen below will be displayed:
{{:add-edit-category1.jpg|}}
  * Add new taxonomy categories by entering data into the "Add New Category" form 
  * Add the relevant translation texts in the appropriate fields 
  * Select the parent that the term belong to in order to set the required hierarchy according to the taxonomy. Leaving the default of "None" means no parent -- the category you have added will be at the top of the hierarchy.
  * Slug: Try to keep the category's slug as close as possible to the category title, using hyphens for spaces and lower case letters. E.g. The slug for the "Agriculture and Fishing" category should become "agriculture-and-fishing" if possible. If left blank, it will be automatically generated from the category title. If the slug is already in use, the auto-generated slug will be given a number to distinguish it, e.g. "agriculture-and-fishing-2". 
  * Click the "Add New Category" button.
  * Done -- the new category should have been added.

==== Update a taxonomy category ====
  * Access the list of Post categories as described in the "Add new taxonomy category" section above
  * Find the category you wish to update and click "Edit"
  * Make the required edits in the "Edit category" form. 
  * Click the "Update" button.
  * Done -- the category will have been updated.