diff --git a/docs/Building_Diagrams/Using_SpiffArena.md b/docs/Building_Diagrams/Builtin_examples.md similarity index 90% rename from docs/Building_Diagrams/Using_SpiffArena.md rename to docs/Building_Diagrams/Builtin_examples.md index 1cd6abc8..b3ab4e3b 100644 --- a/docs/Building_Diagrams/Using_SpiffArena.md +++ b/docs/Building_Diagrams/Builtin_examples.md @@ -1,24 +1,5 @@ -# Using SpiffArena -Sartography (the company developing SpiffWorkflow and SpiffArena) is providing users a platform to explore workflow concepts through a collection of examples, diagrams, and workflows. Users can interact with pre-built models, make modifications, and visualize process flows. -## How to Login to SpiffArena - -```{image} ./images/Login.png -:alt: Login Screen -:class: bg-primary mb-1 -:width: 230px -:align: right -``` -To begin your journey with SpiffArena, open your web browser and navigate to the SpiffArena website (Currently spiffdemo.org). - -On the login screen, you will find the option to log in using Single Sign-On. Click the Single Sign-On button and select your preferred login method, such as using your Gmail account. - - -```{admonition} Note: -Stay tuned as we expand our sign-on options beyond Gmail. -More ways to access SpiffArena are coming your way! -``` -## Exploring the Examples +# Built-in Examples Overview When logging into the dashboard, it is crucial to familiarize yourself with the functions it offers and how the underlying engine operates. In the demo website, we will explore two examples: the Minimal Example and the Essential Example, to provide a clear understanding of the process. @@ -27,14 +8,14 @@ In the demo website, we will explore two examples: the Minimal Example and the E -### Minimal Example +## Minimal Example Let's begin with the Minimal Example, which serves as a "Hello World" process—a simple executable BPMN Diagram designed to demonstrate basic functionality. Rather than immediately starting the process, we will first examine its structure. ![](https://lh3.googleusercontent.com/MBj52gja_U5V4R7AQ1yMTwG3GoexCPLG-7Xwe40xURIOUYqJhGmQRapPln37QM9ylLiy17Oq0B1BHvsRQWVpAzd9ztt2AUs9XG26HUOORNXpgJNOGEt4DXG-_wh6YK7X4ms52W2O5yzOgdlIJ48dMOA) -#### Access the Process Directory +### Access the Process Directory Clicking on the process name will open the directory dedicated to the Minimal Example process. From here, you can start the process if desired, but for the purpose of this example, we will proceed with an explanation of its components and functionality. @@ -54,7 +35,7 @@ The BPMN editor provides a visual representation of the process workflow. -#### Understand the Process Workflow +### Understand the Process Workflow @@ -155,7 +136,8 @@ To view and edit the instructions, click on the editor, and a window will open d ![](https://lh4.googleusercontent.com/wWNqTB2EU4W0Hgz_u2l7PiEqbGVRuZMjtbgGUrckAPP9aD2TRGFvZgVkRXWcx-CV5JsSzWYDsZuXCkTpvmyfdUmFm13bTZ5o5OOf7ykBMoJ-vGBPcxQojSpE9leMn97zZDbEdJmZPgnrChQk6tbjUc8) -3. ##### End Task + +3. **End Task** The next process in the workflow is an end task. @@ -185,10 +167,10 @@ Instructions ![](https://lh5.googleusercontent.com/lcGDq-colYTa0zRq5yObuN6D5aW2wH-PheyYFMPJ9D77lZ_-fQlUrtFHNwKmCod4v1JYrWnblJEzW5VkVFM_I_Q1d8fhiWC98DPK4ZDctI7Jbqf11DdXSJAUVvZ2C2ubv-3FKXzVkbgGY8Fnk0irSdo) -### Essential Example +## Essential Example Now that we have explored the minimal example, let's delve into a more comprehensive BPMN model known as the Essential Example. This example serves as a stepping stone towards a deeper understanding of BPMN, as it incorporates a variety of fundamental concepts that work harmoniously together. -#### **Access the Process Directory** +### **Access the Process Directory** Clicking on the process name will open the directory dedicated to the Essential Example process. Here are the four files in the Process: **BPMN editor** : The BPMN editor is a primary file that runs the engine. In the minimal example, we learned that it allows you to visually design and represent business processes using the Business Process Model and Notation (BPMN) standard. @@ -209,7 +191,7 @@ Here's what a DMN table looks like: **UI Schema**: A file that defines the layout, structure, and behavior of user interfaces, facilitating the development of intuitive and interactive user experiences. ![Image](images/UI-Schema.png) -#### **Process Workflow** +### **Process Workflow** In this BPMN diagram example, the process is outlined step by step: The process initiates with a start event, serving as the entry point for the workflow. Following the start event, a manual task named "Introduction" is incorporated, responsible for displaying a welcoming message to the user. diff --git a/docs/DevOps_installation_integration/Secrets.md b/docs/DevOps_installation_integration/Secrets.md new file mode 100644 index 00000000..a2bfc8ac --- /dev/null +++ b/docs/DevOps_installation_integration/Secrets.md @@ -0,0 +1,45 @@ +# How to Configure Secrets in SpiffArena + +## Introduction + +This documentation aims to guide users and administrators on how to configure secrets in SpiffArena, especially when dealing with BPMN diagrams stored in a public GitHub repository. The primary use case focuses on ensuring that sensitive information like API keys or OAuth tokens are not exposed while still making the process diagrams publicly available. + +## Use Case +You may have service tasks in diagrams that require sensitive information like API keys or OAuth tokens, which you don't want to commit to GitHub. + +SpiffArena allows you to create secrets that are stored in an encrypted format in the database. These secrets can be referenced in the XML of the BPMN diagrams, ensuring that while the process is visible, the sensitive information is not. Secrets are only used in service tasks. + +## Roles and Permissions + +- **SpiffArena Admin**: Can add or configure secrets. +- **External Service Admin**: For example, an admin in Bamboo HR can provide the API key that a SpiffArena admin would then configure as a secret. +- **Diagram Author**: Can reference secrets in service tasks but cannot see the actual secret values. +--- + +## How to Configure Secrets + +### Adding a New Secret + +1. **Navigate to configuration Section**: Go to the configuration section from the top panel and click on "Add a secret". Ensure you have admin access to SpiffArena. +![Configuration Section](images/Secrets_step_1.png) + +2. **Add New Secret**: Create a new secret by entering a key and its corresponding value. Once saved, the value will be encrypted. +![Secrets Section](images/Secrets_step_2.png) + +### Using Secrets in Service Tasks + +1. **Open the BPMN Diagram**: Open the diagram where you want to configure the service task. + +2. **Configure Service Task**: Click on the service task you want to configure and in the service properties panel, search for Operator ID that you want to add secret for and mention response variable to capture the result of the request. + +3. **Add Secret Reference**: In the parameters, you can reference the secret using the following format: + + ```xml + spiffworkflow:parameter id="headers" type="any" value="{ "Authorization": "Bearer SPIFF_SECRET:github_oauth" }" + ``` + + Here, `SPIFF_SECRET:github_oauth` will be replaced by the actual, unencrypted value from the database when the service task runs. +![Secrets Configuration](images/Secrets_configure_2.png) +--- + +Configuring secrets in SpiffArena provides a secure way to handle sensitive information in your BPMN diagrams. It allows you to make your processes public without exposing critical data, thereby enhancing both transparency and security. \ No newline at end of file diff --git a/docs/DevOps_installation_integration/images/Secrets_configure_2.png b/docs/DevOps_installation_integration/images/Secrets_configure_2.png new file mode 100644 index 00000000..cb2e288f Binary files /dev/null and b/docs/DevOps_installation_integration/images/Secrets_configure_2.png differ diff --git a/docs/DevOps_installation_integration/images/Secrets_step_1.png b/docs/DevOps_installation_integration/images/Secrets_step_1.png new file mode 100644 index 00000000..e947b94f Binary files /dev/null and b/docs/DevOps_installation_integration/images/Secrets_step_1.png differ diff --git a/docs/DevOps_installation_integration/images/Secrets_step_2.png b/docs/DevOps_installation_integration/images/Secrets_step_2.png new file mode 100644 index 00000000..e339d0ef Binary files /dev/null and b/docs/DevOps_installation_integration/images/Secrets_step_2.png differ diff --git a/docs/Getting_Started/images/Events.png b/docs/Getting_Started/images/Events.png new file mode 100644 index 00000000..79c52a65 Binary files /dev/null and b/docs/Getting_Started/images/Events.png differ diff --git a/docs/Getting_Started/images/Filter_icon.png b/docs/Getting_Started/images/Filter_icon.png new file mode 100644 index 00000000..8df08fe8 Binary files /dev/null and b/docs/Getting_Started/images/Filter_icon.png differ diff --git a/docs/Building_Diagrams/images/Login.png b/docs/Getting_Started/images/Login.png similarity index 100% rename from docs/Building_Diagrams/images/Login.png rename to docs/Getting_Started/images/Login.png diff --git a/docs/Getting_Started/quick_start.md b/docs/Getting_Started/quick_start.md index 1bcd6780..70aab6ab 100644 --- a/docs/Getting_Started/quick_start.md +++ b/docs/Getting_Started/quick_start.md @@ -9,9 +9,29 @@ ## 🚀 Getting Started with SpiffArena -SpiffArena is a platform that facilitates the execution of business processes. To begin using SpiffArena, you can create your demo account using spiffdemo as explained [here](https://spiff-arena.readthedocs.io/en/latest/UsingSpiffdemo/Getting_Started.html#how-to-login-to-spiffarena). +Sartography (the company developing SpiffWorkflow and SpiffArena) is providing users a platform to explore workflow concepts through a collection of examples, diagrams, and workflows. Users can interact with pre-built models, make modifications, and visualize process flows. -Here, we will provide a generic overview of each section step by step, allowing you to navigate and engage with the platform more effectively. +## How to Login to SpiffArena + +```{image} ./images/Login.png +:alt: Login Screen +:class: bg-primary mb-1 +:width: 230px +:align: right +``` +To begin your journey with SpiffArena, open your web browser and navigate to the SpiffArena website (Currently spiffdemo.org). + +On the login screen, you will find the option to log in using Single Sign-On. Click the Single Sign-On button and select your preferred login method, such as using your Gmail account. + + +```{admonition} Note: +Stay tuned as we expand our sign-on options beyond Gmail. +More ways to access SpiffArena are coming your way! +``` + +## How to Navigate through SpiffArena + +In this section, we will navigate through the platform and provide a generic overview of each section step by step, allowing you to understand and engage with the platform more effectively. ### Step 1: Explore the Home section @@ -20,7 +40,6 @@ Once you are signed in, you can start exploring the home page. The home page has ![Untitled](images/Untitled_2.png) - - The "In Progress" section provides an overview of all ongoing process instances, including those initiated by you, those awaiting your action, or those awaiting action from a team you are a member of (Optional). - The "Completed" section allows you to view all completed process instances, including those initiated by you, those initiated by other SpiffWorkflow users with tasks completed by you and if applicable, those with tasks completed by a group of which you are a member. - The “Start New” section displays the processes you are permitted to start according to your role. @@ -142,6 +161,8 @@ Click on the process instance you want to view. This will take you to the proces By following these steps, you can easily view the steps of the process you initiated and keep track of progress. + + --- ## 🏷️How to view the Process-defined metadata for a process instance @@ -204,6 +225,10 @@ Once you are signed in, navigate to the "Process Instances" section. Within the ![Untitled](images/Untitled_19.png) +If you are on a homepage, you can navigate to the table you wish to filter. Look for the black funnel icon in the top right-hand corner above the table and click on the Icon: By clicking on the filter icon, you'll be taken to a full-screen process view. + +![Filter Icon](images/Filter_icon.png) + ### Step 2: Click on Filter option To filter the list, click on the "Filter" option. This will expand the filter section where you will be able to provide details about the process instance. This allows you to enter various details, including the process model, start date, end date, and time. To refine your search, you can enter multiple filter parameters. @@ -251,3 +276,20 @@ If you want to filter by ID, go to the "Find by Id" section of the page. Enter t You can now view the process instances that you filtered for and take appropriate action based on their status. This can help you manage your workflows more efficiently and keep track of the progress of various process instances. + +## How to check Milestones and Events + +### Milestones +A milestone is a specific point in a process that signifies a significant event or state. It provides a high-level overview of the progress made in the process. + +In BPMN, if you draw an intermediate event and do not specify its type (like message, signal, start, or end) but give it a name, it becomes a milestone. Essentially, a milestone is an event that hasn't been set to something specific. + + +### Events +Events provide a detailed log of everything that happens in a process. They record every task and its execution time. + +![Events](images/Events.png) + +The events tab provides a detailed log of all the tasks and their execution times. It can be noisy due to the granularity of the information, but it's essential for understanding the intricacies of the process. + + diff --git a/docs/Support/Running_Server_Locally.md b/docs/Support/Running_Server_Locally.md new file mode 100644 index 00000000..59b568d9 --- /dev/null +++ b/docs/Support/Running_Server_Locally.md @@ -0,0 +1,52 @@ +# Troubleshooting: Running Server Locally + +When setting up the SpiffWorkflow backend project locally, you might encounter issues related to the `sample-process-models` directory. This documentation aims to address those concerns. + +## Problem + +While following the instructions provided in the repository to set up the SpiffWorkflow backend project locally, you may find that the script `./bin/run_server_locally` expects the `sample-process-models` directory to be present. However, this directory might not be immediately available in the repository. + +## Solutions + +### 1. Clone the `sample-process-models` Repository + +The `sample-process-models` directory refers to a separate repository. To resolve the issue: + +- Navigate to [https://github.com/sartography/sample-process-models](https://github.com/sartography/sample-process-models). + +- Clone the repository right next to `spiff-arena`. + +- Run the `./bin/run_server_locally` script. + +### 2. Use Any Git Repository + +If you prefer not to use the `sample-process-models` directory or want to start from scratch: + +- Locate or create a git repository. + +- Run the following command with the path to your chosen repository + + ``` + SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR=/path/to/any/git/repo ./bin/run_server_locally + ``` + +### 3. Use Docker Compose + +For a potentially faster setup: + +- Follow the guide at [https://www.spiffworkflow.org/posts/articles/get_started_docker](https://www.spiffworkflow.org/posts/articles/get_started_docker). + +- Use the provided commands to run the server with Docker Compose. + +### 4. Access Hosted Version of Spiff + +If you prefer not to install anything locally: + +- Navigate to [https://www.spiffworkflow.org/posts/articles/get_started](https://www.spiffworkflow.org/posts/articles/get_started). +- Access a version of Spiff hosted on the internet. + + + +Setting up the SpiffWorkflow backend project locally can be straightforward once you're aware of the dependencies and options available. Whether you choose to clone the `sample-process-models` repository, use a different git repository, or opt for Docker Compose, the solutions provided should help you get started without any hitches. + +If you encounter further issues, always refer back to the repository's README or seek assistance from our discord community. \ No newline at end of file diff --git a/docs/Support/Welcome_Messages.md b/docs/Support/Welcome_Messages.md new file mode 100644 index 00000000..4f898702 --- /dev/null +++ b/docs/Support/Welcome_Messages.md @@ -0,0 +1,36 @@ +# Welcome Messages in SpiffWorkflow + +## Introduction + +The welcome message is the greeting users see when they log into the platform. It sets the tone for their experience and can be customized to fit the needs of your organization or specific user groups. By customizing the welcome message, **administrators** can tailor the user experience, making it more personalized and relevant to the audience. + +This guide will walk you through the steps to modify this message in SpiffWorkflow. + +## Steps to Update the Welcome Message + +1. **Open the Process:** +Navigate to the onboarding process model within SpiffWorkflow. + + ![Process Model](images/onboarding_1.png) + +2. **Access the `welcome.bpmn` File:** + This is the specific file where the welcome message is configured. Ensure you're at the path `siteadministration.onboarding`. This path is crucial as it's the trigger for the welcome message. + + ![Access Welcome file](images/onboarding_2.png) + + +4. **Locate the End Event:** + The end event within this process contains the welcome message. Any message configured in this end event will be displayed to users upon login. + + ![Click End Event](images/onboarding_3.png) + + +5. **Launch the Editor:** + Use the built-in editor to modify the content of the welcome message. Ensure that your changes are clear, concise, and welcoming to provide users with a positive experience. + + ![Launching Editor](images/onboarding_4.png) + + After making your desired modifications, save the changes to update the welcome message. + + +Once you've updated the welcome message, it will be displayed prominently on the home page after users log in. The message will be positioned in a way that it's one of the first things users see, ensuring they receive the intended greeting every time they access the platform. \ No newline at end of file diff --git a/docs/Support/images/onboarding_1.png b/docs/Support/images/onboarding_1.png new file mode 100644 index 00000000..93109eb0 Binary files /dev/null and b/docs/Support/images/onboarding_1.png differ diff --git a/docs/Support/images/onboarding_2.png b/docs/Support/images/onboarding_2.png new file mode 100644 index 00000000..7316e794 Binary files /dev/null and b/docs/Support/images/onboarding_2.png differ diff --git a/docs/Support/images/onboarding_3.png b/docs/Support/images/onboarding_3.png new file mode 100644 index 00000000..0ae9dac5 Binary files /dev/null and b/docs/Support/images/onboarding_3.png differ diff --git a/docs/Support/images/onboarding_4.png b/docs/Support/images/onboarding_4.png new file mode 100644 index 00000000..757e01b7 Binary files /dev/null and b/docs/Support/images/onboarding_4.png differ diff --git a/docs/index.md b/docs/index.md index a173e73f..04e7b864 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,6 @@ Getting_Started/quick_start.md ```{toctree} :maxdepth: 1 :caption: Building Diagrams -Building_Diagrams/Using_SpiffArena.md Building_Diagrams/learn_basics.md Building_Diagrams/bpmn.md Building_Diagrams/Forms.md @@ -23,6 +22,7 @@ Building_Diagrams/data_objects.md Building_Diagrams/dmn.md Building_Diagrams/Extensions.md Building_Diagrams/pools_and_lanes.md +Building_Diagrams/Builtin_examples.md ``` ```{toctree} @@ -39,12 +39,15 @@ DevOps_installation_integration/admin_and_permissions.md DevOps_installation_integration/permission_url.md DevOps_installation_integration/configure_connector_proxy.md DevOps_installation_integration/deploy_aws_lambda.md +DevOps_installation_integration/Secrets.md ``` ```{toctree} :maxdepth: 1 -:caption: Support +:caption: Support & Administration Support/suspend_resume_terminate.md +Support/Running_Server_Locally.md +Support/Welcome_Messages.md ``` ```{toctree}