From a59f2063d6f9ae40b1730a74ba6f436dfbfa5c52 Mon Sep 17 00:00:00 2001 From: Lyd1aCla1r3 Date: Tue, 7 Dec 2021 10:24:50 -0800 Subject: [PATCH 1/7] ENDOC-379 --- .../next/docs/concepts/pda-architecture.md | 51 ++++++++----------- 1 file changed, 21 insertions(+), 30 deletions(-) diff --git a/vuepress/docs/next/docs/concepts/pda-architecture.md b/vuepress/docs/next/docs/concepts/pda-architecture.md index 9d46adfa4e..88267b942c 100644 --- a/vuepress/docs/next/docs/concepts/pda-architecture.md +++ b/vuepress/docs/next/docs/concepts/pda-architecture.md @@ -1,38 +1,31 @@ # PDA Architecture -The objective of this document is to provide an explanation for the components -that compose the Process Driven Applications plugin (PDA) architecture from a -deployment perspective as well as how they interact with each other. +The document describes the components that comprise the Process Driven Applications (PDA) plugin architecture with respect to +deployment, as well as how they interact with each other. -The image below shows the components in high level: +The image below shows the high level components. ![PDA Architecture](./img/pda-architecture.png) ## PDA MFEs -The PDA Micro Frontends run on the browser and they render the UI custom -components the user interacts with. These components are written in React and -they fetch data from the PDA API, passing the Keycloak token for authentication. -The MFEs also make calls to the Entando Core API in order to retrieve the -settings required for the configuration UI. These components will be available -on Entando App Builder after the PDA plugin bundle is installed and the user -can create pages with them. +The PDA Micro Frontends run on the browser, rendering the custom UI +components the user interacts with. These components are written in React and fetch data from the PDA API, passing the Keycloak token for authentication. + +The MFEs also make calls to the Entando Core API to retrieve the +settings required for the UI configuration. These components are available to assist with page creation after the PDA plugin bundle is installed. The source code for this component: ## PDA API -The Spring Boot application that communicates with the engine and make its data -available in a Rest API. It interacts with Keycloak to validate the token and -with the sidecar to retrieve the connections/sensitive data, depending on how it -was deployed. The application shouldn't call specific engine classes directly, -instead it always calls the abstractions defined in PDA Core library. The engine -implementation to use is decided at runtime based on the connection details -provided. It is important to note that the PDA API application is stateless, -since it doesn't have a database. All data available on the API is retrieved -from the BPM engine. After bundle installation, it will be deployed as a -microservice in the Kubernetes infrastructure and an Ingress will be created to +The PDA API is a Spring Boot application that communicates with the Entando engine and makes engine data available in a Rest API. Subject to deployment configuration, the PDA API interacts with Keycloak to validate the token, and with the sidecar to retrieve the connection and sensitive data. Instead of calling specific engine classes directly, the application calls the abstractions defined in the PDA Core library. + +Engine implementation is determined at runtime based on the connection details +provided. It is important to note that the PDA API does not have a database and is therefore stateless. All data available in the API are retrieved +from the BPM engine. After bundle installation, the API is deployed as a +microservice in the Kubernetes infrastructure. An Ingress is also created to make the API available to the MFEs, as described by the Entando Plugin custom resource. @@ -41,9 +34,9 @@ The source code for this component: ## Sidecar -The sidecar is another application (docker container) deployed in the same Pod -as the PDA API. It exposes services to manage connection details, which will be -stored as secrets in Kubernetes. The PDA API communicates with the sidecar to +The sidecar is another application (Docker container) deployed in the same Pod +as the PDA API. It exposes services to manage connection details, which are +stored as Secrets in Kubernetes. The PDA API communicates with the sidecar to manage BPM engine connection details. The source code for this component: @@ -51,18 +44,16 @@ The source code for this component: ## PDA Core -This is the library that defines the interfaces and abstractions that should be -implemented to interact with specific BPM engines. This way it is possible to -have multiple engine implementations at the same time. +The PDA Core is the library that defines the interface and abstraction implementations that interact with specific BPM engines. It allows multiple engine implementations to exist simultaneously. The source code for this component: ## PAM Impl -The Red Hat PAM implementation for the PDA Core library. If the connection maps -to a PAM engine, these are the classes that are going to be executed when the -PDA API requests for engine operations. This implementation communicates with +The PAM Impl is the Red Hat PAM implementation for the PDA Core library. If the connection maps +to a PAM engine, these are the classes that are executed when the +PDA API requests engine operations. This implementation communicates with the Kie Server, which executes the defined process operations. The source code for this component: From 696e73d5433e995d84329271f800ee807eec8148 Mon Sep 17 00:00:00 2001 From: Lyd1aCla1r3 Date: Tue, 7 Dec 2021 11:38:58 -0800 Subject: [PATCH 2/7] ENDOC-379 Minor fixes --- vuepress/docs/next/docs/concepts/pda-architecture.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/vuepress/docs/next/docs/concepts/pda-architecture.md b/vuepress/docs/next/docs/concepts/pda-architecture.md index 88267b942c..9a8494dfb3 100644 --- a/vuepress/docs/next/docs/concepts/pda-architecture.md +++ b/vuepress/docs/next/docs/concepts/pda-architecture.md @@ -1,6 +1,6 @@ # PDA Architecture -The document describes the components that comprise the Process Driven Applications (PDA) plugin architecture with respect to +This document describes the components that comprise the Process Driven Applications (PDA) plugin architecture with respect to deployment, as well as how they interact with each other. The image below shows the high level components. @@ -9,7 +9,7 @@ The image below shows the high level components. ## PDA MFEs -The PDA Micro Frontends run on the browser, rendering the custom UI +The PDA micro frontends run on the browser, rendering the custom UI components the user interacts with. These components are written in React and fetch data from the PDA API, passing the Keycloak token for authentication. The MFEs also make calls to the Entando Core API to retrieve the @@ -20,7 +20,7 @@ The source code for this component: ## PDA API -The PDA API is a Spring Boot application that communicates with the Entando engine and makes engine data available in a Rest API. Subject to deployment configuration, the PDA API interacts with Keycloak to validate the token, and with the sidecar to retrieve the connection and sensitive data. Instead of calling specific engine classes directly, the application calls the abstractions defined in the PDA Core library. +The PDA API is a Spring Boot application that communicates with the Entando engine, and engine data is made available in a Rest API. Subject to deployment configuration, the PDA API interacts with Keycloak to validate the token, and with the sidecar to retrieve the connection and sensitive data. Instead of calling specific engine classes directly, the application calls the abstractions defined in the PDA Core library. Engine implementation is determined at runtime based on the connection details provided. It is important to note that the PDA API does not have a database and is therefore stateless. All data available in the API are retrieved From 6b59e9f81839ff00cad9fe491d3a131869852122 Mon Sep 17 00:00:00 2001 From: Lyd1aCla1r3 Date: Thu, 9 Dec 2021 16:24:23 -0800 Subject: [PATCH 3/7] ENDOC-379 First pass --- .../customize-the-platform/pda-tutorial.md | 401 ++++++++---------- 1 file changed, 167 insertions(+), 234 deletions(-) diff --git a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md index cbb1db99fc..2fc3cd874f 100644 --- a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md +++ b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md @@ -1,278 +1,233 @@ # Business Objective The Entando Process Driven Applications plugin is built to provide a -rich and full featured user experience to allow for the management and -completion of business processes and automation. The UX is delivered a -general purpose UX layer built using micro frontends that can be +rich and full-featured user experience, facilitating the management and +completion of business processes and automation. + +The general purpose UX layer is created from micro frontends that can be utilized for any business process or task engine. Customers drive the UX -layer by utilizing a pre-developed Entando integration or by -implementing a set of interfaces on the server side. The backend is a -Spring Boot microservice that provides a pluggable interface allowing -for the injection of any underlying process or automation toolkit. The +layer via pre-developed Entando integration, or by +implementing a set of interfaces on the server side. + +The backend is a Spring Boot microservice that provides a pluggable interface to allow the injection of underlying processes or automation toolkits. The interfaces and steps for creating a new PDA backend implementation are -provided below. This document provides an overview of the Entando -Process Driven Apps (PDA) plugin. The initial section covers the -business functionality and user facing micro frontends. The second -section covers the architecture and the points of extension for the PDA -plugin. The third provides a detailed technical overview for developers +provided below. + +This document presents an overview of the Entando +Process Driven Apps (PDA) plugin. The initial section addresses the +business functionality and user-facing micro frontends. The second +section covers the architecture and points of extension for the PDA +plugin. The third section supplies a detailed technical overview of how to to add new functionality to a PDA implementation. # Terminology ## Micro Frontend -A Micro frontend architecture is an approach to developing web -application as a composition of small frontend apps. Instead of writing +A micro frontend architecture uses a composition of small frontend apps to develop a web application. Instead of writing a large monolith frontend application, the application is broken down into domain specific micro frontends, which are self-contained and can be developed and deployed independently. ## Process Automation Manager (PAM) -A business process automation engine built and maintained by Red Hat +Process Automation Manager (PAM) is a business process automation engine built and maintained by Red Hat. -## Business Process Modeling Notation (bpmn) +## Business Process Modeling Notation (BPMN) Business Process Model and Notation (BPMN) is a graphical representation for specifying business processes in a business process model. -## Decision Model and Notation (dmn) +## Decision Model and Notation (DMN) -Decision Model and Notation is a standard published by the Object -Management Group. It is a standard approach for describing and modeling -repeatable decisions within organizations to ensure that decision models -are interchangeable across organizations. +Decision Model and Notation (DMN) is a standard published by the Object +Management Group. It dictates a standardized approach for describing and modeling repeatable decisions within organizations to ensure that decision models are interchangeable across organizations. -## Back End for Front End (BFF) +## Backend for Frontend (BFF) A microservice architecture allows teams to iterate quickly and to -develop technology to scale rapidly. The Backend for Frontend (BFF) -architecture is a type of pattern built with microservices. The key -component of this pattern is an application that connects the front-end -of your application with the backend. This BFF Code Pattern will help -you build that component according to IBM’s best practices. +develop technology to scale rapidly. Backend for Frontend (BFF) +is an architecture pattern built with microservices. The key +component of this pattern is an application connecting the frontend +of an application with the backend. The BFF Code Pattern helps to build that component according to IBM’s best practices. # PDA Micro Frontends -This section provides an overview of each of the micro frontends (MFE) -that are available as part of the Entando PDA plugin. In cases below -where there are details specific to the PAM implementation they are -provided for that MFE. When extending the integration layer to other -engines or custom implementations it will be up to the integrating team -to define behavior and datasource for each MFE. +This section provides an overview of each micro frontend (MFE) that is available as part of the Entando PDA plugin. Details specific to the PAM implementation of an MFE are provided where appropriate. MFE behavior and datasources must be defined if the integration layer is extended to other +engines or custom implementations. ## Task List -The task list MFE provides a user with a list of visible tasks that are -either assigned to that user or that are potentially ownable by that -user. In the default implementation the visible tasks are limited to a -single process instance. At configuration time the application designer +The Task List MFE provides the user with a list of visible tasks that are +either assigned to or potentially ownable by that user. In the default implementation, the visible tasks are limited to a +single process instance. At configuration time, the application designer is given the option to select a set of columns that will be visible in the task list for that page. ### PAM Implementation -The default PAM implementation makes the top level task fields available -in the task list for selection. It is possible to fetch task and process -variables for rendering in the task list but these values are excluded -by default due to the additional API call overhead required. +The default PAM implementation exposes the top level task fields in the task list for selection. It is possible to fetch task and process variables from the task list for rendering, but this is disabled by default to optimize performance. ## Task Details -The task details MFE renders detailed information about a given task. -The task details widget is intended to give the final user processing a -task the information necessary to complete the task at hand. The task -details are rendered in a read only grid. See the styling section below -for changing and customizing the layout. +The Task Details MFE renders detailed information about a given task in a read only grid. The task details widget is intended to give the end user processing a +task the information necessary to complete the task. See the Styling section below to customize the layout. ### PAM Implementation -The PAM integration renders task variables in the task details widget. +The PAM implementation renders task variables in the task details widget. ## Task Comments -The task comments MFE gives the user the ability to view notes attached -to a given task and to add new notes to a task. +The Task Comments MFE enables the user to view and add the notes attached +to a task. ### PAM Implementation The PAM implementation reads and publishes notes to the comments -endpoint +endpoint. ## Task Forms -The task form implementation renders a form specific to a task and gives -the user the ability to complete that form. The form implementation is a +The Task Form implementation renders a form specific to a task and enables +the user to complete that form. The Task Form implementation is a wrapper around a JSON schema that describes the layout, style and -content of the form. It is up to the backend implementation to transform -to the schema and default ux layout needed to render the form. See the -technical documentation below for more on the JSON schema based +content of the form. The backend implementation provides the mapping +to the schema and default UX layout needed to render the form. See the +technical documentation below for more on the JSON schema implementation. ### PAM Implementation The PAM implementation of forms depends on the presence of a form -definition being present on the PAM task. The Entando PAM engine -implementation transforms from the PAM format to the JSON schema to -render the form. And it transforms the API format back to the PAM format -based on the form definition in PAM. There are some limitations on form -customization due to the format required to return data to PAM. See the -forms section in the technical documentation for more information. +definition for the PAM task. The Entando PAM engine implementation transforms the PAM format to the JSON schema to render the form. It also transforms the API format back to the PAM format. There are some limitations on form customization due to the format required to return data to PAM. See the Task Forms section in the technical documentation for more information. ## Attachments -The attachments MFE gives the user to view documents attached to a -task/case/process and to add new documents to a task/case/process. +The Attachments MFE enables the user to view and add documents attached to a +task, case or process. ### PAM Implementation The PAM implementation posts the documents to the PAM endpoints for -storage. Future features will include using Entando document storage for -storing documents and a pluggable document management interface. +storage. Future features will include the use of Entando document storage and a pluggable document management interface. ## New Process Form -The new process form renders a form that allows the final user to -provide the information necessary to instantiate a new business process -instance. The technology for generating the process form is the same as -the JSON schema definition used for task forms. === PAM Implementation -The PAM implementation depends on a form definition being attached to +The New Process Form renders a form enabling the end user to instantiate a new business process instance. The same technology is used to generate a New Process Form and the JSON schema definition for a Task Form. + +### PAM Implementation +The PAM implementation relies on a form definition attached to the process definition. Entando transforms the PAM representation into a -JSON schema form that can be rendered to the final user. +JSON schema form that can be rendered to the end user. ## Summary Card -The summary card MFE provides a view into aggregate data for the process +The Summary Card MFE provides a view into aggregate data for the process implementation. The rendered information includes a total value, a trend -value, and a selector for timeframe. The summary card allows the -application developer to select a request for rendering the requested -information which maps to a call in the underlying engine to provide the -summarized data. +value, and a timeframe selector. The Summary Card allows the +application developer to select a request for rendering information. This request maps to a call in the underlying engine and provides the summarized data. ### PAM Implementation -The PAM implementation of the summary card widget relies on the PAM -custom query functionality. The PAM PDA engine exposes configuration -that allows users/developers to define a custom query in a config file -that will be executed to render the summary card. This implementation -allows the data rendered on the summary cards to be changed via -configuration. In the application there is a properties file that allows -the implementer to provide a custom query for each of the cards. +The PAM implementation of the Summary Card widget relies on the PAM +custom query functionality. The PAM PDA engine exposes a configuration file +where the custom query can be defined. This allows user customization of the data rendered on the summary cards. The application contains a "properties" file where the implementer can submit a custom query for each of the cards. ## Totals Over Time -The totals over time MFE provides a dual axis line/bar graph providing -trend information about the process environment. The MFE also provides -three summary values for comparison over the same time period. +The Totals Over Time MFE provides a dual axis line/bar graph displaying +trend information about the process environment. Three summary values can be compared over a single time period. ### PAM Implementation -The PAM implementation of the totals over time MFE utilizes custom +The PAM implementation of the Totals Over Time MFE utilizes custom queries to fetch the summary data rendered in the chart. The queries used in the implementation are defined in configuration files in the MFE -and can be updated to render data specific to a given implementation. +and can be updated to render implementation specific data. # Customizing the Process Driven Application ## Styling -The Entando PDA MFEs are styled via a material UI theme. That theme can -be downloaded and updated here: - +The Entando PDA MFEs are styled via a Material UI theme. That theme can +be downloaded and updated [here](). ## Implementing a New Engine or Integrating a New Task Source -Implementing a new Engine for Process Driven Applications means to -create a new Java Project and implement the interfaces defined in the -pda-core-engine project. So, the new project should include the -pda-core-engine as a dependency. To see an implementation in action, -take a look at the pda-redhatpam-engine project, which implements the -Red Hat PAM engine integration. After the engine is implemented, the JAR -file resulting from the implementation should be available in the -classpath for entando-process-driven-plugin, which is the project that +Implementing a new engine for Process Driven Applications means +creating a new Java project and implementing the interfaces defined in the +`pda-core-engine` project. The new project should therefore include the +`pda-core-engine` as a dependency. + +To see an implementation in action, consider the `pda-redhatpam-engine` project, which implements the Red Hat PAM engine integration. The resultant JAR file should be available in the classpath for the `entando-process-driven-plugin`, which is the project that is ultimately executed and exposes the Rest APIs for the frontend -application. One way to do that is by publishing the engine +application. + +One way to achieve this is by publishing the engine implementation to a Maven repository and adding it as a dependency to -the entando-process-driven-plugin project. Below are the descriptions of -the key classes and interfaces in the pda-core-engine project that need -to be inherited or implemented when creating a new engine +the `entando-process-driven-plugin` project. Below are the descriptions of +the engine class and key interfaces in the `pda-core-engine` project that must be inherited or implemented when creating a new engine implementation: -- Engine: This class represents a BPM engine and exposes the services - that are available for that specific implementation. It is intended - to be inherited and the subclass should provide the real - implementation for each service by calling the superclass - constructor with the service implementations as arguments. If any - service is not supported, a null value should be passed to the - corresponding constructor argument. The engine can provide - implementations for the the following service interfaces: +### Classes - - TaskService: defines service methods for task retrieval from the - BPM engine. +`Engine`: represents a BPM engine and exposes the services that are available for that specific implementation. It is intended to be inherited, and the subclass should provide the implementation for each service by calling the superclass constructor with the service implementations as arguments. If any service is not supported, a null value should be passed to the corresponding constructor argument. The engine can provide implementations for service interfaces. - - TaskDefinitionService: defines service methods related to task - definition. A task definition specifies which fields or columns - are available for all task instances. +### Interfaces - - TaskCommentService: defines service methods related to task - comment manipulation. It should be implemented if the task - comment is supported by the engine. +`TaskService`: defines service methods for task retrieval from the BPM engine. - - TaskAttachmentService: defines service methods to operate on - task attachments. It should be implemented if the engine - supports file attachment on the task. +`TaskDefinitionService`: defines service methods related to task definition. A task definition specifies which fields or columns are available for all task instances. - - TaskFormService: defines service methods for task form - operations, like retrieving the form definition and submitting a - form. The Form object can be used to render a form dynamically. +`TaskCommentService`: defines service methods related to task comment manipulation. It should be implemented if the task comment is supported by the engine. - - TaskLifecycleService: defines service methods related to the - task lifecycle. The lifecycle operations move the task from one - state to another. +`TaskAttachmentService`: defines service methods to operate on task attachments. It should be implemented if the engine supports file attachment on the task. - - TaskLifecycleBulkService: defines methods for bulk lifecycle - operations. Like the TaskLifecycleService, methods here move the - task from one state to another, but this interface works with - multiple tasks at a time. +`TaskFormService`: defines service methods for task form operations, like retrieving the form definition and submitting a form. The Form object can be used to render a form dynamically. - - ProcessService: defines service methods for process definitions - operations. +`TaskLifecycleService`: defines service methods related to the task lifecycle. The lifecycle operations move the task from one state to another. - - ProcessFormService: defines service methods for process form - operations, like retrieving the form definition and submitting a - form. The Form object can be used to render a form dynamically. +`TaskLifecycleBulkService`: defines methods for bulk lifecycle operations. Like the TaskLifecycleService, methods here move the task from one state to another, but this interface works with multiple tasks at a time. - - GroupService: define service methods related to groups from the - BPM engine. +`ProcessService`: defines service methods for process definitions operations. -## Creating a new PDA MFE +`ProcessFormService`: defines service methods for process form operations, like retrieving the form definition and submitting a form. The Form object can be used to render a form dynamically. -There are no limitations on the stack that could be used to create PDA +`GroupService`: defines service methods related to groups in the BPM engine. + +## Creating a New PDA MFE + +There are no limitations on the stack that can be used to create PDA MFEs. Custom Elements are a great way to hide implementation details -while providing a neutral interface to others. To create a simple PDA -MFE, implement your solution using technologies you are familiar with -and wrap it in a custom element. Build your solution with a custom -element and upload the built files (Settings \> File Browser) in -/public/ folder. Go to `UX Pattern > Widget` section of the admin panel -and press “Add” to add a new widget. Enter widget code, titles, select -group (for free access to everybody, select “Free Access”), and fill the -Custom UI: - - <#assign wp=JspTaglibs["/aps-core"]> - - - -`<#assign wp=JspTaglibs["/aps-core"]>` - provides access to wp variable -that is used to get resource URL. After you add the widget, go to the -page tree, select a page where you would like to use the widget and -configure it. Drag and drop the widget into a frame and publish the -page. +while providing a neutral interface. + +To create a simple PDA MFE: +1. Implement your solution using technologies you are familiar with +and wrap it in a custom element. +2. Upload the build files (Settings \> File Browser) in the /public/ folder. +3. Go to the `UX Pattern > Widget` section of the admin panel +and click “Add” to add a new widget. +4. Enter the widget code and titles. +5. Select group type (for free access to everybody, select “Free Access”). +6. Populate the Custom Element UI: +```sh +<#assign wp=JspTaglibs["/aps-core"]> + + +``` +The variable assignment `<#assign wp=JspTaglibs["/aps-core"]>` provides access to the FreeMarker variable `wp` (web portal) that is used to get resource URL. + +After you add the widget: +1. Go to the page tree and select a page where you would like to use the widget. +2. Configure the widget. +3. Drag and drop the widget into a frame and publish the page. ## Communication between MFEs Communication between MFEs can be achieved using Custom Events. Each -widget can define events that it will emit and register to events that -are important to it. +widget can define events that it will emit and events that +are important to it: const createWidgetEvent = eventType => { return payload => { @@ -289,8 +244,8 @@ are important to it. }; }; -Custom element then creates the events it emits and registers to the -events that it wants to react to +The Custom element then creates the events it emits and registers to the +events that it wants to react to: constructor(props) { super(props); @@ -316,19 +271,13 @@ events that it wants to react to ## Micro Frontend Overview -### Task forms +### Task Forms + +Widgets employ JSON schema to dynamically create any forms they contain. The JSON schemas are converted into React components using the `react-jsonshema-form` library. Entando's initial implementation utilizes Material UI components derived from the Material UI theme library (`rjsf-material-ui`) as a baseline, and includes templates, widgets and fields (`react-jsonshema-form` terms for forms components) that are specific to Entando. + +This section will introduce the basic form configuration, but if you would like to learn more, please refer to the `react-jsonshema-form` documentation. -Widgets containing form (e.g., task completion form widget) use JSON -schema to dynamically create forms. Widget implementation uses -react-jsonshema-form library that converts forms’ JSON schemas into -React components. Our initial implementation uses Material UI components -via Material UI theme library rjsf-material-ui as baseline and has -Entando specific templates, widgets and fields (which are -react-jsonshema-form terms for parts of forms). In this section you will -learn about basic setup of the form, but if you would like to learn -more, please refer to react-jsonshema-form documentation. Themed JSON -form is created using the withTheme() method from the -react-jsonschema-form package +The themed `JSOform` is created using the `withTheme()` method from the `react-jsonschema-form` package: import { withTheme } from 'react-jsonschema-form'; import { Theme as MuiRJSForm } from 'rjsf-material-ui'; @@ -353,31 +302,20 @@ react-jsonschema-form package export default JSONForm; -For JSON Form to work, the form schema is mandatory. It’s a JSON -definition of the form’s structure. Users can also provide form data via -formData variable, which should follow the structure of JSON schema; and -UI schema using uiSchema variable, which allows users to customise the -form’s UI (components, rules, types, etc.) To test JSON schema, UI -schema and form data, you can use react-jsonschema-form sandbox -environment. Custom Entando templates, widgets, and fields provide a -possibility to customise the layout of the form using Grid components. -To specify what area a field or subform should fill, users can provide -size parameter in UI schema’s ui:options object. Size refers to Material -UI’s grid column widths (Material UI documentation) where the area the -from can take up is divided into 12 columns and value 12 (a default -value if size is not provided) means the field or subform should take up -all 12 columns. That means that size should be a value from 1 to 12. If -two fields that are next to each other have size values 8 and 4 -respectively - they will fit into one row, first field being 2 times -wider than the second field. User can also provide innerSize parameter -to size the input inside the field. This helps with formatting - if user -wants a two column layout and have smaller input fields inside these -columns. Multicolumn layout can also be achieved using -generateColumnedOFT(columnSize) functionality, basically providing the -default columnSize to the created form. generateColumnedOFT returns an -ObjectFieldTemplate that is used as a template for all object fields -(fields that contain properties inside of them). To help us understand -the mapping between JSON schema and UI schema lets define an example +A form schema is mandatory for a JSON Form to function because it provides the JSON definition of the form’s structure. Users can also supply form data via the +`formData` variable, which should follow the structure of JSON schema, and +UI schema via the `uiSchema` variable, which allows users to customize the +form’s UI (e.g. components, rules, types). + +You can test the JSON schema, UI schema and form data in the `react-jsonschema-form` sandbox environment. Entando templates, widgets, and fields allow customization of form layout using Grid components. The size parameter in the UI schema’s `ui:options` object specifies the fill area of a field or subform. + +Size refers to the Material UI’s grid column widths (see the Material UI documentation), where the area the form can occupy is divided into 12 columns. A value of 12 (the default value if size is not provided) means the field or subform should take up all 12 columns. If two adjacent fields have size values of 8 and 4, respectively, they will share one row and the first field will be twice as wide as the second. + +In addition, the user can provide an innerSize parameter to scale the input fields inside the columns. This helps with formatting when a user wants to make nonuniform adjustments to sizing. + +Multicolumn layout can also be achieved via `generateColumnedOFT` (`columnSize`) functionality, which assigns the default `columnSize` to the created form. The function `generateColumnedOFT` returns an `ObjectFieldTemplate` that is used as a template for all object fields (fields that contain properties). + +To explain the mapping between JSON schema and UI schema let's define an example schema: { @@ -446,19 +384,17 @@ schema: } } -From this JSON (you can copy & paste it into the react-jsonschema-form +From this JSON (you can copy & paste it into the `react-jsonschema-form` sandbox) we can see that there is a main form with a title “Mortgage -Application Form”. Root “Mortgage Application Form” form has two -properties - one is a subform `Application` and the second one is just a -checkbox field (field ID is inlimit). Application subform contains 2 -fields: Mortgage amount (field ID is mortgageamount) and Down Payment -(field ID is downpayment); and two subforms - Applicant (field ID is -applicant) and Property (field ID is property). Applicant subform -contains 2 fields - Name (field ID is name) and Annual Income (field ID -is annualincome). Property subform contains 2 fields - Age of property -(field ID is age) and Address of property (field ID is address) By -default (without providing UI schema) they are all listed one field per -row. To use Entando’s implementation of Grid layout, users have to +Application Form." The root form `Mortgage Application Form` has two +properties: one is a subform called `Application` and the other is a +checkbox field (field ID is `inlimit`). + +The `Application` subform contains two fields (`Mortgage Amount` with field ID `mortgageamount` and `Down Payment` with field ID `downpayment`) and two subforms (`Applicant` with field ID `applicant` and `Property` with field ID `property`). + +The `Applicant` subform contains two fields (`Name` with field ID `name` and `Annual Income` with field ID `annualincome`). The `Property` subform also contains two fields (`Age of property` with field ID `age` and `Address of property` with field ID `address`). + +By default (without providing UI schema), these are listed as one field per row. To use Entando’s implementation of Grid layout, users have to provide UI schema with details about each field. For example, if we would like to have a layout that looks like this (fields are marked `[ field name ]`): @@ -477,12 +413,7 @@ would like to have a layout that looks like this (fields are marked | | [Address of property] | +----------------------------------------------------+-----------------------+ -To set up the UI schema you have to define each field you want to -customise by addressing using the field IDs - to add options to -Applicant’s Name field, you will have to create an object tree going -from root object through Application —\> Applicant —\> Name (using IDs -it’s Application.applicant.name). UI schema for the table layout defined -above would look like this: +To set up the UI schema, you need to use field IDs to define each field you want to customize. For example, to add options to the `Name` field, create an object tree beginning at the root: `Application` —\> `Applicant` —\> `Name` (equivalent to `Application`.`Applicant`.`Name`). The UI schema for the table layout defined above looks like this: { Application: { @@ -522,31 +453,33 @@ above would look like this: // note that property's fields are not mentioned - defaulting them to 12 columns in are that is available to them }, }, - }; + } - As Material UI components are used for field templates, there might be a need to pass some Material UI options into the field. You can do that by adding muiProps object to the ui:options. - For example, if you would like to make the Down payment field resizable, you can add multiline: true to muiProps option. If you want to make the field take up multiple rows by default, add rows and rowsMax fields. The latter limits how many rows should be added until the scroll bar is shown. - downpayment: { - 'ui:options': { - size: 4, - muiProps: { - multiline: true, - rows: 2, - rowsMax: 4 +As Material UI components are used for field templates, there might be a need to pass some Material UI options into the field. This can be done by adding the `muiProps` object to `ui:options`. + +For example, if you would like to make the down payment field resizable, you can add `multiline: true` to the `muiProps` option. If you want to make the field to take up multiple rows by default, add the fields `rows` and `rowsMax`. The latter limits how many rows can be added until the scroll bar is shown. + + { + downpayment: { + 'ui:options': { + size: 4, + muiProps: { + multiline: true, + rows: 2, + rowsMax: 4 + } } } - } ## Widgets Different types of widgets can be applied by passing the type via -"ui:widget". Property tells the form which UI widget should be used to -render a field. You can read about react-jsonschema-form supported -widgets here. +`ui:widget`. This property specifies the widget to use when the form +renders a UI field. See the documentation to learn about widgets supported by the `react-jsonschema-form`. -## Building From source +## Building from Source -Reference the component projects for instructions to build from source. +Reference the component projects for instructions to build from source code: From ebc9b5c15f100e895143e7e9120b48b5803436ba Mon Sep 17 00:00:00 2001 From: Lyd1aCla1r3 Date: Fri, 10 Dec 2021 12:23:51 -0800 Subject: [PATCH 4/7] ENDOC-379 Minor fixes --- .../customize-the-platform/pda-tutorial.md | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md index 2fc3cd874f..2b3cc46c92 100644 --- a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md +++ b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md @@ -14,11 +14,12 @@ interfaces and steps for creating a new PDA backend implementation are provided below. This document presents an overview of the Entando -Process Driven Apps (PDA) plugin. The initial section addresses the -business functionality and user-facing micro frontends. The second -section covers the architecture and points of extension for the PDA -plugin. The third section supplies a detailed technical overview of how to -to add new functionality to a PDA implementation. +Process Driven Apps (PDA) plugin in three sections: + +- The first section addresses the business functionality and user-facing micro frontends. +- The second section covers the architecture and points of extension for the PDA +plugin. +- The third section supplies a detailed technical overview of how to add new functionality to a PDA implementation. # Terminology @@ -59,7 +60,7 @@ engines or custom implementations. ## Task List The Task List MFE provides the user with a list of visible tasks that are -either assigned to or potentially ownable by that user. In the default implementation, the visible tasks are limited to a +either assigned to or potentially owned by that user. In the default implementation, the visible tasks are limited to a single process instance. At configuration time, the application designer is given the option to select a set of columns that will be visible in the task list for that page. @@ -418,17 +419,17 @@ To set up the UI schema, you need to use field IDs to define each field you want { Application: { 'ui:options': { - size: 12, // <-- this value is not mandatory as size is 12 columns-wide by default + size: 12, // <-- this value is not mandatory; size is 12 columns wide by default }, mortgageamount: { 'ui:disabled': true, // <-- user can define fields disabled at UI schema level 'ui:options': { - size: 6, // <-- Mortgage amount field should take up half of the row + size: 6, // <-- Mortgage Amount field should take up half of the row }, }, downpayment: { 'ui:options': { - size: 4, // <-- Down payment field should take up the other half of the row + size: 4, // <-- Down Payment field should take up the other half of the row }, }, applicant: { @@ -437,12 +438,12 @@ To set up the UI schema, you need to use field IDs to define each field you want }, name: { 'ui:options': { - size: 8, // <-- Applicant name field should take up 8 columns in the 8 columns that Applicant subform occupies + size: 8, // <-- Applicant Name field should take up 8 of the 8 columns that Applicant subform occupies }, }, annualincome: { 'ui:options': { - size: 4, // <-- Annual Income field taking up the remaining 4 columns + size: 4, // <-- Annual Income field should take up the remaining 4 columns }, }, }, @@ -450,14 +451,14 @@ To set up the UI schema, you need to use field IDs to define each field you want 'ui:options': { size: 4, // <-- Property subform should take up the remaining 4 out of 12 columns }, - // note that property's fields are not mentioned - defaulting them to 12 columns in are that is available to them + // note that Property field occupancy is not specified, defaulting to use all 12 of the columns available }, }, } As Material UI components are used for field templates, there might be a need to pass some Material UI options into the field. This can be done by adding the `muiProps` object to `ui:options`. -For example, if you would like to make the down payment field resizable, you can add `multiline: true` to the `muiProps` option. If you want to make the field to take up multiple rows by default, add the fields `rows` and `rowsMax`. The latter limits how many rows can be added until the scroll bar is shown. +For example, if you would like to make the down payment field resizable, you can add `multiline: true` to the `muiProps` option. If you want the field to take up multiple rows by default, add the fields `rows` and `rowsMax`. The latter limits how many rows can be added until the scroll bar is shown. { downpayment: { From 5d09dd829811344f37cccd28dbf08923e7088115 Mon Sep 17 00:00:00 2001 From: Lyd1aCla1r3 Date: Sat, 11 Dec 2021 09:33:28 -0800 Subject: [PATCH 5/7] ENDOC-379 Apply all review comments --- .../next/docs/concepts/pda-architecture.md | 5 +- .../customize-the-platform/pda-tutorial.md | 77 +------------------ 2 files changed, 4 insertions(+), 78 deletions(-) diff --git a/vuepress/docs/next/docs/concepts/pda-architecture.md b/vuepress/docs/next/docs/concepts/pda-architecture.md index 9a8494dfb3..801d822a85 100644 --- a/vuepress/docs/next/docs/concepts/pda-architecture.md +++ b/vuepress/docs/next/docs/concepts/pda-architecture.md @@ -20,10 +20,9 @@ The source code for this component: ## PDA API -The PDA API is a Spring Boot application that communicates with the Entando engine, and engine data is made available in a Rest API. Subject to deployment configuration, the PDA API interacts with Keycloak to validate the token, and with the sidecar to retrieve the connection and sensitive data. Instead of calling specific engine classes directly, the application calls the abstractions defined in the PDA Core library. +The PDA API is a Spring Boot application that communicates with the BPM engine, and BPM engine data is made available in a Rest API. Subject to deployment configuration, the PDA API interacts with Keycloak to validate the token, and with the sidecar to retrieve the connection and sensitive data. Instead of calling specific engine classes directly, the application calls the abstractions defined in the PDA Core library. -Engine implementation is determined at runtime based on the connection details -provided. It is important to note that the PDA API does not have a database and is therefore stateless. All data available in the API are retrieved +The engine implementation is determined at runtime based on the connection details provided. It is important to note that the PDA API does not have a database and is therefore stateless. All data available in the API are retrieved from the BPM engine. After bundle installation, the API is deployed as a microservice in the Kubernetes infrastructure. An Ingress is also created to make the API available to the MFEs, as described by the Entando Plugin custom diff --git a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md index 2b3cc46c92..e5162ceca8 100644 --- a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md +++ b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md @@ -5,9 +5,7 @@ rich and full-featured user experience, facilitating the management and completion of business processes and automation. The general purpose UX layer is created from micro frontends that can be -utilized for any business process or task engine. Customers drive the UX -layer via pre-developed Entando integration, or by -implementing a set of interfaces on the server side. +utilized for any business process or task engine. The UX layer can serve data via the included Entando integration adapter, or by implementing a set of interfaces on the server side. The backend is a Spring Boot microservice that provides a pluggable interface to allow the injection of underlying processes or automation toolkits. The interfaces and steps for creating a new PDA backend implementation are @@ -111,7 +109,7 @@ task, case or process. ### PAM Implementation The PAM implementation posts the documents to the PAM endpoints for -storage. Future features will include the use of Entando document storage and a pluggable document management interface. +storage. ## New Process Form @@ -197,77 +195,6 @@ implementation: `GroupService`: defines service methods related to groups in the BPM engine. -## Creating a New PDA MFE - -There are no limitations on the stack that can be used to create PDA -MFEs. Custom Elements are a great way to hide implementation details -while providing a neutral interface. - -To create a simple PDA MFE: -1. Implement your solution using technologies you are familiar with -and wrap it in a custom element. -2. Upload the build files (Settings \> File Browser) in the /public/ folder. -3. Go to the `UX Pattern > Widget` section of the admin panel -and click “Add” to add a new widget. -4. Enter the widget code and titles. -5. Select group type (for free access to everybody, select “Free Access”). -6. Populate the Custom Element UI: -```sh -<#assign wp=JspTaglibs["/aps-core"]> - - -``` -The variable assignment `<#assign wp=JspTaglibs["/aps-core"]>` provides access to the FreeMarker variable `wp` (web portal) that is used to get resource URL. - -After you add the widget: -1. Go to the page tree and select a page where you would like to use the widget. -2. Configure the widget. -3. Drag and drop the widget into a frame and publish the page. - -## Communication between MFEs - -Communication between MFEs can be achieved using Custom Events. Each -widget can define events that it will emit and events that -are important to it: - - const createWidgetEvent = eventType => { - return payload => { - const widgetEvent = new CustomEvent(eventType, { payload }); - window.dispatchEvent(widgetEvent); - }; - }; - - - const subscribeToWidgetEvent = (eventType, eventHandler) => { - window.addEventListener(eventType, eventHandler); - return () => { - window.removeEventListener(eventType, eventHandler); - }; - }; - -The Custom element then creates the events it emits and registers to the -events that it wants to react to: - - constructor(props) { - super(props); - - // other code - - this.onClickSubmit = createWidgetEvent(‘myWidget.onSubmit’); - } - - connectedCallback() { - - // other code - - this.unsubscribeFromWidgetEvents = subscribeToWidgetEvent( - ‘otherWidget.onClickClear’, - () => { - // callback function when otherWidget fires the onClickClear custom event - } - } - } - # Technical Documentation ## Micro Frontend Overview From 92f039a6e2292f91a0dd3196517b0d8c79d769d3 Mon Sep 17 00:00:00 2001 From: Lyd1aCla1r3 Date: Mon, 13 Dec 2021 09:09:49 -0800 Subject: [PATCH 6/7] ENDOC-379 Minor fix --- .../docs/next/tutorials/customize-the-platform/pda-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md index e5162ceca8..bbe0ebf01b 100644 --- a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md +++ b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md @@ -58,7 +58,7 @@ engines or custom implementations. ## Task List The Task List MFE provides the user with a list of visible tasks that are -either assigned to or potentially owned by that user. In the default implementation, the visible tasks are limited to a +either assigned to or could be claimed by that user. In the default implementation, the visible tasks are limited to a single process instance. At configuration time, the application designer is given the option to select a set of columns that will be visible in the task list for that page. From 5d4bcc7072f2f81d33f29a6a6033876f400582fa Mon Sep 17 00:00:00 2001 From: Lyd1aCla1r3 Date: Mon, 13 Dec 2021 10:18:56 -0800 Subject: [PATCH 7/7] ENDOC-379 Intermediary doc --- .../docs/next/tutorials/customize-the-platform/pda-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md index bbe0ebf01b..4d9cdc001c 100644 --- a/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md +++ b/vuepress/docs/next/tutorials/customize-the-platform/pda-tutorial.md @@ -205,7 +205,7 @@ Widgets employ JSON schema to dynamically create any forms they contain. The JSO This section will introduce the basic form configuration, but if you would like to learn more, please refer to the `react-jsonshema-form` documentation. -The themed `JSOform` is created using the `withTheme()` method from the `react-jsonschema-form` package: +The themed JSON Form is created using the `withTheme()` method from the `react-jsonschema-form` package: import { withTheme } from 'react-jsonschema-form'; import { Theme as MuiRJSForm } from 'rjsf-material-ui';