annotate Sphinx/source/users/lua.rst @ 1113:a588960a72e5 default tip

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