This is an automated email from the ASF dual-hosted git repository. tiagobento pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/incubator-kie-website.git
commit 1529ca8153ddd17c644ce6dcb7c9fd7f2c997f11 Author: Tiago Bento <[email protected]> AuthorDate: Mon Aug 17 11:19:11 2026 -0400 Add DRL chapter, correct jBPM pages, and rework component taglines Bring the jBPM pages in line with what the code in kogito-jbpm actually does. The overview traded its Case management and Business optimization cards — CMMN has no implementation beyond a dead ResourceType constant, and no process-to-OptaPlanner integration exists — for Human tasks and Long-running by design. "What is jBPM?" dropped its jBPM 7-era claims (JEE war/ear, Thorntail, Eclipse editor, JPA/JTA persistence, process repository, OSGi/CDI/EJB) in favour of the add-on based persistence, Quarkus and Spring Boot runtimes, and build-time codegen that replaced them, and now agrees with Get started that the engine ships inside Kogito rather than being an alternative to it. Add a DRL chapter alongside DMN, covering rules, rule units, absence and aggregation, queries, and CEP, with snippets taken from the examples and tests in the monorepo. Rework the banner taglines so they open with what the component is instead of repeating its name, which the banner already renders as the page heading. Kogito keeps its Latin, and now names Drools and jBPM as what backs it; SonataFlow is a platform, not a tool; Tools describes authoring and managing assets rather than counting editors. Also carries the pending hotsite work: the ComponentBanner component, per-component Get started pages, custom breadcrumbs, and the Kogito highlights, which now cite Spring Boot rather than Knative. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> --- docs/about/components.md | 8 +- docs/drools/books.md | 2 +- docs/drools/dmn.mdx | 8 +- docs/drools/drl.mdx | 187 +++++++++++++++++++++ docs/drools/drools.md | 29 ---- docs/drools/drools.mdx | 37 ++++ docs/drools/get-started.md | 33 ++++ docs/drools/papers.md | 2 +- docs/drools/upgrade-recipe.mdx | 4 +- docs/drools/videos.md | 2 +- docs/jbpm/books.md | 42 ++++- docs/jbpm/get-started.md | 36 ++++ docs/jbpm/getting-started.md | 96 ----------- docs/jbpm/jbpm.md | 62 ------- docs/jbpm/jbpm.mdx | 44 +++++ docs/jbpm/what-is-jbpm.md | 44 +++++ docs/kogito/get-started.md | 16 +- docs/kogito/guides.md | 71 ++++---- docs/kogito/kogito.mdx | 10 +- docs/optaplanner/code-example.md | 2 +- docs/optaplanner/compatibility.md | 2 +- docs/optaplanner/get-started.md | 27 +++ .../{optaplanner.md => how-it-works.md} | 24 +-- docs/optaplanner/optaplanner.mdx | 37 ++++ docs/optaplanner/use-cases.md | 2 +- docs/sonataflow/get-started.md | 23 +++ docs/sonataflow/integrations.md | 2 +- docs/sonataflow/sonataflow.md | 19 --- docs/sonataflow/sonataflow.mdx | 42 +++++ docs/tools/chrome.md | 2 +- docs/tools/consoles.md | 2 +- docs/tools/editors.md | 2 +- docs/tools/get-started.md | 28 +++ docs/tools/kie-sandbox.md | 2 +- docs/tools/tools.md | 41 ----- docs/tools/tools.mdx | 41 +++++ docs/tools/vscode.md | 2 +- docusaurus.config.ts | 7 +- src/componentSections.ts | 79 +++++++++ src/components/ComponentBanner/index.tsx | 98 +++++++++++ src/components/ComponentBanner/styles.module.css | 130 ++++++++++++++ src/components/KogitoHighlights/index.tsx | 68 +++++--- src/components/KogitoHighlights/styles.module.css | 33 +--- src/css/custom.css | 42 +++++ src/theme/DocBreadcrumbs/index.tsx | 135 +++++++++++++++ src/theme/DocBreadcrumbs/styles.module.css | 7 + src/theme/Root.tsx | 49 +++++- static/img/kogito.svg | 2 +- static/img/kogito/hero-background.svg | 12 ++ static/img/navbar-logo.svg | 2 +- static/img/sonataflow.svg | 2 +- 51 files changed, 1298 insertions(+), 401 deletions(-) diff --git a/docs/about/components.md b/docs/about/components.md index 526ee98..e3ec35f 100644 --- a/docs/about/components.md +++ b/docs/about/components.md @@ -11,7 +11,7 @@ one stands on its own, and they are designed to work together. The rule engine at the core of KIE. Started in 2001 as an open source rule engine and grew into a full business rule management system, today covering DRL -rules and the DMN decision standard. +rules and the [DMN](https://www.omg.org/spec/DMN/) decision standard. ## [OptaPlanner](/optaplanner) @@ -21,8 +21,9 @@ own right. ## [jBPM](/jbpm) -A workflow engine for long-running business processes, covering BPMN, case -management and human tasks. From jBPM 5 onwards it was rebuilt around the same +A workflow engine for long-running business processes, covering +[BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/), case management and human +tasks. From jBPM 5 onwards it was rebuilt around the same knowledge core as Drools. ## [Kogito](/kogito) @@ -53,4 +54,3 @@ years, some of which grew into projects of their own: - [TrustyAI](https://github.com/trustyai-explainability), for explainability and auditing of AI-augmented decision services, which continues as an independent open source project. -- SonataFlow, which grew out of Kogito. diff --git a/docs/drools/books.md b/docs/drools/books.md index 838fe31..9635ab3 100644 --- a/docs/drools/books.md +++ b/docs/drools/books.md @@ -1,7 +1,7 @@ --- id: books title: Books -sidebar_position: 2 +sidebar_position: 4 --- Books about Drools, and about business rules and decision modelling more diff --git a/docs/drools/dmn.mdx b/docs/drools/dmn.mdx index f2ec59d..4fda1aa 100644 --- a/docs/drools/dmn.mdx +++ b/docs/drools/dmn.mdx @@ -1,10 +1,10 @@ --- id: dmn title: DMN -sidebar_position: 1 +sidebar_position: 3 --- -The Decision Model and Notation (DMN™) is a Standard by OMG® providing a common and visual notation readily understandable by all users and personas. With DMN, business analysts can define the initial decision requirements and then formalize more detailed decision models; technical developers can automate the decisions in any process with a portable execution semantic, while business stakeholders can manage and monitor those decisions. +The Decision Model and Notation (DMN™) is a Standard by [OMG®](https://www.omg.org/) providing a common and visual notation readily understandable by all users and personas. With DMN, business analysts can define the initial decision requirements and then formalize more detailed decision models; technical developers can automate the decisions in any process with a portable execution semantic, while business stakeholders can manage and monitor those decisions. The official webpage of the DMN Standard specification is available at [OMG website](https://www.omg.org/dmn). Drools DMN engine is an open source Java™ implementation providing full runtime support for DMN models at Conformance level 3, meaning 100% of the features in the Standard. @@ -29,9 +29,9 @@ Model business logic with DMN Decision Table, an effective instrument understand Model more complex business logic with the power of all the FEEL Boxed Expression constructs made available by the DMN Standard specification. -Integrate DMN with [BPMN](https://jbpm.org) and [CMMN](https://jbpm.org) to describe an executable and semantically defined business logic to be used in business processes. +Integrate DMN with [BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/) and [CMMN](https://www.omg.org/spec/CMMN/) to describe an executable and semantically defined business logic to be used in business processes. - + ## The DMN TCK diff --git a/docs/drools/drl.mdx b/docs/drools/drl.mdx new file mode 100644 index 0000000..b31fbf5 --- /dev/null +++ b/docs/drools/drl.mdx @@ -0,0 +1,187 @@ +--- +id: drl +title: DRL +sidebar_position: 2 +--- + +DRL — the Drools Rule Language — is the native language of the Drools rule +engine. Where DMN gives business analysts a visual, standardized notation, DRL +gives developers the full expressive power of the engine in plain text files +that live in your source tree, next to your Java code, under version control. + +A rule says *when* something is true, *then* do something. You never call a +rule; you give the engine facts and it works out which rules match, in what +order, and re-evaluates as those facts change. + +## A first rule + +```drl +package org.acme.orders + +import org.acme.orders.Order + +rule "Free shipping over 100" +when + $order : Order( total > 100, freeShipping == false ) +then + modify( $order ) { setFreeShipping( true ) }; +end +``` + +`when` holds the conditions — patterns matched against the facts the engine +knows about. `Order( total > 100 )` reads as "there is an `Order` whose +`total` is greater than 100"; `$order` binds the match so the `then` block can +use it. `modify` changes a fact *and* tells the engine it changed, so any other +rule that cares about `freeShipping` gets reconsidered. That is the part that +makes a rule engine different from a pile of `if` statements: rules react to +each other, and you never wrote the control flow. + +## Rule units + +A loose bag of rules and a shared session works, but it gets hard to reason +about at scale. Rule units are the modern way to organize DRL: a unit is a +typed container that declares the data its rules operate on, so the rules and +their inputs are one cohesive, injectable thing. + +The data holder is a plain Java class: + +```java +public class HelloWorldUnit implements RuleUnitData { + + private final DataStore<String> strings = DataSource.createStore(); + private final List<String> results = new ArrayList<>(); + + public DataStore<String> getStrings() { return strings; } + public List<String> getResults() { return results; } +} +``` + +The DRL binds itself to that unit and navigates its data sources with OOPath +expressions — the `/strings[ ... ]` syntax: + +```drl +package org.acme; +unit HelloWorldUnit; + +rule HelloWorld +when + /strings [ this == "Hello World" ] +then + results.add("it worked!"); +end +``` + +And running it is three lines, with no session bootstrapping to speak of: + +```java +HelloWorldUnit unit = new HelloWorldUnit(); +unit.getStrings().add("Hello World"); + +try (RuleUnitInstance<HelloWorldUnit> instance = + RuleUnitProvider.get().createRuleUnitInstance(unit)) { + instance.fire(); +} +``` + +Rule units are also what [Kogito](/kogito) generates REST endpoints from, so +the same unit you unit-test locally becomes a decision service without +rewriting it. + +## Beyond simple matching + +DRL is a language, not a table format, and the interesting parts show up once +the conditions stop being row-shaped. + +**Absence** is a first-class condition. `not`, `exists` and `forall` let you +match on facts that *aren't* there — something no lookup table expresses +naturally: + +```drl +rule "Flag unreviewed high-value orders" +when + $order : Order( total > 10000 ) + not Review( order == $order ) +then + $order.flagForReview(); +end +``` + +**Aggregation** over the whole working memory, via `accumulate`: + +```drl +rule "Bulk discount" +when + $customer : Customer() + Number( intValue >= 10 ) from accumulate( + $o : Order( customer == $customer, status == "OPEN" ), + count( $o ) ) +then + $customer.applyBulkDiscount(); +end +``` + +**Queries** ask the engine questions instead of firing actions, and they can +recurse — which is how you get backward chaining: + +```drl +query isContainedIn( String x, String y ) + /locations[thing := x, location := y] + or + ( /locations[z := thing, location := y] and isContainedIn(x, z;) ) +end +``` + +**Truth maintenance**: facts inserted logically are retracted automatically +when the reason for them stops holding, so you never write the cleanup pass. + +**Execution control** when you need it — `salience` to order rules, +`no-loop` to stop a rule re-triggering itself, `agenda-group` to partition the +agenda into phases. + +## Events and time + +Declare a type as an event and the same language becomes a +[complex event processing](/drools#complex-event-processing-cep-engine) +engine. Events carry timestamps and durations, they can be reasoned about with +temporal operators, and they expire on their own: + +```drl +declare TemperatureReading + @role( event ) +end + +rule "Sustained overheating" +when + $r : TemperatureReading( celsius > 90 ) over window:time( 10s ) + from entry-point SensorStream +then + alerts.add( new Alert( $r ) ); +end +``` + +`over window:time( 10s )` slides a ten-second window over the stream, and +`from entry-point` keeps that stream partitioned from the rest of working +memory. Because events expire, long-running streams don't grow the session +without bound. + +## Other ways to write the same rules + +DRL text is one surface. The same semantics are reachable through decision +tables in Excel (`drools-decisiontables`), rule templates, and the executable +model API for building rules programmatically in Java — all of which compile +down to the same engine. + +Rules also compose with the rest of the platform: a BPMN business rule task in +[jBPM](/jbpm) calls straight into a DRL rule set, in the same service, with no +remote hop. + +## Resources + +Drools documentation: the +[DRL language reference](pathname:///docs/10.2.x/drools/drools/language-reference/index.html) +is the complete specification — every keyword, operator and conditional +element. The +[rule engine guide](pathname:///docs/10.2.x/drools/drools/rule-engine/index.html) +covers how matching, the agenda and truth maintenance actually work underneath. + +Ready to write some? [Get started](/drools/get-started). diff --git a/docs/drools/drools.md b/docs/drools/drools.md deleted file mode 100644 index 6eb5ee6..0000000 --- a/docs/drools/drools.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -id: drools -title: Drools -sidebar_label: Overview -sidebar_position: 0 ---- - -Drools is a set of projects for intelligent automation and decision management -— a forward-chaining and backward-chaining inference-based rule engine, a DMN -decision engine, and more. - -See the [Drools documentation](pathname:///docs/10.2.x/drools/drools/introduction/) for -the reference manual, published with every Apache KIE release. - -## Rule engine - -A forward-chaining and backward-chaining inference-based rule engine — the -building block of an expert system, a program that emulates the decision-making -of a human expert. - -## DMN engine - -Full runtime support for [Decision Model and Notation](/drools/dmn) models at -Conformance level 3: every feature in the OMG standard. - -## Complex Event Processing (CEP) engine - -Reason over streams of events in the same engine: temporal operators, sliding -time and length windows, and event expiration. diff --git a/docs/drools/drools.mdx b/docs/drools/drools.mdx new file mode 100644 index 0000000..cf369b4 --- /dev/null +++ b/docs/drools/drools.mdx @@ -0,0 +1,37 @@ +--- +id: drools +title: Drools +sidebar_label: Overview +sidebar_position: 0 +hide_title: true +--- + +import DroolsLogo from "@site/static/img/drools.svg"; +import ComponentBanner, { + Feature, + FeatureGrid, +} from "@site/src/components/ComponentBanner"; + +<ComponentBanner Logo={DroolsLogo} name="Drools"> + A set of projects for intelligent automation and decision management — a + forward-chaining and backward-chaining inference-based rule engine, a DMN + decision engine, and more. +</ComponentBanner> + +<FeatureGrid> + <Feature title="Rule engine" id="rule-engine"> + A forward-chaining and backward-chaining inference-based rule engine — the + building block of an expert system, a program that emulates the + decision-making of a human expert. Write rules in [DRL](/drools/drl). + </Feature> + <Feature title="DMN engine" id="dmn-engine"> + Full runtime support for [Decision Model and Notation](/drools/dmn) models + at Conformance level 3: every feature in the + [OMG](https://www.omg.org/) standard. + </Feature> + <Feature title="CEP engine" id="complex-event-processing-cep-engine"> + Complex Event Processing: reason over streams of events in the same + engine — temporal operators, sliding time and length windows, and event + expiration. + </Feature> +</FeatureGrid> diff --git a/docs/drools/get-started.md b/docs/drools/get-started.md new file mode 100644 index 0000000..1009496 --- /dev/null +++ b/docs/drools/get-started.md @@ -0,0 +1,33 @@ +--- +id: get-started +title: Get started +sidebar_position: 1 +--- + +Everything you need to write and run your first rules. + +## Prerequisites + +1. **An IDE** — [VS Code](https://code.visualstudio.com/Download) (preferred), + [IntelliJ IDEA](https://www.jetbrains.com/idea/download/) or + [Eclipse](https://www.eclipse.org/downloads/). +2. **JDK 21** (preferred) or JDK 17 — [Temurin](https://adoptium.net/) works + well. +3. **Maven 3.9+** — [Apache Maven](https://maven.apache.org/). + +## Step by step + +1. **[Understand what Drools is](pathname:///docs/10.2.x/drools/drools/introduction/)** + — what a rule engine does, and when declarative rules beat imperative code. +2. **[Build your first rule project](pathname:///docs/10.2.x/drools/drools/getting-started/#first-rule-project_getting-started)** + — create a Maven project from an archetype, write your first DRL rules and + run them from a test, in either the rule unit or the traditional style. +3. **[Build your first decision service](pathname:///docs/10.2.x/drools/drools/getting-started/#assembly-getting-started-decision-services)** + — the Traffic Violation example: model decision requirements, decision + tables and custom data types in [DMN](/drools/dmn), then evaluate them from + your application. + +From here, the +[reference manual](pathname:///docs/10.2.x/drools/drools/introduction/) covers +the rule engine, the rule language and DMN in depth, published with every +Apache KIE release. diff --git a/docs/drools/papers.md b/docs/drools/papers.md index c488aba..fde0fb8 100644 --- a/docs/drools/papers.md +++ b/docs/drools/papers.md @@ -1,7 +1,7 @@ --- id: papers title: Papers -sidebar_position: 3 +sidebar_position: 5 --- Academic papers and theses about rule engines and decision automation, from Forgy's original Rete paper onwards. diff --git a/docs/drools/upgrade-recipe.mdx b/docs/drools/upgrade-recipe.mdx index 7dc7e43..a189a81 100644 --- a/docs/drools/upgrade-recipe.mdx +++ b/docs/drools/upgrade-recipe.mdx @@ -1,9 +1,11 @@ --- id: upgrade-recipe title: Upgrade recipe -sidebar_position: 5 +sidebar_position: 7 --- +## Upgrade to 10+ + For migration to 10.0.0 or later, please refer to the [Migration Guide](pathname:///docs/10.0.x/drools/drools/migration-guide/index.html). ## Upgrade recipe 7.0 diff --git a/docs/drools/videos.md b/docs/drools/videos.md index d02cd72..fd8b897 100644 --- a/docs/drools/videos.md +++ b/docs/drools/videos.md @@ -1,7 +1,7 @@ --- id: videos title: Videos -sidebar_position: 4 +sidebar_position: 6 --- For general KIE community videos, playlists, and live streams, see the diff --git a/docs/jbpm/books.md b/docs/jbpm/books.md index cf0f3cb..ecb01d2 100644 --- a/docs/jbpm/books.md +++ b/docs/jbpm/books.md @@ -1,12 +1,44 @@ --- id: books title: Books -sidebar_position: 2 +sidebar_position: 3 --- Books about jBPM, written by members of the community. -[](http://kverlaen.blogspot.be/2015/07/book-mastering-jbpm6.html) -[](http://kverlaen.blogspot.be/2014/09/jbpm6-developer-guide.html) -[](http://kverlaen.blogspot.be/2012/12/book-jbpm5-developer-guide.html) -[](http://www.schabell.org/2018/03/book-launced-effective-business-process-management-with-jboss-bpm.html) +## jBPM books + +### [Mastering jBPM6](https://www.packtpub.com/product/mastering-jbpm6/9781783289578) + +[](https://www.packtpub.com/product/mastering-jbpm6/9781783289578) + +- Simone Fiorini, Arun V Gopalakrishnan — ISBN 9781783289578 +- A deep dive into the jBPM6 platform, from modelling processes through to the + engine that runs them and the APIs applications build on. + +### [jBPM6 Developer Guide](https://www.packtpub.com/en-us/product/jbpm6-developer-guide-9781783286614) + +[](https://www.packtpub.com/en-us/product/jbpm6-developer-guide-9781783286614) + +- Mariano Nicolas De Maio, Mauricio Salatino, Esteban Aliverti — ISBN 9781783286614 +- For Java developers and architects who want to understand how a Business + Process Management framework behaves in a real implementation, pairing the + theory behind BPM systems with building adaptable applications on jBPM6. + +### [jBPM5 Developer Guide](https://kverlaen.blogspot.com/2012/12/book-jbpm5-developer-guide.html) + +[](https://kverlaen.blogspot.com/2012/12/book-jbpm5-developer-guide.html) + +- Mauricio Salatino, Esteban Aliverti — ISBN 9781849516440 +- An introduction to BPM and to modelling processes with the + [BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/) standard, working up to more + complex examples that integrate business rules. + +### [Effective Business Process Management with JBoss BPM](http://www.schabell.org/2018/03/book-launced-effective-business-process-management-with-jboss-bpm.html) + +[](http://www.schabell.org/2018/03/book-launced-effective-business-process-management-with-jboss-bpm.html) + +- Eric D. Schabell — free ebook +- A guide to the Red Hat JBoss BPM Suite tooling: data modelling, designing + business rules and processes, worked real-world examples and tips for + testing. diff --git a/docs/jbpm/get-started.md b/docs/jbpm/get-started.md new file mode 100644 index 0000000..f3e0e1a --- /dev/null +++ b/docs/jbpm/get-started.md @@ -0,0 +1,36 @@ +--- +id: get-started +title: Get started +sidebar_position: 1 +--- + +Everything you need to build and run your first process service. In Apache +KIE 10, the jBPM process engine ships inside [Kogito](/kogito) — you build a +Kogito service and model your processes in +[BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/). + +## Prerequisites + +1. **An IDE** — [VS Code](https://code.visualstudio.com/Download) (preferred), + [IntelliJ IDEA](https://www.jetbrains.com/idea/download/) or + [Eclipse](https://www.eclipse.org/downloads/). +2. **JDK 21** (preferred) or JDK 17 — [Temurin](https://adoptium.net/) works + well. +3. **Maven 3.9+** — [Apache Maven](https://maven.apache.org/). + +## Step by step + +1. **[Build your first service](pathname:///docs/10.2.x/kogito/#chap-kogito-creating-running)** + — create a Maven project, design its logic in the Kogito modelers, then run + the service and interact with it. +2. **[Model your process in BPMN 2.0](pathname:///docs/10.2.x/kogito/#proc-bpmn-model-creating_kogito-developing-process-services)** + — create and edit BPMN 2.0 models in the [BPMN modeler](/tools/), from + start event to end event. +3. **[Develop your process service](pathname:///docs/10.2.x/kogito/#chap-kogito-developing-process-services)** + — process variables, user tasks, persistence, messaging, and integrating + processes with decisions. + +From here, the +[example applications](pathname:///docs/10.2.x/kogito/#proc-kogito-app-examples-running_kogito-creating-running) +include `orders.bpmn2`, a small process to run and pick apart. For jBPM 7 and +earlier releases, the manuals are under [Documentation](/documentation). diff --git a/docs/jbpm/getting-started.md b/docs/jbpm/getting-started.md deleted file mode 100644 index 7292e1f..0000000 --- a/docs/jbpm/getting-started.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -id: getting-started -title: Getting Started -sidebar_position: 1 ---- - -## Overview - -Business application can be defined as an automated solution, built with selected frameworks and capabilities that implements business functions and/or business problems. Capabilities can be (among others): - -* persistence -* messaging -* transactions -* business processes, business rules -* planning solutions - -Business application is more of a logical grouping of individual services that represent certain business capabilities. Usually they are deployed separately and can also be versioned individually. Overall goal is that the complete business application will allow particular domain to achieve their business goals e.g. order management, accommodation management, etc. -Business application is - -* Build on any runtime -* Deployable to cloud with just single command -* UI agnostic (doesn’t enforce any UI frameworks and let users to make their own choice) -* Configurable database profiles -* Generated - -Business application consists of (though are not restricted to have only one of each project types) - -* data model project - shared data model between business assets and service -* business assets (kjar) project - easily importable into workbench -* service project - actual service with various capabilities - -**Service project** is the one that is deployable but will in most of the cases include business assets and data model projects. - -**Data model project** represents the common data structures that will be shared between service implementation and business assets. That enables proper encapsulation and promotes reuse and at the same time reduces shortcuts to make data model classes something more than they are - include too much of implementation into data models. - -**Business assets project** represents your business logic as processes, cases, rules, decision tables and more. - -Following are the maven archetype commands need to be used to generate different types of projects: - -* Data model archetype - - ``` - mvn archetype:generate -B -DarchetypeGroupId=org.kie -DarchetypeArtifactId=kie-model-archetype -DarchetypeVersion=7.74.1.Final -DgroupId=com.company -DartifactId=business-application-model -Dversion=1.0-SNAPSHOT -Dpackage=com.company.model - ``` -This command creates a project which generates business-application-model-1.0-SNAPSHOT.jar - -* Business assets project archetype - - ``` - mvn archetype:generate -B -DarchetypeGroupId=org.kie -DarchetypeArtifactId=kie-kjar-archetype -DarchetypeVersion=7.74.1.Final -DgroupId=com.company -DartifactId=business-application-kjar -Dversion=1.0-SNAPSHOT -Dpackage=com.company - ``` -This command creates a project which generates business-application-kjar-1.0-SNAPSHOT.jar - -* Dynamic assets project archetype - - ``` - mvn archetype:generate -B -DarchetypeGroupId=org.kie -DarchetypeArtifactId=kie-kjar-archetype -DarchetypeVersion=7.74.1.Final -DcaseProject=true -DgroupId=com.company -DartifactId=business-application-kjar -Dversion=1.0-SNAPSHOT -Dpackage=com.company - ``` -This command creates a project which generates business-application-kjar-1.0-SNAPSHOT.jar - -Service project archetype can be used based on the capabilities that are needed in the project. Capabilities essentially define the features that your business application will be equipped with. Available options are: - -* Business automation(bpm) covers features for process management, case management, decision management and optimization. These will be by default configured in the service project of your business application. Although you can turn them off via configuration. - - ``` - mvn archetype:generate -B -DarchetypeGroupId=org.kie -DarchetypeArtifactId=kie-service-spring-boot-archetype -DarchetypeVersion=7.74.1.Final -DgroupId=com.company -DartifactId=business-application-service -Dversion=1.0-SNAPSHOT -Dpackage=com.company.service -DappType=bpm - ``` -* Decision management(brm) covers mainly decision and rules related features (backed by Drools project) - - ``` - mvn archetype:generate -B -DarchetypeGroupId=org.kie -DarchetypeArtifactId=kie-service-spring-boot-archetype -DarchetypeVersion=7.74.1.Final -DgroupId=com.company -DartifactId=business-application-service -Dversion=1.0-SNAPSHOT -Dpackage=com.company.service -DappType=brm - ``` -* Business optimization(planner) covers planning problems and solutions related features (backed by OptaPlanner project) - - ``` - mvn archetype:generate -B -DarchetypeGroupId=org.kie -DarchetypeArtifactId=kie-service-spring-boot-archetype -DarchetypeVersion=7.74.1.Final -DgroupId=com.company -DartifactId=business-application-service -Dversion=1.0-SNAPSHOT -Dpackage=com.company.service -DappType=planner - ``` -These commands create a project which generates business-application-service-1.0-SNAPSHOT.jar - -## Build your first Business Application - -To build your first business application,use the above mentioned maven archetype commands to generate a Data project,Business assets project and a Service project with desired capabilities. - -It is recommended to generate all the three types of projects Data Model, Business assets and Service projects using the archetypes in same directory on your computer. - -Once you have the application on your computer just follow these steps to have it up and running - -* go to directory suffixed with -service -* execute ```./launch.sh clean install``` for unix or ```launch.bat clean install``` for windows -* once the boot has finished go to http://localhost:8090 - -## More examples -[Go to examples repository](https://github.com/business-applications) - - - diff --git a/docs/jbpm/jbpm.md b/docs/jbpm/jbpm.md deleted file mode 100644 index f71246a..0000000 --- a/docs/jbpm/jbpm.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: jbpm -title: jBPM -sidebar_label: Overview -sidebar_position: 0 ---- - -jBPM is a toolkit for building business applications to help automate business -processes and decisions. See the [jBPM manuals](/documentation) for the latest -features and for earlier releases. - -## What is jBPM? - -jBPM originates from BPM (Business Process Management) but it has evolved to enable users to pick their own path in business automation. It provides various capabilities that simplify and externalize business logic into reusable assets such as cases, processes, decision tables and more. - -* business processes (BPMN2) -* case management (BPMN2 and CMMN) -* decision management (DMN) -* business rules (DRL) -* business optimisation (Solver) - -jBPM can be used as standalone service or embedded in custom service. It does not mandate any of the frameworks to be used, it can be successfully used in - -* traditional JEE applications - war/ear deployments -* SpringBoot or Thorntail (formerly known as WildFly Swarm) - uberjar deployments -* standalone Java programs - -jBPM is typically used to build business applications. A business application could be defined as a domain-specific solution (built with selected frameworks and capabilities) that solves a particular business problem. To implement the business logic it leverages capabilities from various frameworks like business processes, business rules and planning constraints, but also persistence, messaging, transactions, etc. - -jBPM is open source software, released under the Apache License 2.0. It is written in 100% pure Java™, runs on any JVM and is available in the Maven Central repository too. - -## Cloud-native? - -Looking for a pure cloud-native process automation solution, specifically targeted towards creating intelligent business applications in the cloud? Take a look at [Kogito](/kogito), based on jBPM. - - -## What does jBPM do? - -A business process allows you to model your business goals by describing the steps that need to be executed to achieve that goal and the order, using a flow chart. This greatly improves the visibility and agility of your business logic, results in higher-level and domain-specific representations that can be understood by business users and is easier to monitor. - -The core of jBPM is a light-weight, extensible workflow engine written in pure Java that allows you to execute business processes using the latest BPMN 2.0 specification. It can run in any Java environment, embedded in your application or as a service. - -On top of the core engine, a lot of features and tools are offered to support business processes throughout their entire life cycle: - -* Eclipse-based and web-based editor to support the graphical creation of your business processes and case definitions (drag & drop). -* Pluggable persistence and transactions based on JPA / JTA. -* Pluggable human task service based on WS-HumanTask for including tasks that need to be performed by human actors. -* Management console supporting process instance management, task lists and task form management, and reporting. -* Optional process repository to deploy your process (and other related knowledge). -* History logging (for querying / monitoring / analysis). -* Integration with various frameworks such as CDI/EJB, Spring(Boot), OSGi, etc. - -BPM makes the bridge between business analysts, developers and end users, by offering process management features and tools in a way that both business users and developers like it. Domain-specific nodes can be plugged into the palette, making the processes more easily understood by business users. - -jBPM supports adaptive and dynamic processes that require flexibility to model complex, real-life situations that cannot easily be described using a rigid process. We bring control back to the end users by allowing them to control which parts of the process should be executed, to dynamically deviate from the process, etc. - -jBPM is also not just an isolated process engine. Complex business logic can be modeled as a combination of business processes with business rules and complex event processing. jBPM can be combined with the Drools project to support one unified environment that integrates these paradigms where you model your business logic as a combination of processes, rules and events. - - -## Slides - -[Kris Verlaenen's jBPM presentations](http://www.slideshare.net/krisverlaenen/presentations), viewable in your browser. diff --git a/docs/jbpm/jbpm.mdx b/docs/jbpm/jbpm.mdx new file mode 100644 index 0000000..ebe164d --- /dev/null +++ b/docs/jbpm/jbpm.mdx @@ -0,0 +1,44 @@ +--- +id: jbpm +title: jBPM +sidebar_label: Overview +sidebar_position: 0 +hide_title: true +--- + +import JbpmLogo from "@site/static/img/jbpm.svg"; +import ComponentBanner, { + Feature, + FeatureGrid, +} from "@site/src/components/ComponentBanner"; + +<ComponentBanner Logo={JbpmLogo} name="jBPM"> + A workflow engine for building business applications that automate business + processes. +</ComponentBanner> + +<FeatureGrid> + <Feature title="Business processes" id="business-processes"> + Model your business goals as + [BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/) flow charts, executed by a + light-weight, extensible workflow engine written in pure Java. + </Feature> + <Feature title="Human tasks" id="human-tasks"> + Bring people into the flow: user tasks with pluggable lifecycles, + assignment strategies, notifications and deadlines — and consoles to work + on them. + </Feature> + <Feature + title="Rules and decisions orchestration" + id="rules-and-decisions-orchestration" + > + Business rule tasks call out to [DMN](https://www.omg.org/spec/DMN/) + decisions and DRL rules in the same service, evaluated by + [Drools](/drools/). + </Feature> + <Feature title="Long-running by design" id="long-running-by-design"> + Processes that live for days or months: durable state, timers, signals and + message correlation, service-level agreements, and migration of running + instances onto a new process version. + </Feature> +</FeatureGrid> diff --git a/docs/jbpm/what-is-jbpm.md b/docs/jbpm/what-is-jbpm.md new file mode 100644 index 0000000..a686d4f --- /dev/null +++ b/docs/jbpm/what-is-jbpm.md @@ -0,0 +1,44 @@ +--- +id: what-is-jbpm +title: What is jBPM? +sidebar_position: 2 +--- + +jBPM originates from BPM (Business Process Management) but it has evolved to enable users to pick their own path in business automation. It provides various capabilities that simplify and externalize business logic into reusable assets such as processes, tasks, decision tables and more. + +* business processes ([BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/)) +* human tasks, with pluggable lifecycles, assignment strategies and deadlines +* decision management ([DMN](https://www.omg.org/spec/DMN/)) +* business rules (DRL) + +jBPM is a workflow engine, not a server: it is a set of Java libraries that your service embeds. In Apache KIE 10 the supported way to build that service is [Kogito](/kogito), on either [Quarkus](https://quarkus.io/) or [Spring Boot](https://spring.io/projects/spring-boot). Your BPMN 2.0 models are compiled at build time into the code that runs them, so there is no runtime deployment step and no process repository to manage. + +jBPM is typically used to build business applications. A business application could be defined as a domain-specific solution (built with selected frameworks and capabilities) that solves a particular business problem. To implement the business logic it leverages capabilities from various frameworks like business processes and business rules, but also persistence, messaging, transactions, etc. + +jBPM is open source software, released under the Apache License 2.0. It is written in 100% pure Java™, runs on any JVM and is available in the Maven Central repository too. + +## Cloud-native? + +Looking for a pure cloud-native process automation solution, specifically targeted towards creating intelligent business applications in the cloud? Take a look at [Kogito](/kogito) — it is the cloud-native runtime that the jBPM engine ships inside, so the two are not alternatives: when you add process capabilities to a Kogito service, jBPM is what executes them. Start at [Get started](/jbpm/get-started). + +## What does jBPM do? + +A business process allows you to model your business goals by describing the steps that need to be executed to achieve that goal and the order, using a flow chart. This greatly improves the visibility and agility of your business logic, results in higher-level and domain-specific representations that can be understood by business users and is easier to monitor. + +The core of jBPM is a light-weight, extensible workflow engine written in pure Java that allows you to execute business processes using the latest BPMN 2.0 specification. It can run in any Java environment, embedded in your application or as a service. + +Its BPMN 2.0 coverage is broad: all the gateways (exclusive, inclusive, parallel, complex and event-based), intermediate catch and throw events, boundary events, errors, escalations, signals, messages, timers and links, embedded, event and ad-hoc sub-processes, call activities, multi-instance activities, compensation and transactions, lanes, and collaboration with message correlation. + +On top of the core engine, a lot of features and tools are offered to support business processes throughout their entire life cycle: + +* Web-based and IDE-based [modelers](/tools/) to support the graphical creation of your business processes (drag & drop). +* Pluggable persistence for long-running process state — PostgreSQL and other JDBC databases, MongoDB, Infinispan, RocksDB or the filesystem — added to your service as an add-on. +* A human task service for including tasks that need to be performed by human actors, including a WS-HumanTask-compatible lifecycle. +* Consoles supporting process instance management, task lists and task form management, backed by the Data Index and audit services. +* Timers and scheduled work, delegated to an embedded scheduler or to a standalone Jobs Service. +* Service-level agreement tracking, and migration of already-running process instances onto a new version of a process definition. +* History logging (for querying / monitoring / analysis) through the Data Index and Data Audit add-ons. + +BPM makes the bridge between business analysts, developers and end users, by offering process management features and tools in a way that both business users and developers like it. Domain-specific nodes can be plugged into the palette — declare them in a work item definition (`.wid`) file and the [BPMN editor](/tools/) picks them up as custom tasks — making the processes more easily understood by business users. + +jBPM is also not just an isolated process engine. Complex business logic can be modeled as a combination of business processes with business rules and decisions: a business rule task in your process calls straight into a DRL rule set or a DMN decision, evaluated by [Drools](/drools) in the same service. diff --git a/docs/kogito/get-started.md b/docs/kogito/get-started.md index 1965c26..6aa8779 100644 --- a/docs/kogito/get-started.md +++ b/docs/kogito/get-started.md @@ -1,6 +1,6 @@ --- id: get-started -title: Get Started +title: Get started sidebar_position: 1 --- @@ -13,22 +13,18 @@ Everything you need to build and run your first Kogito service. [Eclipse](https://www.eclipse.org/downloads/). 2. **JDK 21** (preferred) or JDK 17 — [Temurin](https://adoptium.net/) works well. Optionally [GraalVM](https://www.graalvm.org/) for native compilation. -3. **Maven 3.9+** — [Apache Maven](https://maven.apache.org/). The exact - versions behind a release are in the - [build instructions](/community/devs/build-10.2). +3. **Maven 3.9+** — [Apache Maven](https://maven.apache.org/). -## Then, in order +## Step by step 1. **[Understand what Kogito is](pathname:///docs/10.2.x/kogito/#con-kogito-automation_kogito-creating-running)** — what Kogito is, and when it becomes the core of your domain-specific cloud-native services. 2. **[Build your first service](pathname:///docs/10.2.x/kogito/#chap-kogito-creating-running)** - — create a Maven project, design its logic with DMN and BPMN in the Kogito + — create a Maven project, design its logic with + [DMN](https://www.omg.org/spec/DMN/) and + [BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/) in the Kogito modelers, then run the service and interact with it. 3. **[Read the example applications](pathname:///docs/10.2.x/kogito/#ref-kogito-app-examples_kogito-creating-running)** — a sequence of applications of increasing complexity, covering persistence, messaging with Kafka and data indexing. - -From here, the [guides](/kogito/guides) cover individual topics in depth, and -the [Kogito examples](https://github.com/apache/incubator-kie-kogito-examples/) -repository is worth keeping open alongside them. diff --git a/docs/kogito/guides.md b/docs/kogito/guides.md index 1f90c1d..7bfdffa 100644 --- a/docs/kogito/guides.md +++ b/docs/kogito/guides.md @@ -4,23 +4,48 @@ title: Guides sidebar_position: 2 --- -You have gone through the [Get Started guides](/kogito/get-started). You are +You have gone through the [Get started guides](/kogito/get-started). You are now ready to dive into specific topic guides. -## Tooling +## Process services + +### [Developing process services with Kogito](pathname:///docs/10.2.x/kogito/#chap-kogito-developing-process-services) + +As a developer of business processes, you can use Kogito business automation to +develop process services using +[Business Process Model and Notation (BPMN) 2.0](https://www.omg.org/spec/BPMN/2.0/) +models. BPMN 2.0 process models are graphical representations of the steps +required to achieve a business goal. You can design your BPMN 2.0 processes +with the Kogito BPMN modeler in VS Code or import existing BPMN 2.0 processes +into your Kogito projects for deployment and execution. + +### [BPMN 2.0 support in Kogito](pathname:///docs/10.2.x/kogito/#con-bpmn_kogito-developing-process-services) -### [Kogito BPMN and DMN modelers](pathname:///docs/10.2.x/kogito/#con-kogito-modelers_kogito-creating-running) +Business Process Model and Notation (BPMN) 2.0 is a standard established by the +[Object Management Group (OMG)](https://www.omg.org/) for describing and +modeling business processes. -Kogito provides extensions and application graphical modelers that you can use -to design Business Process Model and Notation (BPMN) process models and -Decision Model and Notation (DMN) decision models for your Kogito services. +### [Persistence in Kogito services](pathname:///docs/10.2.x/kogito/#con-persistence_kogito-developing-process-services) + +Kogito supports runtime persistence for preserving process data in your +services across application restarts. Kogito persistence is based on key-value +storage to persist data, such as active process nodes and process instance +variables. + +### [Kogito Management Console](pathname:///docs/10.2.x/kogito/#con-management-console_kogito-developing-process-services) + +The Kogito Management Console is a user interface for viewing the state of all +available Kogito services and managing process instances. You can use the +Management Console to view process, subprocess, and node instance details, +abort process instances, and view domain-specific process data. ## Decision services ### [Developing decision services with Kogito](pathname:///docs/10.2.x/kogito/#collection-kogito-developing-decision-services) As a developer of business decisions, you can use Kogito business automation to -develop decision services using Decision Model and Notation (DMN) models, +develop decision services using +[Decision Model and Notation (DMN)](https://www.omg.org/spec/DMN/) models, Drools Rule Language (DRL) rules, XLS or XLSX spreadsheet decision tables, or a combination of all three methods. @@ -55,36 +80,6 @@ scalable decision management architecture. The decision engine is the Kogito component that stores, processes, and evaluates data to execute business rules and to reach the decisions that you define. -## Process services - -### [Developing process services with Kogito](pathname:///docs/10.2.x/kogito/#chap-kogito-developing-process-services) - -As a developer of business processes, you can use Kogito business automation to -develop process services using Business Process Model and Notation (BPMN) 2.0 -models. BPMN process models are graphical representations of the steps required -to achieve a business goal. You can design your BPMN processes with the Kogito -BPMN modeler in VS Code or import existing BPMN processes into your Kogito -projects for deployment and execution. - -### [BPMN 2.0 support in Kogito](pathname:///docs/10.2.x/kogito/#con-bpmn_kogito-developing-process-services) - -Business Process Model and Notation (BPMN) 2.0 is a standard established by the -Object Management Group (OMG) for describing and modeling business processes. - -### [Persistence in Kogito services](pathname:///docs/10.2.x/kogito/#con-persistence_kogito-developing-process-services) - -Kogito supports runtime persistence for preserving process data in your -services across application restarts. Kogito persistence is based on key-value -storage to persist data, such as active process nodes and process instance -variables. - -### [Kogito Management Console](pathname:///docs/10.2.x/kogito/#con-management-console_kogito-developing-process-services) - -The Kogito Management Console is a user interface for viewing the state of all -available Kogito services and managing process instances. You can use the -Management Console to view process, subprocess, and node instance details, -abort process instances, and view domain-specific process data. - ## Environment configuration ### [Configuring Kogito supporting services and runtime capabilities](pathname:///docs/10.2.x/kogito/#chap-kogito-configuring) @@ -102,5 +97,5 @@ Kogito search, insight, and management capabilities. ### [Using the Kogito Jobs Service](pathname:///docs/10.2.x/kogito/#con-jobs-service_kogito-configuring) Kogito provides a Jobs Service for scheduling Business Process Model and -Notation (BPMN) process events that are configured to be executed at a +Notation (BPMN) 2.0 process events that are configured to be executed at a specified time. These time-based events in a process model are known as jobs. diff --git a/docs/kogito/kogito.mdx b/docs/kogito/kogito.mdx index 882d65c..2e6d2aa 100644 --- a/docs/kogito/kogito.mdx +++ b/docs/kogito/kogito.mdx @@ -3,11 +3,17 @@ id: kogito title: Kogito sidebar_label: Overview sidebar_position: 0 +hide_title: true --- +import KogitoLogo from "@site/static/img/kogito.svg"; +import ComponentBanner from "@site/src/components/ComponentBanner"; import KogitoHighlights from "@site/src/components/KogitoHighlights"; -Kogito is cloud-native business automation for building intelligent -applications, backed by battle-tested capabilities. +<ComponentBanner Logo={KogitoLogo} name="Kogito"> + <strong>Kogito ergo automate:</strong> cloud-native business automation for + building intelligent applications, backed by the battle-tested + [Drools](/drools) and [jBPM](/jbpm). +</ComponentBanner> <KogitoHighlights /> diff --git a/docs/optaplanner/code-example.md b/docs/optaplanner/code-example.md index 8bf533b..330ccb7 100644 --- a/docs/optaplanner/code-example.md +++ b/docs/optaplanner/code-example.md @@ -1,7 +1,7 @@ --- id: code-example title: Code example -sidebar_position: 2 +sidebar_position: 4 --- To optimize a problem from Java™ code, add the `optaplanner-core` jar and call diff --git a/docs/optaplanner/compatibility.md b/docs/optaplanner/compatibility.md index 346ac3c..1da84db 100644 --- a/docs/optaplanner/compatibility.md +++ b/docs/optaplanner/compatibility.md @@ -1,7 +1,7 @@ --- id: compatibility title: Compatibility -sidebar_position: 3 +sidebar_position: 5 --- OptaPlanner works directly from: diff --git a/docs/optaplanner/get-started.md b/docs/optaplanner/get-started.md new file mode 100644 index 0000000..c85b662 --- /dev/null +++ b/docs/optaplanner/get-started.md @@ -0,0 +1,27 @@ +--- +id: get-started +title: Get started +sidebar_position: 1 +--- + +Everything you need to solve your first planning problem. + +## Prerequisites + +1. **An IDE** — [VS Code](https://code.visualstudio.com/Download) (preferred), + [IntelliJ IDEA](https://www.jetbrains.com/idea/download/) or + [Eclipse](https://www.eclipse.org/downloads/). +2. **JDK 21** (preferred) or JDK 17 — [Temurin](https://adoptium.net/) works + well. +3. **Maven 3.9+** — [Apache Maven](https://maven.apache.org/). + +## Step by step + +1. **[Understand what OptaPlanner is](pathname:///docs/10.2.x/optaplanner/)** + — what a planning problem is, and how a constraint solver tackles it. +2. **[Do the Hello World quick start](pathname:///docs/10.2.x/optaplanner/#helloWorldJavaQuickStart)** + — optimize a school timetable from a plain Java application: model the + domain, define the constraints and solve. +3. **[Move to a framework](pathname:///docs/10.2.x/optaplanner/#quarkusJavaQuickStart)** + — the same timetable as a REST application on Quarkus (recommended), or on + [Spring Boot](pathname:///docs/10.2.x/optaplanner/#springBootJavaQuickStart). diff --git a/docs/optaplanner/optaplanner.md b/docs/optaplanner/how-it-works.md similarity index 63% rename from docs/optaplanner/optaplanner.md rename to docs/optaplanner/how-it-works.md index f6855fb..4edcf97 100644 --- a/docs/optaplanner/optaplanner.md +++ b/docs/optaplanner/how-it-works.md @@ -1,16 +1,9 @@ --- -id: optaplanner -title: OptaPlanner -sidebar_label: Overview -sidebar_position: 0 +id: how-it-works +title: How it works +sidebar_position: 3 --- -OptaPlanner is a fast, easy-to-use, open source AI constraint solver for -software developers. - -See the [OptaPlanner documentation](pathname:///docs/10.2.x/optaplanner/) for the -reference manual, published with every Apache KIE release. - ## Modern mathematical optimization OptaPlanner is a lightweight, embeddable planning engine that lets everyday @@ -25,14 +18,9 @@ Acceptance and other metaheuristics) with very efficient score calculation and other state-of-the-art constraint solving techniques for NP-complete and NP-hard problems. -OptaPlanner supports: - -- **Continuous planning** to weekly publish the schedule, 3 weeks before execution -- **Non-disruptive replanning** for changes to an already published schedule -- **Real-time planning** to react on real-time disruptions in the plan within milliseconds -- **Overconstrained planning** when there are too few resources to cover all the work -- **Pinning** so the user is still in control over the schedule - OptaPlanner is open source software, released under the Apache License. It is written in 100% pure Java™, runs on any JVM and is available in the Maven Central repository. + +See the [OptaPlanner documentation](pathname:///docs/10.2.x/optaplanner/) for the +reference manual, published with every Apache KIE release. diff --git a/docs/optaplanner/optaplanner.mdx b/docs/optaplanner/optaplanner.mdx new file mode 100644 index 0000000..3d1243c --- /dev/null +++ b/docs/optaplanner/optaplanner.mdx @@ -0,0 +1,37 @@ +--- +id: optaplanner +title: OptaPlanner +sidebar_label: Overview +sidebar_position: 0 +hide_title: true +--- + +import PlannerLogo from "@site/static/img/planner.svg"; +import ComponentBanner, { + Feature, + FeatureGrid, +} from "@site/src/components/ComponentBanner"; + +<ComponentBanner Logo={PlannerLogo} name="OptaPlanner"> + A fast, easy-to-use, open source AI constraint solver for software + developers. +</ComponentBanner> + +<FeatureGrid> + <Feature title="Continuous planning" id="continuous-planning"> + Publish the schedule weekly, three weeks before execution, so planning + keeps pace with the business rather than happening once. + </Feature> + <Feature title="Replanning" id="replanning"> + Handle changes to an already published schedule without turning it upside + down, and react to real-time disruptions within milliseconds. + </Feature> + <Feature title="Overconstrained planning" id="overconstrained-planning"> + Plan even when there are too few resources to cover all the work, so the + solver degrades gracefully instead of failing. + </Feature> + <Feature title="Pinning" id="pinning"> + Keep the user in control of the schedule by locking the parts of it that + should not move. + </Feature> +</FeatureGrid> diff --git a/docs/optaplanner/use-cases.md b/docs/optaplanner/use-cases.md index be0d17c..cb2a873 100644 --- a/docs/optaplanner/use-cases.md +++ b/docs/optaplanner/use-cases.md @@ -1,7 +1,7 @@ --- id: use-cases title: Use cases -sidebar_position: 1 +sidebar_position: 2 --- OptaPlanner optimizes plans and schedules with _hard constraints_ and _soft diff --git a/docs/sonataflow/get-started.md b/docs/sonataflow/get-started.md new file mode 100644 index 0000000..e9516a8 --- /dev/null +++ b/docs/sonataflow/get-started.md @@ -0,0 +1,23 @@ +--- +id: get-started +title: Get started +sidebar_position: 1 +--- + +Everything you need to build and run your first workflow. + +## Step by step + +1. **[Prepare your environment](pathname:///docs/10.2.x/sonataflow/serverlessworkflow/latest/getting-started/preparing-environment.html)** + — an all-in-one guide to everything the SonataFlow guides expect on your + local machine. +2. **[Get familiar with the tooling](pathname:///docs/10.2.x/sonataflow/serverlessworkflow/latest/getting-started/getting-familiar-with-our-tooling.html)** + — the editors and dev tools available for authoring workflows. +3. **[Create, run and deploy your first project](pathname:///docs/10.2.x/sonataflow/serverlessworkflow/latest/getting-started/introduction-sonataflow-development-guide.html)** + — the starting guide for SonataFlow development, from an empty directory to + a deployed workflow application. + +From here, [Integrations](/sonataflow/integrations) shows the ways SonataFlow +connects to the services and events in your architecture, and the +[SonataFlow guides](pathname:///docs/10.2.x/sonataflow/) cover individual +topics in depth, published with every Apache KIE release. diff --git a/docs/sonataflow/integrations.md b/docs/sonataflow/integrations.md index 94776c8..4040088 100644 --- a/docs/sonataflow/integrations.md +++ b/docs/sonataflow/integrations.md @@ -1,7 +1,7 @@ --- id: integrations title: Integrations -sidebar_position: 1 +sidebar_position: 2 --- Currently, with SonataFlow you can integrate with services and events in your architecture using: diff --git a/docs/sonataflow/sonataflow.md b/docs/sonataflow/sonataflow.md deleted file mode 100644 index c19409d..0000000 --- a/docs/sonataflow/sonataflow.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: sonataflow -title: SonataFlow -sidebar_label: Overview -sidebar_position: 0 ---- - -SonataFlow is a tool for building cloud-native workflow applications. You can use it to do the services and events orchestration and choreography. - -Workflows are written against the -[CNCF Serverless Workflow](https://serverlessworkflow.io/) specification, a -vendor-neutral standard for describing workflows declaratively. SonataFlow -worked with [version 0.8](https://github.com/serverlessworkflow/specification/tree/0.8.x) -of the specification. - -See [Integrations](/sonataflow/integrations) for the ways SonataFlow connects to the services and events in your architecture. - -See the [SonataFlow documentation](pathname:///docs/10.2.x/sonataflow/) for the guides -published with every Apache KIE release. diff --git a/docs/sonataflow/sonataflow.mdx b/docs/sonataflow/sonataflow.mdx new file mode 100644 index 0000000..178ecf0 --- /dev/null +++ b/docs/sonataflow/sonataflow.mdx @@ -0,0 +1,42 @@ +--- +id: sonataflow +title: SonataFlow +sidebar_label: Overview +sidebar_position: 0 +hide_title: true +--- + +import SonataFlowLogo from "@site/static/img/sonataflow.svg"; +import ComponentBanner, { + Feature, + FeatureGrid, +} from "@site/src/components/ComponentBanner"; + +<ComponentBanner Logo={SonataFlowLogo} name="SonataFlow"> + A platform for building cloud-native workflow applications. Use it for the + orchestration and choreography of your services and events. +</ComponentBanner> + +<FeatureGrid> + <Feature title="Orchestration" id="orchestration"> + Coordinate the services in your architecture into end-to-end workflows, + with a workflow in control of every call. + </Feature> + <Feature title="Choreography" id="choreography"> + Let workflows react to events and publish their own, so services + collaborate without a central controller. + </Feature> + <Feature title="An open standard" id="an-open-standard"> + Workflows are written against the + [CNCF Serverless Workflow](https://serverlessworkflow.io/) specification, + a vendor-neutral standard for describing workflows declaratively. + SonataFlow worked with + [version 0.8](https://github.com/serverlessworkflow/specification/tree/0.8.x) + of the specification. + </Feature> + <Feature title="Integrations" id="integrations"> + Connect workflows to the services and events already in your + architecture — see [Integrations](/sonataflow/integrations) for the full + list. + </Feature> +</FeatureGrid> diff --git a/docs/tools/chrome.md b/docs/tools/chrome.md index 24d8c6f..dcecf60 100644 --- a/docs/tools/chrome.md +++ b/docs/tools/chrome.md @@ -1,7 +1,7 @@ --- id: chrome title: Chrome extensions -sidebar_position: 4 +sidebar_position: 5 --- The Chrome extensions add a graphical editor to GitHub itself, so a model in a diff --git a/docs/tools/consoles.md b/docs/tools/consoles.md index 14983bc..d7b4320 100644 --- a/docs/tools/consoles.md +++ b/docs/tools/consoles.md @@ -1,7 +1,7 @@ --- id: consoles title: Dev consoles -sidebar_position: 5 +sidebar_position: 6 --- Development consoles for inspecting a running service: the processes and tasks diff --git a/docs/tools/editors.md b/docs/tools/editors.md index f7e06cf..fd8d201 100644 --- a/docs/tools/editors.md +++ b/docs/tools/editors.md @@ -1,7 +1,7 @@ --- id: editors title: Standalone editors -sidebar_position: 3 +sidebar_position: 4 --- Embeddable builds of the editors, published to npm, for putting a modeller diff --git a/docs/tools/get-started.md b/docs/tools/get-started.md new file mode 100644 index 0000000..7e89de7 --- /dev/null +++ b/docs/tools/get-started.md @@ -0,0 +1,28 @@ +--- +id: get-started +title: Get started +sidebar_position: 1 +--- + +Everything you need to open your first +[BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/), +[DMN](https://www.omg.org/spec/DMN/) or Test Scenario model. + +## Step by step + +1. **[Open KIE Sandbox](/tools/kie-sandbox)** — the editors in your browser, + with nothing to install. Start from a sample or import a repository. +2. **[Install the VS Code extensions](/tools/vscode)** — the same editors + inside your IDE, working on files in your repository. +3. **[Pick your integration](/tools/editors)** — embed the standalone editors + in your own web application, or read models as diagrams directly on GitHub + with the [Chrome extensions](/tools/chrome). + +The BPMN, DMN and Test Scenario editors were all rewritten on React, TypeScript +and PatternFly. They read your existing files unchanged — see +[the release post](/blog/new-generation-editors-kie-10-2) for the migration +path. + +From here, the [overview](/tools/) walks through each editor in turn, and the +[dev consoles](/tools/consoles) let you inspect processes and tasks in a +running jBPM service. diff --git a/docs/tools/kie-sandbox.md b/docs/tools/kie-sandbox.md index 4842ca7..aaed632 100644 --- a/docs/tools/kie-sandbox.md +++ b/docs/tools/kie-sandbox.md @@ -1,7 +1,7 @@ --- id: kie-sandbox title: Web — KIE Sandbox -sidebar_position: 1 +sidebar_position: 2 --- [KIE Sandbox](https://sandbox.kie.org) runs the BPMN, DMN, Test Scenario and DRL diff --git a/docs/tools/tools.md b/docs/tools/tools.md deleted file mode 100644 index 0918bdd..0000000 --- a/docs/tools/tools.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: tools -title: Tools -sidebar_label: Overview -sidebar_position: 0 ---- - -Four editors for the Apache KIE asset types — and four places to run them, from -a browser tab to your own web application. The quickest way to try them is -[KIE Sandbox](/tools/kie-sandbox), with nothing to install. - -## The editors - -- **BPMN Editor** — model BPMN 2.0 business processes on a canvas, with a - context-aware properties panel and validation as you draw. Rewritten for - 10.2.0 on React and TypeScript, replacing the classic GWT editor. -- **DMN Editor** — build decision requirements diagrams and author boxed - expressions, decision tables and FEEL. Rewritten for 10.0.0, and current - with DMN 1.6, the latest OMG specification. -- **DRL Editor** — edit Drools Rule Language files as text, with syntax - highlighting and completion for rules you would rather write by hand than - draw. -- **Test Scenario Editor** — write test scenarios for your decisions and rules - in a spreadsheet-like grid, and keep them in version control next to the - models they cover. Rewritten for 10.1.0. - -The BPMN, DMN and Test Scenario editors were all rewritten for the 10.x line on -React, TypeScript and PatternFly. They read your existing files unchanged — see -[the release post](/blog/new-generation-editors-kie-10-2) for the migration -path. - -## Where to run them - -- [Web — KIE Sandbox](/tools/kie-sandbox) — the editors in your browser, with nothing to install. -- [VS Code extensions](/tools/vscode) — the editors inside your IDE, working on files in your repository. -- [Standalone editors](/tools/editors) — npm packages for embedding an editor in your own web application. -- [Chrome extensions](/tools/chrome) — read and edit models as diagrams directly on GitHub. - -And, apart from the editors: - -- [Dev consoles](/tools/consoles) — inspect processes and tasks in a running jBPM service. diff --git a/docs/tools/tools.mdx b/docs/tools/tools.mdx new file mode 100644 index 0000000..4f14653 --- /dev/null +++ b/docs/tools/tools.mdx @@ -0,0 +1,41 @@ +--- +id: tools +title: Tools +sidebar_label: Overview +sidebar_position: 0 +hide_title: true +--- + +import ToolsLogo from "@site/static/img/tools.svg"; +import ComponentBanner, { + Feature, + FeatureGrid, +} from "@site/src/components/ComponentBanner"; + +<ComponentBanner Logo={ToolsLogo} name="Tools"> + Supporting tooling for authoring and managing the assets that + [Drools](/drools), [jBPM](/jbpm) and [Kogito](/kogito) run — editors for + processes, decisions, rules and test scenarios, and consoles for the + services running them. +</ComponentBanner> + +<FeatureGrid> + <Feature title="BPMN Editor" id="bpmn-editor"> + Model business processes on a canvas, with a context-aware properties + panel and validation as you draw. Supports + [BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/). + </Feature> + <Feature title="DMN Editor" id="dmn-editor"> + Build decision requirements diagrams and author boxed expressions, + decision tables and FEEL. Supports + [DMN](https://www.omg.org/spec/DMN/) 1.2 through DMN 1.6. + </Feature> + <Feature title="DRL Editor" id="drl-editor"> + Edit Drools Rule Language files as text, with syntax highlighting and + completion for rules you would rather write by hand than draw. + </Feature> + <Feature title="Test Scenario Editor" id="test-scenario-editor"> + Write test scenarios for your decisions and rules in a spreadsheet-like + grid, and keep them in version control next to the models they cover. + </Feature> +</FeatureGrid> diff --git a/docs/tools/vscode.md b/docs/tools/vscode.md index 42f5902..d027695 100644 --- a/docs/tools/vscode.md +++ b/docs/tools/vscode.md @@ -1,7 +1,7 @@ --- id: vscode title: VS Code extensions -sidebar_position: 2 +sidebar_position: 3 --- The VS Code extensions put the editors inside your IDE, working directly on the diff --git a/docusaurus.config.ts b/docusaurus.config.ts index fe6e14d..54b2a6a 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -6,7 +6,9 @@ const config: Config = { title: "Apache KIE (incubating)", tagline: "The home of the most popular business automation open-source technologies", - favicon: "img/favicon.ico", + // The favicon is set in src/theme/Root.tsx, not here: pages under a + // component hotsite fly that component's logo instead of the site icon, and + // with both set two `rel="icon"` links are emitted, the last one winning. // Set the production url of your site here url: "https://kie.apache.org/";, @@ -76,8 +78,9 @@ const config: Config = { { from: "/components/jbpm", to: "/jbpm/" }, { from: "/components/jbpm/getting_started", - to: "/jbpm/getting-started", + to: "/jbpm/get-started", }, + { from: "/jbpm/getting-started", to: "/jbpm/get-started" }, { from: "/components/kogito", to: "/kogito/" }, { from: "/components/sonataflow", to: "/sonataflow/" }, { from: "/components/tools", to: "/tools/" }, diff --git a/src/componentSections.ts b/src/componentSections.ts new file mode 100644 index 0000000..750566e --- /dev/null +++ b/src/componentSections.ts @@ -0,0 +1,79 @@ +/** + * The component hotsites: Drools, jBPM and friends, each of which owns a + * top-level docs section. + * + * One list, because several places need the same facts about a section and + * they must not drift: the breadcrumbs need its name to sit between Home and + * the page, and every page under it flies the component's logo as the + * favicon. + */ +export type ComponentSection = { + /** Sidebar name in sidebars.ts. */ + sidebar: string; + /** The component's name, as a reader would say it. */ + label: string; + /** The section's landing page, and the prefix every page under it shares. */ + basePath: string; + /** The component's logo, used as the favicon across the section. */ + logo: string; +}; + +export const COMPONENT_SECTIONS: ComponentSection[] = [ + { + sidebar: "droolsSidebar", + label: "Drools", + basePath: "/drools/", + logo: "/img/drools.svg", + }, + { + sidebar: "optaplannerSidebar", + label: "OptaPlanner", + basePath: "/optaplanner/", + logo: "/img/planner.svg", + }, + { + sidebar: "jbpmSidebar", + label: "jBPM", + basePath: "/jbpm/", + logo: "/img/jbpm.svg", + }, + { + sidebar: "kogitoSidebar", + label: "Kogito", + basePath: "/kogito/", + logo: "/img/kogito.svg", + }, + { + sidebar: "sonataflowSidebar", + label: "SonataFlow", + basePath: "/sonataflow/", + logo: "/img/sonataflow.svg", + }, + { + sidebar: "toolsSidebar", + label: "Tools", + basePath: "/tools/", + logo: "/img/tools.svg", + }, +]; + +export function findSectionBySidebar( + sidebarName: string | undefined, +): ComponentSection | undefined { + return COMPONENT_SECTIONS.find((s) => s.sidebar === sidebarName); +} + +/** + * The section a page belongs to. Matches the landing page itself (with or + * without its trailing slash) and everything beneath it. + */ +export function findSectionByPath( + pathname: string, +): ComponentSection | undefined { + return COMPONENT_SECTIONS.find( + (s) => + pathname === s.basePath || + pathname === s.basePath.replace(/\/$/, "") || + pathname.startsWith(s.basePath), + ); +} diff --git a/src/components/ComponentBanner/index.tsx b/src/components/ComponentBanner/index.tsx new file mode 100644 index 0000000..e039085 --- /dev/null +++ b/src/components/ComponentBanner/index.tsx @@ -0,0 +1,98 @@ +import React from "react"; +import clsx from "clsx"; +import Heading from "@theme/Heading"; + +import styles from "./styles.module.css"; + +type BannerProps = { + Logo: React.ComponentType<React.ComponentProps<"svg">>; + name: string; + children: React.ReactNode; +}; + +/** + * The hero of a component overview page: the component's logo and name over + * its one-paragraph definition, all centered. Pages using it set + * `hide_title: true` — the banner's name is the page's h1. The overview page + * carries nothing after the cards, so Docusaurus's own "Next: Get started" + * pagination is the page's call to action. + */ +export default function ComponentBanner({ + Logo, + name, + children, +}: BannerProps): JSX.Element { + return ( + // Not a <header>: the docs theme zeroes the top margin of whatever + // follows a header element, which would glue the cards to the banner. + <div className={styles.banner}> + <Logo className={styles.logo} role="img" aria-hidden="true" /> + <Heading as="h1" className={styles.name}> + {name} + </Heading> + <div className={styles.tagline}>{children}</div> + </div> + ); +} + +/** + * The component's sub-components (engines, editors, capabilities) as cards. + * `wideLast` puts the cards in two columns and lets the last one span both, + * for an odd card out that would otherwise sit alone in a ragged row. + */ +export function FeatureGrid({ + wideLast, + stacked, + children, +}: { + wideLast?: boolean; + /** One full-width card per row, rather than a grid of columns. */ + stacked?: boolean; + children: React.ReactNode; +}): JSX.Element { + return ( + <div + className={clsx( + styles.grid, + wideLast && styles.gridWideLast, + stacked && styles.gridStacked, + )} + > + {children} + </div> + ); +} + +export function Feature({ + title, + id, + media, + mediaSide, + children, +}: { + title: string; + id?: string; + /** Optional illustration. Shown above the title unless `mediaSide` is set. */ + media?: React.ReactNode; + /** Put the illustration beside the text instead of above it. */ + mediaSide?: "left" | "right"; + children: React.ReactNode; +}): JSX.Element { + return ( + <section + className={clsx( + styles.feature, + mediaSide && styles.featureRow, + mediaSide === "right" && styles.featureRowReverse, + )} + > + {media} + <div> + <Heading as="h2" id={id} className={styles.featureTitle}> + {title} + </Heading> + {children} + </div> + </section> + ); +} diff --git a/src/components/ComponentBanner/styles.module.css b/src/components/ComponentBanner/styles.module.css new file mode 100644 index 0000000..d795f81 --- /dev/null +++ b/src/components/ComponentBanner/styles.module.css @@ -0,0 +1,130 @@ +.banner { + display: flex; + flex-direction: column; + align-items: center; + text-align: center; + padding: 2rem 1rem 0.5rem; +} + +/* Hero art behind the banner, bled to the edges of the content column. The + pseudo-element (rather than a background on .banner itself) is what lets it + bleed past the column's padding; `isolation` keeps the negative z-index + inside the banner instead of dropping it behind the page. */ +.logo { + /* Same treatment as the homepage cards: the logo is a single shape filled + with the theme's primary color. */ + height: clamp(5.5rem, 12vw, 8rem); + width: clamp(5.5rem, 12vw, 8rem); + fill: var(--ifm-color-primary); + margin-bottom: 1.25rem; +} + +/* Same wordmark treatment as "KIE" in the homepage hero. */ +.name { + font-family: "Quicksand", var(--ifm-font-family-base); + font-size: 2.75rem; + margin-bottom: 0.75rem; +} + +.tagline { + max-width: 42rem; + font-size: 1.125rem; + /* Full strength rather than the muted grey body text: this is the one line + that defines the component. Mirrored to white on a dark page, where pure + black would be unreadable. */ + color: #000; +} + +[data-theme="dark"] .tagline { + color: #fff; +} + +.tagline p:last-child { + margin-bottom: 0; +} + +.grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); + gap: 1rem; + margin: 3rem 0; +} + +.gridStacked { + grid-template-columns: 1fr; +} + +/* Exactly four cards read better as a 2×2 than as 3 + 1. */ +@media (min-width: 700px) { + .grid:has(> :nth-child(4):last-child), + .gridWideLast { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + + .gridWideLast > :last-child { + grid-column: 1 / -1; + } +} + +.feature { + padding: 1.25rem 1.5rem; + border: 1px solid var(--ifm-color-emphasis-200); + border-radius: 8px; + /* Not quite opaque: on a page with hero art behind the cards this lifts the + text clear of it while still letting the art register through. */ + background-color: rgb(255 255 255 / 0.82); +} + +[data-theme="dark"] .feature { + background-color: rgb(36 37 38 / 0.82); +} + +/* Illustration beside the text rather than above it. */ +.featureRow { + display: flex; + align-items: center; + gap: 1.75rem; +} + +.featureRowReverse { + flex-direction: row-reverse; +} + +/* A list beside an illustration only fills part of the card, leaving it tall + with dead space alongside. Two columns spend the width instead. */ +@media (min-width: 700px) { + .featureRow ul { + columns: 2; + column-gap: 2.5rem; + } + + .featureRow li { + break-inside: avoid; + } +} + +/* Too narrow to sit side by side: the illustration goes back above the text, + where it needs the gap the flex layout was providing. */ +@media (max-width: 700px) { + .featureRow { + display: block; + } + + .featureRow > :first-child { + margin-bottom: 0.75rem; + } +} + +.feature p:last-child, +.feature ul:last-child { + margin-bottom: 0; +} + +.feature ul { + padding-left: 1.1rem; +} + +.featureTitle { + font-size: 1.15rem; + margin-bottom: 0.5rem; +} diff --git a/src/components/KogitoHighlights/index.tsx b/src/components/KogitoHighlights/index.tsx index c473052..3914ae9 100644 --- a/src/components/KogitoHighlights/index.tsx +++ b/src/components/KogitoHighlights/index.tsx @@ -1,11 +1,13 @@ import useBaseUrl from "@docusaurus/useBaseUrl"; -import Heading from "@theme/Heading"; +import { Feature, FeatureGrid } from "@site/src/components/ComponentBanner"; import styles from "./styles.module.css"; type Highlight = { title: string; image: string; + /** Multiplier on the base illustration size; taller cards carry bigger art. */ + imageScale?: number; body: React.ReactNode; }; @@ -13,18 +15,20 @@ const HIGHLIGHTS: Highlight[] = [ { title: "Kogito ergo cloud", image: "/img/kogito/homepage_graphic_1", + imageScale: 2, body: ( <p> Kogito is designed from ground up to run at scale on cloud infrastructure. By taking advantage of the latest technologies (Quarkus, - Knative, etc.), you get amazingly fast boot times and instant scaling on - orchestration platforms like Kubernetes. + Spring Boot, etc.), you get amazingly fast boot times and instant + scaling on orchestration platforms like Kubernetes. </p> ), }, { title: "Kogito ergo domain", image: "/img/kogito/homepage_graphic_2", + imageScale: 1.5, body: ( <p> Kogito adapts to your business domain rather than the other way around. @@ -37,6 +41,7 @@ const HIGHLIGHTS: Highlight[] = [ { title: "Kogito ergo power", image: "/img/kogito/homepage_graphic_3", + imageScale: 2, body: ( <> <p> @@ -54,33 +59,54 @@ const HIGHLIGHTS: Highlight[] = [ }, ]; -function HighlightColumn({ highlight }: { highlight: Highlight }): JSX.Element { +function HighlightCard({ + highlight, + mediaSide, +}: { + highlight: Highlight; + mediaSide: "left" | "right"; +}): JSX.Element { const image = useBaseUrl(`${highlight.image}.png`); const image2x = useBaseUrl(`${highlight.image}@2x.png`); return ( - <div className={styles.highlight}> - <img - className={styles.image} - src={image} - srcSet={`${image} 1x, ${image2x} 2x`} - alt="" - aria-hidden="true" - /> - <Heading as="h2" className={styles.title}> - {highlight.title} - </Heading> + <Feature + title={highlight.title} + mediaSide={mediaSide} + media={ + <img + className={styles.image} + style={ + { + "--kie-highlight-image-scale": highlight.imageScale ?? 1, + } as React.CSSProperties + } + src={image} + srcSet={`${image} 1x, ${image2x} 2x`} + alt="" + aria-hidden="true" + /> + } + > {highlight.body} - </div> + </Feature> ); } -/** The three "Kogito ergo ..." columns, embedded in the Kogito overview doc. */ +/** + * The three "Kogito ergo ..." cards, embedded in the Kogito overview doc. + * Same cards as the other component overviews, but stacked full width with + * the illustrations alternating side to side down the page. + */ export default function KogitoHighlights(): JSX.Element { return ( - <div className={styles.grid}> - {HIGHLIGHTS.map((highlight) => ( - <HighlightColumn key={highlight.title} highlight={highlight} /> + <FeatureGrid stacked> + {HIGHLIGHTS.map((highlight, index) => ( + <HighlightCard + key={highlight.title} + highlight={highlight} + mediaSide={index % 2 === 0 ? "left" : "right"} + /> ))} - </div> + </FeatureGrid> ); } diff --git a/src/components/KogitoHighlights/styles.module.css b/src/components/KogitoHighlights/styles.module.css index e812c91..7ef42f0 100644 --- a/src/components/KogitoHighlights/styles.module.css +++ b/src/components/KogitoHighlights/styles.module.css @@ -1,32 +1,9 @@ -.grid { - display: grid; - grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); - gap: 2rem; - margin: 2rem 0; -} - -.highlight p:last-child, -.highlight ul:last-child { - margin-bottom: 0; -} - -.highlight ul { - padding-left: 1.1rem; -} +/* The cards themselves come from ComponentBanner, shared with the other + component overviews. Only Kogito's illustration sizing lives here. */ .image { - width: 4.5rem; + display: block; + flex: 0 0 auto; + width: calc(5rem * var(--kie-highlight-image-scale, 1)); height: auto; - margin-bottom: 0.75rem; -} - -/* Cinzel reads as carved rather than typed — the "Kogito ergo ..." motto - face. Caps set solid need a little tracking to breathe. */ -.title { - margin-bottom: 0.5rem; - font-family: "Cinzel", Georgia, serif; - font-size: 1.25rem; - font-weight: 600; - letter-spacing: 0.02em; - line-height: 1.15; } diff --git a/src/css/custom.css b/src/css/custom.css index 1c604f1..fdfcadb 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -224,3 +224,45 @@ html { height: 3rem; margin-right: 0.5rem; } + +/* The Kogito hero, carried over from kogito.kie.org so the overview keeps that + site's vibe. It hangs off the docs main container rather than the banner + itself: the banner is inset by the content column's padding, so the art + would end in a hard vertical edge partway across the page. On <main> it + spans the full width and its own aspect ratio sets the band's height, so + nothing is cropped. Scoped to the Kogito overview by the doc id Docusaurus + puts on <html> (the id contains a slash, hence the attribute selector). */ +html[class*="docs-doc-id-kogito/kogito"] main[class*="docMainContainer"] { + position: relative; + isolation: isolate; +} + +html[class*="docs-doc-id-kogito/kogito"] main[class*="docMainContainer"]::before { + content: ""; + position: absolute; + top: 0; + left: 0; + width: 100%; + /* The art is drawn 2619x884 and scaled to 125% of the column so it reads at + hero size. Anchored top left, so it grows out to the right and the mascot + watermark stays whole. The band's height follows the same scale + (884 x 1.25 = 1105) so the bottom of the composition isn't clipped; keep + the two in step if the scale changes. A background image can't overflow + its box, so the bleed costs no horizontal scroll. */ + aspect-ratio: 2619 / 1105; + z-index: -1; + pointer-events: none; + background: url("/img/kogito/hero-background.svg") no-repeat top left; + background-size: 125% auto; + opacity: 0.33; +} + +/* The art is drawn for a light page: the mascot watermark multiplies away on + a dark one, leaving only the geometric shapes, which need holding back. */ +[data-theme='dark'] + html[class*="docs-doc-id-kogito/kogito"] + main[class*="docMainContainer"]::before, +html[class*="docs-doc-id-kogito/kogito"][data-theme='dark'] + main[class*="docMainContainer"]::before { + opacity: 0.16; +} diff --git a/src/theme/DocBreadcrumbs/index.tsx b/src/theme/DocBreadcrumbs/index.tsx new file mode 100644 index 0000000..21d0199 --- /dev/null +++ b/src/theme/DocBreadcrumbs/index.tsx @@ -0,0 +1,135 @@ +/** + * Swizzled from @docusaurus/theme-classic to add a section crumb. + * + * Every docs section here is an `autogenerated` sidebar over a flat folder, so + * Docusaurus has no category to put between the home crumb and the page, and + * every page reads "Home > Overview". This adds the section itself — the name + * a reader would call the hotsite — giving "Home > Drools > Overview". + */ +import React from "react"; +import clsx from "clsx"; +import { ThemeClassNames } from "@docusaurus/theme-common"; +import { + useSidebarBreadcrumbs, + useHomePageRoute, + useDocsSidebar, +} from "@docusaurus/theme-common/internal"; +import Link from "@docusaurus/Link"; +import { translate } from "@docusaurus/Translate"; +import HomeBreadcrumbItem from "@theme/DocBreadcrumbs/Items/Home"; + +import { findSectionBySidebar } from "@site/src/componentSections"; +import styles from "./styles.module.css"; + +function BreadcrumbsItemLink({ + children, + href, + isLast, +}: { + children: React.ReactNode; + href?: string; + isLast: boolean; +}) { + const className = "breadcrumbs__link"; + if (isLast) { + return ( + <span className={className} itemProp="name"> + {children} + </span> + ); + } + return href ? ( + <Link className={className} href={href} itemProp="item"> + <span itemProp="name">{children}</span> + </Link> + ) : ( + <span className={className}>{children}</span> + ); +} + +function BreadcrumbsItem({ + children, + active, + index, + addMicrodata, +}: { + children: React.ReactNode; + active?: boolean; + index: number; + addMicrodata?: boolean; +}) { + return ( + <li + {...(addMicrodata && { + itemScope: true, + itemProp: "itemListElement", + itemType: "https://schema.org/ListItem";, + })} + className={clsx("breadcrumbs__item", { + "breadcrumbs__item--active": active, + })} + > + {children} + <meta itemProp="position" content={String(index + 1)} /> + </li> + ); +} + +export default function DocBreadcrumbs(): JSX.Element | null { + const breadcrumbs = useSidebarBreadcrumbs(); + const homePageRoute = useHomePageRoute(); + const sidebar = useDocsSidebar(); + + if (!breadcrumbs) { + return null; + } + + const section = findSectionBySidebar(sidebar?.name); + const items = section + ? [ + { type: "link" as const, label: section.label, href: section.basePath }, + ...breadcrumbs, + ] + : breadcrumbs; + + return ( + <nav + className={clsx( + ThemeClassNames.docs.docBreadcrumbs, + styles.breadcrumbsContainer, + )} + aria-label={translate({ + id: "theme.docs.breadcrumbs.navAriaLabel", + message: "Breadcrumbs", + description: "The ARIA label for the breadcrumbs", + })} + > + <ul + className="breadcrumbs" + itemScope + itemType="https://schema.org/BreadcrumbList"; + > + {homePageRoute && <HomeBreadcrumbItem />} + {items.map((item, idx) => { + const isLast = idx === items.length - 1; + const href = + item.type === "category" && item.linkUnlisted + ? undefined + : item.href; + return ( + <BreadcrumbsItem + key={idx} + active={isLast} + index={idx} + addMicrodata={!!href} + > + <BreadcrumbsItemLink href={href} isLast={isLast}> + {item.label} + </BreadcrumbsItemLink> + </BreadcrumbsItem> + ); + })} + </ul> + </nav> + ); +} diff --git a/src/theme/DocBreadcrumbs/styles.module.css b/src/theme/DocBreadcrumbs/styles.module.css new file mode 100644 index 0000000..535b44a --- /dev/null +++ b/src/theme/DocBreadcrumbs/styles.module.css @@ -0,0 +1,7 @@ +/* Copied verbatim from @docusaurus/theme-classic alongside the swizzled + DocBreadcrumbs component. */ + +.breadcrumbsContainer { + --ifm-breadcrumb-size-multiplier: 0.8; + margin-bottom: 0.8rem; +} diff --git a/src/theme/Root.tsx b/src/theme/Root.tsx index ba7ad3c..8514c85 100644 --- a/src/theme/Root.tsx +++ b/src/theme/Root.tsx @@ -1,9 +1,46 @@ -import {useEffect} from 'react'; -import {useLocation, useHistory} from '@docusaurus/router'; +import Head from "@docusaurus/Head"; +import { useLocation } from "@docusaurus/router"; +import useBaseUrl from "@docusaurus/useBaseUrl"; -export default function Root({children}: {children: React.ReactNode}): JSX.Element | null { - const location = useLocation(); - const history = useHistory(); +import { findSectionByPath } from "@site/src/componentSections"; - return <>{children}</>; +const SITE_FAVICON = "/img/favicon.ico"; + +/** + * Flies the component's own logo as the favicon on every page of a component + * hotsite, so a tab parked on the Drools docs is recognisable as Drools, and + * the site's own icon everywhere else. + * + * The favicon is set here rather than by `favicon` in docusaurus.config.ts. + * With both, two `rel="icon"` links are emitted and the browser honours the + * last one — which was the config's, so the component logo never won. + */ +function Favicon(): JSX.Element { + const { pathname } = useLocation(); + const section = findSectionByPath(pathname); + const icon = section?.logo ?? SITE_FAVICON; + const href = useBaseUrl(icon); + + return ( + <Head> + <link + rel="icon" + href={href} + {...(icon.endsWith(".svg") ? { type: "image/svg+xml" } : {})} + /> + </Head> + ); +} + +export default function Root({ + children, +}: { + children: React.ReactNode; +}): JSX.Element { + return ( + <> + <Favicon /> + {children} + </> + ); } diff --git a/static/img/kogito.svg b/static/img/kogito.svg index c3c76a4..34a260f 100644 --- a/static/img/kogito.svg +++ b/static/img/kogito.svg @@ -1 +1 @@ -<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 1024 1024"><defs><style>.cls-2{fill:#fff;}.cls-3{fill:#f5891f;}.cls-4{fill:#97d4e8;}</style></defs><title>kogito_icon_rgb_color_default</title><path fill="#085870" d="M929.37,30.5A70.31,70.31,0,0,0,872.19,1C868.09,1,738,23.67,738,23.67a70.15,70.15,0,0,0-48.1,33.25L668,93.77c-48.41-42.46-101.74-64.7-156-64.7S404.43,51.31,356,93.77L334.11,56.92A70.13,70.13,0,0,0,286,23.67S155.9,1,151.81,1A70.19,70.19,0,0, [...] \ No newline at end of file +<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 1024 1024"><defs><style>.kogito-cls-2{fill:#fff;}.kogito-cls-3{fill:#f5891f;}.kogito-cls-4{fill:#97d4e8;}</style></defs><title>kogito_icon_rgb_color_default</title><path fill="#085870" d="M929.37,30.5A70.31,70.31,0,0,0,872.19,1C868.09,1,738,23.67,738,23.67a70.15,70.15,0,0,0-48.1,33.25L668,93.77c-48.41-42.46-101.74-64.7-156-64.7S404.43,51.31,356,93.77L334.11,56.92A70.13,70.13,0,0,0,286,23.67S155.9,1,151. [...] \ No newline at end of file diff --git a/static/img/kogito/hero-background.svg b/static/img/kogito/hero-background.svg new file mode 100644 index 0000000..f40d01b --- /dev/null +++ b/static/img/kogito/hero-background.svg @@ -0,0 +1,12 @@ +<svg xmlns="http://www.w3.org/2000/svg"; xmlns:xlink="http://www.w3.org/1999/xlink"; width="2619" height="884" viewBox="0 0 2619 884"> + <defs> + <style> + .cls-1 { + opacity: 0.5; + mix-blend-mode: multiply; + } + </style> + </defs> + <image id="hero_background_element" data-name="hero background element" x="804" y="-432" width="1794" height="1223" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABwIAAATHCAYAAADu57OzAAAgAElEQVR4nOzdD7Cs513Y9+fq35WMiGz8BxmbqPwztpCDXVzUTkixPaeGCY7JH4iYUOi0DS1SOowyTUb2dJrpZDo1SqZFSSa+NB5I+ZMExU5CiE2Je8YRDJmOaRhjdEc2GYxRJFvXNsY2XJCELd3O3rvP1Z5zds/uvu/7PO/z5/OZuXN1zx6fPed91nt29/v+nj0TAGBCF++/7ZYQwntCCH/75vse/TnHlrlcvP+2G0II7woh/MLN9z16zkIAAHDcwcHB3SGEbw8hfPfh4eEfnfgEyOTg4OAtIYS/ [...] + <image id="logo_watermark" data-name="logo watermark" class="cls-1" x="-111" y="-156" width="861" height="1022" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA10AAAP+CAYAAADw83UfAAAgAElEQVR4nOzdedAlxXnv+R/0SrPvidjFJiCF2BG72CVLsi3b8ibbknV1JZct29czEZ6JmH/mn4mYOzFxr8eWXdptydo3hCRA7PsmQAhIse/NUg1NL0A3vfdENs9pHU6d9+2zn8qq7yfixPtSdfqlKuucynwqM5/cTg2Rh2KepD0l7WU/d5a0k70W2StaaD83SXpd0gpJr0paaj/ja3nm3camlB0AAACgt9rUcyTtbu3p9rb1bta+3t7eusZ+rrbXG/Z6vb1tnXm3vgkFW8ugKw/FfEn7STpA0jsk7W8f [...] +</svg> diff --git a/static/img/navbar-logo.svg b/static/img/navbar-logo.svg index 14de23f..235d015 100644 --- a/static/img/navbar-logo.svg +++ b/static/img/navbar-logo.svg @@ -1 +1 @@ -<svg width="50px" height="50px" id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 1024 1024"><defs><style>.cls-1{fill:#f5891f;}.cls-2{fill:#97d4e8;}.cls-3{fill:#fff;}.cls-4{fill:#085870;}</style></defs><title>kie_icon_rgb_fullcolor_default</title><path class="cls-1" d="M921.17,381.72V280.19l-251.84,85.9a188.74,188.74,0,0,0-102.28,96.54l-46.6,101.14,45.25,30.1L512,719.41,458.29,593.87l45.26-30.1L456.94,462.63a188.62,188.62,0,0,0-101.47-96.22l-252.65-81v96.29 [...] \ No newline at end of file +<svg width="50px" height="50px" id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 1024 1024"><defs><style>.kie-cls-1{fill:#f5891f;}.kie-cls-2{fill:#97d4e8;}.kie-cls-3{fill:#fff;}.kie-cls-4{fill:#085870;}</style></defs><title>kie_icon_rgb_fullcolor_default</title><path class="kie-cls-1" d="M921.17,381.72V280.19l-251.84,85.9a188.74,188.74,0,0,0-102.28,96.54l-46.6,101.14,45.25,30.1L512,719.41,458.29,593.87l45.26-30.1L456.94,462.63a188.62,188.62,0,0,0-101.47-96 [...] \ No newline at end of file diff --git a/static/img/sonataflow.svg b/static/img/sonataflow.svg index 97ed52a..8a371c3 100644 --- a/static/img/sonataflow.svg +++ b/static/img/sonataflow.svg @@ -1 +1 @@ -<?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 235.66 235.66"><defs><style>.cls-1{fill:none;stroke:#085870;stroke-miterlimit:10;stroke-width:4.59px;}.cls-2{fill:#97d4e8;}.cls-2,.cls-3,.cls-4,.cls-5,.cls-6{stroke-width:0px;}.cls-3{fill:#085870;}.cls-4{fill:#15aae2;}.cls-5{fill:#f5891f;}.cls-6{fill:#fff;}</style></defs><circle class="cls-1" cx="117.83" cy="117.83" r="115.53"/><circle class="cls-2" cx="117.73" cy="117.66" r="91.71"/>< [...] \ No newline at end of file +<?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 235.66 235.66"><defs><style>.sf-cls-1{fill:none;stroke:#085870;stroke-miterlimit:10;stroke-width:4.59px;}.sf-cls-2{fill:#97d4e8;}.sf-cls-2,.sf-cls-3,.sf-cls-4,.sf-cls-5,.sf-cls-6{stroke-width:0px;}.sf-cls-3{fill:#085870;}.sf-cls-4{fill:#15aae2;}.sf-cls-5{fill:#f5891f;}.sf-cls-6{fill:#fff;}</style></defs><circle class="sf-cls-1" cx="117.83" cy="117.83" r="115.53"/><circle class="sf-cls- [...] \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
