#509 - Document usage of task logs

docs/examples/case.md

@@ -165,11 +165,11 @@ Finally the `observable` metadata needs to be defined with its `dataType` as `fi
 
 This way TheHive will pair the observable metadata with the file as its attachment behind the scenes.
 
-## Case tasks
+## Case tasks and logs
 
-For more advanced case handling we can specify tasks which will serve as steps during the evaluation of the case.
+For more advanced case handling we can specify tasks and task logs which will serve as steps and additional actions to take during the evaluation of the case.
 
-Fortunately TheHive API provides different options to add tasks to cases and we will check them out in the next sections.
+Fortunately TheHive API provides different options to add tasks and task logs to cases and we will check them out in the next sections.
 
 ### Add tasks during case creation
 
@@ -199,6 +199,19 @@ In the above example we created an empty case as `case_to_enrich`, and then defi
 
 Finally using a for loop and the `case.create_task` method we added them to our dummy case one by one.
 
+### Add logs to tasks
+
+Tasks can also be enriched with logs which can describe activities that have been carried out during the execution of a task.
+Additionally task logs can store artifacts in the form of attachments to further enrich the task.
+Let's see an example of enriching a case task with a task log containing an attachment.
+
+```python
+--8<-- "examples/case/task_with_task_log.py"
+```
+
+Above we created a case, enriched it with a task, and finally added a task log with a dummy attachemnt to the task.
+
+
 ## Case pages
 
 In order to give more context to a case we can add pages to it, which could serve as additional notes or documentation during investigation.

examples/case/task_with_task_log.py

@@ -0,0 +1,31 @@
+import os
+from tempfile import TemporaryDirectory
+
+from thehive4py import TheHiveApi
+
+hive = TheHiveApi(url="http://localhost:9000", apikey="h1v3b33")
+
+case_to_enrich = hive.case.create(
+    case={
+        "title": "case to enrich",
+        "description": "a case to enrich with task and task log",
+    },
+)
+
+case_task_to_enrich = hive.task.create(
+    case_id=case_to_enrich["_id"],
+    task={"title": "a task to enrich with a task log and attachment"},
+)
+
+with TemporaryDirectory() as tmpdir:
+    task_log_attachment_filepath = os.path.join(tmpdir, "task_log_attachment.txt")
+    with open(task_log_attachment_filepath, "w") as attachment_file:
+        attachment_file.write("attachment content")
+
+    case_task_log = hive.task_log.create(
+        task_id=case_task_to_enrich["_id"],
+        task_log={
+            "message": "a task log with an attachment",
+            "attachments": [task_log_attachment_filepath],
+        },
+    )