diff --git a/docs/conf.py b/docs/conf.py index 37165186..72fa76e9 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,9 +9,8 @@ # -- Project information ----------------------------------------------------- project = 'mercure' -copyright = '2019-2023 The "mercure" authors and contributors' +copyright = '2019-2024 The "mercure" authors and contributors' author = '' - def read_version() -> str: current_version = "0.0.0" version_filepath = os.path.dirname(os.path.realpath(__file__)) + '/../VERSION' @@ -61,7 +60,7 @@ def read_version() -> str: # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/docs/dashboards.rst b/docs/dashboards.rst index d50e3532..05ee4479 100644 --- a/docs/dashboards.rst +++ b/docs/dashboards.rst @@ -20,7 +20,7 @@ The health of a mercure server can be monitored using Graphite for data collecti The diagram shown in the top-left utilizes the data transmitted by the mercure services during each run. If one of the colored blocks disappears for a longer period of time, it indicates that the process might be hanging. Useful are also the other diagrams in the top row, showing pending files and series in the incoming folder as reported by the router module, which can indicate if the server is not able to keep up with the load created by the scanners. -.. image:: dashboards_graphite.png +.. image:: /images/dashboards/graphite.png :width: 550px :align: center :class: border @@ -32,7 +32,7 @@ Dispatch Explorer The Redash dashboard "Dispatch Explorer" allows showing which patient series have been dispatched to a selected target in a selectable time frame. It links to the "Series Events" dashboard that summarizes all information collected for a particular series. -.. image:: dashboards_dispatchexplorer.png +.. image:: /images/dashboards/dispatchexplorer.png :width: 550px :align: center :class: border @@ -89,7 +89,7 @@ Last Series Received The dashboard "Last Series Received" shows the time when the last series from any imaging device has been received. It can be used to detect if there are problems with the DICOM transfer from one of the scanners. The query can be easily modified to provide a trigger for automatic alerts. -.. image:: dashboards_lastseriesreceived.png +.. image:: /images/dashboards/lastseriesreceived.png :width: 550px :align: center :class: border @@ -118,7 +118,7 @@ Received Series The "Received Series" dashboard shows all series that have been received by the router in descending chronological order, with links to the "Series Events" dashboard for details on the series. Using the UI controls on top of the dashboard, series can be searched by patient name, MRN, ACC, and modality. -.. image:: dashboards_receivedseries.png +.. image:: /images/dashboards/receivedseries.png :width: 550px :align: center :class: border @@ -176,7 +176,7 @@ Series Events The "Series Events" dashboard shows all information collected for a particular series, including DICOM tag information on the left side and a journal of how this series has been processed on the right side. -.. image:: dashboards_seriesevents.png +.. image:: /images/dashboards/seriesevents.png :width: 550px :align: center :class: border @@ -256,7 +256,7 @@ System Status The "System Status" dashboard shows all system and webgui events in descending chronological order. Moreover, it shows all error events in the top-right table. -.. image:: dashboards_systemstatus.png +.. image:: /images/dashboards/systemstatus.png :width: 550px :align: center :class: border diff --git a/docs/dashboards_dispatchexplorer.png b/docs/images/dashboards/dispatchexplorer.png old mode 100755 new mode 100644 similarity index 100% rename from docs/dashboards_dispatchexplorer.png rename to docs/images/dashboards/dispatchexplorer.png diff --git a/docs/dashboards_graphite.png b/docs/images/dashboards/graphite.png old mode 100755 new mode 100644 similarity index 100% rename from docs/dashboards_graphite.png rename to docs/images/dashboards/graphite.png diff --git a/docs/dashboards_lastseriesreceived.png b/docs/images/dashboards/lastseriesreceived.png old mode 100755 new mode 100644 similarity index 100% rename from docs/dashboards_lastseriesreceived.png rename to docs/images/dashboards/lastseriesreceived.png diff --git a/docs/dashboards_receivedseries.png b/docs/images/dashboards/receivedseries.png old mode 100755 new mode 100644 similarity index 100% rename from docs/dashboards_receivedseries.png rename to docs/images/dashboards/receivedseries.png diff --git a/docs/dashboards_seriesevents.png b/docs/images/dashboards/seriesevents.png old mode 100755 new mode 100644 similarity index 100% rename from docs/dashboards_seriesevents.png rename to docs/images/dashboards/seriesevents.png diff --git a/docs/dashboards_systemstatus.png b/docs/images/dashboards/systemstatus.png old mode 100755 new mode 100644 similarity index 100% rename from docs/dashboards_systemstatus.png rename to docs/images/dashboards/systemstatus.png diff --git a/docs/header.jpg b/docs/images/header.jpg old mode 100755 new mode 100644 similarity index 100% rename from docs/header.jpg rename to docs/images/header.jpg diff --git a/docs/mercure_logo_w.png b/docs/images/mercure_logo_w.png similarity index 100% rename from docs/mercure_logo_w.png rename to docs/images/mercure_logo_w.png diff --git a/docs/scheme.png b/docs/images/scheme.png old mode 100755 new mode 100644 similarity index 100% rename from docs/scheme.png rename to docs/images/scheme.png diff --git a/docs/ui_log.png b/docs/images/ui/log.png old mode 100755 new mode 100644 similarity index 100% rename from docs/ui_log.png rename to docs/images/ui/log.png diff --git a/docs/ui_login.png b/docs/images/ui/login.png old mode 100755 new mode 100644 similarity index 100% rename from docs/ui_login.png rename to docs/images/ui/login.png diff --git a/docs/images/ui/module_add.png b/docs/images/ui/module_add.png new file mode 100644 index 00000000..36dacdf0 Binary files /dev/null and b/docs/images/ui/module_add.png differ diff --git a/docs/images/ui/module_edit.png b/docs/images/ui/module_edit.png new file mode 100644 index 00000000..6e4619fc Binary files /dev/null and b/docs/images/ui/module_edit.png differ diff --git a/docs/images/ui/modules.png b/docs/images/ui/modules.png new file mode 100644 index 00000000..174f2682 Binary files /dev/null and b/docs/images/ui/modules.png differ diff --git a/docs/images/ui/query.png b/docs/images/ui/query.png new file mode 100644 index 00000000..117084df Binary files /dev/null and b/docs/images/ui/query.png differ diff --git a/docs/ui_queue.png b/docs/images/ui/queue.png similarity index 100% rename from docs/ui_queue.png rename to docs/images/ui/queue.png diff --git a/docs/ui_queue_processing.png b/docs/images/ui/queue_processing.png similarity index 100% rename from docs/ui_queue_processing.png rename to docs/images/ui/queue_processing.png diff --git a/docs/images/ui/rules/edit.png b/docs/images/ui/rules/edit.png new file mode 100644 index 00000000..53d4fbd7 Binary files /dev/null and b/docs/images/ui/rules/edit.png differ diff --git a/docs/ui_rules_edit_information.png b/docs/images/ui/rules/edit_information.png similarity index 100% rename from docs/ui_rules_edit_information.png rename to docs/images/ui/rules/edit_information.png diff --git a/docs/images/ui/rules/edit_notification.png b/docs/images/ui/rules/edit_notification.png new file mode 100644 index 00000000..c6aee43d Binary files /dev/null and b/docs/images/ui/rules/edit_notification.png differ diff --git a/docs/images/ui/rules/edit_processing.png b/docs/images/ui/rules/edit_processing.png new file mode 100644 index 00000000..fc032aba Binary files /dev/null and b/docs/images/ui/rules/edit_processing.png differ diff --git a/docs/images/ui/rules/edit_routing.png b/docs/images/ui/rules/edit_routing.png new file mode 100644 index 00000000..50e8f577 Binary files /dev/null and b/docs/images/ui/rules/edit_routing.png differ diff --git a/docs/ui_rules_edit_trigger.png b/docs/images/ui/rules/edit_trigger.png similarity index 100% rename from docs/ui_rules_edit_trigger.png rename to docs/images/ui/rules/edit_trigger.png diff --git a/docs/images/ui/rules/rules.png b/docs/images/ui/rules/rules.png new file mode 100644 index 00000000..623a8915 Binary files /dev/null and b/docs/images/ui/rules/rules.png differ diff --git a/docs/ui_rules_test.png b/docs/images/ui/rules/test.png old mode 100755 new mode 100644 similarity index 100% rename from docs/ui_rules_test.png rename to docs/images/ui/rules/test.png diff --git a/docs/images/ui/status.png b/docs/images/ui/status.png new file mode 100644 index 00000000..b5e8cfdb Binary files /dev/null and b/docs/images/ui/status.png differ diff --git a/docs/ui_status_control.png b/docs/images/ui/status_control.png old mode 100755 new mode 100644 similarity index 100% rename from docs/ui_status_control.png rename to docs/images/ui/status_control.png diff --git a/docs/images/ui/target_edit.png b/docs/images/ui/target_edit.png new file mode 100644 index 00000000..14983ad8 Binary files /dev/null and b/docs/images/ui/target_edit.png differ diff --git a/docs/images/ui/targets.png b/docs/images/ui/targets.png new file mode 100644 index 00000000..767f6a9b Binary files /dev/null and b/docs/images/ui/targets.png differ diff --git a/docs/ui_users.png b/docs/images/ui/users.png old mode 100755 new mode 100644 similarity index 100% rename from docs/ui_users.png rename to docs/images/ui/users.png diff --git a/docs/index.rst b/docs/index.rst index c3698ce3..d5be3103 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -.. image:: header.jpg +.. image:: /images/header.jpg :align: center :class: headerimage @@ -7,7 +7,7 @@ mercure DICOM Orchestrator mercure is a flexible open-source DICOM orchestration platform. It offers an intuitive web-based user interface as well as extensive monitoring options, making it suitable for routine applications that require high availability. It can be used for dispatching DICOM studies to different targets based on easily definable routing rules and for processing DICOM series with custom-developed algorithms, such as inference of AI models for medical imaging. Processing algorithms can either be executed directly on a mercure server (as Docker containers) or can be executed on connected cluster nodes, typically located on premise but possibly also running as cloud instances. Implemented processing modules can be shared via Docker Hub. -.. image:: scheme.png +.. image:: /images/scheme.png :width: 550px :align: center :class: spacerbottom20 @@ -36,15 +36,16 @@ mercure is a flexible open-source DICOM orchestration platform. It offers an int .. toctree:: :caption: User Guide - :maxdepth: 2 + :glob: intro quickstart install - usage advanced monitoring dashboards + new_features + usage/index .. toctree:: :maxdepth: 1 @@ -76,6 +77,6 @@ mercure is a flexible open-source DICOM orchestration platform. It offers an int :maxdepth: 2 environment - code + source/index roadmap \ No newline at end of file diff --git a/docs/intro.rst b/docs/intro.rst index d5e339df..e639fd4f 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,7 +1,7 @@ What is mercure? ================ -.. image:: scheme.png +.. image:: /images/scheme.png :width: 550px :align: center diff --git a/docs/monitoring.rst b/docs/monitoring.rst index 01d82779..ef61f1a8 100755 --- a/docs/monitoring.rst +++ b/docs/monitoring.rst @@ -8,7 +8,7 @@ Log files All mercure services write detailed logging information into system log files. The most convenient way to review these logs is to use the "Logs" page of the mercure web interface. It shows a separate tab for every mercure service. The log display is updated whenever you switch between tabs or when you click the refresh button on the top-right. -.. image:: ui_log.png +.. image:: /images/ui/log.png :width: 550px :align: center :class: border diff --git a/docs/new_features.rst b/docs/new_features.rst new file mode 100644 index 00000000..c79649c1 --- /dev/null +++ b/docs/new_features.rst @@ -0,0 +1,31 @@ +New Features +=============== + +- Multistep processors +- Multiple dispatch +- Rearranged UI +- Query tool +- Results files +- Restart failed dispatch +- localized timestamps +- new target types (dicomweb etc) +- new rule syntax (optional) +- notifications from results +- sample dashboards need updating +- timezone stuff +- system tag in navbar +- getdcmtags: additional tags +- influxdb +- new receiver algorithm +- manage.py create users +- urgent priorities / offpeak +- notifications templating, emails, PHI +- json editor +- "return to sender" target +- TLS support in receiver +- logs output in queue page, queue page generally + +> Update guide + +- update in install.sh to update dependencies, services +- system status flag for missing services \ No newline at end of file diff --git a/docs/bookkeeper.rst b/docs/source/bookkeeper.rst similarity index 100% rename from docs/bookkeeper.rst rename to docs/source/bookkeeper.rst diff --git a/docs/cleaner.rst b/docs/source/cleaner.rst similarity index 100% rename from docs/cleaner.rst rename to docs/source/cleaner.rst diff --git a/docs/common.rst b/docs/source/common.rst similarity index 100% rename from docs/common.rst rename to docs/source/common.rst diff --git a/docs/dispatch.rst b/docs/source/dispatch.rst similarity index 100% rename from docs/dispatch.rst rename to docs/source/dispatch.rst diff --git a/docs/dispatcher.rst b/docs/source/dispatcher.rst similarity index 100% rename from docs/dispatcher.rst rename to docs/source/dispatcher.rst diff --git a/docs/code.rst b/docs/source/index.rst old mode 100755 new mode 100644 similarity index 100% rename from docs/code.rst rename to docs/source/index.rst diff --git a/docs/process.rst b/docs/source/process.rst old mode 100755 new mode 100644 similarity index 100% rename from docs/process.rst rename to docs/source/process.rst diff --git a/docs/processor.rst b/docs/source/processor.rst old mode 100755 new mode 100644 similarity index 100% rename from docs/processor.rst rename to docs/source/processor.rst diff --git a/docs/router.rst b/docs/source/router.rst similarity index 100% rename from docs/router.rst rename to docs/source/router.rst diff --git a/docs/routing.rst b/docs/source/routing.rst old mode 100755 new mode 100644 similarity index 100% rename from docs/routing.rst rename to docs/source/routing.rst diff --git a/docs/webgui.rst b/docs/source/webgui.rst similarity index 100% rename from docs/webgui.rst rename to docs/source/webgui.rst diff --git a/docs/webinterface.rst b/docs/source/webinterface.rst old mode 100755 new mode 100644 similarity index 100% rename from docs/webinterface.rst rename to docs/source/webinterface.rst diff --git a/docs/support.rst b/docs/support.rst index 22ccbece..cc9b6702 100755 --- a/docs/support.rst +++ b/docs/support.rst @@ -11,7 +11,7 @@ We thank `Zulip `_ for sponsoring our project with a free clo .. container:: bullet - .. image:: zulip-org-logo.svg + .. image:: /images/zulip-org-logo.svg :width: 200px :align: right diff --git a/docs/ui_modules.png b/docs/ui_modules.png deleted file mode 100644 index b87769ce..00000000 Binary files a/docs/ui_modules.png and /dev/null differ diff --git a/docs/ui_modules_edit.png b/docs/ui_modules_edit.png deleted file mode 100644 index 82c74f52..00000000 Binary files a/docs/ui_modules_edit.png and /dev/null differ diff --git a/docs/ui_rules.png b/docs/ui_rules.png deleted file mode 100755 index a1fd85b2..00000000 Binary files a/docs/ui_rules.png and /dev/null differ diff --git a/docs/ui_rules_edit.png b/docs/ui_rules_edit.png deleted file mode 100755 index 0757f633..00000000 Binary files a/docs/ui_rules_edit.png and /dev/null differ diff --git a/docs/ui_rules_edit_notification.png b/docs/ui_rules_edit_notification.png deleted file mode 100644 index fb732806..00000000 Binary files a/docs/ui_rules_edit_notification.png and /dev/null differ diff --git a/docs/ui_rules_edit_processing.png b/docs/ui_rules_edit_processing.png deleted file mode 100644 index beb0d9de..00000000 Binary files a/docs/ui_rules_edit_processing.png and /dev/null differ diff --git a/docs/ui_rules_edit_routing.png b/docs/ui_rules_edit_routing.png deleted file mode 100644 index 1bacbb7b..00000000 Binary files a/docs/ui_rules_edit_routing.png and /dev/null differ diff --git a/docs/ui_status.png b/docs/ui_status.png deleted file mode 100755 index 6f3d2da4..00000000 Binary files a/docs/ui_status.png and /dev/null differ diff --git a/docs/ui_target_edit.png b/docs/ui_target_edit.png deleted file mode 100755 index 0decdc16..00000000 Binary files a/docs/ui_target_edit.png and /dev/null differ diff --git a/docs/ui_targets.png b/docs/ui_targets.png deleted file mode 100755 index a2574fa9..00000000 Binary files a/docs/ui_targets.png and /dev/null differ diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index 5ef0c1bc..00000000 --- a/docs/usage.rst +++ /dev/null @@ -1,292 +0,0 @@ -Usage -===== - - -Web interface -------------- - -mercure can be conveniently configured and controlled using the web-based user interface. To access it, use a modern web browser (e.g., Chrome or Firefox) and enter the IP of your mercure server as URL. Depending on the port that you have selected during the installation (by default 8000), you need to add ":8000" to the URL. - -.. image:: ui_login.png - :width: 550px - :align: center - :class: border - -During the installation, mercure creates a "seed account" that you need to use for the first login. You will be asked to change the password after the first login. - -.. note:: The login credentials for the first login are: Username = admin, Password = router - -To end your session, use the menu on the top-right and select "Logout". - -User management ---------------- - -Users can be created, modified, and deleted on the "Users" page. There are two types of users: Normal users, who can view the configuration and status but not change any settings, and administrators, who have full access. Users with administration rights are indicated by an icon with a shield in the user list. Users can also be added to permission groups. Permission groups are not yet used for anything, but they will be used in future mercure versions to provide granular access control. - -.. image:: ui_users.png - :width: 550px - :align: center - :class: border - -.. tip:: You should create separate accounts for every person using mercure. This will allow you to review which user made changes to the server configuration, as mercure is keeping track of all configuration changes. - - -System status and control -------------------------- - -The status of the mercure server and its service components can be monitored on the "Overview" page. If a service module is running, it will be shown in green color, otherwise it is shown in red. In normal operation, everything should be green. - -.. image:: ui_status.png - :width: 550px - :align: center - :class: border - -The Overview page also shows the disk space available in the folder for buffering the incoming DICOM files. If this bar turns yellow or red, make sure to free up disk space as the mercure server will not be able to receive images if the disk is completely full. - -You can start, stop, and restart services by clicking the "Service Control" button. This will show a dialog where you can select which service(s) to control and which operation to execute (e.g., start or stop). If a service does not react anymore at all, it is also possible to kill a service. - -.. image:: ui_status_control.png - :width: 550px - :align: center - :class: border - -.. note:: If you stop a service, it might take a short moment until the service goes down. This is because the services have been designed to finish the active task before terminating. - -.. note:: The "Service Control" button is only available for systemd- and Docker-type installations but not for Nomad-type installations. Nomad directly takes care restarting services. - -.. tip:: If you don't want to use the web interface, you can also manually control the mercure services from the command line. For systemd-type installations, this can be done with the command "systemctl start -u mercure_router.service" (in this example for the routing service). You can find the names of the individual services in the file **/opt/mercure/config/services.json**. - - -Configuring targets -------------------- - -Target nodes that should receive processed and routed DICOM series (via DICOM, DICOM+TLS or SFTP connection) can be defined and configured on the "Targets" page. The first page shows an overview of the currently configured targets. By clicking on an individual item, you can see the target details (e.g., IP address and port). You can test if the target can be reached by clicking the "Test" button, which will try to ping the server and open a connection (via C-Echo or SFTP). - -.. image:: ui_targets.png - :width: 550px - :align: center - :class: border - -Click the "Add New" button to create a new target. This can be done during normal operation of the server, i.e. it is not necessary to stop any of the services for adding new targets. - -.. image:: ui_target_edit.png - :width: 550px - :align: center - :class: border - -After choosing a unique name for the target, you can edit the target settings. First, you need to select the type of target. Currently, DICOM targets and SFTP targets are supported (other target types, such as DICOMweb, will be added at later time). - -For DICOM targets, enter the parameters of the DICOM node, including the IP address, port, the target AET (application entity title) that should be called on the receiver side, and the source AET with which mercure identifies itself to the target. - -.. tip:: Some DICOM nodes require that you set a specific target AET, while other systems ignore this setting. Likewise, some DICOM nodes only accept images from a sender who's source AET is known, while others ignore the value. Please check with the vendor/operator of your DICOM node which values are required. - -For SFTP targets, enter the hostname or IP, target folder on the server, username, and password. - -.. tip:: It is recommended to create a restricted user account for the SFTP uploads. Never use the credentials of an account with access to sensitive information, as the SFTP credentials are stored in the configuration file. - -.. important:: Support for SFTP transfers is still experimental and should be used with care. - -For DICOM TLS targets, enter the TLS client key path, TLS client certificate path, and the path to the Certificate Authority (CA) certificate file. You will need to add these files to your mercure installation, e.g. in `/opt/mercure/certs`. - -.. important:: Support for DICOM TLS transfers is still experimental and should be used with care. - -.. important:: Due to an incompatibility in DICOM toolkit v3.6.4 and OpenSSL v1.1.1, the dcmtk and openssl versions supported by Ubuntu 20.04, only Ubuntu 22.04 mercure installs support for DICOM+TLS targets. - -On the "Information" tab, you can add information for documentation purpose, including a contact e-mail address (so that it can be looked up who should be contacted if problems with the target occur) and a description of the target. - - -Installing modules ------------------- - -An overview of the installed processing modules can be seen on the "Modules" page. Details are shown by clicking on an item, which also allows editing the module settings. - -.. image:: ui_modules.png - :width: 550px - :align: center - :class: border - -To setup a new processing module, click the "Install Module" button. Select a unique name for the module. It is possible to install the same processing module multiple times under different names with different settings. Specify the processing module by entering the Docker Tag. - -.. note:: The Docker Tag corresponds to the name of the processing module as stored on Docker Hub (example: mercureimaging/mercure-testmodule). For modules that are not distributed via Docker Hub, the Docker container needs to be built locally on the server before it can be used by mercure. - -Afterwards, you can edit additional Docker-specific settings on the "Docker" tab (additional volumes, environment variables, etc.). In most cases, these settings are not needed. - -.. image:: ui_modules_edit.png - :width: 550px - :align: center - :class: border - -Settings for the processing module can be defined on the "Settings" tab. These settings must be entered in **JSON format**. The settings entered on the module page are global modules settings, i.e. they are applied whenever the module is used. The global module settings can be overwritten (or extended) by defining settings for the individual rule (thus, the settings passed to the module are the global module settings merged with the rule-specific processing settings). - -The "Orchestration" tab allows configuring Nomad-specific settings. If you have a systemd- or Docker-type installation, these settings are irrelevant and can be ignored. It is possible to specify "Execution constraints" if the module should be executed on a certain node of your processing cluster (e.g., if a specific GPU or operating system is needed). The field "Resource requirements" can be used to request resources needed for execution of the module (e.g., the amount of memory or CPU cores). - -The "Information" tab can be used to document the current module setup, including a free-text description as well as contact e-mail address. - - -Defining rules --------------- - -After you have configured your targets and processing modules, you can define rules that specify which DICOM series should be processed and to which targets the images should be dispatched. This can be done on the "Rules" page. - -.. image:: ui_rules.png - :width: 550px - :align: center - :class: border - -It is not necessary to stop mercure services while defining new rules. The mercure service modules will automatically reload the new configuration when a rule has been added or modified. Click the "Add New" button to create a new rule, or click on any of the existing rules and select "Edit" to modify it. - -**Filtering tab** - -All rules are evaluated whenever a new DICOM series has been received. The rules can use a set of DICOM tags extracted from the incoming DICOM files. To see the full list of DICOM tags available for writing rules, click the "Available Tags" button. - -.. tip:: If you need additional tags that are currently not in the list, please contact us (or modify the getdcmtags module yourself). - -When writing the selection rule, tags can be referenced using the format @TagName@, for example @PatientName@. When the rule gets evaluated, such tag placeholder will be replaced with the values read from the individual received DICOM series. - -.. image:: ui_rules_edit.png - :width: 550px - :align: center - :class: border - -A received series will processed if the selection rule evaluates to True, and it will be ignored if the rule evaluates to False. If none of the defined rules evaluates to True, the series will be discarded. - -Selection rules can be written in a Python-like syntax. For example, the rule - -.. highlight:: none - -:: - - 'CINE' in @SeriesDescription@ - -will activate for all series that have the word "CINE" in the series description (e.g., "CINE 2ch"). If you only want to send series that are exactly called "CINE", use the following rule instead -:: - - @SeriesDescription@ = 'CINE' - -This rule would not trigger if the series is called "CINE 2ch". Multiple conditions can be combined using the "or" and "and" operators. Here, it is recommended to enclose every sub-condition with "( )". By default, DICOM tags are treated as strings and are case-sensitive. If you want to make your condition case-insensitive, then append ".lower()" to the tag. For example, the rule -:: - - @SeriesDescription@.lower() = 'cine' - -would trigger for series called "CINE" or "cine". If you want to test for numerical value thresholds (e.g., if the slice thickness is lower than 2mm), you first need to convert the tag into a float by writing the tag inside "float( )". This then allows you to write a rule like -:: - - float(@SliceThickness@) < 2.0 - -To test a selection rule before activating it, click the icon with the cog wheels on the left side of input box. If you see a red icon in the dialog, the rule notation is invalid (the dialog will tell you why). If the rule is valid, the dialog will test if the rule would trigger if a DICOM series with the values shown in the lower part of the dialog would be received. You can modify these values and test if the rule reacts as expected. - -.. image:: ui_rules_test.png - :width: 550px - :align: center - :class: border - -.. hint:: If you make a mistake while changing the test values (e.g., missing a quotation mark), you will see a yellow icon. - -If you have validated that your rule triggers as expected, select the desired Action from the drop-down list. The following options are available: - -==================== =============================================================================== -Action Meaning -==================== =============================================================================== -Routing The received series/study will be dispatched to a target (no processing) -Processing & Routing The received series/study will be processed and afterwards dispatched -Processing only The received series/study will be processed (without further dispatching) -Notification only A notification will be triggered if the series/study is received (without neither processing or dispatching) -Force discard The received series/study will be discarded (no other rules will be evaluated) -==================== =============================================================================== - -Depending on the selected Action, the tabs "Processing" and "Routing" will become visible. - -The Trigger control allows selecting when the action should be triggered. If "Completed Series" has been selected, the action is executed when a DICOM series has been received for which the rule evaluates to True. Thus, if multiple series from a patient study are received, these series are processed separately. However, sometimes it is required to process all DICOM series from one patient study together. For example, an AI-based analysis algorithm might require multiple series with different contrast. In this case, the option "Completed Study" needs to be selected, and the additional control "Completion Criteria" will appear, which allows selecting when the study should considered complete. - -.. image:: ui_rules_edit_trigger.png - :width: 550px - :align: center - :class: border - -If it is known which image series are required for the processing, this information can be utilized with the option "List Series Received". It is then necessary to list the Series Descriptions of the required series in the input box on the right side. Here, it is possible to enter substrings of the Series Description and it is possible to combine multiple options using the keywords "or" and "and". This allows handling variability in the Series Descriptions, which often occurs in practice due to inconsistent configuration of imaging devices. If the names of the expected series are unknown, the option "Timeout Reached" can be used, which collects image series belonging to the same study until no further series has been received for a definable timeout period (the timeout time can be set on the Configuration page). A disadvantage of this option is that the processing will be delayed until the timeout period has expired. - -If the Priority control is set to "Urgent", corresponding series or studies will be pushed to the front of the processing queue, while the setting "Off-Peak" enforces that the corresponding series will be only processed at night time. The latter can be helpful to avoid that computationally demanding research studies might delay clinical routine processing during normal work hours. - -Rules can be temporarily disabled by toggling the "Disable Rule" switch. In this case, the rule appears in grayed-out color in the rule list and it will be ignored during processing. By clicking the "Fallback Rule" switch, the current rule will be applied to all DICOM series for which no other rules have triggered. This allows defining a "default" rule. - -**Processing tab** - -For rules involving processing, the "Processing" tab can be used to select the processing module that should be executed and to provide rule-specific module settings. These settings will be merged with the global module settings and will overwrite global settings if the same keys occur in both settings. The settings have to be specified in JSON format. It depends on the individual module which settings are available. This information should be looked up from the module documentation. - -.. image:: ui_rules_edit_processing.png - :width: 550px - :align: center - :class: border - -When selecting the "Retain input images" switch, the module will output both the processed images as well as the unprocessed input images. It depends on the individual application if this option is desired or not. - -.. important:: The "Retain input images" option must not be used with modules that should remove confidential information from the data, such as DICOM anonymization modules. - -**Routing tab** - -For rules involving dispatching, the "Routing" tab can be used to select the target to which the DICOMs should be dispatched (after finishing processing modules, if selected). At this time, images can only be dispatched to a single target per rule. If images should be sent to multiple destinations, it is currently necessary to define multiple rules with different target. This limitation will be removed in future versions of mercure. - -.. image:: ui_rules_edit_routing.png - :width: 550px - :align: center - :class: border - -**Notification tab** - -The "Notification" tab allows configuring webhook calls that are triggered when the rule gets activated, when the processing completes, and when an error occurs that is related to the rule. Webhook calls can be used to send notification messages into Slack, WebEx, Teams, or comparable messaging services. They can also be used for connecting other external services, for example, changing the color of a physical status light. - -.. image:: ui_rules_edit_notification.png - :width: 550px - :align: center - :class: border - -The URL and payload for the webhook call need to be provided. Payload templates for Slack and WebEx can be inserted by pressing the button "Insert Template". To obtain the webhook URL, you need to go into the configuration of your messaging service (e.g., Slack) and follow the instruction for setting up an incoming webhook. - -.. important:: Do not send any sensitive information in the payload because the webhook call will, in most cases, be sent to an externally operated service. - -**Information tab** - -The "Information" tab can be used to document the rule. The purpose of the rule can be written as free-text into the Comment field, and an email address can be written into the Contact field, so that it can be looked up at a later time why the rule was defined and who requested it. It is also possible to add tag attributes to the rule. These tags are not yet used for anything else, but might be used in future versions of mercure for filtering purpose and access control. - -.. image:: ui_rules_edit_information.png - :width: 550px - :align: center - :class: border - - -Queue management ----------------- - -The "Queue" page allows monitoring the status of mercure's processing and routing queues, and it provides basic functions for modifying jobs in the processing queue. - -.. image:: ui_queue.png - :width: 550px - :align: center - :class: border - -.. note:: By default, the views do not update automatically when the page is open, as this could have negative impact on the server load. Press the Refresh button in the top-right corner to update the queue lists. When pressing the Auto Update button, the view will be updated every 10 sec. - -**Queue status** - -The upper part of the page indicates if mercure is currently processing or routing images. Using the switches "Suspend Queue", you can halt the processing or routing queue. In this case, mercure will finish the active job but will not start another job until the queue has been started again. This can be helpful if it is necessary to patch job parameters, or if module settings need to be changed before additional series can be processed. - -**Job status** - -The lower part of the page shows the status of individual jobs in mercure's different queues. - -.. important:: Some of the functions for modifying jobs are still incomplete and will be added in future versions of mercure. - -The "Processing" tab shows the jobs currently placed in the processing queue, i.e. jobs (series or studies) for which processing modules are executed. You can mark jobs by clicking on the corresponding row. This will activate the toolbar above the table, which allows, e.g., displaying additional job information or deleting jobs. Similarly, the "Routing" tab shows the outgoing jobs currently placed in the routing queue. - -.. image:: ui_queue_processing.png - :width: 550px - :align: center - :class: border - -The "Studies" tab show the list of studies currently waiting for complete image arrival, i.e. studies for which a study-level rule has triggered and for which DICOM series are still being collected. It allows enforcing the completion of the series collection by clicking the button "Force study completion". - -The "Failure" tab shows a list of all jobs for which processing errors have occurred, including errors during preparation, processing, and routing. Failed jobs can be restarted -- if possible depending on the error type. - -The "Archive" tab shows a search box that allows reviewing the status of series/studies still residing on the server that have completed processing/routing or that have been discarded because no rule had triggered. Because there is typically a high number of such jobs, it has been implemented as search box instead of a table with all entries. In the future, it will be possible to reprocess such cases (e.g., if a series had not been processed because the selection rule was incorrect). - -.. note:: If you send a DICOM series to mercure, it takes a short time before the series becomes visible on the Queue page (i.e. on the Processing, Routing, or Studies tab) because mercure first waits for expiration of the series completion timeout (60 sec by default). diff --git a/docs/usage/index.rst b/docs/usage/index.rst new file mode 100644 index 00000000..09bdb32d --- /dev/null +++ b/docs/usage/index.rst @@ -0,0 +1,63 @@ +Usage +===== + + .. toctree:: + :maxdepth: 1 + :glob: + + * + +Web interface +------------- + +mercure can be conveniently configured and controlled using the web-based user interface. To access it, use a modern web browser (e.g., Chrome or Firefox) and enter the IP of your mercure server as URL. Depending on the port that you have selected during the installation (by default 8000), you need to add ":8000" to the URL. + +.. image:: /images/ui/login.png + :width: 550px + :align: center + :class: border + +During the installation, mercure creates a "seed account" that you need to use for the first login. You will be asked to change the password after the first login. + +.. note:: The login credentials for the first login are: Username = admin, Password = router + +To end your session, use the menu on the top-right and select "Logout". + +User management +--------------- + +Users can be created, modified, and deleted on the "Users" page. There are two types of users: Normal users, who can view the configuration and status but not change any settings, and administrators, who have full access. Users with administration rights are indicated by an icon with a shield in the user list. Users can also be added to permission groups. Permission groups are not yet used for anything, but they will be used in future mercure versions to provide granular access control. + +.. image:: /images/ui/users.png + :width: 550px + :align: center + :class: border + +.. tip:: You should create separate accounts for every person using mercure. This will allow you to review which user made changes to the server configuration, as mercure is keeping track of all configuration changes. + + +System status and control +------------------------- + +The status of the mercure server and its service components can be monitored on the "Overview" page. If a service module is running, it will be shown in green color, otherwise it is shown in red. In normal operation, everything should be green. + +.. image:: /images/ui/status.png + :width: 550px + :align: center + :class: border + +The Overview page also shows the disk space available in the folder for buffering the incoming DICOM files. If this bar turns yellow or red, make sure to free up disk space as the mercure server will not be able to receive images if the disk is completely full. + +You can start, stop, and restart services by clicking the "Service Control" button. This will show a dialog where you can select which service(s) to control and which operation to execute (e.g., start or stop). If a service does not react anymore at all, it is also possible to kill a service. + +.. image:: /images/ui/status_control.png + :width: 550px + :align: center + :class: border + +.. note:: If you stop a service, it might take a short moment until the service goes down. This is because the services have been designed to finish the active task before terminating. + +.. note:: The "Service Control" button is only available for systemd- and Docker-type installations but not for Nomad-type installations. Nomad directly takes care restarting services. + +.. tip:: If you don't want to use the web interface, you can also manually control the mercure services from the command line. For systemd-type installations, this can be done with the command "systemctl start -u mercure_router.service" (in this example for the routing service). You can find the names of the individual services in the file **/opt/mercure/config/services.json**. + diff --git a/docs/usage/modules.rst b/docs/usage/modules.rst new file mode 100644 index 00000000..fc6ac1da --- /dev/null +++ b/docs/usage/modules.rst @@ -0,0 +1,33 @@ +Modules +------------------ + +An overview of the installed processing modules can be seen on the "Modules" page. Details are shown by clicking on an item, which also allows editing the module settings. + +.. image:: /images/ui/modules.png + :width: 550px + :align: center + :class: border + +To setup a new processing module, click the "Add" button. Select a unique name for the module and specify the processing module by entering the Docker tag. It is possible to install the same processing module multiple times under different names with different settings. + +The default module type "mercure" is the correct type for modules designed to be used in Mercure. Modules that are compatible for MONAI must be installed with this type specified. If you select the wrong one here, you can change it later. + +.. image:: /images/ui/module_add.png + :width: 550px + :align: center + :class: border + +.. note:: The Docker Tag corresponds to the name of the processing module as stored on Docker Hub (example: mercureimaging/mercure-testmodule). For modules that are not distributed via Docker Hub, the Docker container needs to be built locally on the server before it can be used by mercure. + +Afterwards, you can edit additional Docker-specific settings on the "Docker" tab (additional volumes, environment variables, etc.). In most cases, these settings are not needed. + +.. image:: /images/ui/module_edit.png + :width: 550px + :align: center + :class: border + +Settings for the processing module can be defined on the "Settings" tab. These settings must be entered in **JSON format**. The settings entered on the module page are global modules settings, i.e. they are applied whenever the module is used. The global module settings can be overwritten (or extended) by defining settings for the individual rule (thus, the settings passed to the module are the global module settings merged with the rule-specific processing settings). + +The "Orchestration" tab allows configuring Nomad-specific settings. If you have a systemd- or Docker-type installation, these settings are irrelevant and can be ignored. It is possible to specify "Execution constraints" if the module should be executed on a certain node of your processing cluster (e.g., if a specific GPU or operating system is needed). The field "Resource requirements" can be used to request resources needed for execution of the module (e.g., the amount of memory or CPU cores). + +The "Information" tab can be used to document the current module setup, including a free-text description as well as contact e-mail address. \ No newline at end of file diff --git a/docs/usage/query.rst b/docs/usage/query.rst new file mode 100644 index 00000000..53eb276b --- /dev/null +++ b/docs/usage/query.rst @@ -0,0 +1,13 @@ +Query Tool +========== + +Mercure Query enables pulling series and studies from various servers. It is an alternative to the "push" workflows that the Mercure receiver enables. + +.. image:: /images/ui/query.png + :width: 550px + :align: center + :class: border + +To query a node, you must have at least one target with type set to "Pull" or "Both." Other targets will not appear in the dropdown list. + +A query requires one or more accession numbers to start with, separated by commas. Mercure will attempt to query every study that has that one of the listed accessions. \ No newline at end of file diff --git a/docs/usage/queue.rst b/docs/usage/queue.rst new file mode 100644 index 00000000..b1d34be3 --- /dev/null +++ b/docs/usage/queue.rst @@ -0,0 +1,38 @@ +Queue management +================ + +The "Queue" page allows monitoring the status of mercure's processing and routing queues, and it provides basic functions for modifying jobs in the processing queue. + +.. image:: /images/ui/queue.png + :width: 550px + :align: center + :class: border + +.. note:: By default, the views do not update automatically when the page is open, as this could have negative impact on the server load. Press the Refresh button in the top-right corner to update the queue lists. When pressing the Auto Update button, the view will be updated every 10 sec. + +Queue status +------------ + +The upper part of the page indicates if mercure is currently processing or routing images. Using the switches "Suspend Queue", you can halt the processing or routing queue. In this case, mercure will finish the active job but will not start another job until the queue has been started again. This can be helpful if it is necessary to patch job parameters, or if module settings need to be changed before additional series can be processed. + +Job status +---------- + +The lower part of the page shows the status of individual jobs in mercure's different queues. + +.. important:: Some of the functions for modifying jobs are still incomplete and will be added in future versions of mercure. + +The "Processing" tab shows the jobs currently placed in the processing queue, i.e. jobs (series or studies) for which processing modules are executed. You can mark jobs by clicking on the corresponding row. This will activate the toolbar above the table, which allows, e.g., displaying additional job information or deleting jobs. Similarly, the "Routing" tab shows the outgoing jobs currently placed in the routing queue. + +.. image:: /images/ui/queue_processing.png + :width: 550px + :align: center + :class: border + +The "Studies" tab show the list of studies currently waiting for complete image arrival, i.e. studies for which a study-level rule has triggered and for which DICOM series are still being collected. It allows enforcing the completion of the series collection by clicking the button "Force study completion". + +The "Failure" tab shows a list of all jobs for which processing errors have occurred, including errors during preparation, processing, and routing. Failed jobs can be restarted -- if possible depending on the error type. + +The "Archive" tab shows a search box that allows reviewing the status of series/studies still residing on the server that have completed processing/routing or that have been discarded because no rule had triggered. Because there is typically a high number of such jobs, it has been implemented as search box instead of a table with all entries. In the future, it will be possible to reprocess such cases (e.g., if a series had not been processed because the selection rule was incorrect). + +.. note:: If you send a DICOM series to mercure, it takes a short time before the series becomes visible on the Queue page (i.e. on the Processing, Routing, or Studies tab) because mercure first waits for expiration of the series completion timeout (60 sec by default). diff --git a/docs/usage/rules.rst b/docs/usage/rules.rst new file mode 100644 index 00000000..d3eda89a --- /dev/null +++ b/docs/usage/rules.rst @@ -0,0 +1,179 @@ + +Rules +===== + +After you have configured your targets and processing modules, you can define rules that specify which DICOM series should be processed and to which targets the images should be dispatched. This can be done on the "Rules" page. + +.. image:: /images/ui/rules/rules.png + :width: 550px + :align: center + :class: border + +It is not necessary to stop mercure services while defining new rules. The mercure service modules will automatically reload the new configuration when a rule has been added or modified. Click the "Add New" button to create a new rule, or click on any of the existing rules and select "Edit" to modify it. + +Filtering tab +~~~~~~~~~~~~~ + +All rules are evaluated whenever a new DICOM series has been received. The rules can use a set of DICOM tags extracted from the incoming DICOM files. To see the full list of DICOM tags available for writing rules, click the "Available Tags" button. + +.. tip:: If you need additional tags that are currently not in the list, you can enable additional tags in system settings. + + +.. image:: /images/ui/rules/edit.png + :width: 550px + :align: center + :class: border + +A received series will processed if the selection rule evaluates to True, and it will be ignored if the rule evaluates to False. If none of the defined rules evaluates to True, the series will be discarded. + +Selection rules are evaluated as Python expressions. Tags are available as properties on an object called "`tags`", so for instance a rule like: + +.. highlight:: none + +:: + + 'CINE' in tags.SeriesDescription + +will activate for all series that have the word "CINE" in the series description (e.g., "CINE 2ch"). If you only want to send series that are exactly called "CINE", use the following rule instead + +.. warning:: Older versions of Mercure used a syntax like ``'CINE' in %SeriesDescription%``. This syntax is still valid but should not be used in new rules. + + +:: + + tags.SeriesDescription == 'CINE' + +This rule would not trigger if the series is called "CINE 2ch". Multiple conditions can be combined using the "or" and "and" operators. Here, it is recommended to enclose every sub-condition with "( )". By default, DICOM tags are treated as strings and are case-sensitive. If you want to make your condition case-insensitive, then append ".lower()" to the tag. +:: + + tags.SeriesDescription.lower() = 'cine' + +This would trigger for series called "CINE" or "cine". If you want to test for numerical value thresholds (e.g., if the slice thickness is lower than 2mm), you first need to convert the tag into a float by writing the tag inside "``float()``". This then allows you to write a rule like +:: + + float(tags.SliceThickness) < 2.0 + +Testing Rules +^^^^^^^^^^^^^ + +To test a selection rule before activating it, click the icon with the cog wheels on the left side of input box. If you see a red icon in the dialog, the rule notation is invalid (the dialog will tell you why). If the rule is valid, the dialog will test if the rule would trigger if a DICOM series with the values shown in the lower part of the dialog would be received. You can modify these values and test if the rule reacts as expected. + +.. image:: /images/ui/rules/test.png + :width: 550px + :align: center + :class: border + +.. hint:: If you make a mistake while changing the test values (e.g., missing a quotation mark), you will see a yellow icon. + +Rule Actions +^^^^^^^^^^^^ + +If you have validated that your rule triggers as expected, select the desired Action from the drop-down list. The following options are available: + +==================== =============================================================================== +Action Meaning +==================== =============================================================================== +Routing The received series/study will be dispatched to a target (no processing) +Processing & Routing The received series/study will be processed and afterwards dispatched +Processing only The received series/study will be processed (without further dispatching) +Notification only A notification will be triggered if the series/study is received (without neither processing or dispatching) +Force discard The received series/study will be discarded (no other rules will be evaluated) +==================== =============================================================================== + +Depending on the selected Action, the tabs "Processing" and "Routing" will become visible. + +Rule Triggers +^^^^^^^^^^^^^^ + +The Trigger control allows selecting when the action should be triggered. + + +If **Completed Series** is selected, Mercure executes the action when a DICOM series has been received for which the rule evaluates to ``True``. If multiple series from a patient study are received, these series are evaluated separately, and may trigger the same, different, or no rules. + +If **Completed Study** is selected, all series for a given study are evaluated together. For example, an AI-based analysis algorithm might require multiple series with different contrast. On selection, an additional control **Completion Criteria** will appear, which allows selecting when the study should considered complete. Rules with this trigger are only evaluated when the study appears to be complete, and all the series will be routed or processed together. + +.. image:: /images/ui/rules/edit_trigger.png + :width: 550px + :align: center + :class: border + +If **List Series Received** is selected, Mercure evaluates whether the study is complete based on whether specific series have been received using the ``SeriesDescription`` dicom tag. Here is an example expression that will consider the study complete if it receives a series with a ``SeriesDescription`` which contains "Axial T2" and another series that has either "SAG T1 GRE" or "Sag T1 TSE": + +:: + + 'Axial T2' and ('Sag T1 GRE' or 'Sag T1 TSE') + +This allows handling variability in the Series Descriptions, which often occurs in practice due to inconsistent configuration of imaging devices. + +If the names of the expected series are unknown, the option "Timeout Reached" can be used, which collects image series belonging to the same study until no further series has been received for a definable timeout period (the timeout time can be set on the Configuration page). A disadvantage of this option is that the processing will be delayed until the timeout period has expired. + +Priority +^^^^^^^^ + +If the Priority control is set to "Urgent", corresponding series or studies will be pushed to the front of the processing queue, while the setting "Off-Peak" enforces that the corresponding series will be only processed during off-peak hours. The latter can be helpful to avoid that computationally demanding research studies might delay clinical routine processing during normal work hours. + +Rules can be temporarily disabled by toggling the "Disable Rule" switch. In this case, the rule appears in grayed-out color in the rule list and it will be ignored during processing. By clicking the "Fallback Rule" switch, the current rule will be applied to all DICOM series for which no other rules have triggered. This allows defining a "default" rule. + +Processing tab +~~~~~~~~~~~~~~ + +For rules involving processing, the "Processing" tab can be used to select the processing module or modules. To add a module, select it in the dropdown box and press the "+" button to add it to the end of the module list. Each module will be executed in order, left to right. Generally, the output of each module will be used as the input for the next. + +The "settings" input provides rule-specific module settings. These settings will be merged with the global module settings and will overwrite global settings if the same keys occur in both. The settings have to be specified in JSON format. It depends on the individual module which settings are available. This information should be looked up from the module documentation. + +If you are using multiple modules, this will be used for each of the modules. + +.. image:: /images/ui/rules/edit_processing.png + :width: 550px + :align: center + :class: border + +When selecting the "Retain input images" switch, the module will output both the processed images as well as the unprocessed input images. It depends on the individual application if this option is desired or not. + +.. important:: The "Retain input images" option must not be used with modules that should remove confidential information from the data, such as DICOM anonymization modules. + +Routing tab +~~~~~~~~~~~ + +For rules with dispatching, the "Routing" tab can be used to select the target(s) to which the DICOMs should be dispatched after finishing any processing modules. + +.. image:: /images/ui/rules/edit_routing.png + :width: 550px + :align: center + :class: border + +Notification tab +~~~~~~~~~~~~~~~~ + +The "Notification" tab allows configuring webhook calls and emails that can be triggered at various points after a DICOM series is received. + +Webhook calls can be used to send notification messages into Slack, WebEx, Teams, or comparable messaging services. They can also be used for connecting other external services, for example, changing the color of a physical status light. + +.. image:: /images/ui/rules/edit_notification.png + :width: 550px + :align: center + :class: border + +The "webhook body" input is free text, which can be used eg to specify the contents of a Slack message. It supports jinja2 templates. + +The URL and payload for the webhook call need to be provided. Payload templates for Slack and WebEx can be inserted by pressing the button "Insert Template". To obtain the webhook URL, you need to go into the configuration of your messaging service (e.g., Slack) and follow the instruction for setting up an incoming webhook. You can use ``"{{ body }}"`` to interpolate the "webhook body" as an escaped string. + +You can enable PHI inside notifications by setting ``"phi_notifications": True`` in the configuration, which will make it available as ``phi_data.acc``, ``phi_data.mrn`` and ``phi_data.patient_name``. + +.. important:: Be careful sending any sensitive information in the payload because the webhook call will, in most cases, be sent to an externally operated service. + +The "email body" works much the same way as the "webhook body." Select "HTML content" if it should be sent as an HTML email, or leave it unselected to send it as plaintext. + +If either the email address or webhook url is blank, notifications will not be sent via that modality. + +Information tab +=============== + +The "Information" tab can be used to document the rule. The purpose of the rule can be written as free-text into the Comment field, and an email address can be written into the Contact field, so that it can be looked up at a later time why the rule was defined and who requested it. It is also possible to add tag attributes to the rule. These tags are not yet used for anything else, but might be used in future versions of mercure for filtering purpose and access control. + +.. image:: /images/ui/rules/edit_information.png + :width: 550px + :align: center + :class: border + + diff --git a/docs/usage/targets.rst b/docs/usage/targets.rst new file mode 100644 index 00000000..c6bce975 --- /dev/null +++ b/docs/usage/targets.rst @@ -0,0 +1,92 @@ +Targets +======== + +Targets define connections to external services. These are used to send and :doc:`retrieve ` DICOMs. + +Target nodes can be defined and configured on the "Targets" page. The first page shows an overview of the currently configured targets. By clicking on an individual item, you can see the target details (e.g., IP address and port). You can test if the target can be reached by clicking the "Test" button, which will try to ping the server and check the connection. + +.. image:: /images/ui/targets.png + :width: 550px + :align: center + :class: border + +Click the "Add New" button to create a new target. This can be done during normal operation of the server, i.e. it is not necessary to stop any of the services for adding new targets. + +.. image:: /images/ui/target_edit.png + :width: 550px + :align: center + :class: border + +After choosing a unique name for the target, you can edit the target settings. + +.. table:: Target Types + + =========== ======= ============ + Type Push Pull (Query) + =========== ======= ============ + DICOM Y Y + DICOM+TLS Y N + DICOMWeb Y Y + Folder Y N (but see DICOMWeb) + rsync Y N + S3 Y N + SFTP Y N + XNAT Y N + =========== ======= ============ + +Direction +--------- + +The default direction, "store", is available on all targets. This indicates that this target can be used at a routing target. + +"Query" indicates that this target can only be used in the query interface. This should be used for services that cannot or should not be sent to, but can be queried. It is currently available on DICOM and DICOMWeb. + +"both" indicates that this target can be used in both situations. + +DICOM +----- + +For DICOM targets, enter the parameters of the DICOM node, including the IP address, port, the target AET (application entity title) that should be called on the receiver side, and the source AET with which mercure identifies itself to the target. + +.. tip:: Some DICOM nodes require that you set a specific target AET, while other systems ignore this setting. Likewise, some DICOM nodes only accept images from a sender who's source AET is known, while others ignore the value. Please check with the vendor/operator of your DICOM node which values are required. + +For DICOM TLS targets, enter the TLS client key path, TLS client certificate path, and the path to the Certificate Authority (CA) certificate file. You will need to add these files to your mercure installation, e.g. in `/opt/mercure/certs`. + +.. important:: Support for DICOM TLS transfers is still experimental and should be used with care. + +.. important:: Due to an incompatibility in DICOM toolkit v3.6.4 and OpenSSL v1.1.1, the dcmtk and openssl versions supported by Ubuntu 20.04, only Ubuntu 22.04 mercure installs support for DICOM+TLS targets. + +DICOMWeb +-------- + +The DICOMWeb target additionally supports querying a local folder of dicoms. To use this, specify the folder with ``file://``, eg ``file///media/dicoms``. If mercure has write permissions, it will generate a sqlite index, otherwise it will re-index it on each query. Needless to say, if the folder is too large, this would make queries very slow and resource intensive. + +Folder +------ +The folder target is a folder local to Mercure. When running in Docker, this folder will be inside the dispatcher container; for this folder to be available and persist on the base system, the Docker Compose configuration will need to map this folder to a Docker volume or a folder in the base filesystem. + +The "Exclusion Filter" option is a comma-separated list of `glob expressions `_ which specify files to be ignored. For instance, if a processing step produces dicoms, pngs and json, ``*.png,*.json`` will skip the png and json files from being sent. + +rsync +----- + +The rsync connection will use certificate-based authentication if possible, but you can specify a username and password if necessary. + +If the "Execute shell command after transfer" option is set, Mercure will attempt to log in and execute a script named `mercure_complete.sh` in the target folder. The command will be executed as + +``mercure_complete.sh `` + +SFTP +---- + +For SFTP targets, enter the hostname or IP, target folder on the server, username, and password. + +.. tip:: It is recommended to create a restricted user account for the SFTP uploads. Never use the credentials of an account with access to sensitive information, as the SFTP credentials are stored in the configuration file. + +.. important:: Support for SFTP transfers is still experimental and should be used with care. + +Information +----------- + +On the "Information" tab, you can add information for documentation purpose, including a contact e-mail address (so that it can be looked up who should be contacted if problems with the target occur) and a description of the target. +