- Authors: Last, First (ORCID); ...
- License: Apache 2
- Package source code on GitHub
- Submit Bugs and feature requests
- Contact us: support@dataone.org
- DataONE discussions
Notification Service provides a notification system for datasets and portals, to notify both portal owners/editors and the community about events such as downloads, views, citations, derived products, new datasets added to a portal, reminders to update a portal, etc.
DataONE in general, and notification-service in particular, are open source, community projects. We welcome contributions in many forms, including code, graphics, documentation, bug reports, testing, etc.
Use the DataONE discussions to discuss these contributions with us.
- API Usage Examples
- Getting Started - Running Notification Service Yourself
- Developer Guide
- Appendix 1: Building and Publishing the Container Images
Documentation is a work in progress, and can be found here in the README
You can try out API queries on the interactive web page at: ${BASE_URL}/notifications
Example, for the instance running on the NCEAS dev cluster:
- https://notifications.test.dataone.org/notifications
- JWT token: > - Enter it using the
Authorize 🔒button in the web UI
Tip
You can get an auth token by logging into a metacat instance that uses the same CN as the installation being tested, and going to My Profile > Settings > Authentication Token. For example:
- If it's a Production notification service, it should use
https://cn.dataone.org/cn/v2; get a token from any prod metacat, e.g. arcticdata.io - If it's a test/development notification service, it will likely use
https://cn-stage-2.test.dataone.org/cn/v2; get a token from the nceas dev metacat - If you are deploying via the values-rancher-desktop-ns-example.yaml file, the auth link is 'https://cn-sandbox.test.dataone.org/cn/v2'; get a token from cn-sandbox
Example API interactions, using curl:
# BASE_URL: the base URL of the notification service instance you're using
BASE_URL="https://notifications.test.dataone.org"
# TOKEN: a valid JWT token from the CN used by the installation under test (see Tip above)
TOKEN="your-jwt-token-here"
# Subscribe user authenticated with jwt $TOKEN, to update-notifications for
# the dataset identified by {pid}
#
$ curl --request POST "${BASE_URL}/notifications/v1/datasetChanges/{pid}" \
--header "Authorization: Bearer $TOKEN" | jq
# Get a list of subscriptions for user authenticated with jwt $TOKEN:
#
$ curl --request GET "${BASE_URL}/notifications/v1/datasetChanges" \
--header "Authorization: Bearer $TOKEN" | jq
# Unsubscribe user authenticated with jwt $TOKEN, from notifications for the
# dataset identified by {pid}
#
$ curl --request DELETE "${BASE_URL}/notifications/v1/datasetChanges/{pid}" \
--header "Authorization: Bearer $TOKEN" | jqThe simplest way to try out the notification service is to use the Helm chart to deploy in a Kubernetes ("K8s") cluster - see the Helm Chart README.
It is also possible to run locally on your development machine (see Building and Running on a Localhost Web Application Server), although this approach is not well tested or supported.
This section is for developers who want to build, modify, or test the application, or run it locally on their development machine.
Notification Service uses the Jakarta EE framework. Jakarta EE is the latest version of what was formerly Oracle's Java Enterprise Edition (originally J2EE). It has now been moved to the Eclipse Foundation, where it is maintained as open source software.
Here are some useful links for those unfamiliar with Jakarta EE:
This is a java application, built using the Maven build tool, and deployed either on a local machine or in a docker container on a Kubernetes Cluster (deployed using helm).
Tip
You do not need to build the helm chart or container images yourself, as they are already built and published to the GitHub Container Registry (GHCR) each time changes are pushed to GitHub, by this GitHub Action.
See Appendix 1 for instructions on how to build and publish the image manually, if you wish to do so.
Prerequisites: The build and tests require:
- Java 25. It can be downloaded from Adoptium. You can also set Java 25 as the default for only the current directory, using the simple, lightweight jenv tool. This allows you to set global and local Java versions, and switch between them easily.
- Maven v3.9+.
$ mvn clean package [ -DskipTests ]The tests and their resources all reside in the src/test/java directory. They fall into three categories, and it is important to distinguish between them and adhere to their respective conventions:
Unit tests are intended to test individual classes and methods.
Important
Unit tests must have all their dependencies mocked out. They should NEVER require a running instance of the application, or other components like a database.
Unit tests are named *Test.java, and are run using the Maven test goal:
mvn clean testIntegration tests are intended to test the integration and interactions of multiple classes or modules.
Important
Integration tests should NEVER require a running instance of the application (See Smoke Tests). They may, however, rely on other components (such as a database), which are provided and managed by the test framework. (For example, see TestUtils::getTestDb, which uses TestContainers). This enables the test suite to be self-contained, so it will run in CI/CD pipelines.
Integration tests are named *IT.java, and are run using the Maven verify goal (which also runs the unit tests first):
mvn clean verifySmoke tests are intended to be executed against a running instance of the application (e.g. in production), to verify that it is working as expected, after installation or upgrade.
Smoke tests are named *SmokeIT.java, and are run using the Maven verify goal, with the following additional command-line args:
-PsmokeTest: this tells Maven to run only the smoke tests.-DBASE_URL: the base URL of the notification service instance you're using-DTOKEN: a valid JWT token from the CN used by the installation under test (see API Usage Examples for details of how to get a token)
# Can set this as an environment variable, to maintain secrecy:
export TOKEN="your-jwt-token-here"
mvn verify -PsmokeTest -DBASE_URL="https://notifications.test.dataone.org" -DTOKEN="$TOKEN"Note
Prerequisites: In addition to the Java and maven versions listed above, you will need:
- Apache TomEE MicroProfile v10+ (or another web application server that is fully compliant with Jakarta EE 10.
Tomcat version 10 is NOT yet fully compliant with Jakarta EE 10, so for the time being, it is recommended to use Apache TomEE, which is an Apache-maintained combination of Tomcat and the additional libraries needed to support Jakarta EE. TomEE is available in different "flavors"; choose the
MicroProfileversion.) - A running PostgreSQL database. This can easily be started in a container, using the provided script:
./scripts/docker-run-db.sh. - RabbitMQ: you should be able to configure Notification Service to work with any RabbitMQ instance, by editing the settings in
ns-common/src/main/resources/properties.yaml. This approach is not tested or supported, but should work if you have a working RabbitMQ instance running on your local machine.
Build with maven and copy the war file to your TomEE webapps directory:
$ mvn clean package -DskipTests
$ cp ./target/notification-service-[VERSION].war $TOMEE_HOME/webapps/notifications.war
# The war file name determines the context used in the URL.
# In this case, the context is `notifications`, so the base URL
# will be `http://localhost:8080/notifications/...etc`....and (re)start TomEE. You can then visit the URL:
http://localhost:8080/notifications/v1/metrics/ping, which should return {"status":"ok"}. You can also validate that the service is working correctly by running the smoke tests.
-
First package the application using maven, which will create the necessary war and jar files:
$ mvn clean package [ -DskipTests ]
-
Then set the following environment variables:
# Set the tag for the image TAG="feature5" # Set the version - this must match the version in the built jar file's name, which is set in the pom.xml file. NS_VERSION="1.0.0-SNAPSHOT" # Set the platform for the build. # "linux/amd64" is compatible with most cloud providers and Kubernetes clusters. # "linux/arm64" is compatible with Apple M-series chips. PLATFORM="linux/arm64"
-
Then build and push the container images using the provided Dockerfiles:
-
ns-consumer:# build docker buildx build -t ghcr. io/dataoneorg/notification-consumer:"$TAG" \ -f docker/Dockerfile-consumer --build-arg TAG=$TAG --build-arg NS_VERSION=${NS_VERSION} \ --platform "$PLATFORM" --no-cache . # push docker push ghcr.io/dataoneorg/notification-consumer:"$TAG"
-
ns-web-api:# build docker buildx build -t ghcr. io/dataoneorg/notification-service:"$TAG" \ -f docker/Dockerfile-web-api --build-arg TAG=$TAG --build-arg NS_VERSION=${NS_VERSION} \ --platform "$PLATFORM" --no-cache . # push docker push ghcr.io/dataoneorg/notification-service:"$TAG"
Copyright [2024] [Regents of the University of California]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Work on this package was supported by:
- DataONE Network
- Arctic Data Center: NSF-PLR grant #2042102 to M. B. Jones, A. Budden, M. Schildhauer, and J. Dozier
Additional support was provided for collaboration by the National Center for Ecological Analysis and Synthesis, a Center funded by the University of California, Santa Barbara, and the State of California.
