Mercurial > hg > orthanc-book
annotate Sphinx/source/users/lua.rst @ 912:dbe3fd98beb0
lua deadlocks
author | Alain Mazy <am@osimis.io> |
---|---|
date | Thu, 02 Feb 2023 12:13:34 +0100 |
parents | 035fe50b2e00 |
children | b113d1384248 |
rev | line source |
---|---|
0 | 1 .. _lua: |
2 | |
3 Server-side scripting with Lua | |
4 ============================== | |
5 | |
6 .. contents:: | |
7 | |
8 Since release 0.5.2, Orthanc supports server-side scripting through | |
25 | 9 the `Lua <https://en.wikipedia.org/wiki/Lua_(programming_language)>`__ |
0 | 10 scripting language. Thanks to this major feature, Orthanc can be tuned |
11 to specific medical workflows without being driven by an external | |
12 script. This page summarizes the possibilities of Orthanc server-side | |
13 scripting. | |
14 | |
15 Many other examples are `available in the source distribution | |
449 | 16 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Resources/Samples/Lua/>`__. |
0 | 17 |
606
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
18 A more expressive alternative to Lua scripts is provided by |
846 | 19 :ref:`Python plugins <python-plugin>`. |
606
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
20 |
0 | 21 |
75 | 22 Installing a Lua script |
0 | 23 ----------------------- |
24 | |
25 .. highlight:: bash | |
26 | |
27 A custom Lua script can be installed either by the :ref:`configuration | |
28 file <configuration>`, or by uploading it | |
29 through the :ref:`REST API <rest-samples>`. | |
30 | |
31 To install it by the **configuration file** method, you just have to | |
32 specify the path to the file containing the Lua script in the | |
357 | 33 ``LuaScripts`` variable. A comma-separated list of paths can be |
34 specified to install multiple scripts. | |
0 | 35 |
36 To upload a script stored in the file "``script.lua``" through the | |
37 **REST API**, use the following command:: | |
38 | |
39 $ curl -X POST http://localhost:8042/tools/execute-script --data-binary @script.lua | |
40 | |
41 Pay attention to the fact that, contrarily to the scripts installed | |
42 from the configuration file, the scripts installed through the REST | |
43 API are non-persistent: They are discarded after a restart of Orthanc, | |
44 which makes them useful for script prototyping. You can also interpret | |
45 a single Lua command through the REST API:: | |
46 | |
47 $ curl -X POST http://localhost:8042/tools/execute-script --data-binary "print(42)" | |
48 | |
49 *Note:* The ``--data-binary`` cURL option is used instead of | |
50 ``--data`` to prevent the interpretation of newlines by cURL, which is | |
51 `mandatory for the proper evaluation | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
357
diff
changeset
|
52 <https://stackoverflow.com/questions/3872427/how-to-send-line-break-with-curl>`__ |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
357
diff
changeset
|
53 of the possible comments inside the Lua script. |
0 | 54 |
55 Lua API | |
56 ------- | |
57 | |
58 | |
59 .. _lua-callbacks: | |
60 | |
61 Callbacks to react to events | |
62 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
63 | |
355
e4e9cca89c64
clarified mutual exclusion of Lua scripts callbacks.
David Wikler <david.wikler@ulb.ac.be>
parents:
319
diff
changeset
|
64 The Lua engine of Orthanc invokes the following callbacks that |
0 | 65 are triggered on various events. Here are the **generic events**: |
66 | |
67 * ``function Initialize()``: Invoked as soon as the Orthanc server is started. | |
68 * ``function Finalize()``: Invoked just before the Orthanc server is stopped. | |
69 | |
70 Some **permission-related events** allow to filter incoming requests: | |
71 | |
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
72 * ``function ReceivedInstanceFilter(dicom, origin, info)``: Invoked to |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
73 known whether an incoming DICOM instance should be |
0 | 74 accepted. :ref:`See this section <lua-filter-dicom>`. The ``origin`` |
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
75 parameter is :ref:`documented separately <lua-origin>`. The ``info`` |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
76 parameter contains additional information and was added in Orthanc |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
77 1.6.1. |
0 | 78 * ``function IncomingHttpRequestFilter(method, uri, ip, username, |
79 httpHeaders)``: Invoked to known whether a REST request should be | |
80 accepted. :ref:`See this section <lua-filter-rest>`. | |
81 | |
232 | 82 Some **job-related events** allow to react to :ref:`job <jobs>` completion/failure: |
83 | |
84 * ``function OnJobSubmitted(jobId)``: | |
85 Invoked when a new job has been submitted. Note that this does not | |
86 mean the the job execution has started. | |
87 * ``function OnJobFailure(jobId)``: | |
88 Invoked when a job has failed. | |
89 * ``function OnJobSuccess(jobId)``: | |
90 Invoked when a job has completed successfully. | |
91 | |
0 | 92 Some **DICOM-related events** allow to react to the reception of |
93 new medical images: | |
94 | |
95 * ``function OnStoredInstance(instanceId, tags, metadata, origin)``: | |
96 Invoked whenever a new instance has been stored into Orthanc. | |
97 This is especially useful for :ref:`lua-auto-routing`. The ``origin`` | |
98 parameter is :ref:`documented separately <lua-origin>`. | |
99 * ``function OnStablePatient(patientId, tags, metadata)``: Invoked | |
100 whenever a patient has not received any new instance for a certain | |
836 | 101 amount of time (cf. :ref:`stable resources <stable-resources>` |
102 and the option ``StableAge`` in the | |
0 | 103 :ref:`configuration file <configuration>`). The :ref:`identifier |
104 <orthanc-ids>` of the patient is provided, together with her DICOM | |
78 | 105 tags and her :ref:`metadata <metadata>`. |
0 | 106 * ``function OnStableSeries(seriesId, tags, metadata)``: Invoked |
107 whenever a series has not received any new instance for a certain | |
836 | 108 amount of time (cf. :ref:`stable resources <stable-resources>` |
109 and the option ``StableAge`` in the | |
110 :ref:`configuration file <configuration>`). | |
0 | 111 * ``function OnStableStudy(studyId, tags, metadata)``: Invoked |
112 whenever a study has not received any new instance for a certain | |
836 | 113 amount of time (cf. :ref:`stable resources <stable-resources>` |
114 and the option ``StableAge`` in the | |
115 :ref:`configuration file <configuration>`). | |
0 | 116 * ``function IncomingFindRequestFilter(source, origin)``: Invoked |
117 whenever Orthanc receives an incoming C-Find query through the DICOM | |
118 protocol. This allows to inspect the content of the C-Find query, | |
119 and possibly modify it if a patch is needed for some manufacturer. A | |
120 `sample script is available | |
449 | 121 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Resources/Samples/Lua/IncomingFindRequestFilter.lua>`__. |
0 | 122 |
319
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
123 Some other **resource-related events** are available: |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
124 |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
125 * ``function OnDeletedPatient(patientId)``: Invoked when a patient has |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
126 been removed from the Orthanc database (new in Orthanc 1.6.0). |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
127 * ``function OnDeletedStudy(studyId)``: Invoked when a study has been |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
128 removed from the Orthanc database (new in Orthanc 1.6.0). |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
129 * ``function OnDeletedSeries(seriesId)``: Invoked when a series has |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
130 been removed from the Orthanc database (new in Orthanc 1.6.0). |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
131 * ``function OnDeletedInstance(instanceId)``: Invoked when a instance |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
132 has been removed from the Orthanc database (new in Orthanc 1.6.0). |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
133 * ``function OnUpdatedPatient(patientId)``: Invoked when some metadata |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
134 or some attachment associated with the given patient has been |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
135 updated (new in Orthanc 1.6.0). |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
136 * ``function OnUpdatedStudy(studyId)``: Invoked when some metadata or |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
137 some attachment associated with the given study has been updated |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
138 (new in Orthanc 1.6.0). |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
139 * ``function OnUpdatedSeries(seriesId)``: Invoked when some metadata |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
140 or some attachment associated with the given series has been updated |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
141 (new in Orthanc 1.6.0). |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
142 * ``function OnUpdatedInstance(instanceId)``: Invoked when some |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
143 metadata or some attachment associated with the given instance has |
be69f8c86f56
Lua events for deleted/updated resources
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
283
diff
changeset
|
144 been updated (new in Orthanc 1.6.0). |
606
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
145 |
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
146 Furthermore, in versions of Orthanc <= 1.8.2, whenever a DICOM |
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
147 association is negotiated for C-Store SCP, several callbacks are |
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
148 successively invoked to specify which **transfer syntaxes** are |
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
149 accepted for the association. These callbacks are listed in `this |
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
150 sample script |
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
151 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.8.2/OrthancServer/Resources/Samples/Lua/TransferSyntaxEnable.lua>`__. |
2f000ee9b20d
removal of Lua callbacks for transfer syntaxes
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
449
diff
changeset
|
152 These callbacks were removed in Orthanc 1.9.0. |
0 | 153 |
357 | 154 If a callback is specified multiple times in separate scripts, the |
155 event handler of the latest loaded script is used. | |
0 | 156 |
912 | 157 Concurrency and deadlocks |
158 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
159 | |
160 Orthanc only implements a single Lua context. Therefore, all these | |
161 callbacks are guaranteed to be **invoked in mutual exclusion**. | |
162 This implies that Lua scripting in Orthanc does not support any | |
163 kind of concurrency but may also lead to some deadlocks. | |
164 | |
165 If a lua function (e.g. ``OnHeartBeat``) performs an HTTP call to an | |
166 external Rest API (e.g. ``http://myserver.com/orthanc_is_alive.php``) | |
167 which, in turn, calls the Orthanc Rest API (e.g. call ``http://orthanc:8042/system``), | |
168 odds are high that you meet a deadlock because Orthanc, when handling a | |
169 Rest API calls, may try to execute some Lua callbacks (e.g. ``IncomingHttpRequestFilter``) | |
170 while the Lua context is still blocked inside the ``OnHeartBeat`` function. | |
171 | |
172 To avoid deadlocks, always make sure to avoid such back-and-forth communications | |
173 or make sure they happen asynchronously: your webservice should call the | |
174 Orthanc Rest API after it has returned from the endpoint called by | |
175 ``OnHeartBeat``. | |
176 | |
0 | 177 |
178 .. _lua-rest: | |
179 | |
180 Calling the REST API of Orthanc | |
181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
182 | |
183 Lua scripts have :ref:`full access to the REST API <rest>` of Orthanc | |
184 through the following functions: | |
185 | |
252
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
186 * ``RestApiGet(uri, builtin, headers)`` |
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
187 * ``RestApiPost(uri, body, builtin, headers)`` |
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
188 * ``RestApiPut(uri, body, builtin, headers)`` |
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
189 * ``RestApiDelete(uri, builtin, headers)`` |
0 | 190 |
237 | 191 Here is a description of the parameters: |
235
17f8eda5fccb
Documented some parameter types, expected string formatting and added samples.
Tomas Zubiri <me@tomaszubiri.com>
parents:
191
diff
changeset
|
192 |
237 | 193 * ``uri`` specifies the resource being accessed |
194 (e.g. ``/instances``). It must not include the URL schema | |
195 (protocol), hostname or port. | |
0 | 196 |
237 | 197 * In the context of a POST or PUT request, ``body`` is a string |
198 containing the body of the request | |
199 (e.g. ``{"Keep":"StudyDate"}``). This string will often correspond | |
200 to a JSON-formatted version of a `Lua table | |
201 <http://lua-users.org/wiki/TablesTutorial>`__. The ``DumpJson()`` | |
202 function (see below) is very useful to achieve this conversion from | |
203 a Lua table to a plain string. | |
235
17f8eda5fccb
Documented some parameter types, expected string formatting and added samples.
Tomas Zubiri <me@tomaszubiri.com>
parents:
191
diff
changeset
|
204 |
237 | 205 * ``builtin`` is an optional Boolean that specifies whether the |
206 request targets only the built-in REST API of Orthanc (if set to | |
207 ``true``), or the full the REST API after being tainted by plugins | |
208 (if set to ``false``). | |
235
17f8eda5fccb
Documented some parameter types, expected string formatting and added samples.
Tomas Zubiri <me@tomaszubiri.com>
parents:
191
diff
changeset
|
209 |
252
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
210 * ``headers`` is an optional argument and was added in release |
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
211 1.5.7. It allows to provide the REST API endpoint with HTTP headers. |
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
212 |
237 | 213 .. highlight:: bash |
214 | |
215 For instance:: | |
216 | |
217 RestApiPost('/instances/5af318ac-78fb-47ff-b0b0-0df18b0588e0/anonymize', '{}') | |
218 | |
0 | 219 |
783 | 220 Instance modification/routing |
221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
222 | |
804
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
223 The Lua engine offers the following special functions to modify and |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
224 route DICOM instances: |
783 | 225 |
226 * ``ModifyInstance(instanceId, replacements, removals, removePrivateTags)`` | |
804
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
227 modifies an instance. |
783 | 228 * ``SendToModality(instanceId, modality)`` performs a C-Store to the |
804
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
229 target modality. |
783 | 230 * ``SendToPeer(instanceId, peer)`` sends the instance to a remote Orthanc peer. |
231 * ``Delete(instanceId)`` deletes the instance. | |
232 | |
804
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
233 :ref:`See this section <lua-auto-routing>` for examples. As can be |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
234 seen in those examples, these special functions can be chained |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
235 together, although they return no explicit value. |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
236 |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
237 Note that these special functions should only be used for basic use |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
238 cases: Calls to the REST API :ref:`should always be favored for |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
239 auto-routing <lua-auto-routing-better>`. |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
240 |
783 | 241 |
0 | 242 General-purpose functions |
243 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
244 | |
245 The Lua engine of Orthanc contain several general-purpose ancillary | |
246 functions: | |
247 | |
248 * ``PrintRecursive(v)`` recursively prints the content of a `Lua table | |
249 <http://www.lua.org/pil/2.5.html>`__ to the log file of Orthanc. | |
250 * ``ParseJson(s)`` converts a string encoded in the `JSON format | |
251 <https://en.wikipedia.org/wiki/JSON>`__ to a Lua table. | |
252 * ``DumpJson(v, keepStrings)`` encodes a Lua table as a JSON string. | |
253 Setting the optional argument ``keepStrings`` (available from | |
254 release 0.9.5) to ``true`` prevents the automatic conversion of | |
255 strings to integers. | |
256 * ``GetOrthancConfiguration()`` returns a Lua table containing the | |
257 content of the :ref:`configuration files <configuration>` of | |
258 Orthanc. | |
259 | |
260 | |
261 Similarly to the functions to :ref:`call the REST API of Orthanc | |
262 <lua-rest>`, several functions are available to make generic HTTP | |
263 requests to Web services: | |
264 | |
90 | 265 * ``HttpGet(url, headers)`` |
266 * ``HttpPost(url, body, headers)`` | |
267 * ``HttpPut(url, body, headers)`` | |
268 * ``HttpDelete(url, headers)`` | |
0 | 269 * ``SetHttpCredentials(username, password)`` can be used to setup the |
270 HTTP credentials. | |
864 | 271 * ``SetHttpTimeout(timeout)`` can be used to configure a timeout (in seconds). |
272 When contacting an external webservice, it is recommended to configure a very | |
273 short timeout not to lock the Lua context for too long. No other Lua callbacks | |
274 may be run at the same time which may have a significant impact on Orthanc | |
275 responsivness in general. | |
276 | |
0 | 277 |
252
eaad8233e474
HTTP headers available for the RestApiXXX Lua function
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
237
diff
changeset
|
278 The ``headers`` argument is optional and was added in release |
91 | 279 1.2.1. It allows to set the HTTP headers for the HTTP client request. |
0 | 280 |
283 | 281 Example:: |
282 | |
283 local preview = RestApiGet('/instances/' .. instanceId .. '/preview') | |
284 local headers = { | |
285 ["content-type"] = "image/png", | |
286 } | |
864 | 287 |
288 SetHttpCredentials('user', 'pwd') | |
289 SetHttpTimeout(1) | |
283 | 290 HttpPost("http://localhost/my-web-service/instance-preview", preview, headers) |
291 | |
0 | 292 .. _lua-origin: |
293 | |
294 Origin of the instances | |
295 ^^^^^^^^^^^^^^^^^^^^^^^ | |
296 | |
297 Whenever Orthanc decides whether it should should store a new instance | |
298 (cf. the ``ReceivedInstanceFilter()`` callback), or whenever it has | |
299 actually stored a new instance (cf. the ``OnStoredInstance`` | |
300 callback), an ``origin`` parameter is provided. This parameter is a | |
301 `Lua table <http://www.lua.org/pil/2.5.html>`__ that describes from | |
302 which Orthanc subsystem the new instance comes from. | |
303 | |
304 There are 4 possible subsystems, that can be distinguished according | |
305 to the value of ``origin["RequestOrigin"]``: | |
306 | |
307 * ``RestApi``: The instance originates from some HTTP request to the REST | |
308 API. In this case, the ``RemoteIp`` and ``Username`` fields are | |
309 available in ``origin``. They respectively describe the IP address | |
310 of the HTTP client, and the username that was used for HTTP | |
311 authentication (as defined in the ``RegisteredUsers`` | |
312 :ref:`configuration variable <configuration>`). | |
313 * ``DicomProtocol``: The instance originates from a DICOM C-Store. | |
314 The fields ``RemoteIp``, ``RemoteAet`` and ``CalledAet`` | |
315 respectively provide the IP address of the DICOM SCU (client), the | |
316 application entity title of the DICOM SCU client, and the | |
317 application entity title of the Orthanc SCP server. The | |
318 ``CalledAet`` can be used for :ref:`advanced auto-routing scenarios | |
319 <lua-auto-routing>`, when a single instance of Orthanc acts as a | |
320 proxy for several DICOM SCU clients. | |
321 * ``Lua``: The instance originates from a Lua script. | |
322 * ``Plugins``: The instance originates from a plugin. | |
323 | |
324 | |
325 .. _lua-filter-dicom: | |
326 | |
75 | 327 Filtering incoming DICOM instances |
0 | 328 ---------------------------------- |
329 | |
330 .. highlight:: lua | |
331 | |
332 Each time a DICOM instance is received by Orthanc (either through the | |
333 DICOM protocol or through the REST API), the | |
334 ``ReceivedInstanceFilter()`` Lua function is invoked. If this callback | |
335 returns ``true``, the instance is accepted for storage. If it returns | |
336 ``false``, the instance is discarded. This mechanism can be used to | |
337 filter the incoming DICOM instances. Here is an example of a Lua | |
338 filter that only allows incoming instances of MR modality:: | |
339 | |
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
340 function ReceivedInstanceFilter(dicom, origin, info) |
0 | 341 -- Only allow incoming MR images |
342 if dicom.Modality == 'MR' then | |
343 return true | |
344 else | |
345 return false | |
346 end | |
347 end | |
348 | |
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
349 The argument ``dicom`` corresponds to a `Lua table |
0 | 350 <http://www.lua.org/pil/2.5.html>`__ (i.e. an associative array) that |
351 contains the DICOM tags of the incoming instance. For debugging | |
352 purpose, you can print this structure as follows:: | |
353 | |
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
354 function ReceivedInstanceFilter(dicom, origin, info) |
0 | 355 PrintRecursive(dicom) |
356 -- Accept all incoming instances (default behavior) | |
357 return true | |
358 end | |
359 | |
360 The argument ``origin`` is :ref:`documented separately <lua-origin>`. | |
361 | |
387
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
362 The argument ``info`` was introduced in Orthanc 1.6.1. It contains |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
363 some additional information about the received DICOM instance, |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
364 notably: |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
365 |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
366 * ``HasPixelData`` is ``true`` iff. the Pixel Data (7FE0,0010) tag is |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
367 present. |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
368 * ``TransferSyntaxUID`` contains the transfer syntax UID of the |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
369 dataset of the instance (if applicable). |
1974913fd28a
documenting "info" argument in Lua ReceivedInstanceFilter()
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
370 |
0 | 371 |
372 .. _lua-filter-rest: | |
373 | |
75 | 374 Filtering incoming REST requests |
0 | 375 -------------------------------- |
376 | |
377 .. highlight:: lua | |
378 | |
379 Lua scripting can be used to control the access to the various URI of | |
380 the REST API. Each time an incoming HTTP request is received, the | |
381 ``IncomingHttpRequestFilter()`` Lua function is called. The access to | |
382 the resource is granted if and only if this callback script returns | |
383 ``true``. | |
384 | |
385 This mechanism can be used to implement fine-grained `access control | |
25 | 386 lists <https://en.wikipedia.org/wiki/Access_control_list>`__. Here is |
0 | 387 an example of a Lua script that limits POST, PUT and DELETE requests |
388 to an user that is called "admin":: | |
389 | |
390 function IncomingHttpRequestFilter(method, uri, ip, username, httpHeaders) | |
391 -- Only allow GET requests for non-admin users | |
392 | |
393 if method == 'GET' then | |
394 return true | |
395 elseif username == 'admin' then | |
396 return true | |
397 else | |
398 return false | |
399 end | |
400 end | |
401 | |
402 Here is a description of the arguments of this Lua callback: | |
403 | |
404 * ``method``: The HTTP method (GET, POST, PUT or DELETE). | |
405 * ``uri``: The path to the resource (e.g. ``/tools/generate-uid``). | |
406 * ``ip``: The IP address of the host that has issued the HTTP request (e.g. ``127.0.0.1``). | |
407 * ``username``: If HTTP Basic Authentication is enabled in the | |
408 :ref:`configuration file <configuration>`, the name of the user that | |
409 has issued the HTTP request (as defined in the ``RegisteredUsers`` | |
410 configuration variable). If the authentication is disabled, this | |
411 argument is set to the empty string. | |
412 * ``httpHeaders``: The HTTP headers of the incoming request. This | |
413 argument is available since Orthanc 1.0.1. It is useful if the | |
414 authentication should be achieved through tokens, for instance | |
415 against a `LDAP | |
416 <https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol>`__ | |
417 or `OAuth2 <https://en.wikipedia.org/wiki/OAuth>`__ server. | |
418 | |
419 | |
420 .. _lua-auto-routing: | |
421 | |
75 | 422 Auto-routing of DICOM images |
0 | 423 ---------------------------- |
424 | |
425 .. highlight:: lua | |
426 | |
427 Since release 0.8.0, the routing of DICOM flows can be very easily | |
428 automated with Orthanc. All you have to do is to declare your | |
429 destination modality in the :ref:`configuration file <configuration>` | |
430 (section ``DicomModalities``), then to create and install a Lua | |
431 script. For instance, here is a sample script:: | |
432 | |
433 function OnStoredInstance(instanceId, tags, metadata) | |
434 Delete(SendToModality(instanceId, 'sample')) | |
435 end | |
436 | |
437 If this script is loaded into Orthanc, whenever a new DICOM instance | |
438 is received by Orthanc, it will be routed to the modality whose | |
439 symbolic name is ``sample`` (through a Store-SCU command), then it | |
440 will be removed from Orthanc. In other words, this is a **one-liner | |
441 script to implement DICOM auto-routing**. | |
442 | |
443 Very importantly, thanks to this feature, you do not have to use the | |
444 REST API or to create external scripts in order to automate simple | |
445 imaging flows. The scripting engine is entirely contained inside the | |
446 Orthanc core system. | |
447 | |
448 Thanks to Lua expressiveness, you can also implement conditional | |
449 auto-routing. For instance, if you wish to route only patients whose | |
450 name contains "David", you would simply write:: | |
451 | |
452 function OnStoredInstance(instanceId, tags, metadata) | |
453 -- Extract the value of the "PatientName" DICOM tag | |
454 local patientName = string.lower(tags['PatientName']) | |
455 | |
456 if string.find(patientName, 'david') ~= nil then | |
457 -- Only route patients whose name contains "David" | |
458 Delete(SendToModality(instanceId, 'sample')) | |
459 | |
460 else | |
461 -- Delete the patients that are not called "David" | |
462 Delete(instanceId) | |
463 end | |
464 end | |
465 | |
466 Besides ``SendToModality()``, a mostly identical function with the | |
467 same arguments called ``SendToPeer()`` can be used to route instances | |
468 to :ref:`Orthanc peers <peers>`. It is also possible to modify the | |
469 received instances before routing them. For instance, here is how you | |
470 would replace the ``StationName`` DICOM tag:: | |
471 | |
472 function OnStoredInstance(instanceId, tags, metadata) | |
473 -- Ignore the instances that result from a modification to avoid | |
474 -- infinite loops | |
475 if (metadata['ModifiedFrom'] == nil and | |
476 metadata['AnonymizedFrom'] == nil) then | |
477 | |
478 -- The tags to be replaced | |
479 local replace = {} | |
480 replace['StationName'] = 'My Medical Device' | |
481 | |
482 -- The tags to be removed | |
483 local remove = { 'MilitaryRank' } | |
484 | |
485 -- Modify the instance, send it, then delete the modified instance | |
486 Delete(SendToModality(ModifyInstance(instanceId, replace, remove, true), 'sample')) | |
487 | |
488 -- Delete the original instance | |
489 Delete(instanceId) | |
490 end | |
491 end | |
492 | |
493 | |
804
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
494 .. _lua-auto-routing-better: |
e7de02760b59
fix revision 783, to solve bug #203
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
783
diff
changeset
|
495 |
75 | 496 Important remarks about auto-routing |
497 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
19
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
498 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
499 The ``SendToModality()``, ``SendToPeer()``, ``ModifyInstance()`` and |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
500 ``Delete()`` functions are for the most basic cases of auto-routing |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
501 (implying a single DICOM instance, and possibly a basic modification |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
502 of this instance). The ``ModifyInstance()`` function `could also lead |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
503 to problems |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
504 <https://groups.google.com/d/msg/orthanc-users/hmv2y-LgKm8/oMAuGJWMBgAJ>`__ |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
505 if it deals with tags wrongly interpreted as numbers by Lua. |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
506 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
507 For more evolved auto-routing scenarios, remember that Lua scripts |
191 | 508 :ref:`have full access to the REST API of Orthanc <lua-rest>`. This is |
19
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
509 illustrated by the ``AutoroutingModification.lua`` sample available in |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
510 the source distribution of Orthanc:: |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
511 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
512 function OnStoredInstance(instanceId, tags, metadata, origin) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
513 -- Ignore the instances that result from the present Lua script to |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
514 -- avoid infinite loops |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
515 if origin['RequestOrigin'] ~= 'Lua' then |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
516 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
517 -- The tags to be replaced |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
518 local replace = {} |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
519 replace['StationName'] = 'My Medical Device' |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
520 replace['0031-1020'] = 'Some private tag' |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
521 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
522 -- The tags to be removed |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
523 local remove = { 'MilitaryRank' } |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
524 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
525 -- Modify the instance |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
526 local command = {} |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
527 command['Replace'] = replace |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
528 command['Remove'] = remove |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
529 local modifiedFile = RestApiPost('/instances/' .. instanceId .. '/modify', DumpJson(command, true)) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
530 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
531 -- Upload the modified instance to the Orthanc database so that |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
532 -- it can be sent by Orthanc to other modalities |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
533 local modifiedId = ParseJson(RestApiPost('/instances/', modifiedFile)) ['ID'] |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
534 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
535 -- Send the modified instance to another modality |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
536 RestApiPost('/modalities/sample/store', modifiedId) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
537 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
538 -- Delete the original and the modified instances |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
539 RestApiDelete('/instances/' .. instanceId) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
540 RestApiDelete('/instances/' .. modifiedId) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
541 end |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
542 end |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
543 |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
544 Also note that :ref:`other callbacks are available <lua-callbacks>` |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
545 (``OnStablePatient()``, ``OnStableStudy()`` and ``OnStableSeries()``) |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
546 to react to other events than the reception of a single instance |
c98317fedf87
note about autorouting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
547 with ``OnStoredInstance()``. |
75 | 548 |
99
e83da2f99e45
added 'troubleshooting C-Find queries' in the worklist section
amazy
parents:
91
diff
changeset
|
549 .. _lua-fix-cfind: |
75 | 550 |
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
551 Fixing C-Find requests |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
552 ---------------------- |
75 | 553 |
554 :ref:`C-Find requests <dicom-find>` are sometimes interpreted | |
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
555 differently by different DICOM servers (e.g. the ``*`` wildcard, as |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
556 `reported by users |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
557 <https://groups.google.com/d/msg/orthanc-users/3g7V7kqr3g0/IREL88RWAwAJ>`__), |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
558 and sometimes a querying modality might set unexpected DICOM tags |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
559 (cf. `this real-world example |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
560 <https://groups.google.com/d/msg/orthanc-users/PLWKqVVaXLs/n_0x4vKhAgAJ>`__). In |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
561 such situations, it is possible to dynamically fix incoming or |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
562 outgoing C-Find queries using a Lua script. |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
563 |
165
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
564 Sanitizing incoming C-Find requests can be done by implementing the |
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
565 ``IncomingFindRequestFilter(query, origin)`` callback that is called |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
566 whenever the Orthanc C-Find SCP is queried by a remote modality. For |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
567 instance, here is Lua script to remove a private tag that is specified |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
568 by some manufacturer:: |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
569 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
570 function IncomingFindRequestFilter(query, origin) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
571 -- First display the content of the C-Find query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
572 PrintRecursive(query) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
573 PrintRecursive(origin) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
574 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
575 -- Remove the "PrivateCreator" tag from the query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
576 local v = query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
577 v['5555,0010'] = nil |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
578 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
579 return v |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
580 end |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
581 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
582 The ``origin`` argument contains information about which modality has |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
583 issued the request. |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
584 |
443
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
585 Note that this callback allows you to modify the incoming request |
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
586 but will not modify the list of tags that Orthanc will return. |
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
587 |
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
588 Also note that the ``IncomingFindRequestFilter`` callback is not applied to |
165
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
589 C-Find requests targeting :ref:`modality worklists |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
590 <worklists-plugin>`. Since Orthanc 1.4.2, the corresponding |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
591 ``IncomingWorklistRequestFilter`` callback can be used to sanitize |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
592 C-FIND requests against worklists:: |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
593 |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
594 function IncomingWorklistRequestFilter(query, origin) |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
595 PrintRecursive(query) |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
596 PrintRecursive(origin) |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
597 |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
598 -- Implements the same behavior as the "FilterIssuerAet" |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
599 -- option of the sample worklist plugin |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
600 query['0040,0100'][1]['0040,0001'] = origin['RemoteAet'] |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
601 |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
602 return query |
b879a6274065
IncomingWorklistRequestFilter
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
105
diff
changeset
|
603 end |
105
268ec482f051
IncomingFindRequestFilter not applied to worklist plugin
amazy
parents:
99
diff
changeset
|
604 |
443
c66d8b7b1a13
more info about IncomingFindRequestFilter
Alain Mazy <alain@mazy.be>
parents:
387
diff
changeset
|
605 |
77
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
606 Similarly, the callback ``OutgoingFindRequestFilter(query, modality)`` |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
607 is invoked whenever Orthanc acts as a C-Find SCU, which gives the |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
608 opportunity to dynamically fix outgoing C-Find requests before they |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
609 are actually sent to the queried modality. For instance, here is a |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
610 sample Lua callback that would replace asterisk wildcards (i.e. ``*``) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
611 by an empty string for any query/retrieve issued by Orthanc (including |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
612 from Orthanc Explorer):: |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
613 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
614 function OutgoingFindRequestFilter(query, modality) |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
615 for key, value in pairs(query) do |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
616 if value == '*' then |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
617 query[key] = '' |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
618 end |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
619 end |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
620 |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
621 return query |
48c7d2eb98da
Fixing C-Find requests
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
622 end |
668 | 623 |
624 | |
864 | 625 HeartBeat |
626 --------- | |
627 | |
628 .. highlight:: lua | |
629 | |
630 Starting from Orthanc 1.11.1, one can run a Lua callback at regular | |
631 interval. This interval is defined in the ``LuaHeartBeatPeriod`` | |
632 configuration:: | |
633 | |
634 function OnHeartBeat() | |
635 | |
636 -- ping a webservice to notify that Orthanc is still alive | |
637 SetHttpCredentials('user', 'pwd') | |
638 SetHttpTimeout(1) | |
639 HttpPost("http://localhost/my-web-service/still-alive", "my-id", {}) | |
640 | |
641 end | |
642 | |
668 | 643 .. _lua-external-modules: |
644 | |
645 Using external modules | |
646 ---------------------- | |
647 | |
648 Starting with Orthanc 1.3.2, it is possible to use external Lua | |
649 modules if Orthanc was compiled with the ``-DENABLE_LUA_MODULES=ON`` | |
650 while invoking CMake. | |
651 | |
652 Importantly, the modules and the Orthanc server must use the same | |
653 version of Lua for external modules to be properly loaded. | |
654 | |
655 Check out the Orthanc Users forum for old discussions about this | |
656 topic: `reference 1 | |
657 <https://groups.google.com/g/orthanc-users/c/BXfmwU786B0/m/M47slt5GFwAJ>`__, | |
658 `reference 2 | |
659 <https://groups.google.com/g/orthanc-users/c/BXfmwU786B0/m/qpVe8UvGAwAJ>`__, | |
660 `reference 3 | |
661 <https://groups.google.com/g/orthanc-users/c/LDAN5jA0X8M/m/4zrk0_AaBAAJ>`__. |