keycloak_setup_message events_vs_tasks

docs/how_to_guides/deployment/index.md

@@ -11,4 +11,5 @@ work_with_redis_celery_broker
 deploy_a_connector_proxy_as_an_aws_lambda_function
 configure_a_connector_proxy
 manage_process_models
+keycloak_setup
 ```

docs/how_to_guides/deployment/keycloak_setup.md

@@ -0,0 +1,87 @@
+# Keycloak Setup Guide for Clients 
+
+Keycloak is an open-source identity and access management solution that provides authentication, authorization, and user management features. 
+
+This guide outlines the steps to configure Keycloak for a client, including **granting admin privileges** within a realm and **allowing users to log in using Google authentication**.  
+
+## **1. Super Admin Tasks: Allowing Realm User Management**  
+
+To allow user management in a specific **Keycloak realm**, follow these steps:
+
+### **Step 1: Select the Realm in the Keycloak Admin Console**  
+1. Log in to the **Keycloak Admin Console**.  
+2. From the left sidebar, click **Realm Settings**.  
+3. Select the realm you wish to allow access to.
+
+### **Step 2: Enable `security-admin-console` for the Realm**  
+1. Navigate to **Clients**.  
+2. Search for **security-admin-console**.  
+3. Ensure that it is **enabled** for the selected realm.
+
+### **Step 3: Assign Admin Roles to a User**  
+To grant a user admin access for adding/managing users:  
+1. Navigate to **Users** in the left sidebar.  
+2. Find or create the user who needs admin privileges.  
+3. Open the user’s profile and go to the **Role Mapping** tab.  
+4. Add the following roles:  
+   - `view-users`  
+   - `manage-users`  
+5. If you want to grant **full admin access**, search for **realm-management** and grant **all permissions** within realm management.
+
+### **Step 4: Provide the Admin URL**  
+After assigning roles, provide the user with the following URL to access the **Admin Console**:
+
+```
+https://keycloak-[CLIENT'S DOMAIN].spiff.works/admin/[REALM_NAME]/console
+```
+
+#### **Example:**  
+For a client named **Civitos**, the URL would be:  
+```
+https://keycloak-civitos.spiff.works/admin/spiffworkflow/console/#/spiffworkflow/users
+```
+
+## **2. Allowing Everyone from Your Domain to Log into an Instance**  
+*(This example covers **Google as an Identity Provider**, but similar steps can be followed for other providers.)*  
+
+### **Step 1: Set Up Google as an Identity Provider**  
+1. Go to the [Google Developer Console](https://console.cloud.google.com/).  
+2. Select the project associated with Keycloak (**e.g., `spiffdemo-keycloak`**).  
+3. In the search bar, type **“Clients”**.  
+4. Click on **+ Create Client**.
+
+### **Step 2: Configure the OAuth Client**  
+1. Choose **"Web Application"** as the client type.  
+2. Enter a meaningful name based on the client, e.g., **"Jons-chess-boards"**.  
+3. **Leave "Authorized JavaScript Origins" blank.**  
+4. In the **Authorized Redirect URIs** section, add the following:
+
+   ```
+   https://[KEYCLOAK-FOR-CLIENT]/realms/[REALM]/broker/google/endpoint
+   ```
+
+   Typically, this would look something like:
+
+   ```
+   https://keycloak-jons-chess-boards.spiff.works/realms/spiffworkflow/broker/google/endpoint
+   ```
+
+5. Save the configuration and copy the **Client ID** and **Client Secret**.
+
+### **Step 3: Add Google as an Identity Provider in Keycloak**  
+1. Go to the **Keycloak Admin Console**.  
+2. Select the appropriate **Realm**.  
+3. Navigate to **Identity Providers** → **Add Provider** → **Google**.  
+4. Enter the **Client ID** and **Client Secret** from Google.  
+5. Set **First Login Flow** to `first broker login` (or another authentication flow if required).  
+6. Click **Save**.
+
+### **Step 4: Test Login**  
+- Navigate to the client’s login page and verify that **Google Login** is now an option.  
+- Ensure that users from the domain can successfully authenticate using Google.
+## **Conclusion**  
+By following these steps, you can successfully:  
+✔ Grant **admin access** to a user for managing the realm.  
+✔ Enable **Google-based authentication** for all users in a client’s domain.  
+
+This setup ensures a secure and efficient user authentication process within **Keycloak**, providing administrators with the ability to manage users effectively while allowing users to authenticate seamlessly using Google.  

docs/how_to_guides/deployment/manage_permissions.md

@@ -34,12 +34,11 @@ This is just for documentation purposes and isn't used by the system.
 In this example, we are describing permissions for an "admin-type-user."
 
 There are three keys allowed under each permission:
-
-- groups: lists the groups to which the permission applies (admin in this case)
-- actions: lists the specific actions that are permitted for the group
-  - actions can be negated by prepending with "DENY:"
-- uri: defines the target resource for these permissions
-  - /\* indicates that the permissions apply to all resources within the system
+| Key | Description |
+|------|------------|
+| **groups** | Lists the groups to which the permission applies (`admin` in this case). |
+| **actions** | Lists specific allowed actions. Actions can be negated using `"DENY:"`. |
+| **uri** | Defines the target resource. `"/*"` applies permissions to all system resources. |
 
 **Permissions allowed:**
 
@@ -66,6 +65,71 @@ To allow reading and DISALLOW updating, it would look like this:
 ```
 ["read", "DENY:update"]
 ```
+## Default Permissions and User Groups**  
+
+### The "Everyone" Group  
+By default, **every user** who logs into the system is automatically part of the **"everyone"** group.  
+
+- Any **permissions assigned to this group apply to all users** unless explicitly overridden by other settings.  
+- The default group can be changed using the **environment variable**:  
+
+  ```sh
+  SPIFFWORKFLOW_BACKEND_DEFAULT_USER_GROUP
+  ```
+
+  **Example Usage:**  
+  If you want all new users to be assigned to a **custom group** instead of "everyone," set:  
+
+  ```sh
+  export SPIFFWORKFLOW_BACKEND_DEFAULT_USER_GROUP="custom-default-group"
+  ```
+
+## Permission Levels
+
+SpiffWorkflow has **three primary permission levels** that determine what users can do.  
+
+### BASIC Permissions 
+**BASIC** permissions allow users to interact with their own information and tasks.  
+
+Users with this permission can:  
+  ✅ View details about their account and actions.  
+  ✅ Access **all process instances they have created**.  
+  ✅ Navigate the basic features of the platform.  
+  ✅ View tasks assigned to them.  
+  ❌ **Cannot modify or interact with other users' instances.**  
+
+**Use Case**: Assigned to regular users who only interact with their own processes.  
+
+### ELEVATED Permissions
+**ELEVATED** permissions allow users to configure authentication and secrets for external integrations.  
+
+Users with this permission can:  
+  ✅ Define and manage **secrets** (API keys, credentials).  
+  ✅ Set up authentication for external services.  
+  ✅ Enable **SpiffWorkflow service tasks** to securely connect to external systems.  
+
+**Use Case**: Typically assigned to **technical administrators** or **developers** managing system integrations.  
+
+### SUPPORT Permissions  
+**SUPPORT** permissions provide advanced control over process instances.  
+
+Users with this permission can:  
+  ✅ **Pause** a running process.  
+  ✅ **Move** a process back to an earlier point.  
+  ✅ **Migrate** a process to a **new model version**.  
+  ✅ **Modify process data manually**.  
+  ✅ View **detailed execution logs** for debugging.  
+
+This permission is typically **restricted to administrators or support engineers**, as it allows modification of **live workflows**.  
+
+**Use Case**: Assigned to **support teams** responsible for troubleshooting process instances.  
+
+| **Permission Level** | **Capabilities** |
+|----------------------|------------------|
+| **BASIC** | Users can view and interact with their own processes and assigned tasks. |
+| **ELEVATED** | Users can define secrets, configure authentication, and manage external integrations. |
+| **SUPPORT** | Users can **pause, modify, migrate, and debug** any process instance. |
+
 
 ## Site Administration
 

docs/reference/bpmn/message_events.md

@@ -1,7 +1,9 @@
 # Message Events
 
 A Message Event acts as a channel for the exchange of information between different process participants or external systems.
+
 While it might be tempting to associate "message events" with emails, their scope extends beyond digital correspondence.
+
 They signify the transmission of information between various process components, whether within the same process or across different processes.
 
 ![message_relationship](/images/relationship_message.png)
@@ -45,7 +47,9 @@ Similarly, upon receiving a purchase order from the customer, the sales departme
 
 An Intermediate Catch Event is used to wait for and capture a specific message from another source.
 Once activated upon receiving the designated message, it allows the process flow to continue from that point onward.
+
 It's crucial to understand that the process instance remains in a waiting state until triggered by another source or process.
+
 This fundamental distinction sets Intermediate Catch Events apart from Intermediate Throw Events, as Catch Events exclusively await external triggers, while Throw Events initiate those triggers.
 
 ![message_event_example_5](/images/msg_event_example_5.png)
@@ -59,6 +63,7 @@ The process outlined in the previous section can be split into two distinct BPMN
 
 In the given example, there are two Intermediate Catch Events.
 One waits for confirmation from the customer, and the other depends on the shipping department's verification of dispatch before producing the invoice.
+
 Without feedback from both the customer and the shipping department at this stage, the process instance won't move to the subsequent step.
 
 ```{admonition} Note
@@ -70,12 +75,15 @@ Without feedback from both the customer and the shipping department at this stag
 ![end_message_event](/images/end_msg_event.png)
 
 This type of event signifies the completion of a process and indicates that a message is sent to an external recipient to notify them of the process's conclusion.
+
 It serves as the endpoint of the process and sends a message when the process reaches this event.
 
 ![message_event_example_4](/images/msg_event_example_4.png)
 
 Please note that the End Event, when using pools, signifies the conclusion of the process within that specific pool, but it does not necessarily indicate the end of the entire process.
+
 In the provided example, the final step involves sending the customer an invoice.
+
 Prior to this, the last step for the shipping department was to send a confirmation.
 
 ```{admonition} Note
@@ -85,7 +93,9 @@ Prior to this, the last step for the shipping department was to send a confirmat
 ## Correlation
 
 A singular Throw Message Event corresponds exclusively to a single active Catch Message Event.
+
 This correlation is one-to-one, unlike Signal Events that could be sent to multiple active Signal Catch Events.
+
 It is important to configure the correlation of the Catch and Throw Events.
 
 ## Message Event Configuration
@@ -134,11 +144,12 @@ The connected catch event is configured in precisely the same manner as the thro
 | ![conditions](/images/payload_msg.png) | **Variable Name:** order_amount | The Variable Name can include a variable, holding unique information specific to the instance, or in this scenario, the order. |
 | ![conditions](/images/event_correlation_msg.png) | **Correlation:** invoice_number | Select the correlation that can identify the distinct property distinguishing one process instance from another. |
 
-Check out this example on Message Event.
+Learn more about configuring Message Events and the differences between Message Events and Message Tasks.
+
 ```{toctree}
 :maxdepth: 1
-:caption: Message Event Example
 configuring_messages_and_correlation_properties
+message_events_vs_tasks
 ``` 
 
 ```{tags} how_to_guide, building_diagrams

docs/reference/bpmn/message_events_vs_tasks.md

@@ -0,0 +1,70 @@
+# Message Tasks vs. Message Events
+
+In **Business Process Model and Notation (BPMN)**, **Message Tasks** and **Message Events** facilitate communication between different participants in a process. Although both involve message exchanges, they serve different purposes and are used in different contexts.  
+
+This guide explains when to use a **Message Task** versus a **Message Event**, along with examples and best practices.  
+
+## 1. Message Task 
+A **Message Task** represents a task where sending or receiving a message is the primary activity within a process.  
+
+### When to Use a Message Task 
+- **Performing an Activity:** The task itself involves sending or receiving a message.  
+  - Example: An employee sends a request to another department.  
+
+- **Synchronous Communication:** The process **waits for a response** before proceeding.  
+  - Example: A service request is sent, and the process pauses until a reply is received.  
+
+- **Part of a Sequence:** The message exchange is an essential part of the workflow.  
+  - Example: An order confirmation message must be sent before an item is shipped.  
+
+### Example: Message Task Usage
+A customer service representative sends a **refund request** to the finance department and waits for approval.  
+
+**BPMN Representation:**  
+- A **Message Task** labeled **"Send Refund Request"** is part of the process sequence.  
+- The process **cannot continue** until the request is sent and/or a response is received.  
+
+**Key Takeaway:** Use a **Message Task** when a specific task directly involves sending or receiving a message as part of process execution. 
+
+## 2. Message Event 
+A **Message Event** represents the occurrence of a message in a process but does not represent a specific task. It affects the process flow based on the message received or sent.  
+
+### When to Use a Message Event 
+
+- **Process Interruption:** The message **interrupts the flow** or triggers a reaction.  
+  - Example: A customer cancels an order, stopping the shipment process.  
+
+- **Boundary Events:** The message is attached to an activity to indicate that the process should react when the message is received.  
+  - Example: A process is waiting for approval via a message; if rejected, it follows a different path.  
+
+- **Intermediate Events:** The message is sent or received within a process without being an explicit task.  
+  - Example: A notification is sent to a supplier when an order is updated.  
+
+- **Start Events:** A **Message Start Event** starts a process in response to receiving a message from an external source.  
+  - Example: A service request is received, triggering the support ticket process.  
+
+### Example: Message Event Usage  
+A **customer cancels an order** before it is processed.  
+
+**BPMN Representation:**  
+- A **Message Start Event** triggers the **"Cancel Order"** process upon receiving a cancellation request.  
+- A **Message Intermediate Event** indicates that an update notification is sent to the supplier.  
+- A **Message Boundary Event** attached to "Prepare Shipment" allows cancellation before shipment processing starts.  
+
+**Key Takeaway:** Use a **Message Event** when you need to indicate that a message occurrence influences the process flow but is not an activity in itself.  
+
+
+## 3. Summary: Message Task vs. Message Event  
+
+| Feature | **Message Task** | **Message Event** |
+|---------|-----------------|-------------------|
+| **Purpose** | Represents a task where sending or receiving a message is an explicit action. | Represents the occurrence of a message that affects process flow. |
+| **Usage** | When the process explicitly involves sending or receiving a message as an activity. | When a message triggers, interrupts, or signals process changes. |
+| **Flow Behavior** | Appears as a task in the process sequence and must be executed. | Can be a Start, Intermediate, or Boundary Event, influencing process flow. |
+| **Example** | A task where an employee sends a request to another department. | A message received that cancels an ongoing process. |
+
+Use **Message Tasks** when the **act of sending/receiving a message is part of an activity**.  
+
+Use **Message Events** when a message **affects the process flow** but is **not a discrete task**.  
+ 
+Understanding the distinction between **Message Tasks** and **Message Events** ensures accurate BPMN modeling of message-based interactions.