Merge remote-tracking branch 'origin/main' into feature/support_macros_in_permission_yaml

.github/workflows/backend_tests.yml

@@ -75,7 +75,7 @@ jobs:
               database: "sqlite",
             }
           - { python: "3.11", os: "ubuntu-latest", session: "xdoctest" }
-          - { python: "3.11", os: "ubuntu-latest", session: "docs-build" }
+          # - { python: "3.11", os: "ubuntu-latest", session: "docs-build" }
 
     env:
       FLASK_SESSION_SECRET_KEY: super_secret_key
@@ -119,20 +119,23 @@ jobs:
           pipx inject --pip-args=--constraint=.github/workflows/constraints.txt nox nox-poetry
           nox --version
 
-      - name: Checkout Samples
+      # when we get an imcompatible sqlite migration again and need to combine all migrations into one for the benefit of sqlite
-        if: matrix.database == 'sqlite'
+      # see if we can get the sqlite-specific block in the noxfile.py to work instead of this block in the github workflow,
-        uses: actions/checkout@v3
+      # which annoyingly runs python setup outside of the nox environment (which seems to be flakier on poetry install).
-        with:
+      # - name: Checkout Samples
-          repository: sartography/sample-process-models
+      #   if: matrix.database == 'sqlite'
-          path: sample-process-models
+      #   uses: actions/checkout@v3
-      - name: Poetry Install
+      #   with:
-        if: matrix.database == 'sqlite'
+      #     repository: sartography/sample-process-models
-        run: poetry install
+      #     path: sample-process-models
-      - name: Setup sqlite
+      # - name: Poetry Install
-        if: matrix.database == 'sqlite'
+      #   if: matrix.database == 'sqlite'
-        env:
+      #   run: poetry install
-          SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR: "${GITHUB_WORKSPACE}/sample-process-models"
+      # - name: Setup sqlite
-        run: ./bin/recreate_db clean rmall
+      #   if: matrix.database == 'sqlite'
+      #   env:
+      #     SPIFFWORKFLOW_BACKEND_BPMN_SPEC_ABSOLUTE_DIR: "${GITHUB_WORKSPACE}/sample-process-models"
+      #   run: ./bin/recreate_db clean rmall
 
       - name: Setup Mysql
         uses: mirromutth/mysql-action@v1.1
@@ -162,13 +165,13 @@ jobs:
           name: coverage-data
           path: "spiffworkflow-backend/.coverage.*"
 
-      - name: Upload documentation
+      # - name: Upload documentation
-        if: matrix.session == 'docs-build'
+      #   if: matrix.session == 'docs-build'
-        uses: actions/upload-artifact@v3
+      #   uses: actions/upload-artifact@v3
-        with:
+      #   with:
-          name: docs
+      #     name: docs
-          path: docs/_build
+      #     path: docs/_build
-
+      #
       - name: Upload logs
         if: failure() && matrix.session == 'tests'
         uses: "actions/upload-artifact@v3"

.github/workflows/frontend_tests.yml

@@ -91,6 +91,11 @@ jobs:
       - name: wait_for_keycloak
         working-directory: ./spiffworkflow-backend
         run: ./keycloak/bin/wait_for_keycloak 5
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: |
+          echo "$GITHUB_CONTEXT"
       - name: Cypress run
         uses: cypress-io/github-action@v5
         with:

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/.gitignore

@@ -0,0 +1,3 @@
+_build
+.venv
+.vscode

docs/.markdownlint.jsonc

@@ -0,0 +1,5 @@
+{
+  "default": true,
+  "MD013": false,
+  "whitespace": false
+}

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,35 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'SpiffWorkflow'
+copyright = '2023, Sartography'
+author = 'Sartography' # Very ok to add your name here.
+release = '0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['myst_parser']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.venv']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+#html_theme = 'alabaster'
+html_theme = "sphinx_rtd_theme"
+html_static_path = ['static']
+html_logo = "spiffworkflow_logo.png"
+html_theme_options = {
+    'logo_only': True,
+    'display_version': False,
+}
+html_css_files = ["custom.css"]

docs/documentation/documentation.md

@@ -0,0 +1,147 @@
+# How to Contribute to the Documentation
+
+This documentation is currently hosted live at [Spiff-Arena's ReadTheDocs](https://spiff-arena.readthedocs.io/en/latest/)
+
+Please set aside a couple of hours to work through this, as getting this setup correctly once is 10,000 times better than having problems every day for the rest of your life.
+
+## Our Methodology 
+
+The methodology we are following is known as ["Docs as Code"](https://www.writethedocs.org/guide/docs-as-code/).
+
+This means using the same tools and processes that software developers use for writing code to write the documentation for code.
+In following this methodology, you will have to pick up some tools you haven't had to use before (Git, Sphinx).
+Why would a technical writer need to learn these software engineering tools?
+I'll never make the case as well as an article by [Tom Johnson](https://idratherbewriting.com/trends/trends-to-follow-or-forget-docs-as-code.html).
+
+You might notice, when looking at the markdown files, that every sentence starts on a new line.
+Like this one.
+Unless there is a blank line between sentences, Markdown will still render this as a paragraph.
+This is called [Ventilated Prose](https://vanemden.wordpress.com/2009/01/01/ventilated-prose/) and can be very helpful when working in Markdown.
+
+
+## Our Tools
+
+[Markdown](https://www.markdownguide.org/getting-started/) is a "markup language that you can use to add formatting elements to plain text documents."
+You won't be writing the documentation in a word processor, but in simple plain text, and some special syntax that will consistently and professionally format that text.  
+
+The basic Markdown syntax is very simple.
+Here are some [quick examples](https://commonmark.org/help/). And here is a great [10 minute tutorial](https://commonmark.org/help/tutorial/).
+This will cover a lot of the basics, like bolding text, italics, paragraphs, lists and other common formatting techniques.
+
+![Markdown screenshot](./images/markdown.png "Markdown example")
+
+### MyST
+
+Markdown doesn't support some really useful things.
+You can't add footnotes, or create an "aside" comment or build a table.
+Because of this, there are many extensions, and these are typically referred to as Markdown "Flavors."
+The flavor we are using is MyST.
+There is [excellent documentation on MyST](https://myst-parser.readthedocs.io/en/v0.13.5/using/syntax.html) that you should definitely review, so you know everything that is available to you.
+
+
+### Sphinx
+
+This is a large documentation effort.
+Many different Markdown pages will together make up the full website.
+
+You will mostly use Sphinx in the background - you won't be aware of it.
+But if you decide that you want to alter the theme (the colors, styles, etc...) of the final website, Sphinx controls this and offers [themes](https://sphinx-themes.org/) and the ability to change styles / colors and formatting through the site.
+You just need to learn a little CSS to control it.
+
+
+### GitHub
+
+Our project is managed by a version control system called Git.
+You can use GIT to submit changes to the documentation, in the same we use to submit changes to our code.
+It is available on GitHub as the [spiff-arena project](https://github.com/sartography/spiff-arena).
+GitHub also manages versions of the code and handles running tests.
+Readthedocs observes changes in git and manages an automated process that causes our documentation to be built and deployed.
+It will take a bit to get comfortable with Git, but when you do, you will come to love it (or maybe hate it, but with a lot of respect).
+
+## Setup
+
+So that's a lot of tools, and seemingly a lot to learn.
+But you will find that most of it just works - and that once you get into a regular flow, it will become second nature.
+
+
+### Step 1:  Pre-Requisites
+Assure you have been granted write access to our git repository.
+Make sure you have an account on GitHub and then contact dan@sartography.com and ask him to add you as a contributor.
+
+
+### Step 2:  Install VSCode
+[Download VSCode](https://code.visualstudio.com/) and install it on your computer.
+
+### Step 3: Install Python 
+We need python in order to build the website locally so we can really see what our content is going to look like once we publish.
+It's going to be handy for other reasons as well.
+We'll want python to be properly set up inside of VS Code.
+Follow [these directions and brief tutorial](https://code.visualstudio.com/docs/python/python-tutorial) to assure this is set up.
+
+
+### Step 3: Connect VSCode to Git
+VSCode comes with Git built in.
+So you can use VSCode to "pull" changes from others down to your local computer and "push" changes back up to share with others (and to cause our docs site to rebuild).
+
+Here are directions for how to [clone Spiff-Arena](https://learn.microsoft.com/en-us/azure/developer/javascript/how-to/with-visual-studio-code/clone-github-repository?tabs=create-repo-command-palette%2Cinitialize-repo-activity-bar%2Ccreate-branch-command-palette%2Ccommit-changes-command-palette%2Cpush-command-palette#clone-repository).
+**IMPORTANT**: Follow those directions, but be sure to checkout https://github.com/sartography/spiff-arena instead of the project they are using!
+
+You can save the project to any directory on your computer.
+We strongly suggest you create a sub-folder called "projects" in your "home" or "Desktop" folder and checkout the code into this directory.  
+
+### Step 4: Open just the Docs Folder
+
+We've checked out the whole spiff-arena project, but we are only going to be working inside of the docs directory.
+So let's open just that folder in VSCode.
+
+* Go to File -> Open Folder 
+* Select the "docs" folder inside of spiff-arena.
+
+Now clikc on the two pieces of paper at the top corner of your screen, and you should see a project that looks like this without all the rest of the code in your way:
+
+![Docs Directory](./images/docs_dir.png "Docs Directory")
+
+
+### Step 4: Add some extensions
+  * Inside VSCode, go to File -> Preferences -> Extensions
+  * Search for "myst"
+  * click the "install" button.
+  * Repeat, this time doing it for "python extension for VS Code"
+
+![Myst Extension](./images/myst.png "Search or MyST in extensions")
+
+
+### Step 5: Install Python Dependencies
+This project requires a few Python dependencies to work correctly.
+We are going to set up a Virtual Environment for Python to keep us sane later on.
+You can do that by following these steps:
+
+1. Open the Command Palette (Ctrl+Shift+P), start typing the **Python: Create Environment** command to search, and then select the command. 
+1. Select **Venv**
+1. Select Python 3.11 from the list of options if there is nore than one thing to select.
+1. Be sure the the checkbox next to "requirements.txt" is selected. 
+1. Click OK.
+
+### Step 6: Fire up the website
+1. Go to Terminal ->  New Terminal
+1. type:  **sphinx-autobuild . _build/html** at the prompt and hit enter.
+1. Open your browser and go to http://127.0.0.1:8000
+
+
+### Step 7:  Make a change
+1. Open up a markdown file, and make a change. 
+
+### Step 8:  Commit your changes and push them up for everyone.
+1. Select the "git" button on the left hand side of the toolbar (circles with lines between them) ![Git button](./images/git.png "Git button") 
+
+2. Press the blue "Commit" button.
+
+3. Any changes you pushed up should be live on our website within 5 to 10 minutes.
+
+## Linting
+
+Documentation people: please ignore this for now.
+
+We may decide to check the documentation with a "linter" which is designed to keep the documentation consistent and standardized.
+One option is https://github.com/igorshubovych/markdownlint-cli, which uses https://github.com/DavidAnson/markdownlint, which seems to be more popular than https://github.com/markdownlint/markdownlint.
+A `.markdownlint.jsonc` file has been added that configures the same markdownlint program (basically to ignore the rule about long lines, since we are using ventilated prose).

docs/index.md

@@ -0,0 +1,18 @@
+Welcome to SpiffWorkflow's documentation!
+=======================================
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+quick_start/quick_start.md
+documentation/documentation.md
+```
+
+This is great!
+
+Indices and tables
+==================
+
+* [](genindex)
+* [](modindex)
+* [](search)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/quick_start/quick_start.md

@@ -0,0 +1,306 @@
+# Quick start guide
+
+```{admonition} Welcome to the SpiffWorkflow quick start guide!
+:class: info
+
+👇 Throughout this step-by-step guide, we will walk you through key components of SpiffWorkflow, ensuring that you have a clear understanding of how to use the platform effectively.
+```
+
+
+## 🚀 Getting Started with SpiffWorkflow
+
+SpiffWorkflow is a platform that facilitates the execution of business processes performed within the Status platform.
+
+To access SpiffWorkflow, simply sign in using your Keycloak account. Once you have successfully signed in to the Spiff platform, it is crucial to familiarize yourself with the various sections within the SpiffWorkflow. This will enable you to gain a comprehensive understanding of the interface. 
+
+```{image} images/Untitled.png
+:alt: Login Page
+:width: 45%
+```
+```{image} images/Untitled_1.png
+:alt: Home Page
+:width: 45%
+```
+
+```{admonition} Signing In
+:class: warning
+
+⚠️ In the event that you encounter any difficulties signing in to Spiff, please reach out to Jakub (**@jakubgs**) on Discord for assistance and further guidance.
+```
+
+Here, we will provide a generic overview of each section step by step, allowing you to navigate and engage with the platform more effectively.
+
+### Step 1: Explore the Home section
+
+Once you are signed in, you can start exploring the home page. The home page has three tab sections: **In Progress**, **Completed** and **Start New**.  
+
+![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.
+
+```{admonition} Signing In
+:class: info
+💡 **Process:** A process is a sequence of tasks that must be completed to achieve a specific goal.
+
+**Instance:** An instance, on the other hand, represents a specific occurrence of a process. Each instance has its own set of data and state that is updated as the instance progresses through the workflow.
+```
+
+If you are a member of a team, you may also have one or more Instances with tasks waiting for [team name] lists as well.
+
+![Untitled](images/Untitled_3.png)
+
+### Step 2: Explore the Processes section
+
+
+The process section provides a comprehensive view of the process ecosystem by showcasing process groups and process models. 
+
+```{admonition} Process Groups
+:class: info
+💡 A **process group** is a way of grouping a bunch of **process models.** A **process model** contains all the files necessary to execute a specific process.
+```
+-- 
+![Untitled](images/Untitled_4.png)
+
+### Step 3: Explore the Process Instances section
+
+The Process Instance section provides a detailed view of individual process instances, allowing you to track their progress and manage them effectively. This section includes essential information such as the instance ID, process name, the individual who started the process, the end date, and the current status. 
+
+![Untitled](images/Untitled_5.png)
+
+```{admonition} Desktop Notifications
+:class: info
+💡 To receive SpiffWorkflow notifications in StatusApp Desktop, Public key from your Status account should be added to your **Bamboo profile**. This will ensure that workflow-related notifications are sent to you.
+
+```
+
+When getting started with SpiffWorkflow, it's essential to take the time to explore and familiarize yourself with the platform's interface and features. Feel free to ask questions about the platform's features or how to get started. The PPG team is always on hand to provide assistance and support when needed. 
+
+---
+
+## 🌱 How to Start a Process
+
+With SpiffWorkflow, you can easily initiate a new process instance. Here's a step-by-step guide on how to start a process.
+
+### Step 1: Sign in and navigate to Home section
+
+The first thing you need to do is sign in to your account on SpiffWorkflow. Once you're signed in, you'll see three tabs in the Home section: In progress, Completed, and Start New. If you want to start a new process, click the "Start New +" button. This will bring up "Processes I can start" section.
+
+![Untitled](images/Untitled_6.png)
+
+```{admonition} The Landing Page
+:class: info
+💡 The landing page will be the **Home section** by default, and you can navigate to other sections.
+```
+
+### Step 2: Select the process
+
+Next, you will see a list of available processes that you have permission to start. Choose the process you want to initiate and click “Start”.
+
+![Untitled](images/Untitled_7.png)
+
+Congratulations! You have successfully started a new process instance in SpiffWorkflow.
+
+---
+
+## 🔄 How to respond to a request
+
+When using SpiffWorkflow, knowing how to respond to requests is essential to the process. While each request may have unique requirements, the basic steps for responding are similar. The following steps will guide you through the process of responding to requests.
+
+### Step 1: Navigate to the home page
+
+Once you are signed in, navigate to the home page of SpiffWorkflow. On the home page, you will see a list of all the requests that are available to you.  
+
+There will be three types of instances shown: 
+
+- **Started by me:** This section shows a list of process instances that were started by you, providing you with an overview of the instances you have initiated.
+- **Waiting for me:** This section displays a list of process instances with tasks assigned to you and are currently waiting for you to respond to.
+- **Waiting for [team name]:** If you are a member of SpiffWorkflow**,** this section displays a list of process instances with tasks assigned to a group you are a member of and currently waiting for someone in that group to complete them.
+
+![Untitled](images/Untitled_8.png)
+
+In the case of new users who haven't started or been part of any process or been assigned to any team, you won't be able to see any items on the home page.
+
+![Untitled](images/Untitled_9.png)
+
+### Step 2: Respond to the request
+
+Once you have identified the request you need to respond to, simply click on the 'Go' button in the action column to open it. Upon opening the process instance, you can respond to the request based on the requirements of that task. 
+
+Depending on the task requirements, this may involve submitting additional information, reviewing the task or any other action item.
+
+![Untitled](images/Untitled_10.png)
+
+That's it! With these simple steps, you can efficiently review tasks in SpiffWorkflow.
+
+---
+
+## 📑 How to view process steps for the process you just started
+
+After starting a process, it's important to stay informed about its progress. Even though you'll receive notifications when your attention is required, it's natural to be curious about what's happening in the background. Therefore, monitoring the process steps regularly is a great way to ensure everything is moving smoothly.
+
+Here's how you can view the steps of the process you just started.
+
+### Step 1: Navigate to the “Home” or “Process Instance” section.
+
+There are 2 ways of finding your process instances.
+
+Option 1: Once you're signed in, navigate to the home section. Here you will find a list of all the processes instances you've initiated.
+
+![Untitled](images/Untitled_11.png)
+
+Option 2: You can also view the processes you have initiated in the **"Process Instances"** section.
+
+![Untitled](images/Untitled_12.png)
+
+### Step 2: Select the process instance you want to view
+
+Click on the process instance you want to view. This will take you to the process instance information. Navigate to the BPMN diagram section. Here you can see the current task highlighted in **yellow**. The grey represents the path which was taken by the current process steps.
+
+![Untitled](images/Untitled_13.png)
+
+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
+
+The Process-defined **metadata can provide valuable insights into its history, current status, and other important details that is specifically created and used within a particular process. With the SpiffWorkflow platform, users can easily view the metadata for a process instance.
+
+To check the metadata of a process instance, follow these steps.
+
+### Step 1: Navigate to the “Home” or “Process Instance” section.
+
+Once you're signed in, navigate to the home section. Here you will find a list of all the process instances you've initiated under **“Started by me”**.
+
+![Untitled](images/Untitled_14.png)
+
+### Step 2: View metadata for the selected process instance
+
+Click on the process instance you want to view. Upon clicking this, you will be able to view the information about the given instance. You'll find the metadata under the details option in the process instance.
+
+![Untitled](images/Untitled_15.png)
+
+By following these simple steps, you can easily view the metadata for a process instance in SpiffWorkflow.
+
+---
+
+## 📂 How to view Process Model files
+
+The process model files provide great transparency into our internal business rules and processes.  You can dig deep into the decision-making process and really understand how the process and organization operate. With these steps, you'll be able to access process models easily and efficiently.
+
+### Step 1: Head over to the process section
+
+Once you have successfully signed in, navigate to the process section. This section allows you to access all the process groups and process models you have access to.
+
+![Untitled](images/Untitled_16.png)
+
+> **Step 2: Find and click on the process**
+> 
+
+You can either search for a process model using the search bar or navigate through displayed processes to find the process model.
+
+![Untitled](images/Untitled_17.png)
+
+### Step 3: Access the process model files
+
+Once you have clicked on the process you want to view, a list of the model files that are associated with the process will appear. 
+
+![Untitled](images/Untitled_18.png)
+
+By following these simple steps, you can easily view process model files in SpiffWorkflow.
+
+---
+
+## 🔍 How to view and filter process instances
+
+As you work on various process instances in SpiffWorkflow, you may want to view and filter some of them. This can help you track the status of various instances and manage them more efficiently. 
+
+Here are the steps to view and filter process instances in SpiffWorkflow.
+
+### Step 1: Navigate to Process Instances
+
+Once you are signed in, navigate to the "Process Instances" section. Within the "Process Instances" section, you'll see a list of all the instances for the processes you can access.
+
+![Untitled](images/Untitled_19.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.
+
+![Untitled](images/Untitled_20.png)
+
+### Step 3: Apply Filters:
+
+Once you have entered all the relevant filter details, click on the "**Apply**" button to apply the filters. The system will then display all the process instances matching the input details.
+
+![Untitled](images/Untitled_21.png)
+
+To filter process instances by **process-defined metadata**, follow these steps:
+
+- Search for the specific **process** you want to filter and click on the column option to select metadata options.
+
+![Untitled](images/Untitled_22.png)
+
+- The metadata fields will be displayed in dropdown. Select the field you want to display and Click on "**Save**" to apply the changes.
+
+![Untitled](images/Untitled_23.png)
+
+- After saving the details, the newly created column will be displayed. Finally click on “**Apply“** button to reflect the changes.
+
+![Untitled](images/Untitled_24.png)
+
+### (Optional) Step 4: Save Perspectives
+
+If you wish to save the perspectives, click on the "**Save**" button. 
+
+![Untitled](images/Untitled_25.png)
+
+A prompt will appear, allowing you to provide a name for the identifier associated with the saved filter. Enter a descriptive name for the filter identifier and “**Save”** changes. Now you can search for specific processes using Process Instance Perspectives.
+
+![Untitled](images/Untitled_26.png)
+
+![Untitled](images/Untitled_27.png)
+
+### (Optional) Step 5: Filter by ID
+
+![Untitled](images/Untitled_28.png)
+
+If you want to filter by ID, go to the "Find by Id" section of the page. Enter the ID and click "Submit". The system will show you the process instance with the corresponding ID.
+
+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 request additional permissions
+
+As a user, you may be required to access certain process groups or start process models in order to perform desired actions. However, you may not have the necessary access or permissions to do so. In this case, you will need to request access or additional permissions from the admins - PPG team. 
+
+By following these steps, you can submit a request and seek the necessary permissions to perform the desired actions.
+
+### Step 1: Navigate & Search
+
+Once you are signed in, navigate to the "**Process**" section. Use the search bar or browse through the available process models until you find "**Request Access**”. Click on the process model to open it. 
+
+![Untitled](images/Untitled_29.png)
+
+If you want to access the request access process from **Home** section and click on the "**Start New +**" button. This will open the "Processes I can start" section where you can find the “Request Access” process.
+
+![Untitled](images/Untitled_30.png)
+
+### Step 2: Start the Process
+
+Once the "**Process Request**" model is open, initiate the process by clicking on the "Start" button.
+
+![Untitled](images/Untitled_31.png)
+
+### Step 3: Provide Request Details & Submit
+
+A task will be presented to capture the necessary information and details for special permissions request. Find the “**Description”** text field and enter the relevant information and details about your request.
+
+Ensure that all required details have been included such as Process name, Process group name, and type of permissions you need. Click on the "**Submit**" button or similar action to submit your access or special permissions request.
+
+![Untitled](images/Untitled_32.png)
+
+By following these steps, you can request the special permissions needed to carry out your tasks effectively.

docs/requirements.txt

@@ -0,0 +1,46 @@
+alabaster==0.7.13
+appdirs==1.4.4
+astroid==2.15.5
+attrs==23.1.0
+Babel==2.12.1
+cattrs==22.2.0
+certifi==2023.5.7
+charset-normalizer==3.1.0
+colorama==0.4.6
+docutils==0.18.1
+esbonio==0.16.1
+idna==3.4
+imagesize==1.4.1
+Jinja2==3.1.2
+lazy-object-proxy==1.9.0
+livereload==2.6.3
+lsprotocol==2023.0.0a1
+markdown-it-py==2.2.0
+MarkupSafe==2.1.2
+mdit-py-plugins==0.3.5
+mdurl==0.1.2
+myst-parser==1.0.0
+packaging==23.1
+pygls==1.0.2
+Pygments==2.15.1
+pyspellchecker==0.7.2
+PyYAML==6.0
+requests==2.30.0
+six==1.16.0
+snowballstemmer==2.2.0
+Sphinx==6.2.1
+sphinx-autoapi==2.1.0
+sphinx-autobuild==2021.3.14
+sphinx-rtd-theme==1.2.0
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+tornado==6.3.2
+typeguard==3.0.2
+Unidecode==1.3.6
+urllib3==2.0.2
+wrapt==1.15.0

spiffworkflow-backend/noxfile.py

@@ -41,6 +41,18 @@ def setup_database(session: Session) -> None:
     session.env[flask_env_key] = "e7711a3ba96c46c68e084a86952de16f"
     session.env["FLASK_APP"] = "src/spiffworkflow_backend"
     session.env["SPIFFWORKFLOW_BACKEND_ENV"] = "unit_testing"
+
+    if os.environ.get("SPIFFWORKFLOW_BACKEND_DATABASE_TYPE") == "sqlite":
+        # maybe replace this sqlite-specific block with ./bin/recreate_db clean rmall
+        # (if we can make it work, since it uses poetry),
+        # which would also remove the migrations folder and re-create things as a single migration
+        if os.path.exists("migrations"):
+            import shutil
+
+            shutil.rmtree("migrations")
+        for task in ["init", "migrate"]:
+            session.run("flask", "db", task)
+
     session.run("flask", "db", "upgrade")
 
 

spiffworkflow-backend/pyproject.toml

@@ -31,7 +31,7 @@ SpiffWorkflow = {git = "https://github.com/sartography/SpiffWorkflow", rev = "ma
 # SpiffWorkflow = {git = "https://github.com/sartography/SpiffWorkflow", rev = "6cad2981712bb61eca23af1adfafce02d3277cb9"}
 # SpiffWorkflow = {develop = true, path = "../../spiffworkflow/" }
 sentry-sdk = "^1.10"
-sphinx-autoapi = "^2.0"
+# sphinx-autoapi = "^2.0"
 mysql-connector-python = "*"
 pytest-flask = "^1.2.0"
 pytest-flask-sqlalchemy = "^1.1.0"
@@ -93,8 +93,8 @@ safety = "^2.3.1"
 mypy = ">=0.961"
 typeguard = "^3"
 xdoctest = {extras = ["colors"], version = "^1.0.1"}
-sphinx = "^5.0.2"
+# sphinx = "^5.0.2"
-sphinx-autobuild = ">=2021.3.14"
+# sphinx-autobuild = ">=2021.3.14"
 pre-commit = "^2.20.0"
 flake8 = "^4.0.1"
 black = ">=21.10b0"
@@ -111,10 +111,10 @@ pep8-naming = "^0.13.2"
 darglint = "^1.8.1"
 reorder-python-imports = "^3.9.0"
 pre-commit-hooks = "^4.0.1"
-sphinx-click = "^4.3.0"
+# sphinx-click = "^4.3.0"
 Pygments = "^2.10.0"
 pyupgrade = "^3.1.0"
-furo = ">=2021.11.12"
+# furo = ">=2021.11.12"
 
 [tool.poetry.scripts]
 spiffworkflow-backend = "spiffworkflow_backend.__main__:main"

spiffworkflow-frontend/cypress/pilot/NDR_PP1/initiaterequest.cy.js

@@ -847,6 +847,251 @@ describe.only('Initiate a Request - Without Files', () => {
   });
 });
 
+// Form validation - Software and License - Without Files
+describe('Form validation', () => {
+
+  //Special character check
+  it('Special character check', () => {
+    const username = Cypress.env('requestor_username');
+    const password = Cypress.env('requestor_password');
+    cy.log(`=====username : ${username}`);
+    cy.log(`=====password : ${password}`);
+
+    cy.login(username, password);
+    cy.visit('/');
+
+    cy.contains('Start New +').click();
+    cy.contains('Request Goods or Services').click();
+
+    cy.runPrimaryBpmnFile(true);
+
+    /*            cy.contains('Please select the type of request to start the process.');
+                      // wait a second to ensure we can click the radio button
+          
+                      cy.wait(2000);
+                      cy.get('input#root-procurement').click();
+                      cy.wait(2000);
+          
+          
+                      cy.get('button')
+                          .contains(/^Submit$/)
+                          .click();
+          */
+
+    cy.contains('Request Goods or Services', { timeout: 60000 });
+
+    cy.url().then((currentUrl) => {
+      // if url is "/tasks/8/d37c2f0f-016a-4066-b669-e0925b759560"
+      // extract the digits after /tasks
+      const processInstanceId = currentUrl.match(/(?<=\/tasks\/)\d+/)[0];
+      cy.log('==###############===processInstanceId : ', processInstanceId);
+      const projectId = Cypress.env('project_id');
+      cy.wait(2000);
+      cy.get('#root_project').select(projectId);
+      cy.get('#root_category').select('soft_and_lic');
+      cy.get('#root_purpose')
+        .clear()
+        .type(
+          'Purpose is to test all the special characters work in the request. ~!@#$%^&*()_+`-= {}[]\ and ;\',./:"<>? end. | this text goes missing', { parseSpecialCharSequences: false }
+        );
+        //.type(
+        //  'Purpose is to test all the special characters work in the request. Test Special chars ~!@#$%^&*()_+`-= {}|[]\ and ;\',./:"<>? end.', { parseSpecialCharSequences: false }
+        //);
+      cy.get('#root_criticality').select('High');
+      cy.get('#root_period').clear().type('25-11-2025');
+      cy.get('body').click();
+      cy.get('#root_vendor').clear().type('Microsoft');
+      cy.get('#root_payment_method').select('Reimbursement');
+      /* cy.get('button')
+                    .contains(/^Submit$/)
+                    .click();
+
+                cy.contains('Task: Enter NDR Items', { timeout: 60000 });
+*/
+      // item 0
+      cy.get('#root_item_0_sub_category').select('op_src');
+      cy.get('#root_item_0_item_name')
+        .clear()
+        .type(
+          'Special char test ,./;\'[]\=-0987654321`~!@#$%^&*()_+{}:"<>? end.', { parseSpecialCharSequences: false }
+        );
+        //.type(
+        //  'Special char test ,./;\'[]\=-0987654321`~!@#$%^&*()_+{}|:"<>? end.', { parseSpecialCharSequences: false }
+        // );
+      cy.get('#root_item_0_qty').clear().type('2');
+      cy.get('#root_item_0_currency_type').select('Crypto');
+      cy.get('#root_item_0_currency').select('SNT');
+      cy.get('#root_item_0_unit_price').type('1915');
+
+      cy.get('#root_item > div:nth-child(3) > p > button').click();
+
+      // item 1
+      cy.get('#root_item_1_sub_category').select('lic_and_sub');
+      cy.get('#root_item_1_item_name')
+        .clear()
+        .type(
+          'Special char test 2 +_=)(*&^%$#@!~`?></.,":}{\][\';/., <a> {g} [a]end.', { parseSpecialCharSequences: false }
+        );
+        //.type(
+        //  'Special char test 2 +_=)(*&^%$#@!~`?></.,":}{|\][\';/., <a> {g} [a]end.', { parseSpecialCharSequences: false }
+        //);
+      cy.get('#root_item_1_qty').clear().type('1');
+      cy.get('#root_item_1_currency_type').select('Fiat');
+      cy.get('#root_item_1_currency').select('AED');
+      cy.get('#root_item_1_unit_price').type('4500');
+
+      cy.get('button')
+        .contains(/^Submit$/)
+        .click();
+
+      cy.contains(
+        'Review and provide any supporting information or files for your request.',
+        { timeout: 60000 }
+      );
+
+      cy.get('.cds--text-area__wrapper')
+        .find('#root')
+        .type(
+          'Test Special chars afs<sfsd>sfsfs,asfdf. sfsf? sfd/sfs f:sfsf " sfsdf; SDFfsd\' sfsdf{sfsfs} sfsdf[ sfsdf] fsfsfd\ sfsd sfsdf=S dfs+ sfd- sfsdf_ sfsfd (sfsd )sfsfsd * sf&sfsfs ^ sfs % sf $ ss# s@ sf! sfd` ss~ END.', { parseSpecialCharSequences: false }
+        );
+        //.type(
+        //  'Test Special chars afs<sfsd>sfsfs,asfdf. sfsf? sfd/sfs f:sfsf " sfsdf; SDFfsd\' sfsdf{sfsfs} sfsdf[ sfsdf] fsfsfd\ sfsd| sfsdf=S dfs+ sfd- sfsdf_ sfsfd (sfsd )sfsfsd * sf&sfsfs ^ sfs % sf $ ss# s@ sf! sfd` ss~ END.', { parseSpecialCharSequences: false }
+        //);
+
+      // cy.contains('Submit the Request').click();
+
+      // cy.get('input[value="Submit the Request"]').click();
+
+      cy.get('button')
+        .contains(/^Submit$/)
+        .click();
+
+      cy.get('button')
+        .contains(/^Return to Home$/)
+        .click();
+
+      cy.contains('Started by me', { timeout: 60000 });
+      cy.logout();
+      cy.wait(2000);
+    });
+  });
+
+  //Check field max lengths
+  it.only('Check field max lengths', () => {
+    const username = Cypress.env('requestor_username');
+    const password = Cypress.env('requestor_password');
+    cy.log(`=====username : ${username}`);
+    cy.log(`=====password : ${password}`);
+
+    cy.login(username, password);
+    cy.visit('/');
+
+    cy.contains('Start New +').click();
+    cy.contains('Request Goods or Services').click();
+
+    cy.runPrimaryBpmnFile(true);
+
+    /*            cy.contains('Please select the type of request to start the process.');
+                      // wait a second to ensure we can click the radio button
+          
+                      cy.wait(2000);
+                      cy.get('input#root-procurement').click();
+                      cy.wait(2000);
+          
+          
+                      cy.get('button')
+                          .contains(/^Submit$/)
+                          .click();
+          */
+
+    cy.contains('Request Goods or Services', { timeout: 60000 });
+
+    cy.url().then((currentUrl) => {
+      // if url is "/tasks/8/d37c2f0f-016a-4066-b669-e0925b759560"
+      // extract the digits after /tasks
+      const processInstanceId = currentUrl.match(/(?<=\/tasks\/)\d+/)[0];
+      cy.log('==###############===processInstanceId : ', processInstanceId);
+      const projectId = Cypress.env('project_id');
+      cy.wait(2000);
+      cy.get('#root_project').select(projectId);
+      cy.get('#root_category').select('soft_and_lic');
+      cy.get('#root_purpose')
+        .clear()
+        .type(
+          'Sware\nA software license is a document that provides legally binding guidelines for the use and distribution of software.\nSoftware licenses typically provide end users with the right to one or more copies of the software without violating copyrights. This is now more than 250 characters'
+        );
+      cy.get('#root_criticality').select('High');
+      cy.get('#root_period').clear().type('25-11-2025');
+      cy.get('body').click();
+      cy.get('#root_vendor').clear().type('Microsoft');
+      cy.get('#root_payment_method').select('Reimbursement');
+      /* cy.get('button')
+                    .contains(/^Submit$/)
+                    .click();
+
+                cy.contains('Task: Enter NDR Items', { timeout: 60000 });
+*/
+      // item 0
+      cy.get('#root_item_0_sub_category').select('op_src');
+      cy.get('#root_item_0_item_name')
+        .clear()
+        .type(
+          'Open source software is code that is designed to be publicly accessible anyone can see, modify, END. This is now more than 100 characters'
+        );
+      cy.get('#root_item_0_qty').clear().type('2');
+      cy.get('#root_item_0_currency_type').select('Crypto');
+      cy.get('#root_item_0_currency').select('SNT');
+      cy.get('#root_item_0_unit_price').type('1915');
+
+      cy.get('#root_item > div:nth-child(3) > p > button').click();
+
+      // item 1
+      cy.get('#root_item_1_sub_category').select('lic_and_sub');
+      cy.get('#root_item_1_item_name')
+        .clear()
+        .type(
+          'A software license is a document that provides legally binding guidelines for the use and distri END.'
+        );
+      cy.get('#root_item_1_qty').clear().type('1');
+      cy.get('#root_item_1_currency_type').select('Fiat');
+      cy.get('#root_item_1_currency').select('AED');
+      cy.get('#root_item_1_unit_price').type('4500');
+
+      cy.get('button')
+        .contains(/^Submit$/)
+        .click();
+
+      cy.contains(
+        'Review and provide any supporting information or files for your request.',
+        { timeout: 60000 }
+      );
+
+      cy.get('.cds--text-area__wrapper')
+        .find('#root')
+        .type(
+          'test 2021 Newest HP 17.3 inch FHD Laptop, AMD Ryzen 5 5500U 6core(Beat i7-1160G7, up to 4.0GHz),16GB RAM, 1TB PCIe SSD, Bluetooth 4.2, WiFi, HDMI, USB-A&C, Windows 10 S, w/Ghost Manta Accessories, Silver\nhttps://www.amazon.com/HP-i7-11G7-Bluetooth-Windows'
+        );
+
+      // cy.contains('Submit the Request').click();
+
+      // cy.get('input[value="Submit the Request"]').click();
+
+      cy.get('button')
+        .contains(/^Submit$/)
+        .click();
+
+      cy.get('button')
+        .contains(/^Return to Home$/)
+        .click();
+
+      cy.contains('Started by me', { timeout: 60000 });
+      cy.logout();
+      cy.wait(2000);
+    });
+  });
+
+});
+    
 // Software and License - With Files
 describe('Initiate a Request - With Files', () => {
   Cypress._.times(1, () => {

spiffworkflow-frontend/cypress/pilot/NDR_PP1/softwarelicense.cy.js

@@ -3371,12 +3371,13 @@ describe('Software and Licenses Path - With Files and Multiple items', () => {
         cy.get('body').click();
         cy.get('#root_vendor').clear().type('Atlassian');
         cy.get('#root_payment_method').select('Debit Card');
-        cy.get('button')
+        /*cy.get('button')
           .contains(/^Submit$/)
           .click();
 
+        
+        cy.contains('Task: Enter NDR Items', { timeout: 60000 });*/
         // item 0
-        cy.contains('Task: Enter NDR Items', { timeout: 60000 });
         cy.get('#root_item_0_sub_category').select('op_src');
         cy.get('#root_item_0_item_name')
           .clear()

spiffworkflow-frontend/src/components/NavigationBar.tsx

@@ -97,6 +97,9 @@ export default function NavigationBar() {
     aboutLinkElement = <a href="/about">About</a>;
   }
 
+  const userEmail = UserService.getUserEmail();
+  const username = UserService.getPreferredUsername();
+
   const profileToggletip = (
     <div style={{ display: 'flex' }} id="user-profile-toggletip">
       <Toggletip isTabTip align="bottom-right">
@@ -105,15 +108,13 @@ export default function NavigationBar() {
           className="user-profile-toggletip-button"
           type="button"
         >
-          <div className="user-circle">
+          <div className="user-circle">{username[0].toUpperCase()}</div>
-            {UserService.getPreferredUsername()[0].toUpperCase()}
-          </div>
         </ToggletipButton>
         <ToggletipContent className="user-profile-toggletip-content">
           <p>
-            <strong>{UserService.getPreferredUsername()}</strong>
+            <strong>{username}</strong>
           </p>
-          <p>{UserService.getUserEmail()}</p>
+          {username !== userEmail && <p>{userEmail}</p>}
           <hr />
           {aboutLinkElement}
           <a target="_blank" href={documentationUrl} rel="noreferrer">