Merge pull request #1140 from Avaiga/doc/taipy#1704-storing-submissio…

…n-job-status-change-timestamp

Doc/taipy#1704 - Timestamp properties for Job and Submission

docs/release-notes/index.md

@@ -51,6 +51,17 @@ This is the list of changes to Taipy releases as they were published.
   [Get all scenarios](../userman/scenario_features/sdm/scenario/index.md#get-all-scenarios) and
   [Get primary scenarios](../userman/scenario_features/sdm/scenario/index.md#get-primary-scenarios).
 
+- When the status of a `Job^` changes, the timestamp of the status change is now recorded.
+  These timestamps can be accessed using the following properties: *submitted_at*, *run_at*,
+  *finished_at*, *execution_duration*, *pending_duration*, and *blocked_duration*.<br/>
+  For more information, please refer to
+  [Job Status](../userman/scenario_features/sdm/job/index.md#job-status).
+
+- The timestamps of the status changes of a `Submission^` are recorded. These timestamps can be
+  accessed using the following properties: *submitted_at*, *run_at*, *finished_at*, *execution_duration*.<br/>
+  For more information, please refer to
+  [Submission Status](../userman/scenario_features/sdm/submission/index.md#submission-status).
+
 <h4><strong><code>taipy-templates</code></strong> 4.0.0 </h4>
 
 - Creating a new application using any template now also supports initializing the application as a

docs/userman/scenario_features/sdm/job/index.md

@@ -48,13 +48,13 @@ For more details, see the [job selector](../../../../refmans/gui/viselements/cor
 # Job attributes
 A `Job^` entity ìs identified by a unique identifier `id` that is generated by Taipy.
 
-Here is the list of the `Job^`'s attributes:
+Here is the list of `Job^`'s main attributes:
 
-- _task_: The `Task^` of the job.
-- _force_: The force attribute is `True` if the execution of the job has been forced.
-- _creation_date_: The date of the creation of the job with the status `SUBMITTED`.
-- _status_: The status of the job.
-- _stacktrace_: The stacktrace of the exceptions handled during the execution of the jobs.
+- *task*: The `Task^` of the job.
+- *force*: The force attribute is `True` if the execution of the job has been forced.
+- *creation_date*: The date of the creation of the job with the status `SUBMITTED`.
+- *status*: The status of the job.
+- *stacktrace*: The stacktrace of the exceptions handled during the execution of the jobs.
 
 ## Job Status
 
@@ -68,6 +68,22 @@ Here is the list of the `Job^`'s attributes:
 - `SKIPPED`: The job was and will not be executed.
 - `ABANDONED`: The job was abandoned and will not be executed.
 
+When the status of a job changes, the timestamp of the change is recorded. These timestamps can be accessed
+using the following properties:
+
+- *submitted_at*: The datetime when the job was submitted.
+- *run_at*: The datetime when the job started running.
+- *finished_at*: The datetime when the job finished.
+- *execution_duration*: The duration of the job execution in seconds, which is the difference between
+  the *finished_at* and *run_at* timestamps. If the job is not finished, the duration is the difference
+  between the current time and the *run_at* timestamp.
+- *pending_duration*: The duration of the job in the pending state in seconds, which is the duration between
+  the `PENDING` status and the `RUNNING` status. If the job is pending, the duration is the difference between
+  the current time and the datetime when the job was in the `PENDING` status.
+- *blocked_duration*: The duration of the job in the blocked state in seconds, which is the duration between
+  the `BLOCKED` status and the `PENDING` status. If the job is blocked, the duration is the difference between
+  the current time and the datetime when the job was in the `BLOCKED` status.
+
 # Get/Delete Job
 
 Three methods are available to retrieve jobs:

docs/userman/scenario_features/sdm/submission/index.md

@@ -25,15 +25,15 @@ For more details and examples on how to submit scenarios, sequences or tasks, se
 
 # Submission attributes
 
-Here is the list of the `Submission^`'s attributes:
+Here is the list of `Submission^`'s main attributes:
 
 - *entity_id*: The identifier of the entity that was submitted.
-- _id_: The identifier of the `Submission^` entity.
-- _jobs_: A list of jobs.
-- _properties_: A dictionary of additional properties.
-- _creation_date_: The date of this submission's creation.
-- _submission_status_: The current status of this submission.
-- _version_: The string indicates the application version of the submission to instantiate.
+- *id*: The identifier of the `Submission^` entity.
+- *jobs*: A list of jobs.
+- *properties*: A dictionary of additional properties.
+- *creation_date*: The date of this submission's creation.
+- *submission_status*: The current status of this submission.
+- *version*: The string indicates the application version of the submission to instantiate.
     If not provided, the latest version is used.
 
 ## Submission Status
@@ -51,6 +51,16 @@ Here is the list of the `Submission^`'s attributes:
 - `FAILED`: The submission has a job that failed during its execution.
 - `COMPLETED`: The submission has successfully been executed.
 
+The timestamps of the status changes of a `Submission^` are recorded. These timestamps can be accessed
+using the following properties:
+
+- *submitted_at*: The datetime when the entity of the submission was submitted.
+- *run_at*: The datetime when the first job of the submission started running.
+- *finished_at*: The datetime when the all jobs of the submission finished.
+- *execution_duration*: The duration of the submission execution in seconds, which is the difference between
+  the *finished_at* and *run_at*. If the submisison is not finished, the duration is the difference
+  between the current time and the *run_at*.
+
 # Get/Delete Submission
 
 Three methods are available to get existing submissions: