Adding new Taxonomies

[Steven Politzer]

Hello,

My archive is currently looking into testing ATOM but we have found that we need to add a "Jurisdiction" Taxonomy. What are the actual steps to adding new Taxonomies from the developer side?

[Dan Gillean]

Hi Steven,

I can ask our developers to provide some suggestions on where to start. In the meantime, you might start by checking out some of the resources we have available:

• Development resources on the wiki
• Intro to AtoM's code (slides)
• Intro to AtoM development (slides)

One thing to note - Symfony does have a country list built in, and we use it to add a Copyright jurisdiction autocomplete field in the PREMIS Rights template - we also have a Country field in the Repository contact information widget that also makes use of Symfony's country list. Might this be a useful alternative to adding a whole new taxonomy, or do you need users to be able to add, edit, and delete terms?

I'm not a developer so I'm not sure exactly where to look to find these components, but in searching the AtoM code repository for "jurisdiction" I did find these two elements which seem useful in indicating how we've implemented the copyright jurisdiction:

• https://github.com/artefactual/atom/blob/qa/2.4.x/apps/qubit/modules/right/actions/editAction.class.php#L123
• https://github.com/artefactual/atom/blob/qa/2.4.x/apps/qubit/modules/right/templates/_right.php#L37

If you do decide to create a new taxonomy, at least 2 of the files you will need to start looking at will be in lib/model:

• https://github.com/artefactual/atom/blob/qa/2.4.x/lib/model/QubitTaxonomy.php
• https://github.com/artefactual/atom/blob/qa/2.4.x/lib/model/QubitTerm.php

There are likely more... I 'll see if I can get any tips from our team!

Dan Gillean, MAS, MLIS
AtoM Program Manager
Artefactual Systems, Inc.
604-527-2056

@accesstomemory

On Thu, May 25, 2017 at 1:44 AM, Steven Politzer <stevenp...@gmail.com> wrote:

Hello,

My archive is currently looking into testing ATOM but we have found that we need to add a "Jurisdiction" Taxonomy. What are the actual steps to adding new Taxonomies from the developer side?

--
You received this message because you are subscribed to the Google Groups "AtoM Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ica-atom-users+unsubscribe@googlegroups.com.
To post to this group, send email to ica-ato...@googlegroups.com.
Visit this group at https://groups.google.com/group/ica-atom-users.
To view this discussion on the web visit https://groups.google.com/d/msgid/ica-atom-users/1e8477eb-aa02-44f3-a48e-04e9638676a3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Dan Gillean]

Hi again Steven,

With some help from one of our developers, I have found 2 recent pull requests that should help you get started. In both cases, new taxonomies have been added (and additionally, facets have been added to relevant search/browse pages in case that is also useful), so studying them should be fruitful:

• https://github.com/artefactual/atom/pull/31/files
• https://github.com/artefactual/atom/pull/560/commits
• In the second case, all the work is broken up into individual meaningful commits, so you can follow the relevant parts. The first commit makes the necessary changes to add the fixtures and schema migration for the new taxonomy, and work progresses from there.
  

Hope this helps!

Dan Gillean, MAS, MLIS
AtoM Program Manager
Artefactual Systems, Inc.
604-527-2056

@accesstomemory

[Steven Politzer]

Thank you for this. This is exactly what I was looking for. 

A follow up question that you may need to ask the devs: If AToM pushes an update, and we have forked the code slightly (like to add a taxonomy), would the update accomodate for the changes or would we need to readd our code everytime?

To unsubscribe from this group and stop receiving emails from it, send an email to ica-atom-user...@googlegroups.com.

[Dan Gillean]

Hi Steven,

You will have to manage and re-merge your local customizations with each upgrade, unfortunately - AtoM has no way to automatically reconcile code conflicts or manage local changes.

I would suggest making sure that your installation has followed option 2 in our installation instructions - installing from our code repository. This way, you can use git branches to manage your changes, pull in the most recent work, resolve conflicts, etc.

Note that if you think your work would be useful to the broader AtoM community, you might also consider contributing it back to the public project. This way, Artefactual takes on the maintenance of the feature going forward, ensuring it works in future releases, and you don't have to keep maintaining your local customizations.

One caveat with this is that whether or not Artefactual will accept a pull request depends on a number of factors - for example, is your work standards based? If you are adding new fields to one of our standards-based templates (like ISAD or DACS) which are not supported by the standard, then we might not accept the PR. We have a number of tips in the following document:

• https://wiki.accesstomemory.org/Development/Recommendations

Be aware as well that reviewing public PRs is unpaid work for us, so our developers do it as we are able to between other requirements.

Either way, good luck, and let us know how it goes!

Regards,

Dan Gillean, MAS, MLIS
AtoM Program Manager
Artefactual Systems, Inc.
604-527-2056

@accesstomemory

To unsubscribe from this group and stop receiving emails from it, send an email to ica-atom-users+unsubscribe@googlegroups.com.
To post to this group, send email to ica-atom-users@googlegroups.com.

Visit this group at https://groups.google.com/group/ica-atom-users.

To view this discussion on the web visit https://groups.google.com/d/msgid/ica-atom-users/b033a123-99bb-4681-8539-afdd0432d595%40googlegroups.com.

[Steven Politzer]

Thanks for all the help!

[Steven Politzer]

Hi again,

I've been discussing this with my team and I may have misidentified what we were looking for. 

While we do need to be able to add a new Taxonomy, we also need to be able to create a new Access Point for that Taxonomy. In the same place that "Place", "Subject", "Genre", and "Person" go, we would like to add "Jurisdiction" there. 

Are the above instructions helpful with that or is there something additional that needs to be done?

[Arkangel R Carrasco H]

Hi, i want add a new field from Access Point, how to will i can do?

[Dan Gillean]

Hi Arkangel, 

In AtoM, access points use terms, managed in a taxonomy, so the older parts of this thread should be helpful for pointing you in the right direction to create a new taxonomy. We also have general development resources on the wiki, here: 

•   https://wiki.accesstomemory.org/Development#Development_resources

See also some of the developer slide decks on our SlideShare account. Also, this post was about theme development, but in my reply I provided a lot of general development resources for working with AtoM: 

• https://groups.google.com/d/msg/ica-atom-users/ggeIbxmkH_o/NzO0vWkbBQAJ
  

A good place to look would be the original pull request for when the Genre access points were added to AtoM  - it covers a lot: 

• https://github.com/artefactual/atom/commit/c75992279924bf6e84f6e4c99296ff8a837da75d
  

Keep in mind that this pull request is against an older version of AtoM - some things have changed since then (for example, the upgrade of Elasticsearch from 1.7.x to 5.6.x), so you'll need to make sure you familiarize yourself with these changes, and work against the latest code (currently in the qa/2.6.x branch). 

There were also some enhancement and bug fixes in later pull requests - see some of these, for example: 

• https://github.com/artefactual/atom/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aclosed+genre+  

There are a lot of moving parts to consider - import and export support (CSV, EAD, MODS, DC), support across different templates (ISAD, DACS, RAD, MODS, DC), changes to the search index, database changes and schema migrations for upgrading users, adding facets and filters to search/browse pages, etc... so be aware that this will be a major development project, and it will take time and testing to get it right. 

To help orient you, I've also pulled out a few examples that show how the access point fields are integrated into the description templates. 

You can see here in the ISAD template where we add the access point fields to the edit page: 

• https://github.com/artefactual/atom/blob/HEAD/plugins/sfIsadPlugin/modules/sfIsadPlugin/templates/editSuccess.php#L202-L248 

Here is where we show them in the right hand context menu (i.e. side bar) on the description view page of the ISAD template: 

• https://github.com/artefactual/atom/blob/HEAD/plugins/sfIsadPlugin/modules/sfIsadPlugin/templates/indexSuccess.php#L30-L40 

And here is where we show them in the body of the view page record in the ISAD template: 

• https://github.com/artefactual/atom/blob/HEAD/plugins/sfIsadPlugin/modules/sfIsadPlugin/templates/indexSuccess.php#L222-L243  
  

You should also look at the functions and methods defined in this file for term relations and access points: 

• https://github.com/artefactual/atom/blob/HEAD/lib/model/QubitInformationObject.php#L1023-L1121  
  

If you are creating a new taxonomy, you will probably want to be aware of the functions and methods in QubitTerm as well:

• https://github.com/artefactual/atom/blob/HEAD/lib/model/QubitTerm.php  
  

Hope that helps! 

Dan Gillean, MAS, MLIS
AtoM Program Manager
Artefactual Systems, Inc.
604-527-2056

@accesstomemory

To view this discussion on the web visit https://groups.google.com/d/msgid/ica-atom-users/446a7586-d6da-4b7a-bb91-0da9b8f1c3bd%40googlegroups.com.