TaxonWorks icon

TaxonWorks

TaxonWorks is an integrated web-based workbench for taxonomists and biodiversity scientists

Actions20

  • Asserted Distribution Actions
  • Biological Association Actions
  • Citation Actions
  • Collecting Event Actions
  • Collection Object Actions
  • Content Actions
  • Data Attribute Actions
  • Download Actions
  • Identifier Actions
  • Image Actions
  • Notes Actions
  • Observation Matrices Actions
  • Observations Actions
  • OTUs Actions
  • People Actions
  • Projects Actions
  • Sources Actions
  • Taxon Name Classifications Actions
  • Taxon Name Relationships Actions
  • Taxon Names Actions

Collecting Event → Get

AI-generated

Overview

This node integrates with the TaxonWorks web-based workbench, specifically to retrieve data about "Collecting Events" from a TaxonWorks server. The "Get" operation for the "Collecting Event" resource allows users to query collecting event records using various filters and search parameters.

Typical use cases include:

  • Retrieving collecting event data filtered by collectors, geographic areas, or keywords.
  • Searching collecting events within specific spatial boundaries defined by GeoJSON or Well Known Text (WKT).
  • Filtering recent collecting events or those associated with particular OTUs (Operational Taxonomic Units).
  • Using wildcard searches on labels or verbatim locality descriptions.

Practical examples:

  • Fetch all collecting events collected by any of a list of specified collectors.
  • Retrieve collecting events that fall within a certain polygonal geographic area.
  • Search for collecting events with labels matching a wildcard pattern.
  • Get recent collecting events with spatial geographic areas attached.

Properties

Name Meaning
Server The URL of the TaxonWorks server to connect to (e.g., https://sfg.taxonworks.org).
Additional Fields A collection of optional filters and parameters to refine the search query:
- Collecting Events Wildcards Comma-separated wildcards to match against collecting events.
- Collector IDs Comma-separated list of collector IDs to filter collecting events by collectors.
- Collector IDs Or Boolean flag indicating whether to find collecting events with ANY one of these collectors (true) or ALL of these collectors (false).
- Geo JSON GeoJSON string defining a geographic search area polygon. Example: {"type":"Polygon","coordinates":[[[-89.4122,39.8623],[-87.8357,39.8623],[-87.8357,40.7462],[-89.4122,40.7462],[-89.4122,39.8623]]]}.
- Geographic Area IDs Comma-separated list of geographic area IDs to filter collecting events.
- In Labels Wildcard Wildcard string to match against any label in collecting events.
- In Verbatim Locality Wildcard Wildcard string to match against verbatim locality text in collecting events.
- Keyword IDs And Comma-separated list of keyword IDs where all must be present in associated collecting events.
- Keyword IDs Or Comma-separated list of keyword IDs where any may be present in associated collecting events.
- MD5 Verbatim Labels MD5 hash string to match verbatim labels if inLabels is true.
- OTU IDs Comma-separated list of OTU IDs to filter collecting events associated with these OTUs.
- Recent Option to include metadata for recent searches. Values: Both (default), True, False.
- Spatial Geographic Areas Boolean flag to find collecting events having spatial geographic areas.
- Well Known Text (WKT) WKT string describing the geographic search area.
- Page Number specifying the page of results to retrieve (for pagination).
- Per Number specifying how many results per page to retrieve (for pagination).

Output

The node outputs an array of JSON objects representing the collecting events retrieved from the TaxonWorks API according to the specified filters.

  • Each item in the output array corresponds to a collecting event record with its associated fields as returned by the TaxonWorks API.
  • The structure of each collecting event object depends on the TaxonWorks API response but typically includes identifiers, labels, geographic information, collector details, and other metadata.
  • No binary data output is produced by this node.

Dependencies

  • Requires access to a running TaxonWorks server with API enabled.
  • Requires two credentials configured in n8n:
    • An API key credential for user authentication (referred generically as "an API key credential").
    • An API key credential for project authentication (referred generically as "a required project API authentication token").
  • The node makes HTTP GET requests to the TaxonWorks REST API endpoints.
  • The server URL must be provided as an input property.

Troubleshooting

Common Issues

  • Authentication errors: If the API tokens are invalid or missing, the node will fail to authenticate with the TaxonWorks server.
  • Incorrect server URL: Providing an incorrect or unreachable server URL will cause connection failures.
  • Invalid filter parameters: Supplying malformed GeoJSON, WKT, or invalid IDs may result in API errors or empty responses.
  • Pagination misconfiguration: Setting page or per to zero or negative values might lead to unexpected results or no data.

Error Messages and Resolutions

  • 401 Unauthorized: Check that the API key credentials are correctly set up and valid.
  • 404 Not Found: Verify the server URL and resource path; ensure the TaxonWorks API endpoint is correct.
  • 400 Bad Request: Review the additional fields for invalid or unsupported parameter values, especially GeoJSON and WKT formats.
  • Timeouts or Network Errors: Confirm network connectivity to the TaxonWorks server and that it is operational.

Links and References

Discussion