Escalation Events Properties and Form Styling Documentation (#1047)

* Escalation Events Properties and Form Styling Documentation

* Merged side by side forms documentation with existing one

docs/Building_Diagrams/Forms.md

@@ -242,57 +242,49 @@ The schema enforces the following rules:
 - The `Preferred Delivery Date Range` must start no earlier than today and end no later than the `end_date`.
 
 ### Display Fields Side-By-Side on Same Row
+When designing forms, it's often more user-friendly to display related fields, such as First Name and Last Name, side by side on the same row, rather than stacked vertically. The `ui:layout` attribute in your form's JSON schema enables this by allowing you to specify how fields are displayed relative to each other, controlling the grid columns each field occupies for a responsive design.
 
-By default, all form fields will be laid out one on top of the other.
-In some cases, it might be more user-friendly to put two or more fields next to each other on the same conceptual "row."
-Perhaps, you want to let a user fill out a name, and have First Name and Last Name next to each other.
-Don't actually do this; use Full name as a single field. :)
-But in some other case where you actually want to have fields laid out horizontally instead of vertically, do the following:
+#### Form Schema Example:
 
-Example form schema:
+Define your form fields in the JSON schema as follows:
 
 ```json
 {
-  "title": "Side by side",
-  "description": "A simple form demonstrating side-by-side layout of fields",
+  "title": "Side by Side Layout",
+  "description": "Demonstrating side-by-side layout",
   "type": "object",
   "properties": {
-    "firstName": {
-      "type": "string"
-    },
-    "lastName": {
-      "type": "string"
-    },
-    "notes": {
-      "type": "string"
-    }
+    "firstName": {"type": "string"},
+    "lastName": {"type": "string"},
+    "notes": {"type": "string"}
   }
 }
 ```
 
-Example uiSchema:
+#### `ui:layout` Configuration:
+
+The `ui:layout` attribute accepts an array of objects, each representing a conceptual "row" of fields. Here's how to use it:
 
 ```json
 {
   "ui:layout": [
     {
-      "firstName": {
-        "sm": 2,
-        "md": 2,
-        "lg": 4
-      },
-      "lastName": {
-        "sm": 2,
-        "md": 2,
-        "lg": 4
-      }
+      "firstName": {"sm": 2, "md": 2, "lg": 4},
+      "lastName": {"sm": 2, "md": 2, "lg": 4}
     },
-    {
-      "notes": {}
-    }
+    {"notes": {}}
   ]
 }
 ```
+![Styling_Form](images/styling_forms.png)
+
+#### Key Points:
+
+- **Layout Design**: The `ui:layout` specifies that `firstName` and `lastName` should appear side by side. Each field's size adjusts according to the screen size (small, medium, large), utilizing grid columns for responsive design.
+- **Responsive Columns**: Values (`sm`, `md`, `lg`) indicate the number of grid columns a field should occupy, ensuring the form remains functional and visually appealing across devices.
+- **Simplified Configuration**: If column widths are unspecified, the layout will automatically adjust, providing flexibility in design.
+
+#### Example Illustrated:
 
 In this case, we are saying that we want firstName and lastName in the same row, since they are both in the first element of the ui:layout array.
 We are saying that firstName should take up 4 columns when a large display is used.
@@ -309,6 +301,11 @@ If you just specific a uiSchema like this, it will figure out the column widths
       ]
     }
 
+
+By leveraging the `ui:layout` feature, you can design form layouts that are not only functional but also enhance the user experience, making your forms well-organized and accessible across various screen sizes.
+
+
+
 ### Display UI Help in Web Forms
 
 When designing web forms, it's essential to provide users with contextual help to ensure they understand the purpose and requirements of each field.
@@ -402,7 +399,7 @@ Below is an example JSON schema that includes the numeric range field:
 
 This schema defines a numeric range object with `min` and `max` properties, both of which are required.
 
-#### Ui Schema Example
+#### UI Schema Example
 
 ```json
 {
@@ -414,4 +411,4 @@ This schema defines a numeric range object with `min` and `max` properties, both
 
 #### Validation
 
-This will automatically validate that the max value cannot be less than the min value.
+This will automatically validate that the max value cannot be less than the min value.

docs/Building_Diagrams/escalation_events.md

@@ -88,4 +88,45 @@ In this scenario, we observe an End Escalation following a Boundary Event.
 This thrown End Escalation can be intercepted by the boundary event of a Call Activity or at the start of a sub-process, as shown in previous examples on this page.
 In another example, we see an End Escalation event being thrown within a sub-process and caught at the sub-process's boundary.
 The application of the last example aligns with the first, where the escalation can be intercepted either on a Call Activity or at the beginning of a sub-process.
-It's crucial to remember that whether a process is created or terminated in these contexts depends on whether non-interrupting or interrupting events are utilized.
+It's crucial to remember that whether a process is created or terminated in these contexts depends on whether non-interrupting or interrupting events are utilized.
+
+## Configuring Escalation Events Properties
+Setting up an escalation event within a workflow in SpiffWorkflow involves defining both the escalation trigger (throw event) and the point where the escalation is handled (catch event). 
+
+Here's how to set up these components:
+
+**Define the Escalation ID**: Determine the task or process stage where an escalation might need to be triggered due to exceptional circumstances. and decide on a unique identifier for your escalation event.
+
+![Escalation ID](images/Escalation_ID.png)
+
+```{admonition} Note
+⚠  In the above example, the escalation ID is created with `Escalation_Throw_1`.
+```
+
+**Define the Intermediate Throw Escalation Event**:
+ Add an Intermediate Throw Escalation Event immediately after the task identified. Select escalation ID and create a unique **escalation code**. .
+
+![Escalation Order](images/Escalation_Order.png)
+
+```{admonition} Note
+⚠  Escalation code is essential for matching the throw event with its corresponding catch event. Example: `OrderExceedsThreshold`.
+```
+
+**Define the Escalation Catch Event**:
+This can be a boundary event attached to a task where the escalation should be caught and handled, or an intermediate event in the workflow where the escalation process converges.
+
+For a boundary catch event, attach it to the task designated to handle the escalation. For an intermediate catch event, place it at the appropriate point in the process flow.
+
+![Escalation Order](images/Escalation_Order_2.png)
+
+```{admonition} Note
+⚠  Ensure this matches exactly with the code assigned to the throw event to ensure proper linkage. Example: `OrderExceedsThreshold`.
+```
+
+**Set Additional Properties (Optional)**:
+You may need to set additional properties for the escalation event, such as:
+
+- **Payload/Variables**: Configuring any data or process variables that should be passed along with the escalation for handling by the catch event.
+- **Documentation**: Providing details on when the escalation should be triggered and how it should be handled.
+
+After setting up the escalation event, test the workflow to ensure the escalation is triggered under the right conditions and that the catch event handles it as expected