Taxonomy basics

Open Eligibility

By default, Ohana API supports the Open Eligibility taxonomy, which is defined in XML format.

The way we imported the OE taxonomy was to convert the XML to JSON, and then parsed this JSON and imported the taxonomy into the database using the ancestry gem and this script.

Importing your own taxonomy

If you want to use your own taxonomy, one way to do it would be to define it in a CSV file, and import it from there into Ohana. A pull request is in progress for importing a taxonomy from a CSV file. Basically, you would have columns for the name of the category, its unique taxonomy_id, and the taxonomy_id of its parent if it’s a child of another category.

Adding new categories to Open Eligibility's taxonomy

If you want to add new categories to the OE taxonomy, you can write a script similar to the ones mentioned above, or just 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', oe_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_oe_id('102')
# Then create a child
parent.children.create!(name: 'Name of child category', oe_id: 'unique id')

The oe_id you choose must follow the hierarchical pattern currently used. For example, "Emergency" is the first top-level category, and its unique oe_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 oe_id would need to be 101-08. Also, note that oe_id is a String, not an Integer.

Assigning categories to a Service

If you're starting from scratch, the easiest way to categorize a Service is through the admin interface. You can also do it programmatically by writing to the API or writing a local script that uses the API methods directly.

If your data is already categorized, you'll first need to create your taxonomy as explained above. 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.