From 8b02ff2c1810649f1573df5728390974c5e7585e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 6 Sep 2023 13:47:02 +0200 Subject: [PATCH] [1.40.x-prod] KOGITO-9682: Add the workflow-timeout SW to the timeouts-showcase Documentation (#491) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit KOGITO-9682: Add the workflow-timeout SW to the timeouts-showcase Documentation (#441) * KOGITO-9682: Add the workflow-timeout SW to the timeouts-showcase Documentation * Update serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc * Update serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc * Update serverlessworkflow/modules/ROOT/pages/core/timeouts-support.adoc * Update serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc * Update serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc * Update serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc * Update serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc --------- Co-authored-by: Walter Medvedeo Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> Co-authored-by: Marián Macik Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> --- serverlessworkflow/antora.yml | 4 + .../workflow-timeouts-decorated.svg | 515 ++++++++++++++++++ .../timeouts-showcase/workflow-timeouts.svg | 1 + .../ROOT/pages/core/timeouts-support.adoc | 15 +- .../pages/job-services/core-concepts.adoc | 4 +- .../use-cases/timeout-showcase-example.adoc | 40 +- 6 files changed, 564 insertions(+), 15 deletions(-) create mode 100644 serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts-decorated.svg create mode 100644 serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts.svg diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml index b714e4670..8a1d2260c 100644 --- a/serverlessworkflow/antora.yml +++ b/serverlessworkflow/antora.yml @@ -94,3 +94,7 @@ asciidoc: ocp_knative_eventing_url: https://docs.openshift.com/container-platform/4.12/serverless/install/installing-knative-eventing.html ocp_kn_cli_url: https://docs.openshift.com/container-platform/4.12/serverless/install/installing-kn.html serverless_workflow_vscode_extension_name: KIE Serverless Workflow Editor + # references to documents within the documentation. + data_index_xref: xref:/data-index/data-index-core-concepts.adoc + job_service_xref: xref:/job-services/core-concepts.adoc + diff --git a/serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts-decorated.svg b/serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts-decorated.svg new file mode 100644 index 000000000..7650dbc75 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts-decorated.svg @@ -0,0 +1,515 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + Start + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + PrintStartMessage + + + + + + + + + + + + + + + + + + WaitForEvent + + + + + + + + End + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + "workflowExecTimeout": "PT1H" + Workflow is cancelled if it has not finalized within one hour. + + + + + + + diff --git a/serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts.svg b/serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts.svg new file mode 100644 index 000000000..1ba02037d --- /dev/null +++ b/serverlessworkflow/modules/ROOT/assets/images/use-cases/timeouts-showcase/workflow-timeouts.svg @@ -0,0 +1 @@ +StartPrintStartMessageWaitForEventEnd \ No newline at end of file diff --git a/serverlessworkflow/modules/ROOT/pages/core/timeouts-support.adoc b/serverlessworkflow/modules/ROOT/pages/core/timeouts-support.adoc index 422a50f27..7445f1df2 100644 --- a/serverlessworkflow/modules/ROOT/pages/core/timeouts-support.adoc +++ b/serverlessworkflow/modules/ROOT/pages/core/timeouts-support.adoc @@ -10,6 +10,7 @@ For example, you can configure how long a workflow can wait for an event to arri Regardless of its application scope (workflow or state), the timeouts must be configured as an amount of time (a duration), which is considered to start when the referred scope becomes active. Timeouts use the link:https://en.wikipedia.org/wiki/ISO_8601[`ISO 8601` data and time standard] to specify a duration of time and follow the format `PnDTnHnMn.nS` with days considered to be exactly 24 hours. For instance, `PT15M` configures 15 minutes, and `P2DT3H4M` defines 2 days, 3 hours and 4 minutes. +[#workflow-timeout] == Workflow timeout To configure the maximum amount of time a workflow can be running before being canceled, you can use the workflow timeout. This is configured in the header section of the workflow, by using the link:{spec_doc_url}#workflowexectimeout-definition[WorkflowExecTimeout definition]. Only the `duration` property is currently implemented. @@ -21,11 +22,11 @@ For example, to cancel the workflow after an hour of execution, you must use the [source,json] ---- { - "id": "workflow_timeout", + "id": "workflow_timeouts", "version": "1.0", - "name": "Workflow timeout example", - "description": "An example of how workflow timeout works", - "start": "printWaitMessage", + "name": "Workflow Timeouts", + "description": "Simple workflow to show the workflowExecTimeout working", + "start": "PrintStartMessage", "timeouts": { "workflowExecTimeout": "PT1H" } ... @@ -195,12 +196,12 @@ For more information about Event state timeout, see link:{spec_doc_url}#event-ti == Deploying a timed-based workflow -To deploy a workflow that uses timeouts, or any other timer-based action, it is necessary to have a job service running in your environment, which is an independent service responsible to control the workflows timers, see the xref:job-services/core-concepts.adoc#job-service[job service] for more information. +To deploy a workflow that uses timeouts, or any other timer-based action, it is necessary to have a {job_service_xref}[job service] running in your environment, which is an independent service responsible to control the workflows timers, see the {job_service_xref}#integration-with-the-workflows[job service] for more information. The provisioning of this service depends on the work mode that you are using. === {operator_name} Dev Profile -When you work with the {operator_name} Dev Profile, the operator will automatically provide an execution environment that contains an embedded job service instance, as well as an instance of the data index service. +When you work with the {operator_name} Dev Profile, the operator will automatically provide an execution environment that contains an embedded {job_service_xref}[job service] instance, as well as an instance of the {data_index_xref}[data index service]. And thus, there is no need for additional configurations. In the <> you can see the details of how to work with timeouts and the {operator_name} Dev Profile. @@ -213,7 +214,7 @@ When you work with a standalone Quarkus Workflow Project, you must: 2. Ensure that a jobs service instance is available in your environment. -In the xref:job-services/core-concepts.adoc#job-service[job service] guide you can see all the available add-dons and configuration alternatives for this case. +In the {job_service_xref}[job service] guide you can see all the available add-ons and configuration alternatives for this case. [#timeouts-showcase] == Timeouts showcase diff --git a/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc b/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc index 2ad39ed7e..952b5cdc4 100644 --- a/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc +++ b/serverlessworkflow/modules/ROOT/pages/job-services/core-concepts.adoc @@ -43,7 +43,7 @@ This last is not suited for serverless architectures, where the applications mig == Jobs life-span Since the main goal of the Job Service is to work with the active jobs, such as the scheduled jobs that needs to be executed, when a job reaches a final state, it is removed from the Job Service. -However, in some cases where you want to keep the information about the jobs in a permanent repository, you can configure the Job Service to produce status change events, that can be collected by the xref:/data-index/data-index-service.adoc[Data Index Service], where they can be indexed and made available by GraphQL queries. +However, in some cases where you want to keep the information about the jobs in a permanent repository, you can configure the Job Service to produce status change events, that can be collected by the {data_index_xref}[Data Index Service], where they can be indexed and made available by GraphQL queries. [#executing] == Executing @@ -403,7 +403,7 @@ This API is useful in deployment scenarios where you want to use an event based By default, the Job Service Eventing API is prepared to work in a link:{knative_eventing_url}[knative eventing] system. This means that by adding no additional configurations parameters, it'll be able to receive cloud events via the link:{knative_eventing_url}[knative eventing] system to manage the jobs. However, you must still prepare your link:{knative_eventing_url}[knative eventing] environment to ensure these events are properly delivered to the Job Service, see <>. -Finally, the only configuration parameter that you must set, when needed, is to enable the propagation of the Job Status Change events, for example, if you want to register these events in the xref:/data-index/data-index-service.adoc[Data Index Service] +Finally, the only configuration parameter that you must set, when needed, is to enable the propagation of the Job Status Change events, for example, if you want to register these events in the {data_index_xref}[Data Index Service]. [tabs] ==== diff --git a/serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc b/serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc index 1aa5b3ff8..0cf0ae0ad 100644 --- a/serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc +++ b/serverlessworkflow/modules/ROOT/pages/use-cases/timeout-showcase-example.adoc @@ -10,10 +10,38 @@ While all the scenarios contain the same set of workflows, they are provided as The following workflows are provided: +* <> * <> * <> * <> +[#workflow_timeouts_workflow] +== `workflow_timeouts` workflow + +It is a simple workflow that, rather than configuring a timeout for a particular state, is configured for the whole execution of the workflow. +This can be done by using the `workflowExecTimeout` property, which defines the maximum workflow execution time. If this time is surpassed and the workflow has not finished, it will be automatically canceled. + +See the xref:core/timeouts-support.adoc#workflow-timeout[workflow timeout definition] for more information. + +.workflow_timeouts workflow +image::use-cases/timeouts-showcase/workflow-timeouts-decorated.svg[] + +.Workflow execution timeout definition +[source,json] +---- +{ + "id": "workflow_timeouts", + "version": "1.0", + "name": "Workflow Timeouts", + "description": "Simple workflow to show the workflowExecTimeout working", + "start": "PrintStartMessage", + "timeouts": { + "workflowExecTimeout": "PT1H" + } +... +} +---- + [#callback_state_timeouts_workflow] == `callback_state_timeouts` workflow @@ -200,7 +228,7 @@ To execute the workflows you can use any of the available deployment scenarios: [#execute-operator-dev-profile] === {product_name} Operator Dev Profile -When you work with the {operator_name} Dev Profile, the operator will automatically provision an execution environment that contains an embedded job service instance, as well as an instance of the data index service. +When you work with the xref:cloud/operator/developing-workflows.adoc[{operator_name} Dev Profile], the operator will automatically provision an execution environment that contains an embedded {job_service_xref}[job service] instance, as well as an instance of the {data_index_xref}[data index service]. And thus, there is no need for additional configurations when you use timeouts. To execute the workflows you must: @@ -217,7 +245,7 @@ cd kogito-examples/serverless-workflow-examples/serverless-workflow-timeouts-sho [#execute-quarkus-project-embedded-services] === Quarkus Workflow Project with embedded services -Similar to the <<#execute-operator-dev-profile, {operator_name} Dev Profile>>, this scenario shows how to configure the embedded job service and data index service, when you work with a Quarkus Workflow Project. And is also intended for development purposes. +Similar to the <<#execute-operator-dev-profile, {operator_name} Dev Profile>>, this scenario shows how to configure the embedded {job_service_xref}[job service] and {data_index_xref}[data index service], when you work with a Quarkus Workflow project and it is also intended for development purposes. In a command terminal, clone the `kogito-examples` repository, navigate to the cloned directory, and follow link:{kogito_sw_examples_url}/serverless-workflow-timeouts-showcase-embedded/README.md[these steps]: @@ -232,8 +260,8 @@ cd kogito-examples/serverless-workflow-examples/serverless-workflow-timeouts-sho [#execute-quarkus-project-standalone-services] === Quarkus Workflow Project with standalone services -This is the most complex and close to a production scenario. In this case, the workflows, the job service, the data index service, and the database, are deployed as standalone services in the kubernetes/knative cluster. -Additionally, the communications from the workflows to the job service, and from the jobs service to the data index service, are resolved via the knative eventing system. +This is the most complex and close to a production scenario. In this case, the workflows, the {job_service_xref}[job service], the {data_index_xref}[data index service], and the database are deployed as standalone services in the kubernetes or knative cluster. +Additionally, the communications from the workflows to the {job_service_xref}[job service], and from the {job_service_xref}[job service] to the {data_index_xref}[data index service], are resolved via the knative eventing system. [NOTE] ==== @@ -245,9 +273,9 @@ By using the knative eventing system the underlying low level communication syst The following diagram shows the architecture for this use case: -. Every time a workflow needs to program a timer for a given timeout, a cloud event is sent to the job service for that purpose. +. Every time a workflow needs to program a timer for a given timeout, a cloud event is sent to the {job_service_xref}#integration-with-the-workflows[job service] for that purpose. . When a timer is overdue, a rest call is executed to notify the workflow, which then must execute accordingly to the given state semantic. -. Workflow and job status changes are propagated to the Data Index Service via cloud events. +. Workflow and job status changes are propagated to the {data_index_xref}[data index service] via cloud events. .Knative Workflow with Job Service architecture image::use-cases/timeouts-showcase/timeouts-showcase-extended-architecture.png[]