Package: ckanext-doi
ckanext-doiA CKAN extension for assigning a digital object identifier (DOI) to datasets, using the DataCite DOI service.OverviewThis extension assigns a digital object identifier (DOI) to datasets, using the DataCite DOI service.When a new dataset is created it is assigned a new DOI. This DOI will be in the format:https://doi.org/[prefix]/[8 random alphanumeric characters]If the new dataset is active and public, the DOI and metadata will be registered with DataCite.If the dataset is draft or private, the DOI will not be registered with DataCite. When the dataset is made active & public, the DOI will be registered.
This allows datasets to be embargoed, but still provides a DOI to be referenced in publications.You will need a DataCite account to use this extension.DOI MetadataThis extension currently usesDataCite Metadata Schema v4.2.Dataset package fields and CKAN config settings are mapped to the DataCite Schema with default values, but these can be overwritten byimplementingIDoiinterface methods.Required fieldsCKAN FieldDataCite Schemadataset:titletitledataset:authorcreatorconfig:ckanext.doi.publisherpublisherdataset:metadata_created.yearpublicationYeardataset:typeresourceTypeSeemetadata.pyfor full mapping details.InstallationPath variables used below:$INSTALL_FOLDER(i.e. where CKAN is installed), e.g./usr/lib/ckan/default$CONFIG_FILE, e.g./etc/ckan/default/development.iniInstalling from PyPIpipinstallckanext-doiInstalling from sourceClone the repository into thesrcfolder:cd$INSTALL_FOLDER/src
gitclonehttps://github.com/NaturalHistoryMuseum/ckanext-doi.gitActivate the virtual env:.$INSTALL_FOLDER/bin/activateInstall via pip:pipinstall$INSTALL_FOLDER/src/ckanext-doiInstalling in editable modeInstalling from apyproject.tomlin editable mode (i.e.pip install -e) requiressetuptools>=64; however, CKAN 2.9 requiressetuptools==44.1.0. Seeour CKAN forkfor a version of v2.9 that uses an updated setuptools if this functionality is something you need.Post-install setupAdd 'doi' to the list of plugins in your$CONFIG_FILE:ckan.plugins=... doiInitialise the database:ckan-c$CONFIG_FILEdoiinitdbThis extension will only work if you have signed up for an account withDataCite. You will need a development/test account to use this plugin in test mode, and a live account to mint active DOIs.ConfigurationThese are the options that can be specified in your .ini config file.DateCite Credentials[REQUIRED]DataCite Repository account credentials are used to register DOIs. A Repository account is administered by a DataCite Member.NameDescriptionExampleckanext.doi.account_nameYour DataCite Repository account nameABC.DEFGckanext.doi.account_passwordYour DataCite Repository account passwordckanext.doi.prefixThe prefix taken from your DataCite Repository account (from your test account if running in test mode)10.1234Institution Name[REQUIRED]You also need to provide the name of the institution publishing the DOIs (e.g. Natural History Museum).NameDescriptionckanext.doi.publisherThe name of the institution publishing the DOITest/Debug Mode[REQUIRED]If test mode is set to true, the DOIs will use the DataCite test site. The test site uses a separate account, so you must also change your credentials and prefix.NameDescriptionOptionsckanext.doi.test_modeEnable dev/test modeTrue/FalseNote that the DOIs will still display on your web interface ashttps://doi.org/YOUR-DOI, but theywill not resolve. Log in to your test account to view all your minted test DOIs, or replacehttps://doi.org/withhttps://doi.test.datacite.org/dois/in a single URL to view a specific DOI.Other optionsNameDescriptionDefaultckanext.doi.site_urlUsed to build the link back to the datasetckan.site_urlckanext.doi.site_titleSite title to use in the citationNoneUsageCommandsdoidelete-dois: delete all DOIs from the database (notdatacite).ckan-c$CONFIG_FILEdoidelete-doisupdate-doi: update the datacite metadata for one or all packages.ckan-c$CONFIG_FILEdoiupdate-doi[PACKAGE_ID]InterfacesTheIDoiinterface allows plugins to extend thebuild_metadata_dictandbuild_xml_dictmethods.build_metadata_dict(pkg_dict, metadata_dict, errors)Breaking changes from v1:previously calledbuild_metadatanew parameter:errorsnew return value: tuple ofmetadata_dict,errorsExtracts metadata from a pkg_dict for use in generating datacite DOIs. The base method from this extension is run first, then the metadata dict is passed through all the implementations of this method. After running these, if any of the required values (see above) are still in theerrorsdict (i.e. they still could not be handled by any other extension), aDOIMetadataExceptionwill be thrown.ParameterDescriptionpkg_dictThe original package dictionary from which the metadata were extracted.metadata_dictThe current metadata dict, created by the ckanext-doi extension and any previous plugins implementing IDoi.errorsA dictionary of metadata keys and errors generated by previous plugins; this method should remove any keys that it successfully processes and overwrites.build_xml_dict(metadata_dict, xml_dict)Breaking changes from v1:previously calledmetadata_to_xmlparameters rearranged (previouslyxml_dict,metadata)Converts the metadata_dict into an xml_dict that can be passed to thedatacitelibrary'sschema42.tostring()andschema42.validate()methods. The base method from this extension is run first, then the xml dict is passed through all the implementations of this method.ParameterDescriptionmetadata_dictThe original metadata dictionary from which the xml attributes are extracted.xml_dictThe current xml dict, created by the ckanext-doi extension and any previous plugins implementing IDoi.TemplatesPackage citation snippet{%snippet"doi/snippets/package_citation.html",pkg_dict=g.pkg_dict%}Resource citation snippet{%snippet"doi/snippets/resource_citation.html",pkg_dict=g.pkg_dict,res=res%}TestingThere is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in thedocker/folder.To run the tests can be run against ckan 2.9.x and 2.10.x on Python3:Build the required images:docker-composebuildThen run the tests.
The root of the repository is mounted into the ckan container as a volume by the Docker compose configuration, so you should only need to rebuild the ckan image if you change the extension's dependencies.# run tests against ckan 2.9.xdocker-composerunlatest# run tests against ckan 2.10.xdocker-composerunnextNote that the tests mock the DataCite API and therefore don't require an internet connection nor your DataCite credentials to run.