changeset 224:02399e86f046

starting documentation of jobs
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 06 Mar 2019 07:41:49 +0100
parents 9ccafca945d2
children ced9dbf86de8
files Sphinx/source/faq/features.rst Sphinx/source/faq/rest-samples.rst Sphinx/source/users.rst Sphinx/source/users/advanced-rest.rst Sphinx/source/users/anonymization.rst Sphinx/source/users/rest.rst
diffstat 6 files changed, 91 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/faq/features.rst	Mon Mar 04 14:52:43 2019 +0100
+++ b/Sphinx/source/faq/features.rst	Wed Mar 06 07:41:49 2019 +0100
@@ -1,6 +1,9 @@
 Terminology of advanced features
 ================================
 
+.. contents::
+   :depth: 3
+
 .. _peers:
 
 Peers
@@ -235,3 +238,10 @@
 * ``Attachment 9998`` is used by the `Osimis WebViewer plugin <https://bitbucket.org/osimis/osimis-webviewer-plugin>`__ to store instance information.
 * ``Attachment 9999`` is used by the `Osimis WebViewer plugin <https://bitbucket.org/osimis/osimis-webviewer-plugin>`__ to store annotations.
 * ``Attachments 10000-13999`` are used by the `Osimis WebViewer plugin <https://bitbucket.org/osimis/osimis-webviewer-plugin>`__ to store reduced quality images.
+
+
+Jobs
+----
+
+Check out the :ref:`advanced features of the REST API <jobs>`.
+
--- a/Sphinx/source/faq/rest-samples.rst	Mon Mar 04 14:52:43 2019 +0100
+++ b/Sphinx/source/faq/rest-samples.rst	Wed Mar 06 07:41:49 2019 +0100
@@ -6,6 +6,8 @@
 
 * This "Orthanc Book" proposes a :ref:`number of samples showing how
   to use the REST API <rest>` of Orthanc.
+* More advanced features of the REST API can be found :ref:`in this
+  dedicated section <rest-advanced>`.
 * Many working examples written in Python are `available in the source
   distribution
   <https://bitbucket.org/sjodogne/orthanc/src/default/Resources/Samples/Python/>`__.
--- a/Sphinx/source/users.rst	Mon Mar 04 14:52:43 2019 +0100
+++ b/Sphinx/source/users.rst	Wed Mar 06 07:41:49 2019 +0100
@@ -11,3 +11,4 @@
    users/replication.rst
    users/anonymization.rst
    users/lua.rst
+   users/advanced-rest.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/users/advanced-rest.rst	Wed Mar 06 07:41:49 2019 +0100
@@ -0,0 +1,70 @@
+.. _rest-advanced:
+
+Advanced features of the REST API
+=================================
+
+.. contents::
+   :depth: 3
+
+This section of the Orthanc Book is a complement to the description of
+the :ref:`REST API of Orthanc <rest>`. It explains some advanced uses
+of the API.
+
+
+.. _jobs:
+
+Jobs
+----
+
+Since Orthanc 1.4.0, a jobs engine is embedded within Orthanc. Jobs
+are tasks to be done by Orthanc. Jobs are first added to a queue of
+pending tasks, and Orthanc will simultaneously a fixed number of jobs
+(check out :ref:`configuration option <configuration>`
+``ConcurrentJobs``). Once the jobs have been processed, they are tagged
+as successful or failed, and kept in a history (the size of this
+history is controlled by the ``JobsHistorySize`` option).
+
+Synchronous vs. asynchronous
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some calls to the REST API of Orthanc require time to be executed, and
+thus result in adding a job to the processing queue. This notably
+includes the following URIs:
+
+* :ref:`Modifying and anonymizing <anonymization>` DICOM instances.
+* Creating ZIP or media archives.
+* C-Move SCU (``/queries/.../retrieve``).
+* C-Store SCU (``/modalities/.../store``).
+* Sending to an Orthanc peer (``/peers/.../store``).
+* :ref:`Split/merge <split-merge>`.
+* Sending images using the :ref:`transfers accelerator <transfers>` plugin.
+
+Such REST API calls can be configured to be executed in a synchronous
+or an asynchronous mode:
+
+* **Synchronous calls** wait for the end of the execution of their
+  associated job. This is in general the default behavior.
+* **Asynchronous calls** end immediately and return a handle to their
+  associated job. It is up to the caller to monitor the end of the
+  execution by calling the jobs API.
+
+The choice between synchronous and asynchronous modes is done by
+setting the `Synchronous` field (or indifferently `Asynchronous`
+field) in the POST body of the call to the REST API. Note that the
+:ref:`transfers accelerator <transfers>` only run in the asynchronous
+mode.
+
+Even if it is more complex to handle, the asynchronous mode is highly
+recommended for jobs whose execution time can last over a dozen of
+seconds (typically, the creation of an archive or a network transfer).
+Indeed, this prevents timeouts in the HTTP protocol.
+
+
+
+
+.. _pdf:
+
+PDF
+---
+
+TODO
--- a/Sphinx/source/users/anonymization.rst	Mon Mar 04 14:52:43 2019 +0100
+++ b/Sphinx/source/users/anonymization.rst	Wed Mar 06 07:41:49 2019 +0100
@@ -158,12 +158,16 @@
 a JSON body.
 
 
+.. _split-merge: 
+
 Split/merge of DICOM studies
 ----------------------------
 
 Starting with Orthanc 1.5.0, Orthanc supports splitting and merging
 DICOM studies through its REST API.
 
+.. _split:
+
 Splitting
 ^^^^^^^^^
 
@@ -198,6 +202,7 @@
   Orthanc to keep a copy of the original series in the source study.
   By default, the original series are deleted from Orthanc.
 
+.. _merge:
 
 Merging
 ^^^^^^^
--- a/Sphinx/source/users/rest.rst	Mon Mar 04 14:52:43 2019 +0100
+++ b/Sphinx/source/users/rest.rst	Wed Mar 06 07:41:49 2019 +0100
@@ -373,7 +373,7 @@
 .. _peering:
 
 Sending resources to remote Orthanc over HTTP/HTTPS (through Orthanc peering)
-------------------------------------------------------
+-----------------------------------------------------------------------------
 
 Orthanc can send its DICOM instances to remote Orthanc over HTTP/HTTPS through its Rest API. 
 This process can be triggered by the REST API.
@@ -928,6 +928,8 @@
 instance of Orthanc through its REST API. All the possibilities of the
 API have not been described:
 
+* Advanced features of the REST API can be found on :ref:`another page
+  <rest-advanced>`.
 * A :ref:`FAQ entry <rest-samples>` lists where you can find more
   advanced samples of the REST API of Orthanc.
 * The full documentation of the REST API is maintained as an online