From 82b77f1fe4a27f7b6ff8bce1e6ac9a754a0cab89 Mon Sep 17 00:00:00 2001 From: Pascal Mengelt Date: Sat, 7 Dec 2024 13:16:37 +0100 Subject: [PATCH] run documentation/laikaSite. --- docs/bpmnDsl.html | 329 +++++++++++++++++++++++++++++++++++++--------- docs/index.html | 35 +---- 2 files changed, 274 insertions(+), 90 deletions(-) diff --git a/docs/bpmnDsl.html b/docs/bpmnDsl.html index cbd9cb05..d6344dd2 100644 --- a/docs/bpmnDsl.html +++ b/docs/bpmnDsl.html @@ -75,16 +75,21 @@

BPMN DSL

@@ -95,46 +100,118 @@

BPMN DSL

This DSL will bring your domain into your BPMN-Process.

-

Its elements are more or less constructors with the same structure:

- 
BPMN_ELEMENT(
-  id: String,
-  in: Input,
-  out: Output,
-  descr: Optable[String]
-)
+

As the pattern is always the same, we can setup each BPMN Element in the same way.

+ 
object BpmnElement extends CompanyBpmn<Element>Dsl:
+
+  val processName = "mycompany-myproject-myelement" // depending on the element this can be different
+  lazy val descr = "my element..."
+
+  case class In(...)
+  object In:
+    given ApiSchema[In] = deriveApiSchema
+    given InOutCodec[In] = deriveInOutCodec
+
+  case class Out(...)
+  object Out:
+    given ApiSchema[Out] = deriveApiSchema
+    given InOutCodec[Out] = deriveInOutCodec
+
+  lazy val example = <bpmnElement>(
+    In(),
+    Out(),
+  )
+end BpmnElement

So each BPMN Element has:

+ +

Special Case Enums

+

If you have an Enum as an In or Out class, you need to define the example like this:

+ 

+lazy val example = <bpmnElement>(
+  In.CaseA(),
+  Out.CaseA(),
+  ).withEnumInExamples(In.CaseB())
+  .withEnumOutExamples(Out.CaseB())
+ +

We support the following elements:

+ +

Process

+

The Process is the main element of a BPMN. + It is the most complex element and looks like this:

+ 
object MyProcess extends CompanyBpmnProcessDsl:
+
+  val processName = "mycompany-myproject-myprocess"
+  lazy val descr = "my process..."
+  
+  case class In(
+    ...
+    inConfig: Option[InConfig] = None
+  ) extends WithConfig[InConfig]
+  
+  object In:
+    given ApiSchema[In] = deriveApiSchema
+    given InOutCodec[In] = deriveInOutCodec
+  
+  case class InConfig(
+    // Process Configuration
+    ...
+    // Mocks
+    ... )
+  object InConfig:
+    given ApiSchema[InConfig] = deriveApiSchema
+    given InOutCodec[InConfig] = deriveInOutCodec
+    
+  case class InitIn(...)
+  object InitIn:
+    given ApiSchema[InitIn] = deriveApiSchema
+    given InOutCodec[InitIn] = deriveInOutCodec
+  
+  case class Out(...)
+  object Out:
+    given ApiSchema[Out] = deriveApiSchema
+    given InOutCodec[Out] = deriveInOutCodec
+  
+  lazy val example = process(
+    In(),
+    Out(),
+    InitIn()
+  )
+end MyProcess
+

Next to the In and Out classes we have an InitIn- and InConfig class.

+ +

InitIn

+

Each process has an InitWorker that is the first worker that is called when the process is started.

+

Use this class to:

+ + +

InConfig

+

These are technical Process Variables, like:

+ -

Here is an example:

- 
process(
-  id = InvoiceReceiptPIdent,
-  descr = "This starts the Invoice Receipt Process.",
-  in = InvoiceReceipt(),
-  out = InvoiceReceiptCheck() // just for testing
-)
-

The element is a process with its inputs and outputs. As we also want to test its execution, - we defined also an output, also the process does not have one.

-

If your element has no Input and/or Output, just leave it empty, as this is the default case.

- 
process(
-  id = MyDoItItselfProcess
-)
+

The InitWorker will automatically put these variables on the process. + That means you can override them for example in Postman

+
-

We only support elements you can interact with. The next subchapters describe them with an example.

- -

Process

-

We already showed a process example above. Here the sub process Review Invoice:

- 
process(
-  id = "example-invoice-c7-review",
-  descr = "This starts the Review Invoice Process.",
-  in = InvoiceReceipt(),
-  out = InvoiceReviewed()
-)

Business Rule Tasks (Decision DMNs)

We support only Decision DMNs. @@ -159,7 +236,6 @@

singleEntry

This is a single result with one simple value. 

singleEntry(
-    decisionDefinitionKey = "singleEntry",
     in = Input("A"),
     out = 1
   )
@@ -167,7 +243,6 @@

singleResult

This is a single result with more than one value (domain object).

singleResult(
-    decisionDefinitionKey = "singleResult",
     in = Input("A"),
     out = ManyOutResult(1, "🤩")
 )
@@ -175,7 +250,6 @@

collectEntries

This is a list of simple values.

collectEntries(
-    decisionDefinitionKey = "collectEntries",
     in = Input("A"),
     out = Seq(1, 2)
   )
@@ -183,47 +257,178 @@

resultList

This is a list of domain objects.

resultList(
-    decisionDefinitionKey = "resultList",
     in = Input("A"),
     out = List(ManyOutResult(1, "🤩"), ManyOutResult(2, "😂"))
   )

User Task

A User Task describes its form values that it offers and the values it must be completed with.

- 
userTask(
-    id = "ApproveInvoiceUT",
-    descr = "Approve the invoice (or not).",
-    in = InvoiceReceipt(),
-    out = ApproveInvoice()
-  )
+ 
object MyUserTask extends CompanyBpmnUserTaskDsl:
+
+  val name = "mycompany-myproject-myusertask"
+  val descr: String = "my user task..."
+  
+  case class In(...)
+  object In:
+    given ApiSchema[In] = deriveApiSchema
+    given InOutCodec[In] = deriveInOutCodec
+  
+  case class Out(...)
+  object Out:
+    given ApiSchema[Out] = deriveApiSchema
+    given InOutCodec[Out] = deriveInOutCodec
+  
+  lazy val example = userTask(
+    In(),
+    Out()
+  )
+end MyUserTask
+ + +

External Task

+

An External Task describes a worker. + We distinguish different types of Tasks, which are described in the next subchapters.

+ 
### Custom Task
+A _Custom Task_ is a description for a worker that does some business logic, like mapping.
+
+In General, you can do whatever you want with a _Custom Task_. See also _CustomWorker_.
+
+```scala
+object MyCustomTask extends CompanyBpmnCustomTaskDsl:
+
+  val topicName = "mycompany-myproject-myprocessV1.MyCustomTask"
+  val descr: String = "my custom task..."
+  
+  case class In(...)
+  object In:
+    given ApiSchema[In] = deriveApiSchema
+    given InOutCodec[In] = deriveInOutCodec
+  
+  case class Out(...)
+  object Out:
+    given ApiSchema[Out] = deriveApiSchema
+    given InOutCodec[Out] = deriveInOutCodec
+  
+  lazy val example = customTask(
+    In(),
+    Out()
+  )
+end MyCustomTask
+ +

Init Task

+

An Init Task is a description for a worker that initializes a Process.

+

In General, you map the In object to the InitIn object like init process variables. + See also InitWorker.

+

So no extra BPMN Element is needed for this, it is automatically defined by the Process.

+ 
object MyProcess extends CompanyBpmnProcessDsl:
+  ...
+  case class In(
+    ...
+    inConfig: Option[InConfig] = None
+  ) extends WithConfig[InConfig]
+  ...  
+  case class InitIn(...)
+  ...
+end MyProcess
+ +

Service Task

+

A Service Task is a description for a worker that provides a REST API request.

+

See also ServiceWorker.

+ 
object MyServiceTask extends CompanyBpmnServiceTaskDsl:
+
+  val topicName = "mycompany-myproject-myservicetask"
+  val descr: String = "my service task..."
+  val path = "POST: /myService"
+
+  type ServiceIn = MyServiceBody
+  type ServiceOut = NoOutput
+  lazy val serviceInExample = MyServiceBody()
+  lazy val serviceMock = MockedServiceResponse.success204
+
+  case class In(...)
+  object In:
+    given ApiSchema[In] = deriveApiSchema
+    given InOutCodec[In] = deriveInOutCodec
+  
+  case class Out(...)
+  object Out:
+    given ApiSchema[Out] = deriveApiSchema
+    given InOutCodec[Out] = deriveInOutCodec
+  
+  lazy val example = serviceTask(
+    In(),
+    Out(),
+    serviceMock,
+    serviceInExample
+  )
+end MyServiceTask
+

This task is more specific, and so we need to define

+ +
+ +

At the moment we only support these 3 types of External Tasks. + Depending on the use case we can add more types.

+

Receive Message Event

A Receive Message Event represents a catching message event. The input defines the message you expect. This works only as intermediate event. As we don't support throwing Message events we can simplify this to messageEvent:

- 
lazy val messageExample = messageEvent(
-  "message-for-example",
-  in = MessageExampleIn(),
-)
+ 
object MyMessageEvent extends CompanyBpmnMessageEventDsl:
+
+  val messageName = "mycompany-myproject-mymessage"
+  val descr: String = "my message..."
+  
+  case class In(...)
+  object In:
+    given ApiSchema[In] = deriveApiSchema
+    given InOutCodec[In] = deriveInOutCodec
+  
+  lazy val example = messageEvent(In())
+end MyMessageEvent
+

Receive Signal Event

A Receive Signal Event represents a catching signal event. The input defines the signal you expect. This works only as intermediate event. As we don't support Throwing Signal events we can simplify this to signalEvent:

- 
lazy val signalExample = signalEvent(
-  "signal-for-example",
-  in = SignalExampleIn(),
-)
- -

Timer Event

-

A Timer Event represents a timer event. - There is no input needed, you can use it to describe the timers in your API doc, or using them in the Simulations to execute the job of the timer immediately. - This works only as intermediate event.

- 
lazy val timerExample = timerEvent(
-  "timer-for-example",
-)
+ 
object MySignalEvent extends CompanyBpmnSignalEventDsl:
+
+  val messageName = "mycompany-myproject-mysignal-{processInstanceId}"
+  val descr: String = "my signal..."
+
+  case class In(...)
+  object In:
+    given ApiSchema[In] = deriveApiSchema
+    given InOutCodec[In] = deriveInOutCodec
+  
+  lazy val example = signalEvent(In())
+end MySignalEvent
+
diff --git a/docs/index.html b/docs/index.html index 85483c9d..155fa0b9 100644 --- a/docs/index.html +++ b/docs/index.html @@ -6,7 +6,7 @@ - + Intro @@ -20,7 +20,6 @@ - @@ -54,7 +53,7 @@