Merge pull request serverlessworkflow#988 from neuroglia-io/feat-add-…

…use-cases

Add use cases and examples

README.md

@@ -109,8 +109,11 @@ It is a member project of the [CNCF Serverless Working Group](https://github.com
 ## Documentation
 
 The documentation for Serverless Workflow includes:
+
 - [**DSL**](dsl.md): Documents the fundamentals aspects and concepts of the Serverless Workflow DSL
 - [**DSL Reference**](dsl-reference.md): References all the definitions used by the Serverless Workflow DSL
+- [**Examples**](./examples/README.md): A collection of practical examples demonstrating specific features and functionalities of Serverless Workflow.
+- [**Use Cases**](./use-cases/README.md): Detailed use cases illustrating how Serverless Workflow can be applied in various real-world scenarios.
 
 ## Community
 

dsl-reference.md

@@ -1451,7 +1451,7 @@ Defines the [Problem Details RFC](https://datatracker.ietf.org/doc/html/rfc7807)
 |----------|:----:|:--------:|-------------|
 | type | [`uri-template`](#uri-template) | `yes` | A URI reference that identifies the [`error`](#error) type. <br><u>For cross-compatibility concerns, it is strongly recommended to use [Standard Error Types](#standard-error-types) whenever possible.<u><br><u>Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error).<u> |
 | status | `integer` | `yes` | The status code generated by the origin for this occurrence of the [`error`](#error).<br><u>For cross-compatibility concerns, it is strongly recommended to use [HTTP Status Codes](https://datatracker.ietf.org/doc/html/rfc7231#section-6) whenever possible.<u><br><u>Runtimes **MUST** ensure that the property has been set when raising or escalating the [`error`](#error).<u> |
-| instance | `string` | `yes` | A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) used to reference the component the [`error`](#error) originates from.<br><u>Runtimes **MUST** set the property when raising or escalating the [`error`](#error). Otherwise ignore.<u> |
+| instance | `string` | `no` | A [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) used to reference the component the [`error`](#error) originates from.<br><u>Runtimes **MUST** set the property when raising or escalating the [`error`](#error). Otherwise ignore.<u> |
 | title | `string` | `no` | A short, human-readable summary of the [`error`](#error). |
 | detail | `string` | `no` | A human-readable explanation specific to this occurrence of the [`error`](#error). |
 

examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+Welcome to the Serverless Workflow Examples directory! This section contains a collection of brief YAML files, each representing a single workflow definition. 
+
+These examples are designed to demonstrate specific features and functionalities of the Serverless Workflow DSL. They serve as a practical reference to help you understand and implement different aspects of Serverless Workflows in your projects.
+
+## Contributing
+
+We welcome contributions! If you have an example demonstrating a unique feature or use case of Serverless Workflow, feel free to submit a pull request.
+
+For more detailed information on contributing, including guidelines and best practices, please refer to our [Contributing Guide](./CONTRIBUTING.md).

examples/bearer-auth-uri-format.yaml → examples/authentication-bearer.yaml

@@ -12,4 +12,4 @@ do:
           uri: https://petstore.swagger.io/v2/pet/1
           authentication:
             bearer:
-              token: ${ .token }
+              token: ${ .token }

examples/call-custom-function-cataloged.yaml

@@ -0,0 +1,13 @@
+document:
+  dsl: '1.0.0'
+  namespace: samples
+  name: call-custom-function-cataloged
+  version: '1.0.0'
+do:
+  - log:
+      call: https://raw.githubusercontent.com/serverlessworkflow/catalog/main/functions/log/1.0.0/function.yaml
+      with:
+        message: Hello, world!
+        level: information
+        timestamp: true
+        format: '{TIMESTAMP} [{LEVEL}] ({CONTEXT}): {MESSAGE}'

examples/call-custom-function-inline.yaml

@@ -0,0 +1,25 @@
+document:
+  dsl: '1.0.0'
+  namespace: samples
+  name: call-custom-function-inline
+  version: '1.0.0'
+use:
+  functions:
+    getPetById:
+      input:
+        schema:
+          document:
+            type: object
+            properties:
+              petId:
+                type: string
+            required: [ petId ]
+      call: http
+      with:
+        method: get
+        endpoint: https://petstore.swagger.io/v2/pet/{petId}
+do:
+  - getPet:
+      call: getPetById
+      with:
+        petId: 69

examples/call-grpc.yaml

@@ -0,0 +1,18 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: grpc-example
+  version: '0.1.0'
+do:
+  - greet:
+      call: grpc
+      with:
+        proto: 
+          endpoint: file://app/greet.proto
+        service:
+          name: GreeterApi.Greeter
+          host: localhost
+          port: 5011
+        method: SayHello
+        arguments:
+          name: ${ .user.preferredDisplayName }

examples/call-http-endpoint-interpolation.yaml

@@ -0,0 +1,11 @@
+document:
+  dsl: 1.0.0-alpha1
+  namespace: examples
+  name: call-http-shorthand-endpoint
+  version: 1.0.0-alpha1
+do:
+  - getPet:
+      call: http
+      with:
+        method: get
+        endpoint: ${ "https://petstore.swagger.io/v2/pet/\(.petId)" }

examples/call-openapi.yaml

@@ -0,0 +1,14 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: openapi-example
+  version: '0.1.0'
+do:
+  - findPet:
+      call: openapi
+      with:
+        document: 
+          endpoint: https://petstore.swagger.io/v2/swagger.json
+        operationId: findPetsByStatus
+        parameters:
+          status: available

examples/conditional-task.yaml

@@ -0,0 +1,22 @@
+document:
+  dsl: '1.0.0'
+  namespace: default
+  name: conditional-task
+  version: '1.0.0'
+do:
+  - raiseErrorIfUnderage:
+      if: .customer.age < 18
+      raise:
+        error:
+          type: https://superbet-casinos.com/customer/access-forbidden
+          status: 400
+          title: Access Forbidden
+      then: end
+  - placeBet:
+      call: http
+      with:
+        method: post
+        endpoint: https://superbet-casinos.com/api/bet/on/football
+        body:
+          customer: .customer
+          bet: .bet

examples/do-multiple.yaml

@@ -0,0 +1,17 @@
+document:
+  dsl: 1.0.0-alpha1
+  namespace: examples
+  name: call-http-shorthand-endpoint
+  version: 1.0.0-alpha1
+do:
+  - getPet:
+      call: http
+      with:
+        method: get
+        endpoint: https://petstore.swagger.io/v2/pet/{petId}
+  - buyPet:
+      call: http
+      with:
+        method: put
+        endpoint: https://petstore.swagger.io/v2/pet/{petId}
+        body: '${ . + { status: "sold" } }'

examples/emit.yaml

@@ -0,0 +1,19 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: emit
+  version: '0.1.0'
+do:
+  - emitEvent:
+      emit:
+        event:
+          with:
+            source: https://petstore.com
+            type: com.petstore.order.placed.v1
+            data:
+              client:
+                firstName: Cruella
+                lastName: de Vil
+              items:
+                - breed: dalmatian
+                  quantity: 101

examples/for.yaml

@@ -0,0 +1,21 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: for-example
+  version: '0.1.0'
+do:
+  - checkup:
+      for:
+        each: pet
+        in: .pets
+        at: index
+      while: .vet != null
+      do:
+        - waitForCheckup:
+            listen:
+              to:
+                one:
+                  with:
+                    type: com.fake.petclinic.pets.checkup.completed.v2
+            output:
+              as: '.pets + [{ "id": $pet.id }]'        

examples/fork.yaml

@@ -0,0 +1,26 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: fork-example
+  version: '0.1.0'
+do:
+  - raiseAlarm:
+      fork:
+        compete: true
+        branches:
+          - callNurse:
+              call: http
+              with:
+                method: put
+                endpoint: https://fake-hospital.com/api/v3/alert/nurses
+                body:
+                  patientId: ${ .patient.fullName }
+                  room: ${ .room.number }
+          - callDoctor:
+              call: http
+              with:
+                method: put
+                endpoint: https://fake-hospital.com/api/v3/alert/doctor
+                body:
+                  patientId: ${ .patient.fullName }
+                  room: ${ .room.number }

examples/listen-to-all.yaml

@@ -0,0 +1,16 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: listen-to-all
+  version: '0.1.0'
+do:
+  - callDoctor:
+      listen:
+        to:
+          all:
+          - with:
+              type: com.fake-hospital.vitals.measurements.temperature
+              data: ${ .temperature > 38 }
+          - with:
+              type: com.fake-hospital.vitals.measurements.bpm
+              data: ${ .bpm < 60 or .bpm > 100 }

examples/listen-to-any.yaml

@@ -0,0 +1,16 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: listen-to-any
+  version: '0.1.0'
+do:
+  - callDoctor:
+      listen:
+        to:
+          any:
+          - with:
+              type: com.fake-hospital.vitals.measurements.temperature
+              data: ${ .temperature > 38 }
+          - with:
+              type: com.fake-hospital.vitals.measurements.bpm
+              data: ${ .bpm < 60 or .bpm > 100 }

examples/listen-to-one.yaml

@@ -0,0 +1,18 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: listen-to-one
+  version: '0.1.0'
+do: 
+  - waitForStartup:
+      listen:
+        to:
+          one:
+            with:
+              type: com.virtual-wf-powered-race.events.race.started.v1
+  - startup:
+      call: http
+      with:
+        method: post
+        endpoint:
+          uri: https://virtual-wf-powered-race.com/api/v4/cars/{carId}/start

examples/raise.yaml

@@ -0,0 +1,13 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: raise-not-implemented
+  version: '0.1.0'
+do: 
+  - notImplemented:
+      raise:
+        error:
+          type: https://serverlessworkflow.io/errors/not-implemented
+          status: 500
+          title: Not Implemented
+          detail: ${ "The workflow '\( $workflow.definition.document.name ):\( $workflow.definition.document.version )' is a work in progress and cannot be run yet" }

examples/run-container.yaml

@@ -0,0 +1,10 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: run-container
+  version: '0.1.0'
+do:
+  - runContainer:
+      run:
+        container:
+          image: hello-world

examples/run-subflow.yaml

@@ -0,0 +1,14 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: run-subflow
+  version: '0.1.0'
+do:
+  - registerCustomer:
+      run:
+        workflow:
+          namespace: test
+          name: register-customer
+          version: '0.1.0'
+          input:
+            customer: .user

examples/set.yaml

@@ -0,0 +1,14 @@
+document:
+  dsl: '1.0.0-alpha1'
+  namespace: test
+  name: set
+  version: '0.1.0'
+schedule:
+  on:
+    one:
+      with:
+        type: io.serverlessworkflow.samples.events.trigger.v1
+do: 
+  - initialize:
+      set:
+        startEvent: ${ $workflow.input[0] }

examples/try-catch-retry.yaml

@@ -0,0 +1,26 @@
+document:
+  dsl: '1.0.0'
+  namespace: default
+  name: try-catch-retry
+  version: '1.0.0'
+do:
+  - tryGetPet:
+      try:
+        - getPet:
+            call: http
+            with:
+              method: get
+              endpoint: https://petstore.swagger.io/v2/pet/{petId}
+      catch:
+        errors:
+          with:
+            type: https://serverlessworkflow.io.io/dsl/errors/types/communication
+            status: 503
+        retry:
+          delay:
+            seconds: 3
+          backoff:
+            exponential: {}
+          limit:
+            attempt:
+              count: 5