Authenicate against DINA's Keycloak and access its models

gem install dina -v


DINA Ruby Gem

The DINA Consortium develops an open-source web-based information management system for natural history data that consists of several connected software components. At the core of the system is support for assembling, managing and sharing data associated with natural history collections and their curation ("collection management"). Target collections include zoological, botanical, geological and paleontological collections, living collections, biodiversity inventories, observation records, and molecular data.

This Ruby 3.1 gem abstracts the Keycloak configuration and JSON:API models for the DINA collection management system. It depends on the json_api_client where more documentation is available on how to create, update, query, and delete objects.


The DINA APIs for each of its components are under rapid development and so too is this gem. The intent of the latter is to be as closely aligned with the most recent versions of the former. As such, this gem makes use of the DINA APIs via their single, frontend gateway.

Gem Version Continuous Integration Status

Requirements & Dependencies


$ gem install dina


All variables are required and most can be obtained from a DINA system administrator.

  • authorization_url, realm, client_id, user, and password: used in the Keycloak authentication handshake
  • endpoint_url: the single DINA gateway to JSON:API models
  • server_name: a key used to reference authentication token responses (in the event you connect to multiple DINA servers or have multiple credentials)
  • token_store_file: your local file that caches authentication token responses, prefixed by the server_name key.
require 'dina'
settings = {
   authorization_url: "http://localhost/auth",
   endpoint_url: "http://localhost/api",
   realm: "dina",
   client_id: "dina",
   user: "username",
   password: "password",
   server_name: "server",
   token_store_file: "config/token.json"
Dina.config = settings

Instantiate and Save a Person

person =
person.givenNames = "Peter"
person.familyNames = "Pipetter" = ""
=> true

Alternatively, use the create method to save a Person without having to instantiate it first:

data = {
  givenNames: "Peter",
  familyNames: "pipetter",
  email: ""
person = Dina::Person.create(data)

A new instance like person above sets and uses a default UUIDv4, which can be accessed as

Add an Identifier to a person Instance

identifier =
identifier.namespace = "WIKIDATA"
identifier.value = ""
=> true

person.identifiers = [ identifier ]
=> true

Instance objects (like identifier above) must be saved before they can be attached to related objects (like person above).

Query for a Person by Email Address

person = Dina::Person.find_by_email("").first
"displayName"=>"Pipetter, Peter",                                  
"createdOn"=>2022-11-25 17:23:09.262958 UTC,                       

Unlike typical ActiveRecord methods, find or find_by_* methods return an array and so you must additionally use .first or [0].

Delete a Person

person = Dina::Person.find("bf42616e-846c-4dbd-8372-bef44cdfa3e8").first
=> true

Add an instance of a collection method to that of a collecting event

# Find a collection method or create one as you would a person or identifier above
collection_method = Dina::CollectionMethod.find("bf42616e-846c-4dbd-8372-bef44cdfa3e9").first

collecting_event = = "CNC"
collecting_event.collection_method = collection_method
=> true

Upload an Image File and its ObjectStore Metadata

file = = "DAOM"
file.file_path = "/my-directory/my-file.jpg"
=> true

metadata = = "DAOM"
metadata.dcType = "IMAGE"
metadata.dcFormat = "image/jpeg"
metadata.fileExtension = ".jpg"
metadata.fileIdentifier =
=> true


To list available JSON:API Classes:


To list available properties for a Class:

To list relationships and their cardinality for a Class:


Connection Errors

In the event there are SSL certificate verification issues:

Dina::BaseModel.connection_options[:ssl] = { verify: false }


Flush the token from memory and save an empty token file



Bug reports can be filed at


Copyright © 2023 Government of Canada

Authors: David P. Shorthouse


dina is released under the MIT license.