File tree update (#306)

* File tree update

* Update learn_basics.md

---------

Co-authored-by: Phillana26 <134319064+Phillana26@users.noreply.github.com>

docs/glossary/glossary.md

@@ -0,0 +1,8 @@
+# Glossary
+
+## Activity
+
+Refers to the work carried out by an individual or an organization within a process. Activities can be classified into three categories: Task, Subprocess, and Call Activity. These activities can be either atomic or non-atomic. Atomic activities are indivisible and represent single tasks, while non-atomic activities involve multiple steps or subprocesses that work together to achieve a larger objective.
+
+## Workflow
+

docs/how_to/complete_a_task_on_behalf_of_another_user.md

@@ -0,0 +1,79 @@
+# How to complete a task on behalf of another user
+
+
+```{admonition} Goal
+:class: info
+
+Steps to follow for successfully carrying out an activity and changing instance variables should it be required.
+```
+
+---
+
+## 🏞 **Scenario**
+
+A task is assigned to a user who is responsible for completing it. However, due to various reasons, the user may find themselves unable to finish the task within the designated time frame. In such situations, the instance can be completed **by you** **on behalf of the user.** 
+This enables a smooth continuation of the process from the initial user's perspective, allowing them to move on to the next task when they are ready.
+
+---
+
+## 📔How to guide
+
+### Step 1: Find the active Process Instance
+
+[Instance is assigned to another  User](https://www.notion.so/Instance-is-assigned-to-another-User-9cb81c5676cc4ff3b60d7eca4a4b997c) 
+
+### Step 2: Navigate to the active User Task
+
+[How to view process variables](https://www.notion.so/How-to-view-process-variables-ef1a9ac598314499a4625698a1c2feed) 
+
+```{admonition} Note
+:class: note
+
+👤 Note that you need Admin rights to complete the following steps.
+```
+
+### Step 3: Suspend the Process
+
+- **How to suspend process**
+  
+    put link to suspend process here
+
+### Step 4: Complete the task
+
+Select the highlighted activity. This will open a pop-up view of the Instance variables.
+
+Select “Edit” which opens a code editor.
+
+![editBtn](file:///C:/Upwork/Sartography%20Docs/spiff-arena/docs/_build/html/_images/editBtn.png)
+
+
+- Scroll down to find the line to edit.
+
+```{admonition} Note
+:class: note
+
+ℹ️ It is important to identify if any variables require updating and which specific variables need modification in order to achieve the same result as if a user had completed the form. The outcome may vary depending on the necessary adjustments to these variables and the given scenario.
+```
+
+- View input example here: 
+[**Review options available for "review_outcome" field**
+**Approved:** "review_outcome": "app”
+**Rejected:** "review_outcome": "rej”
+**Request additional info:** "review_outcome": "nai” ]
+
+- Select “Save” to apply changes.
+
+- Select to execute activity. **(SCREENSHOT)**
+
+- Select the “Play” button (previously the suspend button) to resume the process.
+
+- After a few seconds, please refresh the page and ensure that it has progressed to the next activity, which should now be the current activity.
+
+| ✅ Success | 🚫 Error |
+| --- | --- |
+| With the current activity successfully completed and the workflow advanced to the next stage, the remaining steps of the process can now proceed smoothly. | In case of an error, consider adding a troubleshooting section for further assistance. |
+---
+
+## 👨‍🏫Examples
+
+[**Steps for Admin** **approving on behalf of Budget owner:** ](https://www.notion.so/Steps-for-Admin-approving-on-behalf-of-Budget-owner-64e76b05ca2a43e7ac2075e71734de22)

docs/index.md

@@ -5,13 +5,14 @@
 :caption: Getting Started
 learn_basics/learn_basics.md
 quick_start/quick_start.md
+learn_basics/bpmn_terminology.md
 ```
 
 ```{toctree}
 :maxdepth: 2
 :caption: Administration
 admin_guide/admin_guide.md
-how_to/bpmn_unit_tests.md
+validating_processes/bpmn_unit_tests.md
 ```
 
 ```{toctree}
@@ -28,6 +29,28 @@ documentation/documentation.md
 wish_list/wish_list.md
 ```
 
+```{toctree}
+:maxdepth: 3
+:caption: Spiffworkflow
+spiffworkflow/navigating-spiffworkflow.md
+spiffworkflow/creatingbpmn.md
+spiffworkflow/examples.md
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: How to
+how_to/complete_a_task_on_behalf_of_another_user.md
+
+```
+
+```{toctree}
+:maxdepth: 3
+:caption: Glossary
+glossary/glossary.md
+
+```
+
 
 ## Indices and tables
 

docs/learn_basics/bpmn_terminology.md

@@ -0,0 +1,144 @@
+# BPMN Terminology
+
+
+
+## Activity
+
+Refers to the work carried out by an individual or an organization within a process. Activities can be classified into three categories: Task, Subprocess, and Call Activity. These activities can be either atomic or non-atomic. Atomic activities are indivisible and represent single tasks, while non-atomic activities involve multiple steps or subprocesses that work together to achieve a larger objective.
+
+## Boundary Event
+
+Refers to an event that can be triggered while an activity is in progress. Boundary events are utilized for error and exception handling purposes.
+
+## BPMN Model
+
+A visual depiction of a business process that is designed to be both human-readable and machine-readable, typically represented in XML format.
+
+## Business Process
+
+A sequence of interconnected activities conducted by individuals and systems, following a defined order, with the aim of delivering a service or product, or accomplishing a specific business objective. These processes involve the receipt, processing, and transfer of information and resources to generate desired outputs.
+
+## Diagram
+
+The visual platform where business processes are represented and mapped out.
+
+## Call Activity
+
+Refers to the act of a parent or higher-level process invoking a pre-defined or reusable child process, which is represented in another process diagram. This invocation allows for the utilization of the child process multiple times, enhancing reusability within the overall model.
+
+## Collapsed Subprocess
+
+A Subprocess that conceals the underlying process it includes.
+
+## Connecting Element
+
+Lines that establish connections between Flow Elements within a process, creating a Flow. There are four distinct types of connecting elements: Sequence Flows, Message Flows, Associations, and Data Associations.
+
+## Elements
+
+The fundamental components used to construct processes. These elements encompass Flow Elements, Connecting Elements, Data Elements, Artifacts, and Swimlanes.
+
+## End Event
+
+Marks the conclusion of a process. An End Event can result in a Message, Error, or Signal outcome.
+
+## Error
+
+Denotes a significant issue encountered during the execution of an Activity or process, indicating a failure or malfunction in the processing.
+
+## Event
+
+An occurrence within a process that influences the Flow and typically involves a trigger and/or a result. Events can be categorized into four types: Start, Intermediate, End, and Boundary.
+
+## Event-Based Gateway
+
+Marks a specific point within the process where alternative paths are initiated based on the occurrence of an Event.
+
+## Exception
+
+An Event within the process that deviates from the normal flow of execution. Exceptions can be triggered by Time, Error, or Message Events.
+
+## Exclusive Gateway
+
+Denotes a juncture within the process where multiple alternative paths are available, but only one path can be chosen. The decision regarding the chosen path is determined by a condition.
+
+## Expanded Subprocess
+
+A Subprocess that shows the process it contains.
+
+## Gateway
+
+A component that governs the available paths within a process. Gateways can merge or diverge paths, or introduce additional paths based on conditions or Events. There are four types of Gateways: Exclusive, Parallel, and Event-Based.
+
+## Intermediate Event
+
+An event that occurs within the middle of a process, neither at the start nor the end. It can be connected to other tasks through connectors or placed on the border of a task. It evaluates conditions and circumstances, triggering events and enabling the initiation of alternative paths within the process.
+
+## Join
+
+Refers to the process of merging two or more parallel Sequence Flows into a single path using a Parallel Gateway.
+
+## Lane
+
+Subdivisions within a Pool that are utilized to assign activities to specific roles, systems, or departments.
+
+## Merge
+
+The process in which two or more parallel Sequence Flow paths converge into a single path, achieved either through multiple incoming Sequence Flows or by utilizing an Exclusive Gateway. This merging of paths is also commonly referred to as an "OR-Join".
+
+## Message
+
+Signifies the content of a communication exchanged between two Participants. The message is transmitted through a Message Flow.
+
+## Non-atomic Activity
+
+Refers to an Activity that can be further decomposed into more detailed steps or subtasks. A Subprocess is an example of a non-atomic Activity. It is also commonly referred to as a "compound" Activity.
+
+## Parallel Gateway
+
+Indicates a specific point within the process where the Flow divides or merges into multiple parallel paths.
+
+## Parent Process
+
+A process that contains a Subprocess.
+
+## Participant
+
+Refers to a business entity, which can be an organization, department, unit, or role involved in a process.
+
+## Pool
+
+Represents a Participant in a process.
+
+## Sequence Flow
+
+Specifies the sequence and behavior of the Flow Elements within a process.
+
+## Signal
+
+An Event that is transmitted to all individuals or entities participating in a process.
+
+## Start Event
+
+Indicates where a process starts.
+
+## Subprocess
+
+A self-contained and compound Activity incorporated within a process, capable of being further decomposed into smaller units of work.
+
+## Swimlane
+
+A visual representation that separates processes based on the Participants responsible for performing them. Swimlanes are comprised of Pools and Lanes.
+
+## Task
+
+An action performed by a person, an application or both.
+
+## Text Annotation
+
+Provides additional information about the elements in a diagram.
+
+## Trigger
+
+A mechanism that detects and identifies a particular condition or circumstance within a Start Event or Intermediate Event, subsequently initiating a corresponding response.
+

docs/learn_basics/learn_basics.md

@@ -35,4 +35,4 @@ Flows represent the sequence or direction of activities in a process. There are
 ### Artifacts
 Artifacts are used to provide additional information or documentation within a process. They include data objects (representing information or data needed for the process), annotations (providing explanatory or descriptive text), and groups (used to visually group related elements).
 
-[def]: images/Untitled_2.png
+[def]: images/Untitled_2.png

docs/spiffworkflow/creatingbpmn.md

@@ -0,0 +1,2 @@
+# Create a BPMN flow
+

docs/spiffworkflow/examples.md

@@ -0,0 +1 @@
+# Examples

docs/spiffworkflow/navigating-spiffworkflow.md

@@ -0,0 +1 @@
+# Navigating Spiffworkflow

docs/validating_processes/bpmn_unit_tests.md

@@ -0,0 +1,48 @@
+# BPMN Unit Tests
+
+Software Engineers test their code.
+With this feature, BPMN authors can test their creations, too.
+These tests can provide you with faster feedback than you would get by simply running your process model, and they allow you to mock out form input and service task connections as well as provide specific input to exercise different branches of your process model.
+BPMN unit tests are designed to give you greater confidence that your process models will work as designed when they are run in the wild, both the first time they are used by real users and also after you make changes to them.
+
+## Creating BPMN Unit Tests
+
+First, create a process model that you want to test.
+Navigate to the process model and add a JSON file based on the name of one of the BPMN files.
+For example, if you have a process model that includes a file called `awesome_script_task.bpmn`, your test JSON file would be called `test_awesome_script_task.json`.
+If you have multiple BPMN files you want to test, you can have multiple test JSON files.
+The BPMN files you test do not have to be marked as the primary file for the process model in question.
+The structure of your json should be as follows:
+
+    {
+      "test_case_1": {
+        "tasks": {
+          "ServiceTaskProcess:service_task_one": {
+            "data": [{ "the_result": "result_from_service" }]
+          }
+        },
+        "expected_output_json": { "the_result": "result_from_service" }
+      }
+    }
+
+The top-level keys should be names of unit tests.
+In this example, the unit test is named "test_case_1."
+Under that, you can specify "tasks" and "expected_output_json."
+
+Under "tasks," each key is the BPMN id of a specific task.
+If you are testing a file that uses Call Activities and therefore calls other processes, there can be conflicting BPMN ids.
+In this case, you can specify the unique activity by prepending the Process id (in the above example, that is "ServiceTaskProcess").
+For simple processes, "service_task_one" (for example) would be sufficient as the BPMN id.
+For User Tasks, the "data" (under a specific task) represents the data that will be entered by the user in the form.
+For Service Tasks, the data represents the data that will be returned by the service.
+Note that all User Tasks and Service Tasks must have their BPMN ids mentioned in the JSON file (with mock task data as desired), since otherwise we won't know what to do when the flow arrives at these types of tasks.
+
+The "expected_output_json" represents the state of the task data that you expect when the process completes.
+When the test is run, if the actual task data differs from this expectation, the test will fail.
+The test will also fail if the process never completes or if an error occurs.
+
+## Running BPMN Unit Tests
+
+Go to a process model and either click “Run Unit Tests” to run all tests for the process model or click on the “play icon” next to a "test_something.json" file.
+Then you will get a green check mark or a red x.
+You can click on these colored icons to get more details about the passing or failing test.

docs/wish_list/wish_list.md

@@ -17,8 +17,11 @@ It might also be available in the footer or under a help icon when displaying a
 
 ## Modeler Experience
 
+### Markdown Support for Process Groups and Models
+Allow us to define a markdown file for a process group or process model, which would be displayed in the process group or process model in the tile view, or at the top of the details page when a group or model is selected.
+
 ### Form Builder
-Let's invest in a much better Form Builder experience, so that it is trivial to build new forms or modify existing forms
+Let's invest in a much better Form Builder experience, so that it is trivial to build new forms or modify existing forms.
 
 
 

spiffworkflow-backend/src/spiffworkflow_backend/services/process_model_service.py

@@ -3,6 +3,7 @@ import os
 import shutil
 import uuid
 from glob import glob
+from json import JSONDecodeError
 from typing import TypeVar
 
 from spiffworkflow_backend.exceptions.api_error import ApiError
@@ -428,7 +429,13 @@ class ProcessModelService(FileSystemService):
 
         if os.path.exists(json_file_path):
             with open(json_file_path) as wf_json:
-                data = json.load(wf_json)
+                try:
+                    data = json.load(wf_json)
+                except JSONDecodeError as jde:
+                    raise ApiError(
+                        error_code="process_model_json_file_corrupted",
+                        message=f"The process_model json file {json_file_path} is corrupted.",
+                    ) from jde
                 if "process_group_id" in data:
                     data.pop("process_group_id")
                 # we don't save `id` in the json file, so we add it back in here.