|
822
|
1 .. _dcmtk-tricks:
|
|
|
2
|
|
|
3 How to guarantee study transfer atomicity ?
|
|
|
4 =========================================
|
|
|
5
|
|
|
6 .. contents::
|
|
|
7 :depth: 3
|
|
|
8
|
|
|
9 Introduction
|
|
|
10 ------------
|
|
|
11
|
|
|
12 There are multiple ways to transfer studies to an Orthanc instance.
|
|
|
13 Only a few of them provide a guarantee that the study has been
|
|
|
14 transferred completely.
|
|
|
15
|
|
|
16 **Notes**:
|
|
|
17
|
|
|
18 * By ``transfer atomicity``, we mean the capability to transfer
|
|
|
19 only full studies and make sure that if a transfer fails before
|
|
|
20 it is complete, no partial data is saved in Orthanc. The study is either
|
|
|
21 fully stored or not stored at all.
|
|
|
22
|
|
|
23 * DICOM, in general, does not provide any way to detect that a study
|
|
|
24 is ``complete``. Actually, a study is never ``complete`` since, e.g,
|
|
|
25 a viewing workstation or an AI algorithm can still add a new enhanced
|
|
|
26 series even years after the study has been acquired.
|
|
|
27 However, it is still important, in many applications, to make sure
|
|
|
28 that a study, in its current state, is fully transmitted to another
|
|
|
29 destination.
|
|
|
30
|
|
|
31 * Both the **client/source** and the **server/destination** might be interrested
|
|
|
32 in the transfer status. Usually, the **client** will have a guarantee that the
|
|
|
33 study was fully transmitted if it receives a successful answer from the server.
|
|
|
34 On the **server** side, it is usually more complex to make sure that the
|
|
|
35 full study has been received.
|
|
|
36
|
|
|
37
|
|
|
38 Summary
|
|
|
39 -------
|
|
|
40
|
|
|
41 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
|
|
|
42 | Transfer method | What can the Client/source trust to make sure | Can Server/destination trust ``StableStudy`` |
|
|
|
43 | | the full study has been stored in the server ? | event to consider the study as complete ? |
|
|
|
44 +==================================================+==================================================+===============================================+
|
|
|
45 | **C-Store** | * If every C-Store receives a success status. | No |
|
|
|
46 | | * If ``/modalities/sample/store`` receives a | |
|
|
|
47 | | 200 or if job is successfull | |
|
|
|
48 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
|
|
|
49 | **C-Store with storage commitment** | * same as above | No |
|
|
|
50 | | * use storage commitment to check which | |
|
|
|
51 | | instances are stored on destination | |
|
|
|
52 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
|
|
|
53 | **DicomWeb** | * If client receives a 200 | No |
|
|
|
54 | | * If ``/dicom-web/servers/sample/stow`` returns | |
|
|
|
55 | | a 200 or if job is successfull | |
|
|
|
56 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
|
|
|
57 | **Orthanc Rest API** | * If every call to ``/instances`` receives a | No |
|
|
|
58 | | 200 | |
|
|
|
59 | | * If ``/peers/sample/store`` receives a | |
|
|
|
60 | | 200 or if job is successfull | |
|
|
|
61 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
|
|
|
62 | **Transfers accelerator plugin** | * If ``/transfers/send`` receives a | Yes (provided that the client sends full |
|
|
|
63 | | 200 or if job is successfull | study) |
|
|
|
64 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
|
|
|
65
|
|
|
66
|
|
|
67 C-Store
|
|
|
68 -------
|
|
|
69
|
|
|
70 If you are sending a study to Orthanc via C-Store, the study will be
|
|
|
71 considered as ``stable`` after a given period of time (defined by
|
|
|
72 the configuration ``StableAge``). This gives no guarantee at all that
|
|
|
73 the study has been fully transferred. The sending modality may have
|
|
|
74 paused transfer for a while and might resume in a few minutes.
|
|
|
75
|
|
|
76 Although inaccurate by design, the ``IsStable`` status in Orthanc is the
|
|
|
77 best way to assume that a study has been fully transferred via DICOM.
|
|
|
78 The default value of ``60 seconds`` is appropriate for most setups.
|
|
|
79
|
|
|
80 **Note**:
|
|
|
81
|
|
|
82 * When Orthanc, acting as C-Store SCP, responds with a success status to a C-Store command,
|
|
|
83 it means that the instance has already been saved in the DB and
|
|
|
84 on the storage.
|
|
|
85
|
|
|
86
|
|
|
87
|
|
|
88 C-Store with storage commitment
|
|
|
89 -------------------------------
|
|
|
90
|
|
|
91 Since release 1.6.0, Orthanc supports :ref:`Storage Commitment <storage-commitment>`.
|
|
|
92 Storage commitment is not a guarantee of atomicity but simply provides a
|
|
|
93 way to check that a set of instances have really been saved by Orthanc.
|
|
|
94
|
|
|
95 Given that Orthanc only responsds to C-Store with a success status once the
|
|
|
96 instance has really been saved in DB and on disk, storage commitment
|
|
|
97 actually do not provide any additional guarantee during transfer.
|
|
|
98
|
|
|
99
|
|
|
100 DicomWeb STOW-RS
|
|
|
101 ----------------
|
|
|
102
|
|
|
103 :ref:`STOW-RS <dicomweb-stow-rs>` can be used to transfer studies to an Orthanc.
|
|
|
104 The STOW-RS request contains a list of DICOM instances to store in the destination
|
|
|
105 Orthanc (likely a complete study).
|
|
|
106
|
|
|
107 Files are stored as they are received which means that, if the transfer is interrupted,
|
|
|
108 only a partial study may be stored on the destination. Therefore, on the destination,
|
|
|
109 a ``StableStudy`` event might be triggered even if the study was not fully received.
|
|
|
110
|
|
|
111
|
|
|
112 **Note**:
|
|
|
113
|
|
|
114 * In earlier Orthanc versions, ``ChunkedTransfers`` was disabled, and the whole study
|
|
|
115 was transmitted in a single HTTP request and parsed only once the full HTTP request
|
|
|
116 had been received. Therefore, the whole study was stored at once on the destination.
|
|
|
117 However, note that ``ChunkedTransfers`` is enabled by default on every Orthanc server
|
|
|
118 but it can be disabled in the client configuration. Also note that studies bigger than
|
|
|
119 2 GB can not be transferred with ``ChunkedTransfers`` disabled which means it is not
|
|
|
120 recommended to perform transfers with disabled ``ChunkedTransfers``.
|
|
|
121
|
|
|
122
|
|
|
123
|
|
|
124 Orthanc Rest API
|
|
|
125 ----------------
|
|
|
126
|
|
|
127 When transferring a study through the Orthanc Rest API, each instance is transferred individually.
|
|
|
128 Therefore, on server side, if the transfer is interrupted, the destination has no way to know that the study
|
|
|
129 has been fully transmitted or not.
|
|
|
130
|
|
|
131 The server will respond with a 200 HTTP status only once the instance is stored in DB and on storage.
|
|
|
132
|
|
|
133
|
|
|
134
|
|
|
135 Transfers Accelerator plugin
|
|
|
136 ----------------------------
|
|
|
137
|
|
|
138 :ref:`Transfers Accelerator plugin <transfers>` has been design to:
|
|
|
139
|
|
|
140 * speed up transfers over HTTP/HTTPS.
|
|
|
141 * guarantee the transfer atomicity
|
|
|
142
|
|
|
143 Provided that the client is sending a full study, the server receiving it
|
|
|
144 will store it completely. Therefore, on server side, the ``StableStudy`` event will trigger only
|
|
|
145 on full studies. |
