# HG changeset patch # User Sebastien Jodogne # Date 1582824549 -3600 # Node ID c5226c5509ca35652434e55576cc5c59eae922d4 # Parent f5b63b30d17814f28857bd7c4c088c42bb734c78 storage commitment scp diff -r f5b63b30d178 -r c5226c5509ca Sphinx/source/images/StorageCommitmentSCP.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/images/StorageCommitmentSCP.svg Thu Feb 27 18:29:09 2020 +0100 @@ -0,0 +1,570 @@ + + diff -r f5b63b30d178 -r c5226c5509ca Sphinx/source/users.rst --- a/Sphinx/source/users.rst Sun Feb 23 11:40:42 2020 +0100 +++ b/Sphinx/source/users.rst Thu Feb 27 18:29:09 2020 +0100 @@ -13,4 +13,5 @@ users/anonymization.rst users/lua.rst users/advanced-rest.rst + users/storage-commitment.rst users/support.rst diff -r f5b63b30d178 -r c5226c5509ca Sphinx/source/users/advanced-rest.rst --- a/Sphinx/source/users/advanced-rest.rst Sun Feb 23 11:40:42 2020 +0100 +++ b/Sphinx/source/users/advanced-rest.rst Thu Feb 27 18:29:09 2020 +0100 @@ -137,6 +137,8 @@ ``Failure``. +.. _jobs-controlling: + Interacting with jobs ^^^^^^^^^^^^^^^^^^^^^ diff -r f5b63b30d178 -r c5226c5509ca Sphinx/source/users/storage-commitment.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/users/storage-commitment.rst Thu Feb 27 18:29:09 2020 +0100 @@ -0,0 +1,204 @@ +.. _storage-commitment: + +Storage commitment +================== + +.. contents:: + :depth: 3 + + +Introduction +------------ + +Starting with **release 1.6.0**, Orthanc implements DICOM storage +commitment, both as an SCP and as a SCU. + +Storage commitment is a feature of the DICOM standard by which an +imaging modality "A" asks a remote imaging modality "B", whether "B" +accepts responsibility for having stored the images "A" has sent to +it. + +Typically, a storage commitment request is issued by "A" after "A" has +sent images to "B" using the :ref:`DICOM C-STORE command +`. If "B" answers that all the images have been properly +received, the modality "A" has the guarantee that the C-STORE commands +ran fine, and thus "A" might decide to remove the images from its +database. If "B" answers that there was an error, "A" might decide to +send the images again. + +For more technical information, one may refer to the storage +commitment `Information Object Definition +`__ +and `Service Class +`__ +in the DICOM standard. Orthanc follows the objective of the IHE +Technical Framework regarding the `Storage Commitment transaction +(RAD-10) +`__. Following +this IHE specification, Orthanc only implements the **Storage +Commitment Push Model SOP Class**, both as an SCU ("Evidence Creator") +and as an SCP ("Image Manager"). + +Orthanc makes the assumption that the storage commitment responses are +sent **asynchronously**, which corresponds to most implementations of +storage commitment. + + +.. _storage-commitment-scp: + +Storage commitment SCP +---------------------- + +Overview +^^^^^^^^ + +Here is a diagram that outlines how storage commitment works in Orthanc: + +.. image:: ../images/StorageCommitmentSCP.svg + :align: center + :width: 650px + +| In this sequence, three DICOM associations are used: The first one + is the usual command to send the DICOM images from some SCU to the + Orthanc SCP (:ref:`C-STORE `), the second association + is the one by which the SCU asks the Orthanc SCP to process a + storage commitment request (the SCU provides a list of DICOM + instances to be checked by specifying their SOP instance UID and + their SOP class UID), and the third one is the storage commitment + response coming from the Orthanc SCP. The response is sent + asynchronously from the Orthanc SCP to the SCU, once the storage + commitment request has been processed by Orthanc. + +The list of the DICOM modalities from which Orthanc accepts incoming +storage commitment requests is specified in the :ref:`configuration +file of Orthanc `, by the ``DicomModalities`` +option. It is possible to disable storage commitment for selected +modalities by setting their dedicated Boolean permission flag +``AllowStorageCommitment`` to ``false``. + +As can be seen, the storage commitment SCP of Orthanc also takes +advantage of the :ref:`jobs engine ` that is embedded within +Orthanc. Whenever Orthanc receives a storage commitment request, it +internally creates a job with a dedicated type (namely +``StorageCommitmentScp``). :ref:`This job can be controlled +` using the REST API of Orthanc, just like any other +job. As a consequence, an external software is able to monitor, cancel +or pause incoming storage commitment requests, by inspecting the list +of jobs whose type is ``StorageCommitmentScp``. + + + +Sample usage +^^^^^^^^^^^^ + +In this section, we show how to query the storage commitment SCP of +Orthanc from the command-line tool ``stgcmtscu``. This free and +open-source tool originates from the `dcm4che project +`__ and simulates a basic storage commitment +SCU. + +.. highlight:: json + +Firstly, we define one DICOM modality corresponding to ``stgcmtscu`` +by creating the following :ref:`configuration file ` +for Orthanc:: + + { + "DicomPort" : 4242, + "DicomModalities" : { + "storage-commitment" : [ "STGCMTSCU", "127.0.0.1", 11114 ] + } + } + + +.. highlight:: text + +Secondly, we start Orthanc using the just-created configuration file:: + + $ ./Orthanc --verbose storage-commitment.json + +We'll be using some sample file ``/tmp/DummyCT.dcm``, whose DICOM tags +"SOP instance UID" and "SOP class UID" can be retrieved as follows:: + + $ dcm2xml /tmp/DummyCT.dcm | grep -E '"SOPInstanceUID"|"SOPClassUID"' + 1.2.840.10008.5.1.4.1.1.4 + 1.2.840.113619.2.176.2025.1499492.7040.1171286242.109 + +Thirdly, we use ``stgcmtscu`` to get the status of one sample DICOM +file. Here is what can be read at the end of the logs of +``stgcmtscu``:: + + $ /home/jodogne/Downloads/dcm4che-5.20.0/bin/stgcmtscu -b STGCMTSCU:11114 -c ORTHANC@localhost:4242 /tmp/DummyCT.dcm + [...] + 18:14:22,949 DEBUG - STGCMTSCU<-ORTHANC(2) >> 1:N-EVENT-REPORT-RQ Dataset receiving... + 18:14:22,949 DEBUG - Dataset: + (0008,1195) UI [2.25.250402771220435242864082979068071491247] TransactionUID + (0008,1198) SQ [1 Items] FailedSOPSequence + >Item #1 + >(0008,1150) UI [1.2.840.10008.5.1.4.1.1.4] ReferencedSOPClassUID + >(0008,1155) UI [1.2.840.113619.2.176.2025.1499492.7040.1171286242.109] ReferencedSOPInstanceUID + >(0008,1197) US [274] FailureReason + (0008,1199) SQ [] ReferencedSOPSequence + +As can be seen, the SOP class/instance UIDs of ``/tmp/DummyCT.dcm`` +are reported by the Orthanc SCP in the ``FailedSOPSequence`` field, +which indicates the fact that Orthanc has not stored this instance +yet. The ``FailureReason`` 274 corresponds to status 0x0112, namely +"No such object instance". + +Fourthly, let's upload the sample file, then execute ``stgcmtscu`` a +second time:: + + $ storescu localhost 4242 /tmp/DummyCT.dcm + $ /home/jodogne/Downloads/dcm4che-5.20.0/bin/stgcmtscu -b STGCMTSCU:11114 -c ORTHANC@localhost:4242 /tmp/DummyCT.dcm + [...] + 18:19:48,090 DEBUG - STGCMTSCU<-ORTHANC(2) >> 1:N-EVENT-REPORT-RQ Dataset receiving... + 18:19:48,090 DEBUG - Dataset: + (0008,1195) UI [2.25.141864351815234988385597655400095444069] TransactionUID + (0008,1199) SQ [1 Items] ReferencedSOPSequence + >Item #1 + >(0008,1150) UI [1.2.840.10008.5.1.4.1.1.4] ReferencedSOPClassUID + >(0008,1155) UI [1.2.840.113619.2.176.2025.1499492.7040.1171286242.109] ReferencedSOPInstanceUID + +The instance of interest is now reported in the +``ReferencedSOPSequence`` tag, instead of ``FailedSOPSequence``. This +shows that Orthanc has properly received the sample instance. + + + +Plugins +^^^^^^^ + +The Orthanc core implements a basic storage commitment SCP. This basic +handler simply checks for the presence of the requested DICOM +instances in the Orthanc database, and makes sure that their SOP class +UIDs do match those provided by the remote storage commitment SCU. + +For more advanced scenarios, it is possible to override this default +SCP to customize the way incoming storage commitment requests are +processed by Orthanc. This customization is done :ref:`by creating an +Orthanc plugin `. + +The custom storage commitment SCP is installed in the Orthanc core by +using the ``OrthancPluginRegisterStorageCommitmentScpCallback()`` +function of the `plugin SDK `__. + +Importantly, this primitive frees the plugin developer from manually +creating the Orthanc jobs. One job is automatically created for each +incoming storage commitment request by the Orthanc core, allowing the +developer to focus only on the processing of the queried instances. + +Note that a `sample plugin +`__ +is also available in the source distribution of Orthanc. + + + +.. _storage-commitment-scu: + +Storage commitment SCU +---------------------- + +*Work in progress* + +*Sample using dcmqrscp*