From 1df22a10e50feaf2d21704b62e4d5d611d22a345 Mon Sep 17 00:00:00 2001 From: Martin Voigt Date: Tue, 16 Jun 2026 16:35:09 +0200 Subject: [PATCH 1/2] Add documentation on automatic content exchange. --- TeSS_docs/_toc.yml | 1 + TeSS_docs/content/exchange.md | 27 +++++++++++++++++++ .../{spaces => content}/graphic-exchange.svg | 0 3 files changed, 28 insertions(+) create mode 100644 TeSS_docs/content/exchange.md rename TeSS_docs/images/{spaces => content}/graphic-exchange.svg (100%) diff --git a/TeSS_docs/_toc.yml b/TeSS_docs/_toc.yml index 8111b0e..1bfad7c 100644 --- a/TeSS_docs/_toc.yml +++ b/TeSS_docs/_toc.yml @@ -32,6 +32,7 @@ parts: sections: - file: content/structured-data-types - file: content/sources + - file: content/exchange - file: content/manual sections: - file: content/manual-events-materials diff --git a/TeSS_docs/content/exchange.md b/TeSS_docs/content/exchange.md new file mode 100644 index 0000000..b331b31 --- /dev/null +++ b/TeSS_docs/content/exchange.md @@ -0,0 +1,27 @@ +# Exchange content + +As introduced in previous sections, TeSS can import content from external sources. This is naturally also possible when the external source is also a TeSS based catalogue. But in this special case there is explicit support thanks to the [mTeSS-X project](../overview/mtess-x). + +```{image} ../images/content/graphic-exchange.svg +:alt: Graphic of multi-spaces +:class: mb-1 +:width: 300px +:align: center +``` + +You may take the following steps to setup automated exchange between two TeSS based catalogues: + +1) Ensure that you have the correct permissions. To set up the exchange of materials, you need to be a site **admin** of the TeSSHub where the content should end up in, or the **owner of a content provider** in this TeSSHub instance. You are owner of content providers that you created yourself by default. +2) Go to the TeSSHub instance where the training should come from and understand what metadata is used there to describe the particular set of training content that should be exchanged. +3) In the source instance, at the top of the list of training materials, select "Harvest using OAI-PMH" in the "Subscribe" menu and copy the OAI-PMH link. +4) Go to the content provider in the target TeSSHub instance where the exchanged content should be associated with and open the "Sources" tab to hit the "Add source" button. +5) Enter the URL that you copied in step 3 into the URL field and select "OAI-PMH" as the ingestion method. +6) Check the "Enabled" checkbox. If you just want to create the source as a draft, don't check this checkbox to avoid automatically exchanging training content yet. If you are an administrator, you may also directly set the new source as approved to enable it. If you are not an administrator, you need to wait until an administrator approves the source before content starts to be exchanged. +7) You may add filter conditions to not exchange the whole content of the source TeSSHub. Only content that satisfies all the conditions in the allow list and none of the conditions in the block list is exchanged. For more complex cases where either one set of conditions or another set of conditions but not necessarily all the conditions should be satisfied for exchange feel free to create multiple sources for each set of conditions. +8) Save the source using the "Register Source" button. +9) After the source is enabled and approved, you may expect content to be exchanged and kept up to date once per day, but this may depend on the configuration of the target TeSSHub instance. + +The whole process is also shown in this video. In this example, training material on Python that is not for beginners is exchanged from ELIXIR TeSS to PaN-Training: + +Please note that the video may be slightly outdated in some cases. The instructions above may be more up to date. + diff --git a/TeSS_docs/images/spaces/graphic-exchange.svg b/TeSS_docs/images/content/graphic-exchange.svg similarity index 100% rename from TeSS_docs/images/spaces/graphic-exchange.svg rename to TeSS_docs/images/content/graphic-exchange.svg From 0b2ff2e4b3c3b64800ca94aabfc2dd1b1638cf6d Mon Sep 17 00:00:00 2001 From: PhilReedData Date: Tue, 23 Jun 2026 08:03:21 +0100 Subject: [PATCH 2/2] Refine the exchange guide, add to homepage, update credit --- TeSS_docs/_config.yml | 4 ++-- TeSS_docs/content/exchange.md | 21 +++++++++++---------- TeSS_docs/index.md | 11 ++++++++++- 3 files changed, 23 insertions(+), 13 deletions(-) diff --git a/TeSS_docs/_config.yml b/TeSS_docs/_config.yml index 401fd82..ca2c45a 100644 --- a/TeSS_docs/_config.yml +++ b/TeSS_docs/_config.yml @@ -6,8 +6,8 @@ ####################################################################################### # Book settings title : TeSS Platform Documentation # The title of the book. Will be placed in the left navbar. -author : Phil Reed, Munazah Andrabi, Finn Bacall, Kenneth Rioja, Carole Goble (OSCARS mTeSS-X project) -copyright : "2025" # Copyright year to be placed in the footer +author : Phil Reed, Munazah Andrabi, Finn Bacall, Kenneth Rioja, Martin Voigt, Oliver Knodel, Carole Goble (OSCARS mTeSS-X project) +copyright : "2025-2026" # Copyright year to be placed in the footer logo : images/logo.svg # A path to the book logo # Force re-execution of notebooks on each build. diff --git a/TeSS_docs/content/exchange.md b/TeSS_docs/content/exchange.md index b331b31..377373a 100644 --- a/TeSS_docs/content/exchange.md +++ b/TeSS_docs/content/exchange.md @@ -1,6 +1,7 @@ # Exchange content -As introduced in previous sections, TeSS can import content from external sources. This is naturally also possible when the external source is also a TeSS based catalogue. But in this special case there is explicit support thanks to the [mTeSS-X project](../overview/mtess-x). +TeSS can import content from a range of external sources. +When the source is also based on TeSS, there are additional features which allow you to customise and automate the exchange, thanks to the [mTeSS-X project](../overview/mtess-x). ```{image} ../images/content/graphic-exchange.svg :alt: Graphic of multi-spaces @@ -9,16 +10,16 @@ As introduced in previous sections, TeSS can import content from external source :align: center ``` -You may take the following steps to setup automated exchange between two TeSS based catalogues: +You may take the following steps to setup automated exchange between two TeSS based catalogues (a **source** and a **destination**): -1) Ensure that you have the correct permissions. To set up the exchange of materials, you need to be a site **admin** of the TeSSHub where the content should end up in, or the **owner of a content provider** in this TeSSHub instance. You are owner of content providers that you created yourself by default. -2) Go to the TeSSHub instance where the training should come from and understand what metadata is used there to describe the particular set of training content that should be exchanged. -3) In the source instance, at the top of the list of training materials, select "Harvest using OAI-PMH" in the "Subscribe" menu and copy the OAI-PMH link. -4) Go to the content provider in the target TeSSHub instance where the exchanged content should be associated with and open the "Sources" tab to hit the "Add source" button. -5) Enter the URL that you copied in step 3 into the URL field and select "OAI-PMH" as the ingestion method. -6) Check the "Enabled" checkbox. If you just want to create the source as a draft, don't check this checkbox to avoid automatically exchanging training content yet. If you are an administrator, you may also directly set the new source as approved to enable it. If you are not an administrator, you need to wait until an administrator approves the source before content starts to be exchanged. -7) You may add filter conditions to not exchange the whole content of the source TeSSHub. Only content that satisfies all the conditions in the allow list and none of the conditions in the block list is exchanged. For more complex cases where either one set of conditions or another set of conditions but not necessarily all the conditions should be satisfied for exchange feel free to create multiple sources for each set of conditions. -8) Save the source using the "Register Source" button. +1) Ensure that you have the correct permissions. To set up the exchange of materials, you need to be a site **admin**, or the **owner of a 'content provider'**, of the destination TeSSHub (where the content should end up). You are the owner of content providers that you create. +2) Go to the source TeSSHub instance (where the training should come from) and understand what metadata (set of filters) is used there to describe the particular set of training content that should be exchanged. +3) In the source instance, at the top of the list of training materials, go to the 'Subscribe' menu, click 'Harvest using OAI-PMH', and copy the OAI-PMH link. +4) Go to the content provider in the target TeSSHub instance (where the exchanged content should be associated with), open the 'Sources' tab then click the 'Add source' button. +5) Enter the URL that you copied in step 3 into the URL field and select 'OAI-PMH' as the ingestion method. +6) If you are ready for the materials to be automatically exchanged, check the 'Enabled' checkbox; otherwise, if you just want to create the source as a draft, don't check this checkbox. If you are an administrator, you may also directly set the new source as 'Approved' to enable it. Everyone else will need to wait until an administrator approves the source before content starts to be exchanged. +7) You may add **filter conditions** to not exchange the whole content of the source TeSSHub. Only content that satisfies all the conditions in the 'Allow' list and none of the conditions in the 'Block' list is exchanged. For more complex cases where either one set of conditions or another set of conditions but not necessarily all the conditions should be satisfied for exchange, feel free to create multiple sources for each set of conditions. +8) Save the source using the 'Register Source' button. 9) After the source is enabled and approved, you may expect content to be exchanged and kept up to date once per day, but this may depend on the configuration of the target TeSSHub instance. The whole process is also shown in this video. In this example, training material on Python that is not for beginners is exchanged from ELIXIR TeSS to PaN-Training: diff --git a/TeSS_docs/index.md b/TeSS_docs/index.md index c08f3bd..7781c1a 100644 --- a/TeSS_docs/index.md +++ b/TeSS_docs/index.md @@ -33,7 +33,7 @@ Global usages of the TeSS Platform :link: overview/mtess-x :link-type: doc -{fas}`arrows-turn-to-dots;sd-text-secondary` **mTeSS-X** +{fas}`boxes-stacked;sd-text-secondary` {fas}`arrows-turn-to-dots;sd-text-secondary` **mTeSS-X** ^^^ Multi-spaces and exchange @@ -90,6 +90,15 @@ Automatically or manually register events, materials or learning paths When to set up a TeSS space, how to credit other spaces' materials ::: +:::{grid-item-card} +:link: content/exchange +:link-type: doc + +{fas}`arrows-turn-to-dots;sd-text-secondary` **Exchange content** +^^^ + +Filter and exchange materials automatically from another TeSSHub +::: :::{grid-item-card} :link: developers/code-data