Working with Taxonomies

Taxonomy refers to the process of classifying information into structured groups. For example, if you have a lot of information on your website, you can generate the navigation keeping in mind your site visitors way of thinking. Taxonomy functionality enables you to categorize all your information in a hierarchical format. Thereby, giving the users to ability to discover the information easily through the ease of navigation. Furthermore, Taxonomy allows assets to be classified appropriately. Generally, you will have many categories with a vast domain that covers a lot of different kinds of assets.

In WSO2 ES, the Taxonomy feature allows the admin of an organization to define the Taxonomy as an XML representation so that Store users can discover assets by navigating to a set of groupings organized into a hierarchy. Furthermore, the asset publisher can assign an asset to a grouping within the Taxonomy, based on a defined taxonomy.

Defining a taxonomy hierarchy

The WSO2 ES administrator is the only user who is authorized to define the taxonomy hierarchy and manage the permissions with regard to the taxonomies via the WSO2 ES Management Console. Follow the instructions below to define a taxonomy hierarchy:

Step 1 - Configure the taxonomy
Step 2 - Manage the taxonomy permissions

Step 1 - Configure the taxonomy hierarchy

Follow the instructions below to configure a taxonomy hierarchy:

Step 1.1 - Define the taxonomy hierarchy
Step 1.2 - Configure the RXT definition based on the taxonomy hierarchy

Step 1.1 - Define the taxonomy hierarchy

Follow the instructions below to define a taxonomy hierarchy:

Sign into the WSO2 ES Management Console.
Click Extensions, navigate to the Configure menu and click Taxonomy.
Click Add new Taxonomy.

Define the taxonomy and click Save. For more information, see Taxonomy definition.
WSO2 ES ships a taxonomy template by default. If required, you can use the default definition as it is, you can customize the definition based on your requirements or you can define the taxonomy from scratch.

Click here to view a sample taxonomy definition...

The following is a sample of a taxonomy definition.

<taxonomy id="Teams" name="Teams">
   <root id="wso2Teams" displayName="WSO2 Teams">
      <node id="sales" displayName="Sales" />
      <node id="marketing" displayName="Marketing" />
      <node id="hR" displayName="HR" />
      <node id="engineering" displayName="Engineering">
         <node id="governanceTG" displayName="Governance TG">
            <node id="esGReg" displayName="ES/GReg" />
            <node id="is" displayName="IS" />
            <node id="security" displayName="Security" />
         </node>
         <node id="platformTG" displayName="Platform TG">
            <node id="asCarbon" displayName="AS/Carbon" />
            <node id="dS" displayName="DS" />
            <node id="developerStudio" displayName="Developer Studio" />
            <node id="uiUX" displayName="UI/UX" />
            <node id="platformExtension" displayName="Platform Extension" />
         </node>
         <node id="integrationTG" displayName="Integration TG">
            <node id="esbGwLb" displayName="ESB/GW/LB" />
            <node id="mb" displayName="MB" />
            <node id="bpsBrs" displayName="BPS/BRS" />
            <node id="uiUX" displayName="PC " />
            <node id="platformExtension" displayName="DIS" />
         </node>
         <node id="dataTG" displayName="Data TG">
            <node id="dasDss" displayName="DAS/DSS" />
            <node id="cep" displayName="CEP" />
            <node id="ml" displayName="ML" />
            <node id="analytics" displayName="Analytics" />
            <node id="research" displayName="Research" />
         </node>
         <node id="apiTG" displayName="API TG">
            <node id="apiManager" displayName="API Manager" />
            <node id="appManager" displayName="App Manager" />
            <node id="emmIot" displayName="EMM/IOT" />
         </node>
         <node id="qaTG" displayName="QA TG">
            <node id="qa" displayName="QA" />
            <node id="qaa" displayName="QAA" />
         </node>
         <node id="cloudTG" displayName="Cloud TG">
            <node id="appFactory" displayName="AppFactory /SS" />
            <node id="cloudTeam" displayName="Cloud Team" />
            <node id="paas" displayName="PaaS" />
            <node id="devOpsTeam" displayName="DevOps Team" />
         </node>
      </node>
      <node id="Finance" displayName="Finance" />
      <node id="Admin" displayName="Admin" />
   </root>
</taxonomy>

The elements that are present in the taxonomy definition are explained as follows:

The Taxonomy IDs can not be duplicated in the Taxonomy node definition or across separate Taxonomies. For example, if there is a Taxonomy named Team and Service, the Taxonomy IDs defined in the Team and Service Taxonomies should be unique.

This is the main taxonomy element. You need to have the id and name attribute for the taxonomy file. WSO2 ES uses the name attribute to distinguish the taxonomy definitions and the name of the taxonomy is displayed in the WSO2 ES Management Console taxonomy list, Publisher taxonomy view, and Store taxonomy view.
```
<taxonomy id="teams" name="Teams">
</taxonomy>
```
Do not use special characters (especially # and -) for the Taxonomy id and name.
The root element, which also has an id and name as attributes, is used as the topmost level to wrap the taxonomy hierarchy content. Unlike the node element display names, the root element display names are not displayed anywhere. However, when you add a taxonomy for an asset the taxonomy is stored with the root element (e.g., wso2teams/ engineering/...).
```
<taxonomy id="teams" name="Teams">
	<root id="wso2teams" displayName="WSO2 Teams">
	</root>
</taxonomy>
```
Do not use special characters (especially # and -) for the root id. You can use special characters for the root displayName with the exception of the following.
- #
- -
The node element is displayed in the Publisher and Store taxonomy view, under its respective taxonomy name. You can use the node element to write a tree-structured taxonomy hierarchy.
```
<taxonomy id="teams" name="Teams">
    <root id="wso2teams" displayName="WSO2 Teams">
	<node id="engineering" displayName="Engineering"></node>
    </root>
</taxonomy>
```
Do not use special characters (especially # and -) for the node id. You can use special characters for the node displayName with the exception of the following.
- #
- -

Use nested node elements to define children nodes. For example, the following code snippet describes the way in which the ES/GReg child node is defined for the Engineering parent node.

<taxonomy id="teams" name="Teams">
    <root id="wso2teams" displayName="WSO2 Teams">
	<node id="engineering" displayName="Engineering">
                <node id="esgreg" displayName="ES/GReg"> </node>
            </node>
    </root>
</taxonomy>

When writing a new taxonomy file, please maintain unique ids for each element. Furthermore, the id should not have special characters.
Define global taxonomies as follows:
When you create a global taxonomy file, it will automatically be available for all asset types without enabling specifically. Make a normal taxonomy a global taxonomy by adding a new attribute named global="true" in the taxonomy main element as follows:
```
<taxonomy id="teams" name="Teams"  global="true" >
</taxonomy>
```

Click Save to save the taxonomy definition.

Step 1.2 - Configure the RXT definition based on the taxonomy hierarchy

Follow the instructions below to configure the RXT definition based on the taxonomy hierarchy:

In the following instructions, it is assumed that you have already signed into the WSO2 ES Management Console.

Click Extensions, navigate to the Configure menu and click Artifact Types.
Click Add new artifact if you wish to configure a new artifact with the newly added taxonomy, or click View/Edit if you wish to configure an existing artifact with the newly added taxonomy.
Update the RXT definition as follows:
1. Define the taxonomy in the RXT.
  Define each Taxonomy under a separate <taxonomy> element. Furthermore, the taxonomy name attribute should be identical to the name defined in the taxonomy file.
  1. If you wish to define only one taxonomy, nest one <taxonomy> element within the <taxonomies> element.
    Example
    <taxonomies> <taxonomy name="Teams" /> </taxonomies>
  2. If you wish to define multiple taxonomies, nest multiple <taxonomy> elements within the <taxonomies> element.
    <taxonomies> <taxonomy name="Teams" /> <taxonomy name="Locations" /> </taxonomies>
- If required, disable global taxonomies being auto-inherited into the specific RXT type by adding an attribute named excludeGlobal="true" into the <taxonomies> element.
  Example
```
<taxonomies excludeGlobal="true">
   <taxonomy name="Teams" />
   <taxonomy name="Locations" />
</taxonomies>
```
If you were in the process of configuring an existing artifact, restart the WSO2 ES Server.
Skip this step in the following instances:
- If you configured a new artifact.
- If you have enabled hot deployment in WSO2 ES.

Step 2 - Manage the taxonomy permissions

The admin can grant multiple users the permission to manage the Taxonomy hierarchy.

Follow the instructions below to grant the taxonomy management permission to a specific user.

In the following instructions, it is assumed that you have already signed into the WSO2 ES Management Console.

Click Main, navigate to the Users and Roles menu and click List.
Click Roles.
Select a specific user and click Permissions.
Click on the Taxonomy option to grant the selected user with the Taxonomy permission.
Click Update.

What's Next?

For information on how the publishers apply these Taxonomies to assets, see Working with Taxonomies in the Publisher.
For information on how users can use the Taxonomies to filter their asset, see Filtering Assets.