NSL Integration - AtlasOfLivingAustralia/profile-hub GitHub Wiki

Required Services

The Profiles application uses the following NSL services

acceptable-name

This is used to match user-entered names to the NSL. A response with a single name (i.e. count: 1) is considered to be a match. 0 or more than 1 names are both treated as no match.

Expected response structure (as of 12/8/15)

Only the fields that we use are listed here.

{
  "count": 1,
  "names": [
    {
      "_links": {
        "permalink": {
          "link": "https://biodiversity.org.au/boa/name/apni/89770",
          ...
        }
      },
      ...
      "primaryInstance": [
        {
          ...
          "citationHtml": "Willis, J.H. & Court, A.B. (1956), Changes in the nomenclature of three Victorian Monocotyledons. <i>Muelleria</i> 1(1)"
        }
      ],
      "fullName": "Poa fax J.H.Willis & Court",
      "fullNameHtml": "<scientific><name id='89770'><scientific><name id='72805'><element><i>Poa</i></element></name></scientific> <element><i>fax</i></element> <authors><author id='8322' title='Willis, J.H. &amp; Court, A.B.'>J.H.Willis & Court</author></authors></name></scientific>",
      "simpleName": "Poa fax",
      "simpleNameHtml": "<scientific><name id='89770'><scientific><name id='72805'><element><i>Poa</i></element></name></scientific> <element><i>fax</i></element></name></scientific>"
    }
  ]
}

Note: the name author is extracted from the fullNameHtml element by taking the text between the <authors> tags and stripping out any HTML.

apni-concepts

This service is used by the UI to display the nomenclature block (aka concept) and the drop-down list of concepts. See below for more details.

Expected response structure (as of 20/6/16)

Only the fields that we use are listed here.

{
  "name": {
    "...": ""
  },
  "references": [
    {
      "...": "",
      "_links": {
        "permalink": {
          "link": "..."
        }
      }, 
      "APCReference": "true",
      "citation": "Smith, J. in Hooker, W.J. (ed.) (1846), An Enumeration of ferns cultivated in the Royal Gardens at Kew, in December 1845; with characters and observations on some of the genera and species. Botanical Magazine 72 (Comp.)",
      "citationHtml": "Smith, J. in Hooker, W.J. (ed.) (1846), An Enumeration of ferns cultivated in the Royal Gardens at Kew, in December 1845; with characters and observations on some of the genera and species. <i>Botanical Magazine</i> 72 (Comp.)",
      "citations": [
        {
          "instance": {
            "...": "",
            "_links": {
              "permalink": {
                "link": "https://biodiversity.org.au/boa/instance/apni/936523",
                "...": ""
              }
            }
          },
          "page": "198",
          "...": "",
          "relationship": "taxonomic synonym: <scientific><name id='71252'><scientific><name id='70914'><element><i>Doodia</i></element></name></scientific> <element><i>maxima</i></element> <authors><author id='7475' title='Smith, John'>J.Sm.</author></authors></name></scientific>",
          "nameType": "...",
          "fullName": "...",
          "simpleName": "...",
          "...": ""
        }
      ],
      "notes": [
        {
          "instanceNoteKey": "Type",
          "instanceNoteText": "\"Queensland? Leichhardt. S. Australia. Stony ground, Cooper's Creek A.C. Gregory.\""
        }
      ]
    }
  ]
}

find-concept

This service is used during the bulk import process to find the nomenclature block (aka concept). It is used instead of apni-concepts because it has better performance and only returns a single nomenclature.

Expected response structure (as of 20/6/16)

Only the fields that we use are listed here.

{
  "...": "",
  "instance": {
    "...": "",
    "_links": {
      "permalink": {
        "link": "https://biodiversity.org.au/boa/instance/apni/578620",
        "...": ""
      }
    },
    "...": "",
    "citation": "Parris, B.S. in McCarthy, P.M. (ed.) (1998), Doodia. Flora of Australia 48",
    "citationHtml": "Parris, B.S. in McCarthy, P.M. (ed.) (1998), Doodia. <i>Flora of Australia</i> 48"
  }
}

Name resource

This is used when displaying a profile to retrive the protolgue and name status.

Expected response structure (as of 20/06/16)

Only the fields that we use are listed here.

{
  "name": {
    ...
    "status": "legitimate",
    ...
    "primaryInstance": [
      {
        ...
        "citationHtml": "Brown, R. (1810), <i>Prodromus Florae Novae Hollandiae</i>"
      }
    ]
  }
}

Export Names as CSV

This service is used during the bulk import process to retrieve and cache all NSL names so we don't need to invoke a service for every name being imported.

Expected response structure (as of 20/6/16)

A CSV with at least the following fields:

  • canonicalName
  • canonicalNameHtml
  • scientificName
  • scientificNameHtml
  • scientificNameID (this is the instance url, e.g. https://biodiversity.org.au/boa/name/apni/54425)
  • taxonRank
  • scientificNameAuthorship
  • namePublishedIn
  • namePublishedInYear
  • nomenclaturalStatus

Nomenclature

During a bulk import, the system uses the NSL find-concepts service if the 'NSL search' nomenclature matching strategy has been chosen. This returns the instanceId of the first citation in the nomenclature block. If the source data includes a nomenclature id, then it is assumed that this id is also the instanceId of the first citation in the target nomenclature block, NOT the reference id.

When viewing/editing a profile, the system uses the NSL apni-concepts service. This returns all of the references (concepts), each with a list of citations. We need to store the instanceId of the first citation of the selected concept, NOT the reference id.

This is due to performance issues during the bulk import: apni-concepts does a lot of work, and running the bulk import with several threads across 10-20,000 records put too much load on the NSL servers.

The following sequence diagram outlines the basic flow for identifying a nomenclature concept.

⚠️ **GitHub.com Fallback** ⚠️