orthanc-book: Sphinx/source/users/lua.rst annotate

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 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
449 2922fb1bd65e fix links Sebastien Jodogne <s.jodogne@gmail.com> parents: 443 diff changeset	16 <https://hg.orthanc-server.com/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
846 2f8ee0aef0a6 added uclouvain Sebastien Jodogne <s.jodogne@gmail.com> parents: 836 diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	21
75 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	22 Installing a Lua script
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	23 -----------------------
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 .. highlight:: bash
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	26
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	27 A custom Lua script can be installed either by the :ref:`configuration
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	28 file <configuration>`, or by uploading it
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	29 through the :ref:`REST API <rest-samples>`.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	30
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	31 To install it by the configuration file method, you just have to
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	32 specify the path to the file containing the Lua script in the
357 6b432ce3a56e typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 355 diff changeset	33 ``LuaScripts`` variable. A comma-separated list of paths can be
6b432ce3a56e typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 355 diff changeset	34 specified to install multiple scripts.
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	35
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	36 To upload a script stored in the file "``script.lua``" through the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	37 REST API, use the following command::
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	38
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	39 $ 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	40
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	41 Pay attention to the fact that, contrarily to the scripts installed
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	42 from the configuration file, the scripts installed through the REST
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	43 API are non-persistent: They are discarded after a restart of Orthanc,
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	44 which makes them useful for script prototyping. You can also interpret
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	45 a single Lua command through the REST API::
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	46
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	47 $ 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	48
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	49 Note: The ``--data-binary`` cURL option is used instead of
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	50 ``--data`` to prevent the interpretation of newlines by cURL, which is
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	54
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	55 Lua API
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	56 -------
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 .. _lua-callbacks:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	60
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	61 Callbacks to react to events
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	62 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	65 are triggered on various events. Here are the generic events:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	66
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	67 * ``function Initialize()``: Invoked as soon as the Orthanc server is started.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	68 * ``function Finalize()``: Invoked just before the Orthanc server is stopped.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	69
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	70 Some permission-related events allow to filter incoming requests:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	78 * ``function IncomingHttpRequestFilter(method, uri, ip, username,
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	79 httpHeaders)``: Invoked to known whether a REST request should be
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	80 accepted. :ref:`See this section <lua-filter-rest>`.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	81
232 15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	82 Some job-related events allow to react to :ref:`job <jobs>` completion/failure:
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	83
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	84 * ``function OnJobSubmitted(jobId)``:
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	85 Invoked when a new job has been submitted. Note that this does not
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	86 mean the the job execution has started.
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	87 * ``function OnJobFailure(jobId)``:
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	88 Invoked when a job has failed.
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	89 * ``function OnJobSuccess(jobId)``:
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	90 Invoked when a job has completed successfully.
15823481cf8f added Jobs Lua callback amazy parents: 191 diff changeset	91
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	92 Some DICOM-related events allow to react to the reception of
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	93 new medical images:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	94
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	95 * ``function OnStoredInstance(instanceId, tags, metadata, origin)``:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	96 Invoked whenever a new instance has been stored into Orthanc.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	97 This is especially useful for :ref:`lua-auto-routing`. The ``origin``
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	98 parameter is :ref:`documented separately <lua-origin>`.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	99 * ``function OnStablePatient(patientId, tags, metadata)``: Invoked
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	100 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	101 amount of time (cf. :ref:`stable resources <stable-resources>`
a9c35bf108fa stable age ref Alain Mazy <am@osimis.io> parents: 804 diff changeset	102 and the option ``StableAge`` in the
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	103 :ref:`configuration file <configuration>`). The :ref:`identifier
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	104 <orthanc-ids>` of the patient is provided, together with her DICOM
78 d6bd1dd820e5 metadata Sebastien Jodogne <s.jodogne@gmail.com> parents: 77 diff changeset	105 tags and her :ref:`metadata <metadata>`.
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	106 * ``function OnStableSeries(seriesId, tags, metadata)``: Invoked
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	107 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	108 amount of time (cf. :ref:`stable resources <stable-resources>`
a9c35bf108fa stable age ref Alain Mazy <am@osimis.io> parents: 804 diff changeset	109 and the option ``StableAge`` in the
a9c35bf108fa stable age ref Alain Mazy <am@osimis.io> parents: 804 diff changeset	110 :ref:`configuration file <configuration>`).
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	111 * ``function OnStableStudy(studyId, tags, metadata)``: Invoked
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	112 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	113 amount of time (cf. :ref:`stable resources <stable-resources>`
a9c35bf108fa stable age ref Alain Mazy <am@osimis.io> parents: 804 diff changeset	114 and the option ``StableAge`` in the
a9c35bf108fa stable age ref Alain Mazy <am@osimis.io> parents: 804 diff changeset	115 :ref:`configuration file <configuration>`).
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	116 * ``function IncomingFindRequestFilter(source, origin)``: Invoked
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	117 whenever Orthanc receives an incoming C-Find query through the DICOM
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	118 protocol. This allows to inspect the content of the C-Find query,
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	119 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	120 `sample script is available
449 2922fb1bd65e fix links Sebastien Jodogne <s.jodogne@gmail.com> parents: 443 diff changeset	121 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Resources/Samples/Lua/IncomingFindRequestFilter.lua>`__.
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	153
357 6b432ce3a56e typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 355 diff changeset	154 If a callback is specified multiple times in separate scripts, the
6b432ce3a56e typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 355 diff changeset	155 event handler of the latest loaded script is used.
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	156
912 dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	157 Concurrency and deadlocks
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	158 ^^^^^^^^^^^^^^^^^^^^^^^^^
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 Orthanc only implements a single Lua context. Therefore, all these
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	161 callbacks are guaranteed to be invoked in mutual exclusion.
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	162 This implies that Lua scripting in Orthanc does not support any
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	163 kind of concurrency but may also lead to some deadlocks.
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	164
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	165 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	166 external Rest API (e.g. ``http://myserver.com/orthanc_is_alive.php``)
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	167 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	168 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	169 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	170 while the Lua context is still blocked inside the ``OnHeartBeat`` function.
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	171
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	172 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	173 or make sure they happen asynchronously: your webservice should call the
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	174 Orthanc Rest API after it has returned from the endpoint called by
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	175 ``OnHeartBeat``.
dbe3fd98beb0 lua deadlocks Alain Mazy <am@osimis.io> parents: 864 diff changeset	176
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	177
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	178 .. _lua-rest:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	179
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	180 Calling the REST API of Orthanc
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
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	183 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	184 through the following functions:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	190
237 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	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 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	193 * ``uri`` specifies the resource being accessed
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	194 (e.g. ``/instances``). It must not include the URL schema
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	195 (protocol), hostname or port.
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	196
237 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	197 * In the context of a POST or PUT request, ``body`` is a string
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	198 containing the body of the request
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	199 (e.g. ``{"Keep":"StudyDate"}``). This string will often correspond
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	200 to a JSON-formatted version of a `Lua table
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	201 <http://lua-users.org/wiki/TablesTutorial>`__. The ``DumpJson()``
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	202 function (see below) is very useful to achieve this conversion from
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	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 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	205 * ``builtin`` is an optional Boolean that specifies whether the
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	206 request targets only the built-in REST API of Orthanc (if set to
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	207 ``true``), or the full the REST API after being tainted by plugins
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	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 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	213 .. highlight:: bash
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	214
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	215 For instance::
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	216
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	217 RestApiPost('/instances/5af318ac-78fb-47ff-b0b0-0df18b0588e0/anonymize', '{}')
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	218
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	219
783 0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	220 Instance modification/routing
0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	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 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 * ``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 0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	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 0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	230 * ``SendToPeer(instanceId, peer)`` sends the instance to a remote Orthanc peer.
0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	231 * ``Delete(instanceId)`` deletes the instance.
0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	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 0fbe952b2906 list more lua functions Alain Mazy <am@osimis.io> parents: 668 diff changeset	241
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	242 General-purpose functions
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	243 ^^^^^^^^^^^^^^^^^^^^^^^^^
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	244
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	245 The Lua engine of Orthanc contain several general-purpose ancillary
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	246 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 * ``PrintRecursive(v)`` recursively prints the content of a `Lua table
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	249 <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	250 * ``ParseJson(s)`` converts a string encoded in the `JSON format
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	251 <https://en.wikipedia.org/wiki/JSON>`__ to a Lua table.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	252 * ``DumpJson(v, keepStrings)`` encodes a Lua table as a JSON string.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	253 Setting the optional argument ``keepStrings`` (available from
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	254 release 0.9.5) to ``true`` prevents the automatic conversion of
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	255 strings to integers.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	256 * ``GetOrthancConfiguration()`` returns a Lua table containing the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	257 content of the :ref:`configuration files <configuration>` of
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	258 Orthanc.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	259
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	260
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	261 Similarly to the functions to :ref:`call the REST API of Orthanc
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	262 <lua-rest>`, several functions are available to make generic HTTP
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	263 requests to Web services:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	264
90 e6a15f619786 added headers in HttpPost/Delete/Get/Put amazy parents: 78 diff changeset	265 * ``HttpGet(url, headers)``
e6a15f619786 added headers in HttpPost/Delete/Get/Put amazy parents: 78 diff changeset	266 * ``HttpPost(url, body, headers)``
e6a15f619786 added headers in HttpPost/Delete/Get/Put amazy parents: 78 diff changeset	267 * ``HttpPut(url, body, headers)``
e6a15f619786 added headers in HttpPost/Delete/Get/Put amazy parents: 78 diff changeset	268 * ``HttpDelete(url, headers)``
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	269 * ``SetHttpCredentials(username, password)`` can be used to setup the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	270 HTTP credentials.
864 035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	271 * ``SetHttpTimeout(timeout)`` can be used to configure a timeout (in seconds).
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	272 When contacting an external webservice, it is recommended to configure a very
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	273 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	274 may be run at the same time which may have a significant impact on Orthanc
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	275 responsivness in general.
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	276
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 025744919357 additional info Sebastien Jodogne <s.jodogne@gmail.com> parents: 90 diff changeset	279 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	280
283 443af82172b0 added a sample of headers for HttpPost lua method amazy parents: 252 diff changeset	281 Example::
443af82172b0 added a sample of headers for HttpPost lua method amazy parents: 252 diff changeset	282
443af82172b0 added a sample of headers for HttpPost lua method amazy parents: 252 diff changeset	283 local preview = RestApiGet('/instances/' .. instanceId .. '/preview')
443af82172b0 added a sample of headers for HttpPost lua method amazy parents: 252 diff changeset	284 local headers = {
443af82172b0 added a sample of headers for HttpPost lua method amazy parents: 252 diff changeset	285 ["content-type"] = "image/png",
443af82172b0 added a sample of headers for HttpPost lua method amazy parents: 252 diff changeset	286 }
864 035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	287
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	288 SetHttpCredentials('user', 'pwd')
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	289 SetHttpTimeout(1)
283 443af82172b0 added a sample of headers for HttpPost lua method amazy parents: 252 diff changeset	290 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	291
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	292 .. _lua-origin:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	293
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	294 Origin of the instances
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	295 ^^^^^^^^^^^^^^^^^^^^^^^
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	296
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	297 Whenever Orthanc decides whether it should should store a new instance
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	298 (cf. the ``ReceivedInstanceFilter()`` callback), or whenever it has
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	299 actually stored a new instance (cf. the ``OnStoredInstance``
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	300 callback), an ``origin`` parameter is provided. This parameter is a
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	301 `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	302 which Orthanc subsystem the new instance comes from.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	303
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	304 There are 4 possible subsystems, that can be distinguished according
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	305 to the value of ``origin["RequestOrigin"]``:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	306
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	307 * ``RestApi``: The instance originates from some HTTP request to the REST
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	308 API. In this case, the ``RemoteIp`` and ``Username`` fields are
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	309 available in ``origin``. They respectively describe the IP address
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	310 of the HTTP client, and the username that was used for HTTP
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	311 authentication (as defined in the ``RegisteredUsers``
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	312 :ref:`configuration variable <configuration>`).
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	313 * ``DicomProtocol``: The instance originates from a DICOM C-Store.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	314 The fields ``RemoteIp``, ``RemoteAet`` and ``CalledAet``
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	315 respectively provide the IP address of the DICOM SCU (client), the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	316 application entity title of the DICOM SCU client, and the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	317 application entity title of the Orthanc SCP server. The
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	318 ``CalledAet`` can be used for :ref:`advanced auto-routing scenarios
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	319 <lua-auto-routing>`, when a single instance of Orthanc acts as a
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	320 proxy for several DICOM SCU clients.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	321 * ``Lua``: The instance originates from a Lua script.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	322 * ``Plugins``: The instance originates from a plugin.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	323
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	324
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	325 .. _lua-filter-dicom:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	326
75 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	327 Filtering incoming DICOM instances
0 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
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	330 .. highlight:: lua
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	331
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	332 Each time a DICOM instance is received by Orthanc (either through the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	333 DICOM protocol or through the REST API), the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	334 ``ReceivedInstanceFilter()`` Lua function is invoked. If this callback
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	335 returns ``true``, the instance is accepted for storage. If it returns
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	336 ``false``, the instance is discarded. This mechanism can be used to
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	337 filter the incoming DICOM instances. Here is an example of a Lua
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	338 filter that only allows incoming instances of MR modality::
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	341 -- Only allow incoming MR images
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	342 if dicom.Modality == 'MR' then
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	343 return true
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	344 else
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	345 return false
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	346 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	347 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	350 <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	351 contains the DICOM tags of the incoming instance. For debugging
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	352 purpose, you can print this structure as follows::
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	355 PrintRecursive(dicom)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	356 -- Accept all incoming instances (default behavior)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	357 return true
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	358 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	359
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	360 The argument ``origin`` is :ref:`documented separately <lua-origin>`.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	371
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	372 .. _lua-filter-rest:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	373
75 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	374 Filtering incoming REST requests
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
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	377 .. highlight:: lua
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	378
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	379 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	380 the REST API. Each time an incoming HTTP request is received, the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	381 ``IncomingHttpRequestFilter()`` Lua function is called. The access to
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	382 the resource is granted if and only if this callback script returns
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	383 ``true``.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	384
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	385 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	386 lists <https://en.wikipedia.org/wiki/Access_control_list>`__. Here is
0 901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	387 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	388 to an user that is called "admin"::
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	389
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	390 function IncomingHttpRequestFilter(method, uri, ip, username, httpHeaders)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	391 -- Only allow GET requests for non-admin users
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	392
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	393 if method == 'GET' then
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	394 return true
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	395 elseif username == 'admin' then
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	396 return true
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	397 else
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	398 return false
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	399 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	400 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	401
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	402 Here is a description of the arguments of this Lua callback:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	403
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	404 * ``method``: The HTTP method (GET, POST, PUT or DELETE).
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	405 * ``uri``: The path to the resource (e.g. ``/tools/generate-uid``).
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	406 * ``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	407 * ``username``: If HTTP Basic Authentication is enabled in the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	408 :ref:`configuration file <configuration>`, the name of the user that
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	409 has issued the HTTP request (as defined in the ``RegisteredUsers``
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	410 configuration variable). If the authentication is disabled, this
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	411 argument is set to the empty string.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	412 * ``httpHeaders``: The HTTP headers of the incoming request. This
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	413 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	414 authentication should be achieved through tokens, for instance
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	415 against a `LDAP
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	416 <https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol>`__
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	417 or `OAuth2 <https://en.wikipedia.org/wiki/OAuth>`__ server.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	418
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	419
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	420 .. _lua-auto-routing:
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	421
75 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	422 Auto-routing of DICOM images
0 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
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	425 .. highlight:: lua
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	426
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	427 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	428 automated with Orthanc. All you have to do is to declare your
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	429 destination modality in the :ref:`configuration file <configuration>`
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	430 (section ``DicomModalities``), then to create and install a Lua
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	431 script. For instance, here is a sample script::
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	432
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	433 function OnStoredInstance(instanceId, tags, metadata)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	434 Delete(SendToModality(instanceId, 'sample'))
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	435 end
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 If this script is loaded into Orthanc, whenever a new DICOM instance
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	438 is received by Orthanc, it will be routed to the modality whose
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	439 symbolic name is ``sample`` (through a Store-SCU command), then it
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	440 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	441 script to implement DICOM auto-routing**.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	442
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	443 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	444 REST API or to create external scripts in order to automate simple
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	445 imaging flows. The scripting engine is entirely contained inside the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	446 Orthanc core system.
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	447
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	448 Thanks to Lua expressiveness, you can also implement conditional
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	449 auto-routing. For instance, if you wish to route only patients whose
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	450 name contains "David", you would simply write::
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 function OnStoredInstance(instanceId, tags, metadata)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	453 -- Extract the value of the "PatientName" DICOM tag
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	454 local patientName = string.lower(tags['PatientName'])
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 if string.find(patientName, 'david') ~= nil then
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	457 -- Only route patients whose name contains "David"
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	458 Delete(SendToModality(instanceId, 'sample'))
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 else
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	461 -- Delete the patients that are not called "David"
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	462 Delete(instanceId)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	463 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	464 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	465
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	466 Besides ``SendToModality()``, a mostly identical function with the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	467 same arguments called ``SendToPeer()`` can be used to route instances
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	468 to :ref:`Orthanc peers <peers>`. It is also possible to modify the
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	469 received instances before routing them. For instance, here is how you
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	470 would replace the ``StationName`` DICOM tag::
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	471
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	472 function OnStoredInstance(instanceId, tags, metadata)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	473 -- Ignore the instances that result from a modification to avoid
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	474 -- infinite loops
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	475 if (metadata['ModifiedFrom'] == nil and
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	476 metadata['AnonymizedFrom'] == nil) then
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	477
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	478 -- The tags to be replaced
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	479 local replace = {}
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	480 replace['StationName'] = 'My Medical Device'
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 removed
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	483 local remove = { 'MilitaryRank' }
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	484
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	485 -- Modify the instance, send it, then delete the modified instance
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	486 Delete(SendToModality(ModifyInstance(instanceId, replace, remove, true), 'sample'))
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	487
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	488 -- Delete the original instance
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	489 Delete(instanceId)
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	490 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	491 end
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	492
901e8961f46e initial commit Sebastien Jodogne <s.jodogne@gmail.com> parents: diff changeset	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 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	496 Important remarks about auto-routing
16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	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 6e0a0b57697b Added missing word bgo-osimis parents: 165 diff changeset	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 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	548
99 e83da2f99e45 added 'troubleshooting C-Find queries' in the worklist section amazy parents: 91 diff changeset	549 .. _lua-fix-cfind:
75 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	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 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	553
16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	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 15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	623
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	624
864 035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	625 HeartBeat
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	626 ---------
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	627
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	628 .. highlight:: lua
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	629
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	630 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	631 interval. This interval is defined in the ``LuaHeartBeatPeriod``
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	632 configuration::
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	633
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	634 function OnHeartBeat()
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	635
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	636 -- ping a webservice to notify that Orthanc is still alive
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	637 SetHttpCredentials('user', 'pwd')
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	638 SetHttpTimeout(1)
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	639 HttpPost("http://localhost/my-web-service/still-alive", "my-id", {})
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	640
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	641 end
035fe50b2e00 heartbeat Alain Mazy <am@osimis.io> parents: 846 diff changeset	642
668 15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	643 .. _lua-external-modules:
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	644
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	645 Using external modules
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	646 ----------------------
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	647
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	648 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	649 modules if Orthanc was compiled with the ``-DENABLE_LUA_MODULES=ON``
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	650 while invoking CMake.
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 Importantly, the modules and the Orthanc server must use the same
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	653 version of Lua for external modules to be properly loaded.
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	654
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	655 Check out the Orthanc Users forum for old discussions about this
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	656 topic: `reference 1
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	657 <https://groups.google.com/g/orthanc-users/c/BXfmwU786B0/m/M47slt5GFwAJ>`__,
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	658 `reference 2
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	659 <https://groups.google.com/g/orthanc-users/c/BXfmwU786B0/m/qpVe8UvGAwAJ>`__,
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	660 `reference 3
15a0635eef4b lua modules Sebastien Jodogne <s.jodogne@gmail.com> parents: 606 diff changeset	661 <https://groups.google.com/g/orthanc-users/c/LDAN5jA0X8M/m/4zrk0_AaBAAJ>`__.

Mercurial > hg > orthanc-book

annotate Sphinx/source/users/lua.rst @ 912:dbe3fd98beb0