Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds support for external resources #701

Closed
wants to merge 7 commits into from
Closed

Adds support for external resources #701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
68a272a
Added the resources.json schema
cdavernas Oct 24, 2022
aa65b41
Fixed Workflow Definition Structure property descriptions to match th…
cdavernas Oct 24, 2022
69fa217
Added example and updated roadmap
cdavernas May 30, 2023
d2e864c
Updated roadmap
cdavernas May 30, 2023
c6aa5dd
Merge branch 'main' into external-resources
cdavernas May 30, 2023
8ccce76
Merge branch 'main' into external-resources
cdavernas Feb 15, 2024
7a4fe8a
Update examples/README.md
cdavernas Feb 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 139 additions & 0 deletions examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Provides Serverless Workflow language examples
- [Online Food Ordering](#Online-Food-Ordering)
- [Continuing as a new Execution](#Continuing-as-a-new-Execution)
- [Process Transactions (Foreach State with conditions)](#Process-Transactions)
- [Import external resources](#import-external-resources)

### Hello World Example

Expand Down Expand Up @@ -4944,3 +4945,141 @@ functions:
</td>
</tr>
</table>

### Import External Resources

#### Description

For the example, let's assume we have developed a number of workflows to orchestrate an hypothetical, event-driven management solution around the Swagger Pet Store API.

At start, we were copy/pasting the many Pet Store function definitions from workflow to workflow as we needed them. Even though that was very tedious, we just coped with it, until that day where the names of a couple of functions changed in the `swagger.json`, breaking most of our workflows.

We then sat down, and agreed for our sanity to respect the DRY principle, and only declare those functions once, in an hypothetical `https://fake.examples/sw/petstore.yaml` file, that could look like the following:

```yaml
functions:
- name: add-pet
type: openapi
operation: https://petstore.swagger.io/v2/swagger.json#addPet
- name: get-pet-by-id
type: openapi
operation: https://petstore.swagger.io/v2/swagger.json#getPetById
- name: update-pet
type: openapi
operation: https://petstore.swagger.io/v2/swagger.json#updatePet
- name: delete-pet
type: openapi
operation: https://petstore.swagger.io/v2/swagger.json#deletePet
```

Starting from there, we could now reuse those definitions in any workflows by just importing them:

#### Workflow Definition

<table>
<tr>
<th>JSON</th>
<th>YAML</th>
</tr>
<tr>
<td valign="top">

```json
{
"id": "get-pet-availability",
"name": "Get Pet Availability",
"version": "1.0.0",
"specVersion": 0.8,
"resources": [
{
"name": "petstore",
"uri": "https://test.com/myresource.json"
}
],
"functions": [
{
"name": "email-send",
"type": "openapi",
"operation": "smtp.json#send"
}
],
"states": [
{
"name": "get-pet",
"type": "operation",
"actions": [
{
"name": "get-pet-by-id",
"functionRef": {
"refName": "petstore.get-pet-by-id",
"arguments": {
"petId": "${ .input.petId }"
}
},
"actionDataFilter": {
"toStateData": "${ .pet }"
}
},
{
"name": "send-pet-status-by-email",
"functionRef": {
"refName": "email-send",
"arguments": {
"from": "info@petstore.io",
"to": "${ .input.client.email }",
"subject": "Pet Inquiry Result",
"isBodyHtml": true,
"body": "The status of the pet you enquired (${ .input.petId }) about is '${ .pet.status }'"
}
}
}
],
"end": true
}
]
}
```

</td>
<td valign="top">

```yaml
id: get-pet-availability
name: Get Pet Availability
version: 1.0.0
specVersion: 0.8
resources:
- name: petstore
uri: 'https://test.com/myresource.json'
functions:
- name: email-send
type: openapi
operation: 'smtp.json#send'
states:
- name: get-pet
type: operation
actions:
- name: get-pet-by-id
functionRef:
refName: petstore.get-pet-by-id
arguments:
petId: '${ .input.petId }'
actionDataFilter:
toStateData: '${ .pet }'
- name: send-pet-status-by-email
functionRef:
refName: email-send
arguments:
from: info@petstore.io
to: '${ .input.client.email }'
subject: Pet Inquiry Result
isBodyHtml: true
body: >-
The status of the pet you enquired (${ .input.petId }) about is
'${ .pet.status }'
end: true
```

</td>
</tr>
</table>
1 change: 1 addition & 0 deletions roadmap/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ _Status description:_
| ✔️| Add the new `WORKFLOW` reserved keyword to workflow expressions |
| ✔️| Update `ForEach` state iteration parameter example. This parameter is an expression variable, not a JSON property |
| ✔️| Add the new `rest` function type [spec doc](https://github.com/serverlessworkflow/specification/tree/main/specification.md#using-functions-for-restful-service-invocations) |
| ✔️| Add support for importing and referencing externally defined workflow `resources` |
| ✏️️| Add inline state defs in branches | |
| ✏️️| Add "completedBy" functionality | |
| ✏️️| Define workflow context | |
Expand Down
25 changes: 8 additions & 17 deletions schema/auth.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,14 @@
"description": "Serverless Workflow specification - auth schema",
"type": "object",
"auth": {
"oneOf": [
{
"type": "string",
"format": "uri",
"description": "URI to a resource containing auth definitions (json or yaml)"
},
{
"type": "array",
"description": "Workflow auth definitions",
"items": {
"type": "object",
"$ref": "#/definitions/authdef"
},
"additionalItems": false,
"minItems": 1
}
]
"type": "array",
"description": "Workflow auth definitions",
"items": {
"type": "object",
"$ref": "#/definitions/authdef"
},
"additionalItems": false,
"minItems": 1
},
"required": [
"auth"
Expand Down
25 changes: 8 additions & 17 deletions schema/errors.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,14 @@
"description": "Serverless Workflow specification - errors schema",
"type": "object",
"errors": {
"oneOf": [
{
"type": "string",
"format": "uri",
"description": "URI to a resource containing error definitions (json or yaml)"
},
{
"type": "array",
"description": "Workflow Error definitions. Defines checked errors that can be explicitly handled during workflow execution",
"items": {
"type": "object",
"$ref": "#/definitions/errordef"
},
"additionalItems": false,
"minItems": 1
}
]
"type": "array",
"description": "Workflow Error definitions. Defines checked errors that can be explicitly handled during workflow execution",
"items": {
"type": "object",
"$ref": "#/definitions/errordef"
},
"additionalItems": false,
"minItems": 1
},
"required": [
"errors"
Expand Down
25 changes: 8 additions & 17 deletions schema/events.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,14 @@
"description": "Serverless Workflow specification - events schema",
"type": "object",
"events": {
"oneOf": [
{
"type": "string",
"format": "uri",
"description": "URI to a resource containing event definitions (json or yaml)"
},
{
"type": "array",
"description": "Workflow CloudEvent definitions. Defines CloudEvents that can be consumed or produced",
"items": {
"type": "object",
"$ref": "#/definitions/eventdef"
},
"additionalItems": false,
"minItems": 1
}
]
"type": "array",
"description": "Workflow CloudEvent definitions. Defines CloudEvents that can be consumed or produced",
"items": {
"type": "object",
"$ref": "#/definitions/eventdef"
},
"additionalItems": false,
"minItems": 1
},
"required": [
"events"
Expand Down
25 changes: 8 additions & 17 deletions schema/functions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,14 @@
"description": "Serverless Workflow specification - functions schema",
"type": "object",
"functions": {
"oneOf": [
{
"type": "string",
"format": "uri",
"description": "URI to a resource containing function definitions (json or yaml)"
},
{
"type": "array",
"description": "Workflow function definitions",
"items": {
"type": "object",
"$ref": "#/definitions/function"
},
"additionalItems": false,
"minItems": 1
}
]
"type": "array",
"description": "Workflow function definitions",
"items": {
"type": "object",
"$ref": "#/definitions/function"
},
"additionalItems": false,
"minItems": 1
},
"required": [
"functions"
Expand Down
100 changes: 100 additions & 0 deletions schema/resources.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
{
"$id": "https://serverlessworkflow.io/schemas/0.8/resources.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Serverless Workflow specification - resources schema",
"type": "object",
"resources":{
"type": "array",
"description": "Defines the external resources referenced by the workflow",
"items": {
"type": "object",
"$ref": "#/definitions/resourceRef"
},
"additionalItems": false,
"minItems": 1
},
"required":[
"resources"
],
"definitions":{
"resourceRef":{
"type": "object",
"description": "References an external resource",
"properties": {
"name": {
"type": "string",
"description": "The name of the external resource. It must be lowercased and must only contain alphanumeric characters, with the exception of `-` and `_`. The name is used as prefix to reference any definition contained in the referenced resource.",
"pattern": "^[a-z0-9-_]+$"
cdavernas marked this conversation as resolved.
Show resolved Hide resolved
},
"uri": {
"type": "string",
"format": "uri",
"description": "The uri at which to find the referenced external resource definition"
},
"authRef": {
"type": "string",
"description": "References the (inline) auth definition used to retrieve the referenced external resource"
}
},
"required": [
"name",
"uri"
]
},
"resourceDef":{
cdavernas marked this conversation as resolved.
Show resolved Hide resolved
"type": "object",
"description": "Defines an external resource",
"properties": {
"constants": {
"type": "object"
},
"secrets": {
"type": "array",
"items": {
"$ref": "secrets.json#/secrets"
}
},
"retries": {
"type": "array",
"items": {
"$ref": "retries.json#/retries"
}
},
"auth": {
"type": "array",
"items": {
"$ref": "auth.json#/auth"
}
},
"timeouts": {
"type": "array",
"items": {
"$ref": "timeouts.json#/timeouts"
}
},
"events": {
"type": "array",
"items": {
"$ref": "events.json#/events"
}
},
"functions": {
"type": "array",
"items": {
"$ref": "functions.json#/functions"
}
},
"errors": {
"type": "array",
"items": {
"$ref": "errors.json#/errors"
}
},
"metadata":{
cdavernas marked this conversation as resolved.
Show resolved Hide resolved
"type": "object",
"additionalProperties": true
}
}
}
}
}
Loading
Loading