Accession records are *upserted*, meaning that when the matching accession record
Accession records are *upserted*, meaning that:
. exists, it will be updated
. does not exist, a new record will be created
. when the matching accession record exists, it will be updated.
. when it does not exist, a new record will be created.
Accession data in the database will be updated with whatever data is provided in the
request JSON.
=== Accession identity
Prior to full adoption of Permanent Unique Identifiers for Germplasm, accessions could be
Prior to full adoption of Permanent Unique Identifiers for germplasm, accessions could be
identified by the holding institute code (INSTCODE) and the accession number (ACCENUMB).
Genebanks maintaining two or more collections of crops would sometimes use the same
accession number, unique within one collection.
However, genebanks maintaining two or more collections of crops sometimes use identical
accession numbers in different collections.
Genesys uses the *instCode*, *acceNumb* and *genus* triplet to uniquely identify an
accession in an institute. For accessions with a <<doi, DOI>> assigned in <<glis, GLIS>> it will
use the DOI to uniquely identify the record:
For this reason, Genesys uses the *INSTCODE*, *ACCENUMB* and *GENUS* triplet to uniquely identify an
accession. For accessions with a digital object identifier ( https://en.wikipedia.org/wiki/Digital_object_identifier[DOI]) assigned in the ITPGRFA Secretariat Global Information System (
http://www.fao.org/plant-treaty/areas-of-work/global-information-system/en/[GLIS]), it will
use the DOI to uniquely identify the record.
.Identifiers in an accession JSON object
[source,json,linenums]
----
{
...
...
@@ -42,18 +45,18 @@ use the DOI to uniquely identify the record:
=== JSON data model
The JSON data model of accession passport data closely follows <<mcpd2, MCPD>> definitions.
The JSON data model of accession passport data closely follows
By default, institutes in Genesys are configured to "Use unique accession numbers within the institute".
The accession JSON object must provide two identifying elements: `instCode` and `acceNumb`.
In cases where accession numbers are not unique within the institute, `genus` is used to identify
the unique accession within the institute. Then the Accession JSON object must always provide three
the unique accession within the institute. In such a case the Accession JSON object must always provide three
identifying elements: `instCode`, `acceNumb` and `genus`.
All other fields are optional.
.Example fields in an accession JSON object
[source,json,linenums]
----
{
...
...
@@ -92,8 +95,9 @@ All other fields are optional.
=== Geographic data JSON model
The `geo` field in accession JSON captures geographic data:
The `geo` field in accession JSON captures geographic data.
.Geographic data in a JSON object
[source,json,linenums]
----
{
...
...
@@ -112,21 +116,26 @@ The `geo` field in accession JSON captures geographic data:
|Field name
|Description
|DECLATITUDE|Latitude expressed in decimal degrees. Positive values are North of the Equator; negative values are South of the Equator (e.g. `-44.6975`).
|DECLONGITUDE|Longitude expressed in decimal degrees. Positive values are East of the Greenwich Meridian; negative values are West of the Greenwich Meridian (e.g. `+120.9123`).
|DECLATITUDE|Latitude expressed in decimal degrees. Positive values are north of the Equator; negative values are south of the Equator (e.g. `-44.6975`).
|DECLONGITUDE|Longitude expressed in decimal degrees. Positive values are east of the Greenwich Meridian; negative values are west of the Greenwich Meridian (e.g. `+120.9123`).
|ELEVATION|Elevation of collecting site expressed in meters above sea level. Negative values are not allowed.
|COORDUNCERT|Uncertainty associated with the coordinates in meters. Leave the value empty if the uncertainty is unknown.
|COORDDATUM|The geodetic datum or spatial reference system upon which the coordinates given in decimal latitude
and longitude are based (e.g. `WGS84`, `ETRS89`, `NAD83`). The GPS uses the WGS84 datum.
|GEOREFMETH|The georeferencing method used (`GPS`, determined from `map`, `gazetteer`, or `estimated using software`).
Leave the value empty if georeferencing method is not known.
|===
=== Collecting data JSON model
The `coll` field in accession JSON captures collecting data:
The `coll` field in accession JSON captures collecting data.
.Collecting data in a JSON object
[source,json,linenums]
----
{
...
...
@@ -147,20 +156,27 @@ The `coll` field in accession JSON captures collecting data:
|Field name
|Description
|COLLDATE|Collecting date of the sample, where YYYY is the year, MM is the month and DD is the day. Missing data (MM or DD) should be indicated with hyphens or '00' [double szero].
|COLLDATE|Collecting date of the sample, in the format `YYYYMMDD`. Missing data (`MM` or `DD`) may be indicated with two hyphens or two zeros.
|COLLSITE|Location information below the country level that describes where the accession was collected,
preferable in English. This might include the distance in kilometers and direction from the nearest town,
village or map grid reference point, (e.g. `7km south of Curitiba in the state of Parana`).
preferably in English. This might include the distance in kilometers and direction from the nearest town,
village or map grid reference point (e.g. `7km south of Curitiba in the state of Parana`).
|COLLNUMB|Original identifier assigned by the collector(s) of the sample, normally composed of the
name or initials of the collector(s) followed by a number (e.g. `FM9909`). This identifier is
essential for identifying duplicates held in different collections.
|COLLSRC|Collecting/acquisition source
|COLLCODE|FAO WIEWS code of the institute collecting the sample.
|COLLNAME|Name of the institute collecting the sample. This descriptor should only be used if
|COLLSRC|Collecting/acquisition source.
|COLLCODE|FAO WIEWS code of the institute that collected the sample.
|COLLNAME|Name of the institute that collected the sample. This descriptor should only be used if
COLLCODE cannot be filled because the FAO WIEWS code for this institute is not available.
|COLLINSTADDRESS|Address of the institute collecting the sample. This descriptor should only
|COLLINSTADDRESS|Address of the institute that collected the sample. This descriptor should only
be used if COLLCODE cannot be filled because the FAO WIEWS code for this institute is not available.
|COLLMISSID|Identifier of the collecting mission used by the Collecting Institute (e.g. `CIATFOR-052`, `CN426`).
|COLLMISSID|Identifier of the collecting mission as used by the collecting institute (e.g. `CIATFOR-052`, `CN426`).
|===
...
...
@@ -169,16 +185,16 @@ The `coll` field in accession JSON captures collecting data:
To reset or clear an existing value in the accession passport data, it should be provided
as `null`. Not providing a field means the field in the database should not be modified.
.Clearing the country of origin from an accession by sending a `null` value
[source,json,linenums]
----
{
"instCode": "NGA039",
"acceNumb": "TMp-123",
"genus": "Musa",
"orgCty": null <1>
"orgCty": null
}
----
<1> Country of origin of accession is cleared by sending a `null` value.
=== Insert or update accessions
...
...
@@ -187,25 +203,24 @@ or updating existing records in Genesys. It accepts a JSON array of Accession JS
The array provides for sending batches of 50 or 100 accessions in one call, reducing
the HTTP overhead and improving performance.
NOTE: Only the instCode and acceNumb are required (And in some cases genus).
NOTE: If a property is set to `null`, the existing value will be removed from the database.
NOTE: The server will return an error when `instCode` of JSONs does not match the `instCode` in the URL!
NOTE: Only the `instCode` and `acceNumb` are required (and in some cases the `genus`).
The server will return an error when the `instCode` of JSONs does not match the `instCode` in the URL!
=== Deleting accessions
With the introduction of permanent identifiers for accession records in Genesys we have
also introduced the *Accession Archive*. The Archive holds passport data for accession records
also introduced the *accession archive*. The archive holds passport data for accession records
that have been deleted from the active database.
REST endpoint URL `/api/v0/acn/{instCode}/delete` accepts an array of `instCode`, `acceNumb`, `genus` triplets
and deletes corresponding accession record from Genesys. The *DELETE* permission is required for this operation.
and deletes the corresponding accession records from Genesys. The *DELETE* permission is required for this operation.
NOTE: Delete operation will fail if C&E data exists for any accessions listed.
NOTE: The delete operation will fail if C&E data exists for any accessions listed.
.Delete 3 accessions from active database
.Deleting three accessions from the active database
[source,http,linenums]
----
POST /api/v0/acn/SYR002/delete
...
...
@@ -224,11 +239,3 @@ POST /api/v0/acn/SYR002/delete
"genus": "Vicia"
}]
----
[bibliography]
- [[[mcpd2]]] Alercia, A; Diulgheroff, S; Mackay, M.
