Taxonomy basics

Open Eligibility

By default, Ohana API supports the Open Eligibility (OE) taxonomy. To use it, just follow the installation instructions.

Technical details about storing the OE taxonomy in the Ohana API database (for informational purposes only)

In order to recreate the hierarchical structure of the OE taxonomy (which is defined in XML format), and to allow users to assign categories to Services via the admin interface (see screenshot at the end), we first converted the taxonomy from XML to JSON. We then wrote this script to parse the JSON and create the categories in the database using the ancestry gem.

Importing your own taxonomy

If you want to use your own taxonomy, follow the instructions in this wiki article.

Adding new categories to Open Eligibility's taxonomy

If you want to add new categories to the OE taxonomy, you can write a script, or add them one by one in the Rails console using the commands provided by the ancestry gem. Read the gem’s documentation for more details.

For example, to create a new top-level category:

Category.create!(name: 'Name of top-level category', taxonomy_id: 'unique id')

To create a new child of an existing category:

# First find the parent category by its unique `taxonomy_id`
parent = Category.find_by_taxonomy_id('102')
# Then create a child
parent.children.create!(name: 'Name of child category', taxonomy_id: 'unique id')

The taxonomy_id you choose must follow the hierarchical pattern currently used. For example, "Emergency" is the first top-level category, and its unique taxonomy_id is 101. It has several children: 101-01, 101-02, through 101-07. If you wanted to create a new child immediately under "Emergency", its taxonomy_id would need to be 101-08. Also, note that taxonomy_id is a String, not an Integer.

The easiest way to examine the structure of the Open Eligibility taxonomy is to view data/sample.csv/taxonomy.csv. If you look closely, you'll notice that some taxonomy IDs might be missing in the sequence. For example, the sequence goes from 103-05 to 103-05-02. That's because the category corresponding to 103-05-01 used to exist in version 1.0 of the taxonomy, but was removed in version 2.0.

If you decide to remove certain categories from the taxonomy, it is extremely important that you do not reset the sequence. Each category must always be linked to its unique taxonomy_id. A category's taxonomy_id can never change.

Assigning categories to a Service

If you're starting from scratch, the easiest way to categorize a Service is through the admin interface (see screenshot below). You can also do it programmatically by writing to the API or writing a local script similar to this one:

# Find the Service whose id is 23
service = Service.find(23)
# Set that Service's category_ids to an array of Category IDs
service.category_ids = cat_ids(%w(101 101-01))
# Save the Service
service.save!

# cat_ids method that returns an array of Category 
# primary keys based on their taxonomy_id
def cat_ids(taxonomy_ids)
  return [] unless taxonomy_ids.present?
  Category.where(taxonomy_id: taxonomy_ids).pluck(:id)
end

If your data is already categorized, you'll first need to create your taxonomy. Then you can add a taxonomy_ids column to your services.csv file, which would contain a comma-separated list of taxonomy ids. For example, if you were using the Open Eligibility taxonomy and you wanted to make sure a Service was categorized with "Emergency" and "Disaster Response", then your taxonomy_ids column would contain "101, 101-01".

Screenshot of Open Eligibility taxonomy checkboxes in admin interface