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

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

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 16d516fdc642 note 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 6b432ce3a56e typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 355 diff changeset	34 ``LuaScripts`` variable. A comma-separated list of paths can be
6b432ce3a56e typo 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 6b432ce3a56e typo Sebastien Jodogne <s.jodogne@gmail.com> parents: 355 diff changeset	155 If a callback is specified multiple times in separate scripts, the
6b432ce3a56e typo 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 1a701dfdfcad fix 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 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	197 * ``uri`` specifies the resource being accessed
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	198 (e.g. ``/instances``). It must not include the URL schema
1a701dfdfcad fix 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 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	201 * 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	202 containing the body of the request
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	203 (e.g. ``{"Keep":"StudyDate"}``). This string will often correspond
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	204 to a JSON-formatted version of a `Lua table
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	205 <http://lua-users.org/wiki/TablesTutorial>`__. The ``DumpJson()``
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	206 function (see below) is very useful to achieve this conversion from
1a701dfdfcad fix 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 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	209 * ``builtin`` is an optional Boolean that specifies whether the
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	210 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	211 ``true``), or the full the REST API after being tainted by plugins
1a701dfdfcad fix 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 1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	217 .. highlight:: bash
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	218
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	219 For instance::
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	220
1a701dfdfcad fix Sebastien Jodogne <s.jodogne@gmail.com> parents: 236 diff changeset	221 RestApiPost('/instances/5af318ac-78fb-47ff-b0b0-0df18b0588e0/anonymize', '{}')
1a701dfdfcad fix 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 16d516fdc642 note 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 16d516fdc642 note 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 16d516fdc642 note 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 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	500 Important remarks about auto-routing
16d516fdc642 note 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 16d516fdc642 note 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 16d516fdc642 note 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 16d516fdc642 note Sebastien Jodogne <s.jodogne@gmail.com> parents: 64 diff changeset	557
16d516fdc642 note 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>`__.

Mercurial > hg > orthanc-book

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