-
Notifications
You must be signed in to change notification settings - Fork 146
/
dsl-reference.md
1571 lines (1272 loc) · 56.1 KB
/
dsl-reference.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Serverless Workflow DSL - Reference
## Table of Contents
- [Abstract](#abstract)
- [Definitions](#definitions)
+ [Workflow](#workflow)
- [Document](#document)
- [Use](#use)
- [Schedule](#schedule)
+ [Task](#task)
- [Call](#call)
+ [AsyncAPI](#asyncapi-call)
+ [gRPC](#grpc-call)
+ [HTTP](#http-call)
+ [OpenAPI](#openapi-call)
- [Composite](#composite)
- [Emit](#emit)
- [For](#for)
- [Listen](#listen)
- [Raise](#raise)
- [Run](#run)
+ [Container](#container-process)
+ [Shell](#shell-process)
+ [Script](#script-process)
+ [Workflow](#workflow-process)
- [Switch](#switch)
- [Set](#set)
- [Try](#try)
- [Wait](#wait)
+ [Flow Directive](#flow-directive)
+ [External Resource](#external-resource)
+ [Authentication](#authentication)
- [Basic](#basic-authentication)
- [Bearer](#bearer-authentication)
- [Certificate](#certificate-authentication)
- [Digest](#digest-authentication)
- [OAUTH2](#oauth2-authentication)
+ [Extension](#extension)
+ [Error](#error)
- [Standard Error Types](#standard-error-types)
+ [Event Consumption Strategy](#event-consumption-strategy)
+ [Event Filter](#event-filter)
+ [Retry](#retry)
+ [Input](#input)
+ [Output](#output)
+ [Timeout](#timeout)
+ [Duration](#duration)
+ [HTTP Response](#http-response)
+ [HTTP Request](#http-request)
## Abstract
This document provides comprehensive definitions and detailed property tables for all the concepts discussed in the Serverless Workflow DSL. It serves as a reference guide, explaining the structure, components, and configurations available within the DSL. By exploring this document, users will gain a thorough understanding of how to define, configure, and manage workflows, including task definitions, flow directives, and state transitions. This foundational knowledge will enable users to effectively utilize the DSL for orchestrating serverless functions and automating processes.
## Definitions
### Workflow
A [workflow](#workflow) serves as a blueprint outlining the series of [tasks](#task) required to execute a specific business operation. It details the sequence in which [tasks](#task) must be completed, guiding users through the process from start to finish, and helps streamline operations, ensure consistency, and optimize efficiency within an organization.
#### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| document | [`document`](#document) | `yes` | Documents the defined workflow. |
| input | [`input`](#input) | `no` | Configures the workflow's input. |
| use | [`use`](#use) | `no` | Defines the workflow's reusable components, if any. |
| do | [`map[string, task]`](#task) | `yes` | The [task(s)](#task) that must be performed by the [workflow](#workflow). |
| timeout | [`timeout`](#timeout) | `no` | The configuration, if any, of the workflow's timeout. |
| output | [`output`](#output) | `no` | Configures the workflow's output. |
| schedule | [`schedule`](#schedule) | `no` | Configures the workflow's schedule, if any. |
| evaluate | [`evaluate`](#evaluate) | `no` | Configures runtime expression evaluation. |
#### Document
Documents the workflow definition.
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| dsl | `string` | `yes` | The version of the DSL used to define the workflow. |
| namespace | `string` | `yes` | The workflow's namespace.<br> |
| name | `string` | `yes` | The workflow's name.<br> |
| version | `string` | `yes` | The workflow's [semantic version]
| title | `string` | `no` | The workflow's title. |
| summary | `string` | `no` | The workflow's Markdown summary. |
| tags | `map[string, string]` | `no` | A key/value mapping of the workflow's tags, if any. |
#### Use
Defines the workflow's reusable components.
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| authentications | [`map[string, authentication]`](#authentication) | `no` | A name/value mapping of the workflow's reusable authentication policies. |
| errors | [`map[string, error]`](#error) | `no` | A name/value mapping of the workflow's reusable errors. |
| extensions | [`map[string, extension]`](#extension) | `no` | A name/value mapping of the workflow's reusable extensions. |
| functions | [`map[string, task]`](#task) | `no` | A name/value mapping of the workflow's reusable tasks. |
| retries | [`map[string, retryPolicy]`](#retry) | `no` | A name/value mapping of the workflow's reusable retry policies. |
| secrets | `string[]` | `no` | A list containing the workflow's secrets. |
#### Schedule
Configures the schedule of a workflow.
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| every | [`duration`](#duration) | `no` | Specifies the duration of the interval at which the workflow should be executed. Unlike `after`, this option will run the workflow regardless of whether the previous run is still in progress.<br>*Required when no other property has been set.* |
| cron | `string` | `no` | Specifies the schedule using a CRON expression, e.g., '0 0 * * *' for daily at midnight.<br>*Required when no other property has been set.* |
| after | [`duration`](#duration) | `no` | Specifies a delay duration that the workflow must wait before starting again after it completes. In other words, when this workflow completes, it should run again after the specified amount of time.<br>*Required when no other property has been set.* |
| on | [`eventConsumptionStrategy`](#event-consumption-strategy) | `no` | Specifies the events that trigger the workflow execution.<br>*Required when no other property has been set.* |
#### Evaluate
Configures a workflow's runtime expression evaluation.
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| language | `string` | `yes` | The language used for writting runtime expressions.<br>*Defaults to `jq`.* |
| mode | `string` | `yes` | The runtime expression evaluation mode.<br>*Supported values are:*<br>- `strict`: requires all expressions to be enclosed within `${ }` for proper identification and evaluation.<br>- `loose`: evaluates any value provided. If the evaluation fails, it results in a string with the expression as its content.<br>*Defaults to `strict`.*
#### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: order-pet
version: '1.0.0'
title: Order Pet - 1.0.0
summary: >
# Order Pet - 1.0.0
## Table of Contents
- [Description](#description)
- [Requirements](#requirements)
## Description
A sample workflow used to process an hypothetic pet order using the [PetStore API](https://petstore.swagger.io/)
## Requirements
### Secrets
- my-oauth2-secret
use:
authentications:
petStoreOAuth2:
oauth2: my-oauth2-secret
extensions:
externalLogging:
extend: all
before:
call: http
with:
method: post
uri: https://fake.log.collector.com
body:
message: "${ \"Executing task '\($task.reference)'...\" }"
after:
call: http
with:
method: post
uri: https://fake.log.collector.com
body:
message: "${ \"Executed task '\($task.reference)'...\" }"
functions:
getAvailablePets:
call: openapi
with:
document:
uri: https://petstore.swagger.io/v2/swagger.json
operation: findByStatus
parameters:
status: available
secrets:
- my-oauth2-secret
do:
getAvailablePets:
call: getAvailablePets
output:
from: "$input + { availablePets: [.[] | select(.category.name == "dog" and (.tags[] | .breed == $input.order.breed))] }"
submitMatchesByMail:
call: http
with:
method: post
endpoint:
uri: https://fake.smtp.service.com/email/send
authentication: petStoreOAuth2
body:
from: noreply@fake.petstore.com
to: ${ .order.client.email }
subject: Candidates for Adoption
body: >
Hello ${ .order.client.preferredDisplayName }!
Following your interest to adopt a dog, here is a list of candidates that you might be interested in:
${ .pets | map("-\(.name)") | join("\n") }
Please do not hesistate to contact us at info@fake.petstore.com if your have questions.
Hope to hear from you soon!
----------------------------------------------------------------------------------------------
DO NOT REPLY
----------------------------------------------------------------------------------------------
```
### Task
A task within a [workflow](#workflow) represents a discrete unit of work that contributes to achieving the overall objectives defined by the [workflow](#workflow).
It encapsulates a specific action or set of actions that need to be executed in a predefined order to advance the workflow towards its completion.
[Tasks](#task) are designed to be modular and focused, each serving a distinct purpose within the broader context of the [workflow](#workflow).
By breaking down the [workflow](#workflow) into manageable [tasks](#task), organizations can effectively coordinate and track progress, enabling efficient collaboration and ensuring that work is completed in a structured and organized manner.
The Serverless Workflow DSL defines a list of [tasks](#task) that **must be** supported by all runtimes:
- [Call](#call), used to call services and/or functions.
- [Composite](#composite), used to define a minimum of two subtasks to perform.
- [Emit](#emit), used to emit [events](#event).
- [For](#for), used to iterate over a collection of items, and conditionally perform a task for each of them.
- [Listen](#listen), used to listen for an [event](#event) or more.
- [Raise](#raise), used to raise an [error](#error) and potentially fault the [workflow](#workflow).
- [Run](#run), used to run a [container](#container), a [script](#script) or event a [shell](#shell) command.
- [Switch](#switch), used to dynamically select and execute one of multiple alternative paths based on specified conditions
- [Set](#set), used to dynamically set or update the [workflow](#workflow)'s data during the its execution.
- [Try](#try), used to attempt executing a specified [task](#task), and to handle any resulting [errors](#error) gracefully, allowing the [workflow](#workflow) to continue without interruption.
- [Wait](#wait), used to pause or wait for a specified duration before proceeding to the next task.
#### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| input | [`input`](#input) | `no` | An object used to customize the task's input and to document its schema, if any. |
| output | [`output`](#output) | `no` | An object used to customize the task's output and to document its schema, if any. |
| timeout | [`timeout`](#timeout) | `no` | The configuration of the task's timeout, if any. |
| then | [`flowDirective`](#flow-directive) | `no` | The flow directive to execute next.<br>*If not set, defaults to `continue`.* |
#### Call
Enables the execution of a specified function within a workflow, allowing seamless integration with custom business logic or external services.
##### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| call | `string` | `yes` | The name of the function to call. |
| with | `map` | `no` | A name/value mapping of the parameters to call the function with |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
getPetById:
call: http
with:
method: get
uri: https://petstore.swagger.io/v2/pet/{petId}
```
Serverless Workflow defines several default functions that **MUST** be supported by all implementations and runtimes:
- [AsyncAPI](#asyncapi)
- [gRPC](#grpc-call)
- [HTTP](#http-call)
- [OpenAPI](#openapi-call)
##### AsyncAPI Call
The [AsyncAPI Call](#asyncapi-call) enables workflows to interact with external services described by [AsyncAPI](https://www.asyncapi.com/).
###### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| document | [`externalResource`](#external-resource) | `yes` | The AsyncAPI document that defines the operation to call. |
| operationRef | `string` | `yes` | A reference to the AsyncAPI operation to call. |
| server | `string` | `no` | A reference to the server to call the specified AsyncAPI operation on.<br>If not set, default to the first server matching the operation's channel. |
| message | `string` | `no` | The name of the message to use. <br>If not set, defaults to the first message defined by the operation. |
| binding | `string` | `no` | The name of the binding to use. <br>If not set, defaults to the first binding defined by the operation |
| payload | `any` | `no` | The operation's payload, as defined by the configured message |
| authentication | `string`<br>[`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the AsyncAPI operation. |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
greetUser:
call: asyncapi
with:
document: https://fake.com/docs/asyncapi.json
operation: findPetsByStatus
server: staging
message: getPetByStatusQuery
binding: http
payload:
petId: ${ .pet.id }
```
##### gRPC Call
The [gRPC Call](#grpc-call) enables communication with external systems via the gRPC protocol, enabling efficient and reliable communication between distributed components.
###### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| proto | [`externalResource`](#external-resource) | `yes` | The proto resource that describes the GRPC service to call. |
| service.name | `string` | `yes` | The name of the GRPC service to call. |
| service.host | `string` | `yes` | The hostname of the GRPC service to call. |
| service.port | `integer` | `no` | The port number of the GRPC service to call. |
| service.authentication | [`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the GRPC service. |
| method | `string` | `yes` | The name of the GRPC service method to call. |
| arguments | `map` | `no` | A name/value mapping of the method call's arguments, if any. |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
greetUser:
call: grpc
with:
proto: file://app/greet.proto
service:
name: GreeterApi.Greeter
host: localhost
port: 5011
method: SayHello
arguments:
name: ${ .user.preferredDisplayName }
```
##### HTTP Call
The [HTTP Call](#http-call) enables workflows to interact with external services over HTTP.
###### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| method | `string` | `yes` | The HTTP request method. |
| endpoint | [`endpoint`](#endpoint) | `yes` | An URI or an object that describes the HTTP endpoint to call. |
| headers | `map` | `no` | A name/value mapping of the HTTP headers to use, if any. |
| body | `any` | `no` | The HTTP request body, if any. |
| output | `string` | `no` | The http call's output format.<br>*Supported values are:*<br>*- `raw`, which output's the base-64 encoded [http response](#http-response) content, if any.*<br>*- `content`, which outputs the content of [http response](#http-response), possibly deserialized.*<br>*- `response`, which outputs the [http response](#http-response).*<br>*Defaults to `content`.* |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
getPetById:
call: http
with:
method: get
uri: https://petstore.swagger.io/v2/pet/{petId}
```
##### OpenAPI Call
The [OpenAPI Call](#openapi-call) enables workflows to interact with external services described by [OpenAPI](https://www.openapis.org).
###### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| document | [`externalResource`](#external-resource) | `yes` | The OpenAPI document that defines the operation to call. |
| operationId | `string` | `yes` | The id of the OpenAPI operation to call. |
| arguments | `map` | `no` | A name/value mapping of the parameters, if any, of the OpenAPI operation to call. |
| authentication | [`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when calling the OpenAPI operation. |
| output | `string` | `no` | The OpenAPI call's output format.<br>*Supported values are:*<br>*- `raw`, which output's the base-64 encoded [http response](#http-response) content, if any.*<br>*- `content`, which outputs the content of [http response](#http-response), possibly deserialized.*<br>*- `response`, which outputs the [http response](#http-response).*<br>*Defaults to `content`.* |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
getPets:
call: openapi
with:
document: https://petstore.swagger.io/v2/swagger.json
operation: findPetsByStatus
parameters:
status: available
```
#### Composite
Serves as a pivotal orchestrator within workflow systems, enabling the seamless integration and execution of multiple subtasks to accomplish complex operations. By encapsulating and coordinating various subtasks, this task type facilitates the efficient execution of intricate workflows.
##### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| execute.sequentially | [`map(string, task)`](#task) | `no` | The tasks to perform sequentially.<br>*Required if `execute.concurrently` has not been set, otherwise ignored.*<br>*If set, must contains **at least** two [`tasks`](#task).* |
| execute.concurrently | [`map(string, task)`](#task) | `no` | The tasks to perform concurrently.<br>*Required if `execute.sequentially` has not been set, otherwise ignored.*<br>*If set, must contains **at least** two [`tasks`](#task).* |
| execute.compete | `boolean` | `no` | Indicates whether or not the concurrent [`tasks`](#task) are racing against each other, with a single possible winner, which sets the composite task's output.<br>*Ignored if `execute.sequentially` has been set. Defaults to `false`.*<br>*Must **not** be set if the [`tasks`](#task) are executed sequentially.* |
##### Examples
*Executing tasks sequentially:*
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
bookTrip:
execute:
sequentially:
bookHotel:
call: http
with:
method: post
endpoint:
uri: https://fake-booking-agency.com/hotels/book
authentication: fake-booking-agency-oauth2
body:
name: Four Seasons
city: Antwerp
country: Belgium
bookFlight:
call: http
with:
method: post
endpoint:
uri: https://fake-booking-agency.com/flights/book
authentication: fake-booking-agency-oauth2
body:
departure:
date: '01/01/26'
time: '07:25:00'
from:
airport: BRU
city: Zaventem
country: Belgium
arrival:
date: '01/01/26'
time: '11:12:00'
to:
airport: LIS
city: Lisbon
country: Portugal
```
*Executing tasks concurrently:*
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
raiseAlarm:
execute:
concurrently:
callNurse:
call: http
with:
method: put
uri: https://fake-hospital.com/api/v3/alert/nurses
body:
patientId: ${ .patient.fullName }
room: ${ .room.number }
callDoctor:
call: http
with:
method: put
uri: https://fake-hospital.com/api/v3/alert/doctor
body:
patientId: ${ .patient.fullName }
room: ${ .room.number }
```
#### Emit
Allows workflows to publish events to event brokers or messaging systems, facilitating communication and coordination between different components and services. With the Emit task, workflows can seamlessly integrate with event-driven architectures, enabling real-time processing, event-driven decision-making, and reactive behavior based on incoming events.
##### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| emit.event | [`event`](#event) | `yes` | Defines the event to emit. |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
placeOrder:
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
```
#### For
Allows workflows to iterate over a collection of items, executing a defined set of subtasks for each item in the collection. This task type is instrumental in handling scenarios such as batch processing, data transformation, and repetitive operations across datasets.
##### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| for.each | `string` | `no` | The name of the variable used to store the current item being enumerated.<br>Defaults to `item`. |
| for.in | `string` | `yes` | A [runtime expression](#runtime-expressions) used to get the collection to enumerate. |
| for.at | `string` | `no` | The name of the variable used to store the index of the current item being enumerated.<br>Defaults to `index`. |
| while | `string` | `no` | A [runtime expression](#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. |
| do | [`task`](#task) | `yes` | The task to perform for each item in the collection. |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
checkup:
for:
each: pet
in: .pets
at: index
while: .vet != null
do:
checkForFleas:
if: $pet.lastCheckup == null
listen:
to:
one:
with:
type: com.fake.petclinic.pets.checkup.completed.v2
output:
to: '.pets + [{ "id": $pet.id }]'
```
#### Listen
Provides a mechanism for workflows to await and react to external events, enabling event-driven behavior within workflow systems.
##### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| listen.to | [`eventConsumptionStrategy`](#event-consumption-strategy) | `yes` | Configures the event(s) the workflow must listen to. |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
callDoctor:
listen:
to:
any:
- with:
type: com.fake-hospital.vitals.measurements.temperature
data:
temperature: ${ .temperature > 38 }
- with:
type: com.fake-hospital.vitals.measurements.bpm
data:
temperature: ${ .bpm < 60 or .bpm > 100 }
```
#### Raise
Intentionally triggers and propagates errors. By employing the "Raise" task, workflows can deliberately generate error conditions, allowing for explicit error handling and fault management strategies to be implemented.
##### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| raise.error | [`error`](#error) | `yes` | Defines the error to raise. |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
processTicket:
switch:
highPriority:
when: .ticket.priority == "high"
then: escalateToManager
mediumPriority:
when: .ticket.priority == "medium"
then: assignToSpecialist
lowPriority:
when: .ticket.priority == "low"
then: resolveTicket
default:
then: raiseUndefinedPriorityError
raiseUndefinedPriorityError:
raise:
error:
type: https://fake.com/errors/tickets/undefined-priority
status: 400
title: Undefined Priority
escalateToManager: {...}
assignToSpecialist: {...}
resolveTicket: {...}
```
#### Run
Provides the capability to execute external [containers](#container-process), [shell commands](#shell-process), [scripts](#script-process), or [workflows](#workflow-process).
##### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| run.container | [`container`](#container-process) | `no` | The definition of the container to run.<br>*Required if `script`, `shell` and `workflow` have not been set.* |
| run.script | [`script`](#script-process) | `no` | The definition of the script to run.<br>*Required if `container`, `shell` and `workflow` have not been set.* |
| run.shell | [`shell`](#shell-process) | `no` | The definition of the shell command to run.<br>*Required if `container`, `script` and `workflow` have not been set.* |
| run.workflow | [`workflow`](#workflow-process) | `no` | The definition of the workflow to run.<br>*Required if `container`, `script` and `shell` have not been set.* |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
runContainer:
run:
container:
image: fake-image
runScript:
run:
script:
language: js
code: >
Some cool multiline script
runShell:
run:
shell:
command: 'echo "Hello, ${ .user.name }"'
runWorkflow:
run:
workflow:
reference: another-one:0.1.0
input: {}
```
##### Container Process
Enables the execution of external processes encapsulated within a containerized environment, allowing workflows to interact with and execute complex operations using containerized applications, scripts, or commands.
###### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| image | `string` | `yes` | The name of the container image to run |
| command | `string` | `no` | The command, if any, to execute on the container |
| ports | `map` | `no` | The container's port mappings, if any |
| volumes | `map` | `no` | The container's volume mappings, if any |
| environment | `map` | `no` | A key/value mapping of the environment variables, if any, to use when running the configured process |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
runContainer:
run:
container:
image: fake-image
```
##### Script Process
Enables the execution of custom scripts or code within a workflow, empowering workflows to perform specialized logic, data processing, or integration tasks by executing user-defined scripts written in various programming languages.
###### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| language | `string` | `yes` | The language of the script to run |
| code | `string` | `no` | The script's code.<br>*Required if `source` has not been set.* |
| source | [externalResource](#external-resource) | `no` | The script's resource.<br>*Required if `code` has not been set.* |
| environment | `map` | `no` | A key/value mapping of the environment variables, if any, to use when running the configured process |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
runScript:
run:
script:
language: js
code: >
Some cool multiline script
```
##### Shell Process
Enables the execution of shell commands within a workflow, enabling workflows to interact with the underlying operating system and perform system-level operations, such as file manipulation, environment configuration, or system administration tasks.
###### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| command | `string` | `yes` | The shell command to run |
| arguments | `map` | `no` | A list of the arguments of the shell command to run |
| environment | `map` | `no` | A key/value mapping of the environment variables, if any, to use when running the configured process |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
runShell:
run:
shell:
command: 'echo "Hello, ${ .user.name }"'
```
##### Workflow Process
Enables the invocation and execution of nested workflows within a parent workflow, facilitating modularization, reusability, and abstraction of complex logic or business processes by encapsulating them into standalone workflow units.
###### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| name | `string` | `yes` | The name of the workflow to run |
| version | `string` | `yes` | The version of the workflow to run. Defaults to `latest` |
| input | `any` | `no` | The data, if any, to pass as input to the workflow to execute. The value should be validated against the target workflow's input schema, if specified |
###### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
runShell:
run:
workflow:
reference: another-one:0.1.0
input:
foo: bar
```
#### Set
A task used to set data.
##### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| set | `object` | `yes` | A name/value mapping of the data to set. |
##### Examples
```yaml
document:
dsl: 1.0.0-alpha1
namespace: default
name: set
version: '0.1.0'
do:
initialize:
set:
shape: circle
size: ${ .configuration.size }
fill: ${ .configuration.fill }
```
#### Switch
Enables conditional branching within workflows, allowing them to dynamically select different paths based on specified conditions or criteria
##### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| switch | [`map[string, case]`](#switch-case) | `yes` | A name/value map of the cases to switch on |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
processOrder:
switch:
case1:
when: .orderType == "electronic"
then: processElectronicOrder
case2:
when: .orderType == "physical"
then: processPhysicalOrder
default:
then: handleUnknownOrderType
processElectronicOrder:
execute:
sequentially:
validatePayment: {...}
fulfillOrder: {...}
then: exit
processPhysicalOrder:
execute:
sequentially:
checkInventory: {...}
packItems: {...}
scheduleShipping: {...}
then: exit
handleUnknownOrderType:
execute:
sequentially:
logWarning: {...}
notifyAdmin: {...}
```
##### Switch Case
Defines a switch case, encompassing of a condition for matching and an associated action to execute upon a match.
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| when | `string` | `no` | A runtime expression used to determine whether or not the case matches.<br>*If not set, the case will be matched by default if no other case match.*<br>*Note that there can be only one default case, all others **MUST** set a condition.*
| then | [`flowDirective`](#flow-directive) | `yes` | The flow directive to execute when the case matches. |
#### Try
Serves as a mechanism within workflows to handle errors gracefully, potentially retrying failed tasks before proceeding with alternate ones.
##### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| try | [`task`](#task) | `yes` | The task to perform. |
| catch | [`catch`](#catch) | `yes` | Configures the errors to catch and how to handle them. |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
processOrder:
try:
call: http
with:
method: get
uri: https://
catch:
errors:
with:
type: https://serverlessworkflow.io.io/dsl/errors/types/communication
status: 503
as: error
retry:
delay:
seconds: 3
backoff:
exponential: {}
limit:
attempt:
count: 5
```
##### Catch
Defines the configuration of a catch clause, which a concept used to catch errors.
###### Properties
| Name | Type | Required | Description |
|:--|:---:|:---:|:---|
| errors | [`errorFilter`](#retry) | `no` | The definition of the errors to catch |
| as | `string` | `no` | The name of the runtime expression variable to save the error as. Defaults to 'error'. |
| when | `string`| `no` | A runtime expression used to determine whether or not to catch the filtered error |
| exceptWhen | `string` | `no` | A runtime expression used to determine whether or not to catch the filtered error |
| retry | [`retryPolicy`](#retry) | `no` | The retry policy to use, if any, when catching errors |
| do | [`task`](#task) | `no` | The definition of the task to run when catching an error |
#### Wait
Allows workflows to pause or delay their execution for a specified period of time.
##### Properties
| Name | Type | Required | Description|
|:--|:---:|:---:|:---|
| wait | `string`<br>[`duration`](#duration) | `yes` | The amount of time to wait.<br>If a `string`, must be a valid [ISO 8601](#) duration expression. |
##### Examples
```yaml
document:
dsl: '1.0.0-alpha1'
namespace: test
name: sample-workflow
version: '0.1.0'
do:
delay10Seconds:
wait:
seconds: 10
```
### Flow Directive
Flow Directives are commands within a workflow that dictate its progression.
| Directive | Description |
| --------- | ----------- |
| `continue` | Instructs the workflow to proceed with the next task in line. This action may conclude the execution of a particular workflow or branch if there are not task defined after the continue one. |
| `exit` | Halts the current branch's execution, potentially terminating the entire workflow if the current task resides within the main branch. |
| `end` | Provides a graceful conclusion to the workflow execution, signaling its completion explicitly. |
### External Resource
Defines an external resource.
#### Properties
| Property | Type | Required | Description |
|----------|:----:|:--------:|-------------|
| name | `string` | `no` | The name, if any, of the defined resource. |
| uri | `string` | `yes` | The URI at which to get the defined resource. |
| authentication | [`authentication`](#authentication) | `no` | The authentication policy, or the name of the authentication policy, to use when fecthing the resource. |
##### Examples
```yaml