Workshop updates 4

docs/workshops/example-orchestrator/create-your-own.md

@@ -4,5 +4,11 @@ To cap off this workshop we will create a new product and workflows by using the
 Orchestrator provides the user. In this scenario you will create a product that is very similar to the provided
 L2VPN product, but constrained to two interfaces. In other words a L2 Point-to-Point circuit.
 
-A description of what this L2 product could look like can be found
-[in this section of the documentation](../../../orchestrator-core/architecture/product-modeling/l2-point-to-point/).
+A description of what this L2 product could look like is included below (see also
+[this section of the documentation](../../../orchestrator-core/architecture/product-modeling/l2-point-to-point/)).
+
+
+{%
+   include-markdown "../../../orchestrator-core/docs/architecture/product-modeling/l2-point-to-point.md"
+   heading-offset=1
+%}

docs/workshops/example-orchestrator/execute-workflows.md

@@ -75,3 +75,6 @@ You can log in to the router and check the status of ISIS using:
 show network-instance default protocols isis adjacency
 show network-instance default protocols isis interface
 ```
+
+Feel free to play around with the created devices.
+Can you manage to send a ping through the created link?

docs/workshops/example-orchestrator/generator.md

@@ -19,32 +19,30 @@ total 32
 ```
 
 This directory houses all the configuration of the initial products that the example orchestrator provides. It is a
-starting point for developing new products. In this workshop we will create a new file and generate the
-L2-Point-to-Point model and workflows by configuring it with this yaml file.
+starting point for developing new products.
 
-### Step 2 - Configure the YAML
-
-Create a new file in the template directory called `l2-p2p.yaml`
+Create a new file in the template directory called `l2_p2p.yaml`:
 
 ```shell
-touch templates/l2-p2p.yaml
+touch templates/l2_p2p.yaml
 ```
 
+In this workshop we will generate the L2-Point-to-Point model and workflows by configuring it with this yaml file.
+
+### Step 2 - Configure the YAML
+
 This file will contain the Initial product type configuration. Please create a yaml configuration reflecting the
 product model as described on the [previous page](create-your-own.md). The goal is to configure the generator to
 reuse as many of the product blocks already existing in the orchestrator as possible.
 
-!!! tip "Inspiration"
-    Take a look at the `l2vpn.yaml` model for inspiration. As you can see this file has been configured in a certain
-    way to reflect the configuration of the product. For more in depth documentation take a look at the [reference
-    doc](../../orchestrator-core/reference-docs/cli.md#generate).
+Take a look at the [`l2vpn.yaml`](https://github.com/workfloworchestrator/example-orchestrator/blob/main/templates/l2vpn.yaml) model for inspiration.
+As you can see, this file has been configured in a certain way to reflect the configuration of the product.
+For more in depth documentation about `generate` take a look at the [reference
+doc](../../orchestrator-core/reference-docs/cli.md#generate).
 
-!!! danger "What can I do when I encounter errors?"
-    If you get stuck just remove all generated files, edit the yaml and try again.
-
-??? example "Answer - l2-p2p.yaml"
+??? example "Answer - l2_p2p.yaml"
     When creating the YAML you should notice that you do not have to create the **SAP** product blocks again. You just
-    have reference the **SAPS** in the **Virtual Circuit** configuration. In this way you start reusing existing
+    have reference the **SAP** in the **Virtual Circuit** configuration. In this way you start reusing existing
     building blocks that already exist in the orchestrator. We cannot reuse the existing Virtual Circuit with the
     generator due to the different limits on the amount of SAPS that can be connected to the Virtual Circuit of the
     L2 P2P product.
@@ -53,7 +51,7 @@ reuse as many of the product blocks already existing in the orchestrator as poss
     config:
       summary_forms: true
     name: l2_p2p
-    type: L2P2P
+    type: L2p2p
     tag: L2P2P
     description: "L2 Point-to-Point"
     fixed_inputs:
@@ -66,7 +64,7 @@ reuse as many of the product blocks already existing in the orchestrator as poss
         description: "Level of network redundancy"
     product_blocks:
       - name: l2_p2p_virtual_circuit
-        type: L2P2PVirtualCircuit
+        type: L2p2pVirtualCircuit
         tag: VC
         description: "virtual circuit product block"
         fields:
@@ -106,12 +104,15 @@ docker compose exec -it orchestrator bash
 source .venv/bin/activate
 ```
 
+!!! danger "What can I do when I encounter errors?"
+    If you want to start over, use `git restore .` and `git clean -id` from your example-orchestrator directory to undo changes.
+
 #### Product Blocks
 
 Run the command to generate the domain models product blocks:
 
 ```shell
-python main.py generate product-blocks -cf templates/l2-p2p.yaml --no-dryrun
+python main.py generate product-blocks -cf templates/l2_p2p.yaml --no-dryrun
 ```
 
 The `--no-dryrun` option will immediately write the files to the `products/product_blocks` folder and create:
@@ -123,7 +124,7 @@ product and defines the strict hierarchy of virtual circuit and saps.
 Now create the product.
 
 ```shell
-python main.py generate product -cf templates/l2-p2p.yaml --no-dryrun
+python main.py generate product -cf templates/l2_p2p.yaml --no-dryrun
 ```
 
 This will create the file `products/product_types/l2_p2p.py`. When looking at this file you can see it created the
@@ -134,45 +135,55 @@ domain model, fixed inputs and imported the correct product blocks to be used in
 Now generate the workflows. This command will always create 4 sets of workflows `create`, `modify`, `terminate` and
 `validate`. These can be implemented as the user sees fit.
 
-!!! warning
-    There is a bug in `generate workflows` which makes it overwrite the contents of workflows/shared.py. Make sure to
-    backup the contents, or restore it afterwards. Bug is tracked in
-    https://github.com/workfloworchestrator/orchestrator-core/issues/1757.
-
 Run the command:
 
 ```shell
-python main.py generate workflows -cf templates/l2-p2p.yaml --no-dryrun --force
+python main.py generate workflows -cf templates/l2_p2p.yaml --no-dryrun
 ```
 
 As you can see this file needs to be run with the --force flag as it needs to overwrite a number of configuration
-files. Furthermore it will populate the files in `workflows.l2_p2p`. Feel free to take a look and see what it
-already has done.
+files. Furthermore it will populate the files in `workflows/l2_p2p/`. Do that now:
+
+```shell
+python main.py generate workflows -cf templates/l2_p2p.yaml --no-dryrun --force
+```
+
+!!! warning
+    There is a [bug](https://github.com/workfloworchestrator/orchestrator-core/issues/1757) in `generate workflows`
+    which makes it overwrite the contents of `workflows/shared.py` instead of
+    extend it with the missing elements. You can use `git restore` to restore it aftwards.
+
+Take a look around to see which files have been created by now.
+Can you explain what each of them are for?
 
 #### Database migrations
 
 As a final step the user must generate and run the migrations to wire up the database. This is done as follows.
 
 ```shell
-python main.py generate migration -cf templates/l2-p2p.yaml
+python main.py generate migration -cf templates/l2_p2p.yaml
 python main.py db upgrade heads
 ```
 
 ### Step 4 - Profit
 
-If this has been executed without errors, you should be able to create a new subscription for the l2-p2p product by
-running the create workflow through the UI. All it does is create the domain model and fill it in with some
-rudimentary values from the input form, but it's a starting point. Users can now go into the workflow source code
-and start implementing steps to provision the resource that is being created by the create workflow. Take some time
-in the orchestrator UI to see what has been configured.
+If this has been executed without errors, you should see the option **l2_p2p protected** and
+**l2_p2p unprotected** appear in the **New subscription** menu, as well as in the Metadata pages.
+Select either product, and try to fill in the form. There is a small quirk with one of the fields, which has been
+left in as an exercise to understand the interaction between the workflow form and the UI.
+
+Once you submit the form you'll notice that creating the subscription does not work right away, as
+the "initial_input_form_generator" still needs to be extended with a field to select Port subscriptions for the SAPs,
+and the "construct_l2_p2p_model" step will need to be updated accordingly.
+This is out of scope for the workshop.
 
-- Metadata pages
-- Action menu
-- Available workflows
+But this should give you an idea how the generator gives users a head start by setting up a product and workflows according
+to the best practices. They can then go into the workflow source code and start implementing steps
+to provision the resource that is being created by the create workflow.
 
 ### Step 5 - Bonus
 
-Implement a new step in the create workflow that manipulates the subscription in a certain way. An example could be
+Add a new step in the `create_l2_p2p` workflow that manipulates the subscription in a certain way. An example could be
 to change the subscription description, or any other value you can think of that exists in the subscription.
 
 ??? example "Answer"

docs/workshops/example-orchestrator/scenario.md

@@ -58,10 +58,10 @@ flowchart
     node1 --- port1
     node2 --- port2
     port3 --- node3
-    subgraph sg_l2ptp[L2PointToPoint subscription]
+    subgraph sg_l2p2p[L2p2p subscription]
         direction LR
         l2ptp_sap1[SAPBlock]
-        l2ptp_vc[VirtualCircuitBlock]
+        l2ptp_vc[L2p2pVirtualCircuitBlock]
         l2ptp_sap2[SAPBlock]
         l2ptp_sap1 --- l2ptp_vc
         l2ptp_vc --- l2ptp_sap2
@@ -89,7 +89,7 @@ flowchart
     style sg_port2 rx:20,ry:20,fill:#ffe699
     style sg_port3 rx:20,ry:20,fill:#c5e0b4
     style sg_l2vpn rx:20,ry:20,fill:#ffe699
-    style sg_l2ptp rx:20,ry:20,fill:#c5e0b4
+    style sg_l2p2p rx:20,ry:20,fill:#c5e0b4
 
     classDef default rx:10,ry:10,fill:#ff9300,stroke:#333,stroke-width:1px
 ```

docs/workshops/example-orchestrator/workflow-introduction.md

@@ -1,11 +1,14 @@
-> This document assumes you are already familiar with the key safeguards and potential pitfalls outlined in the [Architecture of workflows](../../orchestrator-core/architecture/application/workflow.md)
-
 ### Continuing the Workshop
 
 The next sections introduce the workflow concept and its relationship to the product model.
-Code examples referenced throughout can be found in the example orchestrator under the `.workflows.node` directory.
+Code examples referenced throughout can be found in the example orchestrator under the `workflows/` directory.
 
 Please read at least the following pages to grasp the functionality of how workflows work and how the user/frontend will interact with the Orchestrator API:
 
 * [Workflow Basics](workflow-basics.md)
 * [Create Workflow](node-create.md)
+
+!!! info
+    For more in-depth details you can consult the
+    [Architecture of workflows](../../orchestrator-core/architecture/application/workflow.md), but this is not required
+    to complete this workshop.