Feature/service cutter documentation

_cmls/systematic-service-decomposition-tutorial-1.cml

@@ -0,0 +1,48 @@
+BoundedContext CargoTracking {
+  Aggregate Cargo {
+    owner CargoPlaner
+
+    Entity Cargo {
+      aggregateRoot
+      - TrackingId trackingId
+      - Location origin
+      - RouteSpecification routeSpecification
+      - Itinerary itinerary
+      - Delivery delivery
+    }
+    /* shortened Aggregate here */
+  }
+  Aggregate Location {
+    owner Administrators
+
+    Entity Location {
+      aggregateRoot
+      - UnLocode unLocode
+      String name
+    }
+    /* shortened Aggregate here */
+  }
+  Aggregate Handling {
+    owner CargoTracker
+
+    DomainEvent HandlingEvent {
+      - HandlingEventType handlingEventType
+      - Voyage voyage
+      - Location location
+      Date completionTime
+      Date registrationTime
+      - Cargo cargo
+    }
+    /* shortened Aggregate here */
+  }
+  Aggregate Voyage {
+    owner VoyageManager
+
+    Entity Voyage {
+      aggregateRoot
+      - VoyageNumber voyageNumber
+      - Schedule schedule
+    }
+    /* shortened Aggregate here */
+  }
+}

_cmls/systematic-service-decomposition-tutorial-1.html

@@ -0,0 +1,49 @@
+<div class="highlight"><pre><span></span><span class="k">BoundedContext</span> CargoTracking {
+  <span class="k">Aggregate</span> Cargo {
+    <span class="k">owner</span> CargoPlaner
+
+    <span class="k">Entity</span> Cargo {
+      <span class="k">aggregateRoot</span>
+      - <span class="k">TrackingId</span> trackingId
+      - <span class="k">Location</span> origin
+      - <span class="k">RouteSpecification</span> routeSpecification
+      - <span class="k">Itinerary</span> itinerary
+      - <span class="k">Delivery</span> delivery
+    }
+    <span class="c">/* shortened Aggregate here */</span>
+  }
+  <span class="k">Aggregate</span> Location {
+    <span class="k">owner</span> Administrators
+
+    <span class="k">Entity</span> Location {
+      <span class="k">aggregateRoot</span>
+      - <span class="k">UnLocode</span> unLocode
+      <span class="k">String</span> name
+    }
+    <span class="c">/* shortened Aggregate here */</span>
+  }
+  <span class="k">Aggregate</span> Handling {
+    <span class="k">owner</span> CargoTracker
+
+    <span class="k">DomainEvent</span> HandlingEvent {
+      - <span class="k">HandlingEventType</span> handlingEventType
+      - <span class="k">Voyage</span> voyage
+      - <span class="k">Location</span> location
+      <span class="k">Date</span> completionTime
+      <span class="k">Date</span> registrationTime
+      - <span class="k">Cargo</span> cargo
+    }
+    <span class="c">/* shortened Aggregate here */</span>
+  }
+  <span class="k">Aggregate</span> Voyage {
+    <span class="k">owner</span> VoyageManager
+
+    <span class="k">Entity</span> Voyage {
+      <span class="k">aggregateRoot</span>
+      - <span class="k">VoyageNumber</span> voyageNumber
+      - <span class="k">Schedule</span> schedule
+    }
+    <span class="c">/* shortened Aggregate here */</span>
+  }
+}
+</pre></div>

_cmls/systematic-service-decomposition-tutorial-2.cml

@@ -0,0 +1,19 @@
+UseCase ViewTracking {
+  reads "Cargo.trackingId", "HandlingEvent.type", "HandlingEvent.location", "HandlingEvent.completionTime", "Delivery.transportStatus", "Delivery.estimatedArrivalTime", "Delivery.misdirected", "Voyage.voyageNumber", "RouteSpecification.destination"
+}
+
+UseCase ViewCargos {
+  reads "Cargo.trackingId", "RouteSpecification.destination", "RouteSpecification.arrivalDeadline", "Delivery.routingStatus", "Itinerary.itineraryNumber"
+}
+
+UseCase BookCargo {
+  reads "Location.unLocode"
+  writes "Cargo.trackingId", "RouteSpecification.origin", "RouteSpecification.arrivalDeadline", "RouteSpecification.destination"
+}
+
+UseCase ChangeCargoDestination {
+  reads "Cargo.trackingId", "RouteSpecification.destination"
+  writes "RouteSpecification.destination"
+}
+
+/* we shortened this listing to save space (find all use cases in the original CML file) */

_cmls/systematic-service-decomposition-tutorial-2.html

@@ -0,0 +1,20 @@
+<div class="highlight"><pre><span></span><span class="k">UseCase</span> ViewTracking {
+  <span class="k">reads</span> <span class="s">&quot;Cargo.trackingId&quot;</span>, <span class="s">&quot;HandlingEvent.type&quot;</span>, <span class="s">&quot;HandlingEvent.location&quot;</span>, <span class="s">&quot;HandlingEvent.completionTime&quot;</span>, <span class="s">&quot;Delivery.transportStatus&quot;</span>, <span class="s">&quot;Delivery.estimatedArrivalTime&quot;</span>, <span class="s">&quot;Delivery.misdirected&quot;</span>, <span class="s">&quot;Voyage.voyageNumber&quot;</span>, <span class="s">&quot;RouteSpecification.destination&quot;</span>
+}
+
+<span class="k">UseCase</span> ViewCargos {
+  <span class="k">reads</span> <span class="s">&quot;Cargo.trackingId&quot;</span>, <span class="s">&quot;RouteSpecification.destination&quot;</span>, <span class="s">&quot;RouteSpecification.arrivalDeadline&quot;</span>, <span class="s">&quot;Delivery.routingStatus&quot;</span>, <span class="s">&quot;Itinerary.itineraryNumber&quot;</span>
+}
+
+<span class="k">UseCase</span> BookCargo {
+  <span class="k">reads</span> <span class="s">&quot;Location.unLocode&quot;</span>
+  <span class="k">writes</span> <span class="s">&quot;Cargo.trackingId&quot;</span>, <span class="s">&quot;RouteSpecification.origin&quot;</span>, <span class="s">&quot;RouteSpecification.arrivalDeadline&quot;</span>, <span class="s">&quot;RouteSpecification.destination&quot;</span>
+}
+
+<span class="k">UseCase</span> ChangeCargoDestination {
+  <span class="k">reads</span> <span class="s">&quot;Cargo.trackingId&quot;</span>, <span class="s">&quot;RouteSpecification.destination&quot;</span>
+  <span class="k">writes</span> <span class="s">&quot;RouteSpecification.destination&quot;</span>
+}
+
+<span class="c">/* we shortened this listing to save space (find all use cases in the original CML file) */</span>
+</pre></div>

_cmls/systematic-service-decomposition-tutorial-3.cml

@@ -0,0 +1,28 @@
+BoundedContext CargoTracking {
+  Aggregate Cargo {
+    owner CargoPlaner
+
+    /* removed content here to save space */
+  }
+  Aggregate Location {
+    owner Administrators
+
+    /* removed content here to save space */
+  }
+  Aggregate Handling {
+    owner CargoTracker
+
+    /* removed content here to save space */ 
+  }
+  Aggregate Voyage {
+    owner VoyageManager
+
+    /* removed content here to save space */
+  }
+}
+
+/* team definitions: */
+BoundedContext CargoPlaner { type TEAM }
+BoundedContext CargoTracker { type TEAM }
+BoundedContext VoyageManager { type TEAM }
+BoundedContext Administrators { type TEAM }

_cmls/systematic-service-decomposition-tutorial-3.html

@@ -0,0 +1,29 @@
+<div class="highlight"><pre><span></span><span class="k">BoundedContext</span> CargoTracking {
+  <span class="k">Aggregate</span> Cargo {
+    <span class="k">owner</span> CargoPlaner
+
+    <span class="c">/* removed content here to save space */</span>
+  }
+  <span class="k">Aggregate</span> Location {
+    <span class="k">owner</span> Administrators
+
+    <span class="c">/* removed content here to save space */</span>
+  }
+  <span class="k">Aggregate</span> Handling {
+    <span class="k">owner</span> CargoTracker
+
+    <span class="c">/* removed content here to save space */</span> 
+  }
+  <span class="k">Aggregate</span> Voyage {
+    <span class="k">owner</span> VoyageManager
+
+    <span class="c">/* removed content here to save space */</span>
+  }
+}
+
+<span class="c">/* team definitions: */</span>
+<span class="k">BoundedContext</span> CargoPlaner { <span class="k">type</span> <span class="k">TEAM</span> }
+<span class="k">BoundedContext</span> CargoTracker { <span class="k">type</span> <span class="k">TEAM</span> }
+<span class="k">BoundedContext</span> VoyageManager { <span class="k">type</span> <span class="k">TEAM</span> }
+<span class="k">BoundedContext</span> Administrators { <span class="k">type</span> <span class="k">TEAM</span> }
+</pre></div>

_data/docs.yml

@@ -70,6 +70,7 @@
   - event-storming
   - event-sourcing-and-cqrs-modeling
   - jhipster-microservice-generation
+  - systematic-service-decomposition
 
 - title: IDE Plugins and Extensions
   docs:

_docs/generators/service-cutter.md

@@ -12,48 +12,52 @@ For more information about Service Cutter we refer to its projects wiki and two
  * [Service Cutter: A Systematic Approach to Service Decomposition (Paper)](https://link.springer.com/chapter/10.1007/978-3-319-44482-6_12)
  * [Service Cutter: A Systematic Approach to Service Decomposition (HSR Bachelor Thesis)](https://eprints.hsr.ch/476/)
 
-<div class="alert alert-custom">
-<strong>Note:</strong> The Service Cutter generators are not yet supported in our new Visual Studio Code extension. We continuously work on the extension and will support them soon! To use this generators you have to use the Eclipse plugin for now. You can find a feature support table for Eclipse and VS Code <a href="/docs/ide/">here</a>.
-</div>
-
 ## User Guide
 The following sections describe how to use the Service Cutter generators and create the input files for Service Cutter.
 
 ### Generate Entity Relationship Model File
 Service Cutter uses an [Entity-Relationship Model](https://github.com/ServiceCutter/ServiceCutter/wiki/ERM) Diagram (ERD) file that contains entities and nanoentities to describe the applications structure as its first and mandatory input. 
 
-We assume you have a CML file with your model in Eclipse (with our plugin installed). A right-click to the CML-file will guide you to a **Context Mapper** context menu. When selecting the action **Service Cutter: Generate Input File (JSON)**, you generate the Service Cutter ERD file in the required JSON format:
+We assume you have a CML file with your model in your IDE with Context Mapper installed. In the context menu of the editor you find the action **Generate Service Cutter Input (ERD as JSON)**. By running this command, you generate the Service Cutter ERD file in the required JSON format:
 
 <a href="/img/service-cutter-input-generation-1.png">![Generate ServiceCutter ERD File](/img/service-cutter-input-generation-1.png)</a>
 
-<div class="alert alert-custom">
-<strong>Note</strong> that the <strong>Context Mapper</strong> menu entry is also available within the context menu uf the CML editor 
-(right-click anywhere in the editor).
-</div>
-
 ### Generate SCL File
 The second input file for Service Cutter deals with additional *User representations*. Service Cutter takes them in JSON format, but  there is some manual work required to create these file. Hence, we implemented another DSL which makes this step much easier. These files have the file extension `*.scl*` (for *Service Cutter Language*).
 
-A SCL file can be generated out of a CML file. Again, a right-click to the CML-file will open the **Context Mapper** context menu. You can initialize your SCL file with the action **Service Cutter: Initialize User Representations File (Exemplary)**:
+An SCL file can be generated out of a CML file. Again, a right-click in the CML editor will allow you to call the action **Generate Service Cutter User Representations (SCL)**:
 
 <a href="/img/service-cutter-input-generation-2.png">![Generate ServiceCutter SCL File](/img/service-cutter-input-generation-2.png)</a>
 
-**Note:** The generated SCL file is a template that intends to help you by setting the structure expected by Service Cutter. The following generated parts are only examples, and 
-will have to be adjusted:
+The SCL grammar allows you to describe all [user representations supported by Service Cutter](https://github.com/ServiceCutter/ServiceCutter/wiki/User-Representations):
+
+ * Entity Relationship Model (ERM)
+ * Use Cases
+ * Shared Owner Groups
+ * Aggregates
+ * Entities
+ * Predefined Services
+ * Separated Security Zones
+ * Security Access Groups
+ * Compatibilities
+
+Most of the user representations we derive from the CML model automatically. The ERM is derived from the Entities and their references in CML. The Use Cases and Shared Owner Groups can be modeled in CML as well (have a look at our [service decomposition tutorial](/docs/systematic-service-decomposition/)). We further derive the Aggregates and Entities for Service Cutter from the corresponding counterparts in CML. In addition, we derive Predefined Services from already existing Bounded Contexts of your CML model. The remaining user representations have to be described manually, in case they are relevant for your application.
+
+However, the generated SCL file already contains most of the representations:
 
- * **[Use Cases](https://github.com/ServiceCutter/ServiceCutter/wiki/Use-Cases)**
- * **All [Compatibilities](https://github.com/ServiceCutter/ServiceCutter/wiki/Compatibilities)**
- * **[Security Access Groups](https://github.com/ServiceCutter/ServiceCutter/wiki/Security-access-groups)**
- * **[Separated Security Zone](https://github.com/ServiceCutter/ServiceCutter/wiki/Separated-security-zones)**
- * **[Shared Owner Group](https://github.com/ServiceCutter/ServiceCutter/wiki/Shared-owner-groups)**
+<a href="/img/service-cutter-input-generation-2-1.png">![Generated SCL File](/img/service-cutter-input-generation-2-1.png)</a>
 
-The following elements are actually derived from the CML model and do not have to be changed:
+**Note:** The automatically derived user representations are overwritten if you call the generator again.
 
- * **[Aggregates](https://github.com/ServiceCutter/ServiceCutter/wiki/Aggregates)** (derived from your Aggregates in the CML file)
- * **[PredefinedService](https://github.com/ServiceCutter/ServiceCutter/wiki/Predefined-services)** (derived from your bounded contexts in the CML file)
+#### Examplary SCL File
+In case you want to add more user representations that are missing in the automatically generated ones, you can generate an exemplary SCL file that illustrates the syntax for all possible representations. Just call the **Generate Service Cutter User Representation Example File (SCL)** action to generate an example:
+
+<a href="/img/service-cutter-input-generation-2-2.png">![Generate Exemplary SCL File](/img/service-cutter-input-generation-2-2.png)</a>
+
+**Note:** This generated SCL file is only exemplary and intended to help you setting up the structure in the actual SCL file generated in the step above.
 
 ### Generate User Representations JSON File
-Once you have prepared your SCL file, you can generate the corresponding JSON file with the action **Service Cutter: Generate User Representations File (JSON)** in the context menu:
+Once you have prepared your SCL file, you can generate the corresponding JSON file with the action **Generate Service Cutter User Representation JSON File** in the context menu:
 
 <a href="/img/service-cutter-input-generation-3.png">![Generate ServiceCutter JSON out of SCL File](/img/service-cutter-input-generation-3.png)</a>
 
@@ -67,3 +71,8 @@ Have fun with cutting your services :)
 *Note:* Service Cutter has not been updated in a while, and only intended to demonstrate the possibilities of criteria-based graph clustering in the context of service decomposition (and establish a method and a first catalog of criteria). So do not expect mature, production-ready cuts to be suggested, but view them as a discussion and design workshop input. Further research is required to harden the approach; such research is ongoing (evidence: [40+ citations of the Service Cutter paper presented at ESOCC 2016](https://www.researchgate.net/publication/307873263_Service_Cutter_A_Systematic_Approach_to_Service_Decomposition)).  
 
 <a href="/img/service-cutter-insurance-example.png">![Service Cutter Insurance Example](/img/service-cutter-insurance-example.png)</a>
+
+## Further Links
+Note that you can also generate new service cuts in Context Mapper directly without using Service Cutter! We integrated the Service Cutter library into Context Mapper so that our users are able to generate new service decompositions out of CML models easily.
+
+ * Have a look at our [Systematic Service Decomposition with Context Mapper and Service Cutter](/docs/systematic-service-decomposition/) tutorial.