diff --git a/.github/workflows/gdc-all-channels.yml b/.github/workflows/gdc-all-channels.yml index 2f9624de..4ef1799d 100644 --- a/.github/workflows/gdc-all-channels.yml +++ b/.github/workflows/gdc-all-channels.yml @@ -2,7 +2,8 @@ name: Generate list of all GDC channels on: schedule: - - cron: '0 * * * *' # runs every hour + - cron: '0/15 * * * *' # runs every 15 minutes + # - cron: '0 * * * *' # runs every hour # - cron: '* * * * *' # runs every minute, for debugging env: diff --git a/.github/workflows/guide-infcom.yml b/.github/workflows/guide-infcom.yml new file mode 100644 index 00000000..a7569103 --- /dev/null +++ b/.github/workflows/guide-infcom.yml @@ -0,0 +1,47 @@ +name: WIS2 Guide for INFCOM review + +on: + push: + branches: + - INFCOM-4 + +env: + FILE_BASENAME: wis2-guide-DRAFT-INFCOM-4 + +jobs: + build-wis2-guide: + name: Generate documentation + runs-on: ubuntu-latest + steps: + - name: Install dependencies + run: | + sudo apt-get update -y \ + && sudo apt-get install -y pandoc \ + && sudo gem install asciidoctor asciidoctor-pdf + - name: checkout repository + uses: actions/checkout@master + - name: build documentation + run: | + mkdir -p /tmp/wis2-guide/guide/images \ + && cd guide \ + && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \ + && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \ + && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc \ + && cp images/*.png /tmp/wis2-guide/guide/images \ + && cd .. + - name: checkout gh-pages branch + uses: actions/checkout@master + with: + ref: gh-pages + - name: update gh-pages branch and publish + run: | + git checkout gh-pages + git config --global user.email "tomkralidis@gmail.com" + git config --global user.name "Tom Kralidis" + rm -rf guide/infcom + mkdir -p guide/infcom + mv -f /tmp/wis2-guide/* guide/infcom + git add . + git commit -am "update WIS2 Guide INFCOM build" + git push + diff --git a/.github/workflows/guide.yml b/.github/workflows/guide.yml index 37b90bc6..d6b87ef1 100644 --- a/.github/workflows/guide.yml +++ b/.github/workflows/guide.yml @@ -19,18 +19,18 @@ jobs: && sudo apt-get install -y pandoc \ && sudo gem install asciidoctor asciidoctor-pdf - name: checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@master - name: build documentation run: | mkdir -p /tmp/wis2-guide/guide/images \ && cd guide \ - && asciidoctor --trace -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \ + && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \ && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \ && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc \ && cp images/*.png /tmp/wis2-guide/guide/images \ && cd .. - name: checkout gh-pages branch - uses: actions/checkout@v3 + uses: actions/checkout@master with: ref: gh-pages - name: update gh-pages branch and publish diff --git a/.github/workflows/test-guide-infcom.yml b/.github/workflows/test-guide-infcom.yml new file mode 100644 index 00000000..ff8a6c4c --- /dev/null +++ b/.github/workflows/test-guide-infcom.yml @@ -0,0 +1,31 @@ +name: Test WIS2 Guide build for INFCOM review + +on: + pull_request: + branches: + - INFCOM-4 + paths: + - '**.adoc' + +env: + FILE_BASENAME: wis2-guide-DRAFT-INFCOM-4 + +jobs: + build-wis2-guide: + name: Test documentation build + runs-on: ubuntu-latest + steps: + - name: Install dependencies + run: | + sudo apt-get update -y \ + && sudo apt-get install -y pandoc \ + && sudo gem install asciidoctor asciidoctor-pdf + - name: checkout repository + uses: actions/checkout@master + - name: build documentation + run: | + mkdir -p /tmp/wis2-guide/guide/images \ + && cd guide \ + && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \ + && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \ + && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc diff --git a/.github/workflows/test-guide.yml b/.github/workflows/test-guide.yml index ac48da73..dd4229e2 100644 --- a/.github/workflows/test-guide.yml +++ b/.github/workflows/test-guide.yml @@ -3,7 +3,7 @@ name: Test WIS2 Guide build on: pull_request: paths: - - '**.adoc' + - '**.adoc' env: FILE_BASENAME: wis2-guide-APPROVED @@ -19,11 +19,11 @@ jobs: && sudo apt-get install -y pandoc \ && sudo gem install asciidoctor asciidoctor-pdf - name: checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@master - name: build documentation run: | mkdir -p /tmp/wis2-guide/guide/images \ && cd guide \ - && asciidoctor --trace -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \ + && asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o /tmp/wis2-guide/guide/${FILE_BASENAME}.html index.adoc \ && asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output /tmp/wis2-guide/guide/${FILE_BASENAME}.docx \ && asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o /tmp/wis2-guide/guide/${FILE_BASENAME}.pdf index.adoc diff --git a/WIS2-Development/Readme.md b/WIS2-Development/Readme.md deleted file mode 100644 index 06eaef52..00000000 --- a/WIS2-Development/Readme.md +++ /dev/null @@ -1 +0,0 @@ -Welcome to the WIS2 Development Repository, the reference hub for new advancements in the WMO Information System 2.0 (WIS2). This repository includes proposals for the establishment of Sensor Centres, the WIS2 Global Replay service, a shared MQTT service, and other key components aimed at enhancing the WIS 2.0. diff --git a/WIS2-Development/Sensor-Centre.adoc b/WIS2-Development/Sensor-Centre.adoc deleted file mode 100644 index 8b137891..00000000 --- a/WIS2-Development/Sensor-Centre.adoc +++ /dev/null @@ -1 +0,0 @@ - diff --git a/guide/Makefile b/guide/Makefile index b18ad3d3..1ff50f92 100644 --- a/guide/Makefile +++ b/guide/Makefile @@ -1,7 +1,7 @@ FILE_BASENAME=wis2-guide-APPROVED html: - asciidoctor --trace -o ${FILE_BASENAME}.html index.adoc + asciidoctor --trace -a stylesheet=css/wmo-asciidoc.css -o ${FILE_BASENAME}.html index.adoc pdf: asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o ${FILE_BASENAME}.pdf index.adoc diff --git a/guide/README.md b/guide/README.md index 6cb9ee1a..aed6f517 100644 --- a/guide/README.md +++ b/guide/README.md @@ -27,10 +27,7 @@ asciidoctor --trace -o wis2-guide.html index.adoc asciidoctor --trace -r asciidoctor-pdf --trace -b pdf -o wis2-guide.pdf index.adoc # create Word document asciidoctor --trace --backend docbook --out-file - index.adoc | pandoc --from docbook --to docx --output wis2-guide.docx -``` - # check links -```bash find . -name "???.adoc" -exec asciidoc-link-check -p -c asciidoc-link-check-config.json {} \; ``` diff --git a/guide/css/wmo-asciidoc.css b/guide/css/wmo-asciidoc.css new file mode 100644 index 00000000..acb8e596 --- /dev/null +++ b/guide/css/wmo-asciidoc.css @@ -0,0 +1,65 @@ +@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; +@import "https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@2.0/data/stylesheets/asciidoctor-default.css"; + +h1, h2, h3, h4, h5, h6, +.sidebarblock > .content > .title { + color: #005398; + font-weight: bold; +} + +#toctitle { + color: #005398; + font-weight: bold; +} + +#content #toc { + border: 1px solid #005398; + margin-bottom: 1.25em; + padding: 1.25em; + background: #ffffff; + border-radius: 4px; +} + +#header { + border-bottom: 4px solid #005398; + margin-top: 10px; + +} + +#header>h1:first-child { + color: #005398; + margin-top: 15px; + margin-bottom: 0; +} + +#header::before { + content: ""; + display: block; + height: 72px; + background: url("images/wmo-logo-en.png") no-repeat left center; + background-size: contain; +} + +body { + font-family: "Montserrat", sans-serif; +} + +.subheader, .admonitionblock td.content>.title, .audioblock>.title, .exampleblock>.title, .imageblock>.title, .listingblock>.title, .literalblock>.title, .stemblock>.title, .openblock>.title, .paragraph>.title, .quoteblock>.title, table.tableblock>.title, .verseblock>.title, .videoblock>.title, .dlist>.title, .olist>.title, .ulist>.title, .qlist>.title, .hdlist>.title { + line-height: 1.45; + color: #005398; + font-weight: 400; + margin-top: 0; + margin-bottom: .25em; +} + +#footer { + max-width: none; + background: #005398; + padding: 1.25em; +} + +#footer-text { + color: #ffffff; + line-height: 1.44; + font-weight: bold; +} diff --git a/guide/images/wmo-logo-en.png b/guide/images/wmo-logo-en.png new file mode 100644 index 00000000..6d5f66f0 Binary files /dev/null and b/guide/images/wmo-logo-en.png differ diff --git a/guide/index.adoc b/guide/index.adoc index c7d97c24..f7fa0da2 100644 --- a/guide/index.adoc +++ b/guide/index.adoc @@ -1,8 +1,8 @@ -:title: Guide to the WMO Information System Volume II (APPROVED) - WMO Information System 2.0 +:title: Guide to the WMO Information System (WMO-No. 1061), Volume II - WMO Information System 2.0 (APPROVED) :titletext: {title} -:version: 1.0.0 -:date: {docdate} -:copyright: Copyright © 2024 World Meteorological Organization (WMO) +:version: 1.2.0 +:date: 2026-02-02 +:copyright: Copyright © 2026 World Meteorological Organization (WMO) :doctype: book :encoding: utf-8 :lang: en @@ -17,7 +17,7 @@ |=== |{set:cellbgcolor:#FFFFFF} |[big]*World Meteorological Organization* -|Date: {date} +|Date: 2026-02-02 |Version: {version} |Document status: APPROVED |Document location: https://wmo-im.github.io/wis2-guide/guide/wis2-guide-APPROVED.html @@ -42,6 +42,8 @@ include::sections/part4/index.adoc[] include::sections/part5/index.adoc[] +include::sections/annex_a.adoc[] + // include::sections/other-considerations.adoc[] diff --git a/guide/sections/annex_a.adoc b/guide/sections/annex_a.adoc new file mode 100644 index 00000000..02a50433 --- /dev/null +++ b/guide/sections/annex_a.adoc @@ -0,0 +1,11 @@ +[appendix] +:appendix-caption: Annex +== Revision History + +[cols="12,18,12,12,46",options="header"] +|=== +|Date |Release |Proposed by | Primary clauses modified |Approved by +|June 2024| 1.0.0 | SC-IMT | Initial approval for publication| EC-78 +|November 2024 | 1.1.0 | SC-IMT |https://github.com/wmo-im/wis2-guide/milestone/3?closed=1[See GitHub]| Fast-track 2024-2 +|February 2026 | 1.2.0 | SC-IMT |https://github.com/wmo-im/wis2-guide/milestone/7?closed=1[See GitHub] |Fast-track 2025-2 +|=== diff --git a/guide/sections/part1/data-consumer.adoc b/guide/sections/part1/data-consumer.adoc index 8afcda8d..45ff9143 100644 --- a/guide/sections/part1/data-consumer.adoc +++ b/guide/sections/part1/data-consumer.adoc @@ -12,7 +12,7 @@ The Global Discovery Catalogue is accessible via an API and provides a low-barri ==== 1.2.2 How to subscribe to notifications about the availability of new data -WIS2 provides notifications about updates to datasets, for example, a notification may indicate that a new observation record from an automatic weather station has been added to a dataset of surface observations. These notifications are published on Message Brokers. Where data consumers need to use data rapidly once they have been published (for example, as inputs to a weather prediction model), they should subscribe to one or more Global Brokers to get notification messages using Message Queuing Telemetry Transport (MQTT) protocol.footnote[Subscribing to notifications about newly available data ensures that the data consumers do not need to continually to poll the data server to check for updates.] +WIS2 provides notifications about updates to datasets, for example, a notification may indicate that a new observation record from an automatic weather station has been added to a dataset of surface observations. These notifications are published on Message Brokers. Where data consumers need to use data rapidly once they have been published (for example, as inputs to a weather prediction model), they should subscribe to one or more Global Brokers to get notification messages using Message Queuing Telemetry Transport (MQTT) protocol.footnote:[Subscribing to notifications about newly available data ensures that the data consumers do not need to continually to poll the data server to check for updates.] In WIS2, notifications are republished by Global Brokers to ensure resilient distribution. Consequently, there will be multiple places where one can subscribe. Data consumers requiring real-time notifications must subscribe to Global Brokers. Data consumers should subscribe to more than one Global Broker to ensure that notifications continue to be received if a Global Broker instance fails. diff --git a/guide/sections/part1/data-publisher.adoc b/guide/sections/part1/data-publisher.adoc index 6f6ea672..9dd80304 100644 --- a/guide/sections/part1/data-publisher.adoc +++ b/guide/sections/part1/data-publisher.adoc @@ -27,9 +27,9 @@ Copies of all discovery metadata records from WIS2 are held in the Global Discov Depending on local arrangements, your GISC may be able to assist in transferring discovery metadata record(s) to the Global Discovery Catalogues. If this is not the case, data publishers will need to publish the discovery metadata record(s) themselvesfootnote:[In the future, WIS2 may provide metadata publication services (for example, through a WIS2 metadata management portal) to assist with this task. However, such services are not currently available.] using one of two methods: * The simplest method is to encode the discovery metadata record as a file and publish it to an HTTP server, where it can be accessed with a URL. -* Alternatively, a data publisher may operate a local metadata catalogue through which discovery metadata records can be shared using an API (for example, OGC API – Recordsfootnote:[See OGC API - Records - Part 1: Core: https://docs.ogc.org/DRAFTS/20-004.html.]). Each discovery metadata record (for instance, an item that is part of the discovery metadata catalogue) can be accessed with a unique URL via the API . +* Alternatively, a data publisher may operate a local metadata catalogue through which discovery metadata records can be shared using an API (for example, OGC API – Records). Each discovery metadata record (for instance, an item that is part of the discovery metadata catalogue) can be accessed with a unique URL via the API. -In both cases, a notification message needs to be published on a Message Broker that tells WIS2 that there is a new discovery metadata record to upload and that it can be accessed at the specified URL.footnote:[Both data and metadata are published using the same notification message mechanism to announce the availability of new resources.] Notification messages shall conform to the specification given in the _Manual on WIS_, Volume II - Appendix E. WIS2 Notification Message. They must also be published on a topic that conforms to the specification given in the _Manual on WIS_, Volume II - Appendix D. WIS2 Topic Hierarchy. For example, metadata published by Deutscher Wetterdienst would use the following topic: ``origin/a/wis2/de-dwd/metadata/core``. +In both cases, a notification message needs to be published on a Message Broker that tells WIS2 that there is a new discovery metadata record to upload and that it can be accessed at the specified URL.footnote:[Both data and metadata are published using the same notification message mechanism to announce the availability of new resources.] Notification messages shall conform to the specification given in the _Manual on WIS_, Volume II - Appendix E. WIS2 Notification Message. They must also be published on a topic that conforms to the specification given in the _Manual on WIS_, Volume II - Appendix D. WIS2 Topic Hierarchy. For example, metadata published by Deutscher Wetterdienst would use the following topic: ``origin/a/wis2/de-dwd/metadata``. These discovery metadata records are then propagated through the Global Service components into the Global Discovery Catalogue, where data consumers can search and browse for datasets of interest. @@ -37,6 +37,8 @@ Upon receipt of a new discovery metadata record, a Global Discovery Catalogue (s Discovery metadata must be published in the Global Discovery Catalogues before the data are published. +Discovery metadata should be re-published on a daily basis. + ==== 1.3.3 How to provide data to WIS2 WIS2 is based on the web architecture.footnote:[See Architecture of the World Wide Web, Volume One: https://www.w3.org/TR/webarch/.] As such it is _resource oriented_. Datasets are resources; the "granules" of data grouped in a dataset are resources; and the discovery metadata records that describe datasets are resources. In web architecture, every resource has a unique identifier (such as a URIfootnote:[See RFC 3986 - Uniform Resource Identifier (URI) - Generic Syntax: https://datatracker.ietf.org/doc/html/rfc3986.]), which can be used to resolve the identified resource and interact with it (for example, to download a representation of the resource over an open-standard protocol such as HTTP). diff --git a/guide/sections/part2/global-services.adoc b/guide/sections/part2/global-services.adoc index 3dcaa003..82d48360 100644 --- a/guide/sections/part2/global-services.adoc +++ b/guide/sections/part2/global-services.adoc @@ -5,9 +5,9 @@ The successful operation of WIS2 depends on a set of Global Services running wel Depending on the nature of the Global Service, the following are the minimum capabilities needed to ensure that the level of service as a whole reaches 100% (or very close): -* Three Global Brokers, with each Global Broker connected to at least two other Global Brokers; -* Three Global Caches, with each Global Cache connected to at least two Global Brokers and capable of downloading data from all WIS2 Nodes providing core data; -* Two Global Discovery Catalogues, with each Global Discovery Catalogue connected to at least one Global Broker; +* Three Global Brokers, with each Global Broker connected to at least two other Global Brokers; +* Three Global Caches, with each Global Cache connected to at least two Global Brokers and capable of downloading data from all WIS2 Nodes providing core data; +* Two Global Discovery Catalogues, with each Global Discovery Catalogue connected to at least one Global Broker; * Two Global Monitors - each Global Monitor should scrape the metrics from all other Global Services In addition to the above, WIS architecture can accommodate adding (or removing) Global Services. Candidate WIS centres should inform their WIS NFP and contact the WMO Secretariat to discuss their offer to provide a Global Service. @@ -36,11 +36,10 @@ WIS2 Global Services (Global Brokers, Global Caches, and Global Discovery Catalo There is no requirement for WIS2 Nodes to provide monitoring metrics. However their WIS2 interfaces may be queried remotely by Global Services, which can then provide metrics on the availability of WIS2 Nodes. -Metrics for WIS2 monitoring should follow the naming convention ``wmo__``, where ```` is the name of the responsible WMO programme and ```` is the name of the metric. Examples of WIS2 metrics include: +Metrics for WIS2 monitoring should follow the naming convention ``wmo__``, where ```` is the name of the responsible WMO programme and ```` is the name of the metric. Examples of WIS2 metrics include (but are not limited to): - ``wmo_wis2_gc_downloaded_total``, and - - ``wmo_wis2_gb_messages_invalid_total``. +* ``wmo_wis2_gc_downloaded_total`` +* ``wmo_wis2_gb_messages_invalid_total`` The full set of the WIS2 monitoring metrics is given in WMO: WIS2 Metric Hierarchy footnote:[See https://github.com/wmo-im/wis2-metric-hierarchy.] @@ -83,6 +82,7 @@ In the following sections, and for each Global Service, a set of metrics is defi ** An off the shelf broker implementing both MQTT 3.1.1 and MQTT 5.0 in a highly available setup, typically in a cluster mode. Tools such as EMQX, HiveMQ, VerneMQ, RabbitMQ (in its latest versions) are compliant with these requirements. The open source version of Mosquitto cannot be clustered and therefore should not be used as part of a Global Broker. ** Additional features, including anti-loop detection, notification message format compliance, validation of the published topic, and metrics provision. +* When connected to a local WIS centre broker or a Global Service broker, the metric ``wmo_wis2_gb_connected_flag`` will be equal to 1. When the connection cannot be established or is interrupted the metric ``wmo_wis2_gb_connected_flag`` will be equal to 0. * When receiving a message from a local WIS centre broker or a Global Service broker, the metric ``wmo_wis2_gb_messages_received_total`` will be increased by 1. * A Global Broker will check if a discovery metadata record exists corresponding to the topic on which a message has been published. If there is no corresponding discovery metadata record, the Global Broker will discard non-compliant messages and will raise an alert. The metric ``wmo_wis2_gb_messages_no_metadata_total`` will be increased by 1. The Global Broker should not request information from a Global Discovery Catalogue for each notification message but should keep a cache of all valid topics for every ``centre-id``. * A Global Broker will check that the topic on which the message is received is valid. If the topic is invalid, the Global Broker will discard non-compliant messages and will raise an alert. The metric ``wmo_wis2_gb_invalid_topic_total`` will be increased by 1. @@ -91,7 +91,7 @@ In the following sections, and for each Global Service, a set of metrics is defi * A Global Broker will republish a message only once. It will record the message identifier (``id``) (as defined in the WIS2 Notification Message) of messages already published and will discard subsequent identical messages (those with the same message ``id``). This is the anti-loop feature of the Global Broker. * When publishing a message to the local broker, the metric ``wmo_wis2_gb_messages_published_total`` will be increased by 1. * All above-defined metrics will be made available on HTTPS endpoints that the Global Monitor will ingest from regularly. -* As a convention, the Global Broker centre-id will be ``tld-{centre-name}-global-broker``. +* As a convention, the Global Broker centre-id will be ``{tld}-{centre-name}-global-broker``. * A Global Broker should operate with a fixed IP address so that WIS2 Nodes can permit access to download resources based on IP address filtering. A Global Broker should also operate with a publicly resolvable Domain Name System (DNS) name pointing to that IP address. The WMO Secretariat must be informed of the IP address and/or hostname and any subsequent changes. ==== 2.7.4 Global Cache @@ -120,7 +120,7 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This * If core data are not cached on a Global Cache (that is, if the data are flagged as ``"cache": false`` or if the Global Cache decides not to cache these data), the Global Cache shall nevertheless republish the WIS2 Notification Message to the ``cache/a/wis2/...`` topic. In this case, the message id will be changed, and the rest of the message will not be modified. * A Global Cache should operate with a fixed IP address so that WIS2 Nodes can permit access to download resources based on IP address filtering. A Global Cache should also operate with a publicly resolvable DNS name pointing to that IP address. The WMO Secretariat must be informed of the IP address and/or hostname, and any subsequent changes. * A Global Cache should validate the integrity of the resources it caches and only accept data that match the integrity value from the WIS2 Notification Message. If the WIS2 Notification Message does not contain an integrity value, the Global Cache should accept the data as valid. In this case, the Global Cache may add an integrity value to the message it republishes. -* As a convention, the Global Cache centre-id will be ``tld-{centre-name}-global-cache``. +* As a convention, the Global Cache centre-id will be ``{tld}-{centre-name}-global-cache``. ===== 2.7.4.2 Practices and procedures @@ -138,6 +138,7 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This **** If the message contains an integrity value for the data, verify the integrity of the data; **** If data is downloaded successfully, move the data to the HTTP endpoint of the Global Cache; **** Wait until the data becomes available at the endpoint; +**** Add the property ``properties.global-cache`` with the value of the centre identifier of the Global Cache to identify the origin of the data source downloaded by downstream applications; **** Modify the message identifier and the canonical link's ``href`` of the received message and leave all other fields untouched; **** Republish the modified message to topic ``cache/a/wis2/...`` ,matching the ``+/a/wis2/...`` where the original message has been received; **** The metric ``wmo_wis2_gc_downloaded_total`` will be increased by 1; The metric ``wmo_wis2_gc_dataserver_last_download_timestamp_seconds`` will be updated with the timestamp (in seconds) of the last successful download from the WIS2 Node or Global Cache; @@ -147,6 +148,7 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This * If the Global Cache is not able to download the data, the metric ``wmo_wis2_gc_downloaded_error_total`` will be increased by 1. * A Global Cache shall provide the metric defined in this Guide at an HTTP endpoint. * A Global Cache should make sure that data are downloaded in parallel and that downloads are not blocking each other. +* A Global Cache will implement https://datatracker.ietf.org/doc/html/rfc2616#section-10[Status Code Definitions] as defined by the https://datatracker.ietf.org/doc/html/rfc2616[HTTP specification]. * The metric ``wmo_wis2_gc_dataserver_status_flag`` will reflect the status of the connection to the download endpoint of the centre. Its value will be 1 when the endpoint is up and 0 otherwise. * The metric ``wmo_wis2_gc_last_metadata_timestamp_seconds`` will reflect the datetime (as a timestamp, the number of seconds since the UNIX epoch) of the last metadata resource processed by a given centre. @@ -156,12 +158,12 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This ===== 2.7.5.1 Technical considerations * The Global Discovery Catalogue provides data consumers with a mechanism for discovering and searching for datasets of interest as well as learning how to interact with and find out more information about those datasets. -* The Global Discovery Catalogue implements the OGC API – Records – Part 1: Core standardfootnote:[See OGC-API Records - Part 1 https://docs.ogc.org/DRAFTS/20-004.html.], adhering to the following conformance classes and their dependencies: +* The Global Discovery Catalogue implements the OGC API – Records – Part 1: Core standardfootnote:[See OGC-API Records - Part 1 https://docs.ogc.org/is/20-004r1/20-004r1.html.], adhering to the following conformance classes and their dependencies: ** Searchable Catalog (Deployment); ** Searchable Catalog - Sorting (Deployment); ** Searchable Catalog - Filtering (Deployment); -** JSON (Building Block); -** HTML (Building Block). +** JSON (Common Component); +** HTML (Common Component). * The Global Discovery Catalogue will make discovery metadata available via the collection identifier `wis2-discovery-metadata`. * The Global Discovery Catalogue advertises the availability of datasets and how to access them or subscribe to updates. * The Global Discovery Catalogue does not advertise or list the availability of individual data objects that comprise a dataset (that is, data files). @@ -181,13 +183,13 @@ In WIS2, Global Caches provide access to WMO core data for data consumers. This * A Global Discovery Catalogue will generate and store a zip file of all WCMP2 records once a day; this file will be made be accessible via HTTP. The zipfile will include a directory named after the centre-id of the Global Discovery Catalogue containing all WCMP2 records. * A Global Discovery Catalogue will publish a WIS2 Notification Message of its zip file of all WCMP2 records on its centre-id's +metadata+ topic (for example, `origin/a/wis2/centre-id/metadata`, where `centre-id` is the centre identifier of the Global Discovery Catalogue). * A Global Discovery Catalogue may initialize itself (cold start) from a zip file of all WCMP2 records published. -* As a convention, a Global Discovery Catalogue's centre-id will be ``tld-{centre-name}-global-discovery-catalogue``. +* As a convention, a Global Discovery Catalogue's centre-id will be ``{tld}-{centre-name}-global-discovery-catalogue``. -===== 2.7.5.2 Global Discovery Catalogue reference implementation: wis2-gdc +===== 2.7.5.2 Global Discovery Catalogue Reference Implementation: wis2-gdc To provide a Global Discovery Catalogue, Members may use whichever software components they consider most appropriate to comply with the WIS2 technical regulations. -To assist Members in participating in WIS2, a free and open-source Global Discovery Catalogue reference implementation, wis2-gdc, is available for download and use. wis2-gdc builds on mature and robust free and open-source software components that are widely adopted for operational use. +To assist Members in participating in WIS2, a free and open-source Global Discovery Catalogue Reference Implementation, wis2-gdc, is available for download and use. wis2-gdc builds on mature and robust free and open-source software components that are widely adopted for operational use. wis2-gdc provides the functionality required for the Global Discovery Catalogue, including the following technical functions: @@ -210,5 +212,5 @@ wis2-gdc is managed as a free and open source project. Source code, issue tracki * The Global Monitor will collect metrics as defined in the OpenMetrics standard. * The Global Monitor will monitor the "health" (that is, the performance) of components at NCs/DCPCs, as well as Global Services. * The Global Monitor will provide a web-based dashboard that displays the WIS2 system performance and data availability. -* As a convention, the Global Monitor centre-id will be ``tld-{centre-name}-global-monitor``. +* As a convention, the Global Monitor centre-id will be ``{tld}-{centre-name}-global-monitor``. * The main task of the Global Monitor will be to regularly query the metrics provided by the relevant WIS2 entities, aggregate and process the data and then provide the results to the end user in a suitable presentation. diff --git a/guide/sections/part2/operations.adoc b/guide/sections/part2/operations.adoc index bbadcfb0..00890bd1 100644 --- a/guide/sections/part2/operations.adoc +++ b/guide/sections/part2/operations.adoc @@ -277,7 +277,7 @@ harvest and merge these catalogues, creating a global map of the ocean data. IODE harvests all metadata shared by ODIS partners, combines these metadata and creates a knowledge graph, and processes these metadata to export derivative products (for example, diagnostic reports and cloud-optimized data products). -The Ocean InfoHub (OIH) system is IODE's reference implementation of a +The Ocean InfoHub (OIH) system is IODE's Reference Implementation of a discovery system leveraging ODIS. ODIS architecture and tools are free and open-source software (FOSS), with regular releases published for the community. diff --git a/guide/sections/part2/wis2-architecture.adoc b/guide/sections/part2/wis2-architecture.adoc index 7859dbcc..15621ada 100644 --- a/guide/sections/part2/wis2-architecture.adoc +++ b/guide/sections/part2/wis2-architecture.adoc @@ -38,17 +38,17 @@ These roles are outlined below. ==== 2.2.3 Global Service operator * To ensure highly available global data exchange, a WIS centre may operate one or more Global Services: - i) The Global Discovery Catalogue enables users to search all datasets provided by data publishers and discover where and how to interact with those datasets (for example, to subscribe to updates, to access/download/visualize data, to access more detailed information about the dataset); - ii) A Global Broker provides highly available messaging services through which users may subscribe to notifications about all datasets provided by data publishers; - iii) A Global Cache provides a highly available download service for cached copies of core data downloaded from data publishers’ web services; - iv) A Global Monitor gathers and displays system performance, data availability, and other metrics from all WIS2 Nodes and Global Services. + i) The Global Discovery Catalogue enables users to search all datasets provided by data publishers and discover where and how to interact with those datasets (for example, to subscribe to updates, to access/download/visualize data, to access more detailed information about the dataset); + ii) A Global Broker provides highly available messaging services through which users may subscribe to notifications about all datasets provided by data publishers; + iii) A Global Cache provides a highly available download service for cached copies of core data downloaded from data publishers’ web services; + iv) A Global Monitor gathers and displays system performance, data availability, and other metrics from all WIS2 Nodes and Global Services. ==== 2.2.4 Data consumer * This role represents anyone wanting to find, access, and use data from WIS2. Examples include NMHSs, government agencies, research institutions, private sector organizations, and so forth. * Data consumers search or browse a Global Discovery Catalogue (or another search engine) to discover the datasets that meet their needs ("datasets of interest"). -* Data consumers subscribe via a Global Broker to receive notification messages about the availability of data or metadata associated with their datasets of interest. -* Data consumers determine whether the data or metadata referenced in the notification messages are required. -* Data consumers download data from a Global Cache or WIS2 Node. +* Data consumers subscribe via a Global Broker to receive notification messages about the availability of data or metadata associated with their datasets of interest. +* Data consumers determine whether the data or metadata referenced in the notification messages are required. +* Data consumers download data from a Global Cache or WIS2 Node. === 2.3 WIS2 specifications diff --git a/guide/sections/part2/wis2node.adoc b/guide/sections/part2/wis2node.adoc index a14a0028..8dc5c448 100644 --- a/guide/sections/part2/wis2node.adoc +++ b/guide/sections/part2/wis2node.adoc @@ -93,11 +93,11 @@ A WIS2 Node must be able to publish datasets and compliant discovery metadata. T If contacted by a Global Monitor for a performance issue via a GISC, the WIS2 Node should provide metrics to the GISC and the Global Monitor when service is restored to inform them of the resolution of the issue. -==== 2.6.3 WIS2 Node reference implementation: WIS2 in a box +==== 2.6.3 WIS2 Node Reference Implementation: WIS2 in a box When providing a WIS2 Node, Members may use whichever software components they consider most appropriate to comply with the WIS2 technical regulations. -To assist Members, a free and open-source reference implementation called “WIS2 in a box” (wis2box) is available. wis2box implements the requirements for a WIS2 Node and contains additional enhancements. wis2box is built free and open-source software components that are mature, robust and widely adopted for operational use. +To assist Members, a free and open-source Reference Implementation called “WIS2 in a box” (wis2box) is available. wis2box implements the requirements for a WIS2 Node and contains additional enhancements. wis2box is built free and open-source software components that are mature, robust and widely adopted for operational use. wis2box provides the functionality required for both data publisher and data consumer roles, as well as the following technical functions: