Link Existing Accession and Archival Descriptions / Accruals

Skip to first unread message

Apr 15, 2019, 9:26:03 AM4/15/19
to AtoM Users

Is there a way in the UI to link existing accessions and archival descriptions that may have existed at the time of importing data, but did not have a linked Accession Number at that time. Also, is there a way to link multiple accessions (accruals) together post importing CSV data? As there was no accrual feature in the software we were using and would like to look at using this feature in AtoM.

Or what fields might I need to modify in the database to do this.

Thank you!

Dan Gillean

Apr 15, 2019, 1:14:30 PM4/15/19
to ICA-AtoM Users
Hi Tom, 

Linking existing descriptions to existing accessions is straightforward, and can be done via the user interface. See: 
The autocomplete drop-down can sometimes be finnicky when trying to find results, especially if you have many descriptions, and many of those have similar titles. For example, if you had many descriptions starting with "Letters from" then you might not easily find the specific description by searching for "Letters" in the drop-down menu. 

If you can, try typing a more unusual word from the title of the entry to which you want to link. If it is called ‘Letters concerning Germany’, try typing ‘Germany’ or ‘concerning Germany’ instead of ‘Letters’. If this approach still doesn't work, one suggestion I've heard from our users is to temporarily add a unique word (like "zebra" for example) to the title, to be able to find the target record easily. Edit the target record, and add a word like zebra to the title. Then return to the record where you want to make the link, and use "zebra" as a keyword in the autocomplete field to find the target related description. Once you've found the correct record and successfully linked the two, you can go back and remove zebra (or whatever unique keyword you've chosen) from the edited title.

Obviously this is not an ideal workaround, but it should allow you to find the description you need!

Regarding changing an existing accession record to become an accrual for another existing accession: this is a bit trickier, and I don't think there is currently a way to do this via the CSV import. It would be a fair bit of work to do this for a large number of accessions, but with a bit of help from a developer, I have figured out how you can accomplish this using SQL. 

Before we proceed, please be aware: I am not a developer, and you should proceed at your own risk, and ONLY after you've made a backup of your data! I tested this locally once and it worked, but I (and Artefactual) will not be responsible if something goes wrong. 

To access the MySQL command prompt from the terminal, we need to know our database name, as well as the username and password we used during installation and configuration of the database. You can access it with these credentials like so: 
  • mysql -u yourusername -pYOURPASSWORD atom
This should give you access to the MYSQL command prompt. In the example command above, I've used yourusername, YOURPASSWORD, and atom as placeholders - please swap in the correct ones used during the installation process. If you don't recall what they are, you can always try looking in 2 places to see the credentials you used - either in config/config.php, or in /root/my.cnf
In the database, there is no separate table for accruals - an accrual is simply an accession record that has a parent/child relationship with another accession. We capture this relationship information in the relation table. It looks like this: 

mysql> describe relation;
| Field          | Type        | Null | Key | Default | Extra |
| id             | int(11)     | NO   | PRI | NULL    |       |
| subject_id     | int(11)     | NO   | MUL | NULL    |       |
| object_id      | int(11)     | NO   | MUL | NULL    |       |
| type_id        | int(11)     | YES  | MUL | NULL    |       |
| start_date     | date        | YES  |     | NULL    |       |
| end_date       | date        | YES  |     | NULL    |       |
| source_culture | varchar(16) | YES  |     | NULL    |       |
7 rows in set (0.00 sec)

We are going to make an insertion into this table, to add the relationship. The main (parent) accession's object ID would be used as the object_id, while the accrual's object ID would be used as the subject_id. The type_id should be set to 175. So, we're going to have to do a few things first to get those IDs. 

First, we can use the slug of our accessions to get the related object IDs, like so: 
  • SELECT object_id FROM slug WHERE slug='your-accession-slug';
Repeat this for both accessions, and write down the IDs returned. For this example, let's say my parent accession's ID was 11111 and the accession I want to become the accrual was 22222. So later, I know i will want my object_id to be 11111 and the subject_id to be 22222.

We have one more step before we can insert our values into the relation table. Every object in AtoM's database, including relation objects, also needs an entry in the object table. Before proceeding, we need to create a new entry in the object table, and then get the entry's ID, to be used in our relation table update: 
  • INSERT INTO object (class_name, created_at) VALUES ('QubitRelation', '2019-04-15 13:00:00');
You'll notice that I've added a value for the created_at column of the object table, using today's date. the class_name will need to be QubitRelation for this to work. 

Now let's look up the obect ID that was created by this INSERT statement:
This should give you the ID we will use when we update the relation table. Write this one down too! For my example, let's say this was 012345.

Now we have all the information we need to update the relation table, and make one accession an accrual of the other. To summarize - in the relation table, here are the values we want to update:
  • subject_id: the object ID of the acession that will become the accrual
    • In my example: 22222
  • object_id: the object ID of the accession that will be the parent of the accrual
    • In my example 11111
  • type_id: set this to 175
  • id: the ID of the insertion we made into the object table
    • In my example: 012345
Let's try updating the relation table now, using the values from my example: 
  • INSERT INTO relation (id, subject_id, object_id, type_id) VALUES (012345, 22222, 11111, 175);
Swap in the values you actually get inside the parentheses following VALUES in the statement above. 

You should be done! Before reviewing our work in the user interface, I recommend repopulating the index, clearing the application cache, and restarting PHP-FPM (and memcached if you are using it). Run all the following commands from AtoM's root installation directory. 

Repopulating the index and clearing the application cache: 
  • php symfony search:populate
  • php symfony cc
Restarting PHP-FPM will depend on the version of Ubuntu, and the version of PHP you have installed, but assuming you are using Ubuntu 16.04 with PHP 7.0:
  • sudo systemctl restart php7.0-fpm
If you're using memcached: 
  • sudo systemctl restart memcached
You should be good to go! 


Dan Gillean, MAS, MLIS
AtoM Program Manager
Artefactual Systems, Inc.

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
To post to this group, send email to
Visit this group at
To view this discussion on the web visit
For more options, visit

Dan Gillean

Apr 15, 2019, 1:31:12 PM4/15/19
to ICA-AtoM Users
Hi again Tom, 

Regarding the first question, I almost forgot about this! You can add a qubitParentSlug column to link incoming accessions to existing descriptions: 
It is an undocumented feature that existing accessions can be updated by a CSV import that uses the same accessionNumber values - we have a note for ourselves to test and document this in our documentation issues (here). Once again, if you choose to test this, back up your data, and test with a small batch first. 

If you do want to test this out, you could try creating a CSV of one of your accessions, and populate only the accessionNumber column, and add a new qubitParentSlug column. In the qubitParentSlug column, add the slug of the description you want to link. I would probably try deleting all the other columns first, and then import that and see if it works. Keep in mind that you will probably have to repopulate the search index and clear the cache after. 


Dan Gillean, MAS, MLIS
AtoM Program Manager
Artefactual Systems, Inc.

Lise Summers

Apr 15, 2019, 9:30:21 PM4/15/19
to AtoM Users
Hi Tom

We are using the export and re-import option to relink some descriptions that were detached from their accessions.  We find them by search and either export the records from the search results via csv, or save to the clipboard and export that way.

Doing it record by record is slow, tedious and fiddly :)

Lise Summers
State Records Office Western Australia
Reply all
Reply to author
0 new messages