run documentation/laikaSite.

docs/functionalityDsls/worker.html

@@ -75,9 +75,11 @@
   <p class="header"><a href="#">Workers</a></p>
 
   <ul class="nav-list">
-    <li class="level1 nav-leaf"><a href="#init-process-worker">Init Process Worker</a></li>
-    <li class="level1 nav-leaf"><a href="#service-worker">Service Worker</a></li>
-    <li class="level1 nav-leaf"><a href="#custom-worker">Custom Worker</a></li>
+    <li class="level1 nav-node"><a href="#custom-worker">Custom Worker</a></li>
+    <li class="level2 nav-leaf"><a href="#runwork">runWork</a></li>
+    <li class="level2 nav-leaf"><a href="#custominit">customInit</a></li>
+    <li class="level1 nav-node"><a href="#service-worker">Service Worker</a></li>
+    <li class="level2 nav-leaf"><a href="#apiuri">apiUri</a></li>
   </ul>
 
   <p class="footer"></p>
@@ -87,15 +89,157 @@
       <main class="content">
 
         <h1 id="workers" class="title">Workers</h1>
+        <p>The implementation of an <strong><em>External Task</em></strong> is done by a <em><strong>Worker</strong></em>.</p>
+        <p>So for each <em>External Task</em> type we have a DSL for an according <em>Worker</em>.</p>
 
-        <h2 id="init-process-worker" class="section"><a class="anchor-link left" href="#init-process-worker"><i class="icofont-laika link">&#xef71;</i></a>Init Process Worker</h2>
+        <h2 id="custom-worker" class="section"><a class="anchor-link left" href="#custom-worker"><i class="icofont-laika link">&#xef71;</i></a>Custom Worker</h2>
+        <p>The <em>Custom Worker</em> is a general <em>Worker</em> that can used for any business logic or integration.</p>
+        <p>It automatically does:</p>
+        <ul>
+          <li>validate the input variables</li>
+        </ul>
+        <p>You can create:</p>
+        <ul>
+          <li>business logic that can&#39;t be handled by the expression language in the BPMN itself</li>
+          <li>a service integration that is not covered by the <em>Service Worker</em></li>
+          <li>whatever you want</li>
+        </ul>
+        <pre class="keep-together pdf epub"><code class="nohighlight"><span class="keyword">import</span><span> </span><span class="identifier">mycompany</span><span>.</span><span class="identifier">myproject</span><span>.</span><span class="identifier">bpmn</span><span>.</span><span class="identifier">myprocess</span><span>.</span><span class="identifier">v1</span><span>.</span><span class="type-name">MyCustomTask</span><span>.*
+
+</span><span class="annotation">@Configuration</span><span>
+</span><span class="keyword">class</span><span> </span><span class="type-name">MyCustomTaskWorker</span><span> </span><span class="keyword">extends</span><span> </span><span class="type-name">CompanyCustomWorkerDsl</span><span>[</span><span class="type-name">In</span><span>, </span><span class="type-name">Out</span><span>]:
+
+  </span><span class="keyword">lazy</span><span> </span><span class="keyword">val</span><span> </span><span class="identifier">customTask</span><span> = </span><span class="identifier">example</span><span>
+
+  </span><span class="keyword">def</span><span> </span><span class="declaration-name">runWork</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>): </span><span class="type-name">Either</span><span>[</span><span class="type-name">CamundalaWorkerError</span><span>.</span><span class="type-name">CustomError</span><span>, </span><span class="type-name">Out</span><span>] =
+    </span><span class="comment">// your business logic
+</span><span>    ???
+  </span><span class="keyword">override</span><span> </span><span class="keyword">def</span><span> </span><span class="declaration-name">validate</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>): </span><span class="type-name">Either</span><span>[</span><span class="type-name">CamundalaWorkerError</span><span>.</span><span class="type-name">ValidatorError</span><span>, </span><span class="type-name">In</span><span>] =
+    ??? </span><span class="comment">// custom validation logic here  </span></code></pre>
+        <ul>
+          <li><code>lazy val customTask</code> is just needed for the compiler to check the correctness of the types.</li>
+          <li><code>runWork</code> is the method that is called by the <em>Worker</em> to execute the business logic.</li>
+          <li>The code can either:</li>
+        </ul>
+        <ul>
+          <li>complete the task successfully with a result -&gt; <code>Right[Out]</code></li>
+        </ul>
+        <ul>
+          <li>fail the task with an error -&gt; <code>Left[CamundalaWorkerError.CustomError]</code></li>
+          <li><code>override def validate(in: In)</code> is optional and can be used to add more sophisticated validation logic.
+          If the validation fails, the process will fail.</li>
+        </ul>
+        <p>Examples:</p>
+
+        <h3 id="runwork" class="section"><a class="anchor-link left" href="#runwork"><i class="icofont-laika link">&#xef71;</i></a>runWork</h3>
+        <p>TODO</p>
+
+        <h3 id="validate"><a class="anchor-link left" href="#validate"><i class="icofont-laika link">&#xef71;</i></a>validate</h3>
+        <p>This is the same in every worker type.
+        TODO</p>
+        <pre><code class="nohighlight"><span>## </span><span class="type-name">Init</span><span> </span><span class="type-name">Process</span><span> </span><span class="type-name">Worker</span><span>
+</span><span class="type-name">The</span><span> </span><span class="identifier">_Init</span><span> </span><span class="type-name">Process</span><span> </span><span class="type-name">Worker_</span><span> </span><span class="identifier">is</span><span> </span><span class="identifier">a</span><span> </span><span class="identifier">special</span><span> </span><span class="identifier">_Worker_</span><span> </span><span class="identifier">that</span><span> </span><span class="identifier">is</span><span> </span><span class="identifier">used</span><span> </span><span class="identifier">to</span><span> </span><span class="identifier">start</span><span> </span><span class="identifier">a</span><span> </span><span class="identifier">process</span><span>.
+
+</span><span class="type-name">It</span><span> </span><span class="identifier">automatically</span><span> </span><span class="identifier">does</span><span>:
+- </span><span class="identifier">validate</span><span> </span><span class="identifier">the</span><span> </span><span class="identifier">input</span><span> </span><span class="identifier">variables</span><span>
+- </span><span class="identifier">merge</span><span> </span><span class="identifier">the</span><span> </span><span class="identifier">_inConfig_</span><span> </span><span class="identifier">variables</span><span> </span><span class="keyword">with</span><span> </span><span class="identifier">manual</span><span> </span><span class="identifier">overrides</span><span>
+
+</span><span class="type-name">You</span><span> </span><span class="identifier">can</span><span>:
+- </span><span class="identifier">init</span><span> </span><span class="identifier">input</span><span> </span><span class="identifier">process</span><span> </span><span class="identifier">variables</span><span> </span><span class="keyword">with</span><span> </span><span class="keyword">default</span><span> </span><span class="identifier">values</span><span>.
+- </span><span class="identifier">init</span><span> </span><span class="identifier">process</span><span> </span><span class="identifier">variables</span><span> </span><span class="identifier">used</span><span> </span><span class="identifier">to</span><span> </span><span class="identifier">control</span><span> </span><span class="identifier">the</span><span> </span><span class="identifier">process</span><span> </span><span class="identifier">flow</span><span>, 
+  </span><span class="identifier">like</span><span> </span><span class="identifier">counters</span><span>, </span><span class="identifier">variables</span><span> </span><span class="identifier">that</span><span> </span><span class="identifier">may</span><span> </span><span class="identifier">not</span><span> </span><span class="identifier">be</span><span> </span><span class="identifier">on</span><span> </span><span class="identifier">the</span><span> </span><span class="identifier">process</span><span>.
+- </span><span class="identifier">create</span><span> </span><span class="identifier">simplified</span><span> </span><span class="identifier">process</span><span> </span><span class="identifier">variables</span><span> </span><span class="identifier">to</span><span> </span><span class="identifier">simplify</span><span> </span><span class="identifier">the</span><span> </span><span class="identifier">process</span><span> </span><span class="identifier">flow</span><span>.
+- </span><span class="identifier">validate</span><span> </span><span class="identifier">the</span><span> </span><span class="identifier">input</span><span> </span><span class="identifier">variables</span><span>, </span><span class="keyword">if</span><span> </span><span class="identifier">you</span><span> </span><span class="identifier">need</span><span> </span><span class="identifier">more</span><span> </span><span class="identifier">sophisticated</span><span> </span><span class="identifier">validation</span><span> </span><span class="identifier">logic</span><span>, 
+  </span><span class="identifier">than</span><span> </span><span class="identifier">you</span><span> </span><span class="identifier">can</span><span> </span><span class="identifier">do</span><span> </span><span class="keyword">with</span><span> </span><span class="identifier">the</span><span> </span><span class="keyword">type</span><span> </span><span class="identifier">definition</span><span>.
+
+</span><span class="identifier">``</span><span>`</span><span class="identifier">scala</span><span>
+</span><span class="keyword">import</span><span> </span><span class="identifier">mycompany</span><span>.</span><span class="identifier">myproject</span><span>.</span><span class="identifier">bpmn</span><span>.</span><span class="identifier">myprocess</span><span>.</span><span class="identifier">v1</span><span>.</span><span class="type-name">MyProcess</span><span>.*
+
+</span><span class="annotation">@Configuration</span><span>
+</span><span class="keyword">class</span><span> </span><span class="type-name">MyProcessWorker</span><span> </span><span class="keyword">extends</span><span> </span><span class="type-name">CompanyInitWorkerDsl</span><span>[</span><span class="type-name">In</span><span>, </span><span class="type-name">Out</span><span>, </span><span class="type-name">InitIn</span><span>, </span><span class="type-name">InConfig</span><span>]:
+
+  </span><span class="keyword">lazy</span><span> </span><span class="keyword">val</span><span> </span><span class="identifier">inOutExample</span><span> = </span><span class="identifier">example</span><span>
+
+  </span><span class="keyword">def</span><span> </span><span class="declaration-name">customInit</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>): </span><span class="type-name">InitIn</span><span> =
+    ??? </span><span class="comment">// init logic here
+</span><span>  </span><span class="keyword">override</span><span> </span><span class="keyword">def</span><span> </span><span class="declaration-name">validate</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>): </span><span class="type-name">Either</span><span>[</span><span class="type-name">CamundalaWorkerError</span><span>.</span><span class="type-name">ValidatorError</span><span>, </span><span class="type-name">In</span><span>] =
+    ??? </span><span class="comment">// custom validation logic here</span></code></pre>
+        <ul>
+          <li><code>lazy val inOutExample</code> is just needed for the compiler to check the correctness of the types.</li>
+          <li><code>customInit</code> is the method that is called by the <em>Worker</em> to execute the init logic.</li>
+          <li>The method sets the process variables according the <em>InitIn</em> object.
+          Be aware that this can not fail, as the input variables are already validated.</li>
+          <li><code>override def validate(in: In)</code> is optional and can be used to add more sophisticated validation logic.
+          If the validation fails, the process will fail.</li>
+        </ul>
+        <p>Examples:</p>
+
+        <h3 id="custominit" class="section"><a class="anchor-link left" href="#custominit"><i class="icofont-laika link">&#xef71;</i></a>customInit</h3>
         <p>TODO</p>
 
         <h2 id="service-worker" class="section"><a class="anchor-link left" href="#service-worker"><i class="icofont-laika link">&#xef71;</i></a>Service Worker</h2>
+        <p>The <em>Service Worker</em> is a special <em>Worker</em> that is used to call a REST API service.</p>
+        <p>It automatically does:</p>
+        <ul>
+          <li>validate the input variables</li>
+        </ul>
+        <p>You can provide:</p>
+        <ul>
+          <li>the method and the path of the service</li>
+          <li>the query parameters</li>
+          <li>the headers</li>
+          <li>the mapping of the input- or output request body</li>
+        </ul>
+        <pre><code class="nohighlight"><span class="keyword">import</span><span> </span><span class="identifier">mycompany</span><span>.</span><span class="identifier">myproject</span><span>.</span><span class="identifier">bpmn</span><span>.</span><span class="identifier">myprocess</span><span>.</span><span class="identifier">v1</span><span>.</span><span class="type-name">MyServiceTask</span><span>.*
+
+</span><span class="annotation">@Configuration</span><span>
+</span><span class="keyword">class</span><span> </span><span class="type-name">MyServiceTaskWorker</span><span> </span><span class="keyword">extends</span><span> </span><span class="type-name">CompanyServiceWorkerDsl</span><span>[</span><span class="type-name">In</span><span>, </span><span class="type-name">Out</span><span>]:
+
+  </span><span class="keyword">lazy</span><span> </span><span class="keyword">val</span><span> </span><span class="identifier">serviceTask</span><span> = </span><span class="identifier">example</span><span>
+
+  </span><span class="keyword">def</span><span> </span><span class="declaration-name">apiUri</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>) = </span><span class="string-literal">uri&quot;</span><span class="substitution">$serviceBasePath</span><span class="string-literal">/myService&quot;</span><span>
+  </span><span class="keyword">override</span><span> </span><span class="keyword">protected</span><span> </span><span class="keyword">lazy</span><span> </span><span class="keyword">val</span><span> </span><span class="identifier">method</span><span>: </span><span class="type-name">Method</span><span> = </span><span class="type-name">Method</span><span>.</span><span class="type-name">POST</span><span>
+
+  </span><span class="keyword">override</span><span> </span><span class="keyword">protected</span><span> </span><span class="keyword">def</span><span> </span><span class="declaration-name">inputHeaders</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>): </span><span class="type-name">Map</span><span>[</span><span class="type-name">String</span><span>, </span><span class="type-name">String</span><span>] =
+  ??? </span><span class="comment">// map the input variables to the headers
+</span><span>  </span><span class="keyword">override</span><span> </span><span class="keyword">def</span><span> </span><span class="declaration-name">querySegments</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>) =
+    ??? </span><span class="comment">// map the input variables to the query parameters  
+</span><span>  </span><span class="keyword">override</span><span> </span><span class="keyword">def</span><span> </span><span class="declaration-name">inputMapper</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>): </span><span class="type-name">Option</span><span>[</span><span class="type-name">ServiceIn</span><span>] =
+    ??? </span><span class="comment">// map the input variables to the service request body
+</span><span>  </span><span class="keyword">override</span><span> </span><span class="keyword">def</span><span> </span><span class="declaration-name">outputMapper</span><span>(
+                           </span><span class="identifier">out</span><span>: </span><span class="type-name">ServiceResponse</span><span>[</span><span class="type-name">ServiceOut</span><span>],
+                           </span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>
+                         ): </span><span class="type-name">Either</span><span>[</span><span class="type-name">ServiceMappingError</span><span>, </span><span class="type-name">Out</span><span>] =
+    ??? </span><span class="comment">// map the service response body and header to the output variables
+</span><span>  </span><span class="keyword">override</span><span> </span><span class="keyword">def</span><span> </span><span class="declaration-name">validate</span><span>(</span><span class="identifier">in</span><span>: </span><span class="type-name">In</span><span>): </span><span class="type-name">Either</span><span>[</span><span class="type-name">CamundalaWorkerError</span><span>.</span><span class="type-name">ValidatorError</span><span>, </span><span class="type-name">In</span><span>] =
+    ??? </span><span class="comment">// custom validation logic here</span></code></pre>
+        <ul>
+          <li><code>lazy val serviceTask</code> is just needed for the compiler to check the correctness of the types.</li>
+          <li><code>def apiUri(in: In)</code> the path of the service, with the path parameters from the <code>in</code> object.
+          The only required function.</li>
+          <li><code>override protected lazy val method: Method</code> is the HTTP method. Default is <code>Method.GET</code>.</li>
+          <li><code>override def querySegments(in: In)</code> is optional and can be used to add query parameters to the request.</li>
+          <li><code>override def inputHeaders(in: In)</code> is optional and can be used to add headers to the request.</li>
+          <li><code>override def inputMapper(in: In)</code> is optional and can be used to map the input variables to the request body.</li>
+          <li><code>override def outputMapper(out: ServiceResponse[ServiceOut], in: In)</code> is optional and can be used to map the response body and -headers to the output variables.</li>
+          <li><code>override def validate(in: In)</code> is optional and can be used to add more sophisticated validation logic.
+          If the validation fails, the process will fail.</li>
+        </ul>
+        <p>Examples:</p>
+
+        <h3 id="apiuri" class="section"><a class="anchor-link left" href="#apiuri"><i class="icofont-laika link">&#xef71;</i></a>apiUri</h3>
         <p>TODO</p>
 
-        <h2 id="custom-worker" class="section"><a class="anchor-link left" href="#custom-worker"><i class="icofont-laika link">&#xef71;</i></a>Custom Worker</h2>
+        <h3 id="querysegments"><a class="anchor-link left" href="#querysegments"><i class="icofont-laika link">&#xef71;</i></a>querySegments</h3>
+        <p>TODO</p>
+
+        <h3 id="inputheaders"><a class="anchor-link left" href="#inputheaders"><i class="icofont-laika link">&#xef71;</i></a>inputHeaders</h3>
         <p>TODO</p>
+
+        <h3 id="inputmapper"><a class="anchor-link left" href="#inputmapper"><i class="icofont-laika link">&#xef71;</i></a>inputMapper</h3>
+        <p>TODO</p>
+
+        <h3 id="outputmapper"><a class="anchor-link left" href="#outputmapper"><i class="icofont-laika link">&#xef71;</i></a>outputMapper</h3>
 
 
 <hr class="footer-rule"/>