Merge pull request #35 from workfloworchestrator/1026-example-orchestrator-use-a-modify-workflow-as-a-reconcile-workflow-in-surf-orchestrator

Example of reconcile workflow for L2VPN

Author: tvdven

README.md

@@ -1047,7 +1047,7 @@ A modify workflow also follows a general pattern, like described below.
 The `@modify_workflow` decorator adds some additional steps to the
 workflow that are always needed.
 
-```pyrhon
+```python
 @modify_workflow("Modify node", initial_input_form=initial_input_form_generator)
 def modify_node() -> StepList:
     return (
@@ -1191,6 +1191,55 @@ the orchestrator, a task (a workflow with `Target.SYSTEM`) can be
 written that will retrieve a list of all L2VPNs from IMS and compare it
 against a list of all L2VPN subscription from the orchestrator.
 
+### Reconcile workflow
+
+A reconcile workflow is similar to a modify workflow but without requiring user input via forms.
+This makes the reconcile workflow useful for synchronization the existing configuration of
+subscriptions with OSS and/or BSS.
+
+The `@reconcile_workflow` removes the need for user input forms by basically running a
+`modify_workflow` where the `initial_input_form` is automatically set to `None`.
+
+```python
+@reconcile_workflow("Reconcile l2vpn")
+def reconcile_l2vpn() -> StepList:
+    return begin >> update_l2vpn_in_external_systems
+```
+
+1. Minimal required information of the subscription is collected and consists of the subscriptions
+existing configuration.
+2. Necessary subscription administration (`@reconcile_workflow`):
+    1. Register reconcile process for this subscription
+    2. Set subscription ‘out of sync’ to prevent the start of other processes
+3. Interact with OSS and/or BSS, in this example
+    1. Update subscription in external systems (OSS and/or BSS) (`update_l2vpn_in_external_systems`)
+4. Set subscription ‘in sync’ (`@reconcile_workflow`)
+
+Because both a `@modify_workflows` and `@reconcile_workflow` need to have the same update steps for
+a similar product (e.g. `l2vpn`), these update steps can be extracted into a separate variable:
+
+```python
+# variable containing update steps which are both used in modify and reconcile workflows
+update_l2vpn_in_external_systems = begin >> update_l2vpn_in_nrm
+
+
+@modify_workflow("Modify l2vpn", initial_input_form=initial_input_form_generator)
+def modify_l2vpn() -> StepList:
+    return (
+        begin
+        >> set_status(SubscriptionLifecycle.PROVISIONING)
+        >> update_subscription
+        >> update_subscription_description
+        >> set_status(SubscriptionLifecycle.ACTIVE)
+        >> update_l2vpn_in_external_systems
+    )
+
+
+@reconcile_workflow("Reconcile l2vpn")
+def reconcile_l2vpn() -> StepList:
+    return begin >> update_l2vpn_in_external_systems
+```
+
 ## Services
 
 Services are collections of helper functions that deliver a service to

migrations/versions/schema/2025-08-28_0e8d17ce0f06_reconcile_workflows_l2vpn.py

@@ -0,0 +1,40 @@
+"""Reconcile workflows L2VPN.
+
+Revision ID: 0e8d17ce0f06
+Revises: d946c20663d3
+Create Date: 2025-08-28 13:02:03.796540
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "0e8d17ce0f06"
+down_revision = "d946c20663d3"
+branch_labels = None
+depends_on = None
+
+
+from orchestrator.migrations.helpers import create_workflow, delete_workflow
+
+new_workflows = [
+    {
+        "name": "reconcile_l2vpn",
+        "target": "RECONCILE",
+        "description": "Reconcile SN8 L2Vpn",
+        "product_type": "L2vpn",
+    }
+]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for workflow in new_workflows:
+        create_workflow(conn, workflow)
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    for workflow in new_workflows:
+        delete_workflow(conn, workflow["name"])

workflows/__init__.py

@@ -37,6 +37,8 @@
 LazyWorkflowInstance("workflows.l2vpn.modify_l2vpn", "modify_l2vpn")
 LazyWorkflowInstance("workflows.l2vpn.terminate_l2vpn", "terminate_l2vpn")
 LazyWorkflowInstance("workflows.l2vpn.validate_l2vpn", "validate_l2vpn")
+LazyWorkflowInstance("workflows.l2vpn.modify_l2vpn", "reconcile_l2vpn")
+
 
 LazyWorkflowInstance("workflows.tasks.bootstrap_netbox", "task_bootstrap_netbox")
 LazyWorkflowInstance("workflows.tasks.wipe_netbox", "task_wipe_netbox")

workflows/l2vpn/modify_l2vpn.py

@@ -12,13 +12,12 @@
 # limitations under the License.
 
 
-from pydantic_forms.types import UUIDstr
 from orchestrator.types import SubscriptionLifecycle
 from orchestrator.workflow import StepList, begin, step
 from orchestrator.workflows.steps import set_status
-from orchestrator.workflows.utils import modify_workflow
+from orchestrator.workflows.utils import modify_workflow, reconcile_workflow
 from pydantic_forms.core import FormPage
-from pydantic_forms.types import FormGenerator, State
+from pydantic_forms.types import FormGenerator, State, UUIDstr
 
 from products.product_types.l2vpn import L2vpn, L2vpnProvisioning
 from products.services.description import description
@@ -37,7 +36,9 @@ class ModifyL2vpnForm(FormPage):
     user_input_dict = user_input.model_dump()
 
     summary_fields = ["speed", "speed_policer"]
-    yield from modify_summary_form(user_input_dict, subscription.virtual_circuit, summary_fields)
+    yield from modify_summary_form(
+        user_input_dict, subscription.virtual_circuit, summary_fields
+    )
 
     return user_input_dict | {"subscription": subscription}
 
@@ -66,13 +67,22 @@ def update_l2vpn_in_nrm(subscription: L2vpnProvisioning) -> State:
     return {"subscription": subscription}
 
 
+# variable containing update steps which are both used in modify and reconcile workflows
+update_l2vpn_in_external_systems = begin >> update_l2vpn_in_nrm
+
+
 @modify_workflow("Modify l2vpn", initial_input_form=initial_input_form_generator)
 def modify_l2vpn() -> StepList:
     return (
         begin
         >> set_status(SubscriptionLifecycle.PROVISIONING)
         >> update_subscription
         >> update_subscription_description
-        >> update_l2vpn_in_nrm
         >> set_status(SubscriptionLifecycle.ACTIVE)
+        >> update_l2vpn_in_external_systems
     )
+
+
+@reconcile_workflow("Reconcile l2vpn")
+def reconcile_l2vpn() -> StepList:
+    return begin >> update_l2vpn_in_external_systems