You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kie.apache.org by fj...@apache.org on 2024/03/14 12:08:35 UTC
(incubator-kie-kogito-docs) branch main updated: [Fix #526] Document and give example of JSON in data (#582)
This is an automated email from the ASF dual-hosted git repository.
fjtiradosarti pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new cfa237a26 [Fix #526] Document and give example of JSON in data (#582)
cfa237a26 is described below
commit cfa237a26e8a1d1b56fb73e55c834cee22a49d96
Author: Francisco Javier Tirado Sarti <65...@users.noreply.github.com>
AuthorDate: Thu Mar 14 13:08:30 2024 +0100
[Fix #526] Document and give example of JSON in data (#582)
* [Fix #526] Document and give example of JSON in data
Also adding function of type expression and more info on $SECRET data
type
* Update serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
Co-authored-by: Ricardo Zanini <15...@users.noreply.github.com>
* Update serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
Co-authored-by: Ricardo Zanini <15...@users.noreply.github.com>
* Update serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
Co-authored-by: Ricardo Zanini <15...@users.noreply.github.com>
* Update serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
Co-authored-by: Ricardo Zanini <15...@users.noreply.github.com>
* Update serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
Co-authored-by: Ricardo Zanini <15...@users.noreply.github.com>
* Apply Kalyanis suggestions from code review
Co-authored-by: Kalyani Desai <43...@users.noreply.github.com>
---------
Co-authored-by: Ricardo Zanini <15...@users.noreply.github.com>
Co-authored-by: Dominik Hanák <do...@users.noreply.github.com>
Co-authored-by: Kalyani Desai <43...@users.noreply.github.com>
---
.../pages/core/understanding-jq-expressions.adoc | 52 +++++++++++++++++++++-
1 file changed, 51 insertions(+), 1 deletion(-)
diff --git a/serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc b/serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
index 7bfa2f464..d7cd35ade 100644
--- a/serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
+++ b/serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc
@@ -13,10 +13,27 @@ Each workflow instance is associated with a data model. A data model consists of
The workflow expressions in the link:{spec_doc_url}#workflow-expressions[Serverless Workflow specification] are used to interact with the data model. The supported expression languages include link:{jsonpath_url}[JsonPath] and link:{jq_url}[jq]. jq expression language is the default language. However, you can change the expression language to JsonPath using the `expressionLang` property.
-This document describes the usage of jq expressions in switch state conditions, action function arguments, and data filtering.
+This document describes the usage of jq expressions in functions, switch state conditions, action function arguments, data filtering, and event publishing.
JQ expression might be tricky to master, for non trivial cases, it is recommended to use helper tools like link:{jq_play}[JQ Play] to validate the expression before including it in the workflow file.
+[[ref-example-jq-expression-function]]
+== Example of jq expression in functions
+
+Expressions can be used in functions of type `expression` to manipulate the workflow model. As with any other function, the result of the expression evaluation will be merged into the model.
+
+For example, in the link:{kogito_sw_examples_url}/serverless-workflow-expression-quarkus[`serverless-workflow-expression-quarkus`] example application, a max function adds to the model two properties: `max`, containing the maximum value of `x` coordinate in the `numbers` array (which is a workflow input parameter) and `min`, containing the minimum value of `y` coordinate
+
+.Example conditions in `serverless-workflow-expression-quarkus`
+[source,json]
+----
+ {
+ "name": "max",
+ "type": "expression",
+ "operation": "{max: .numbers | max_by(.x), min: .numbers | min_by(.y)}"
+ }
+----
+
[[ref-example-jq-expression-switch-conditions]]
== Example of jq expressions in switch conditions
@@ -197,6 +214,29 @@ You can find an example of event data filtering in the link:{kogito_sw_examples_
----
The previous example of the event filter copies the content of CloudEvent data `result` field into the workflow model `move` field.
+
+[[ref-example-jq-expression-event-publishing]]
+== Example of jq expressions in event publishing.
+
+When publishing a Cloud Event, you can select the data that is being published using a jq expression that generates a JSON object. Note that in yaml double quotes are required to allow using `{}` characters.
+
+.Example data expression returning an object
+[source,yaml]
+----
+transition:
+ nextState: WaitForSaveTransformationCompletionEvent
+ produceEvents:
+ - eventRef: saveTransformationEvent
+ data: "{gitRepo:.repositoryURL|sub(\"http(s)?://\";\"ssh://\"), branch: .targetBranch, token: .token, workspaceId: .workspaceId, projectId: .projectId, transformId: .transformId, workflowCallerId: $WORKFLOW.instanceId}"
+----
+
+In the previous example, a CloudEvent was published when the state transitioned. Its `data` field looks like
+
+.Example of generated event
+[source,json]
+----
+data={"gitRepo":"ssh://bitbucket.org/m2k-test","branch":"aaaaaaasssss","token":null,"workspaceId":"b93980cb-3943-4223-9441-8694c098eeb9","projectId":"9b305fe3-d441-48ce-b01b-d314e86e14ec","transformId":"723dce89-c25c-4c7b-9ef3-842de92e6fe6","workflowCallerId":"7ddb5193-bedc-4942-a857-596b31f377ed"}
+----
--
== Workflow secrets, constants and context
@@ -204,6 +244,7 @@ The previous example of the event filter copies the content of CloudEvent data `
As per specification, you can use link:{spec_doc_url}#workflow-constants[Workflow Constants] and link:{spec_doc_url}#workflow-secrets[Workflow Secrets] whenever an expression is accepted.
In {product_name} you can use `$SECRET` to access any configuration property, not just sensitive ones.
So, assuming you have added to your `application.properties` a line with the `myname=john` property, the following function will append the string `my name is john` to the `message` variable
+[source,json]
----
{
"name": "secretMessage",
@@ -212,6 +253,15 @@ So, assuming you have added to your `application.properties` a line with the `my
}
----
+`$SECRET` always returns a value of type string. If you want to use it in a comparison with a value that is not a string, you must perform the conversion explicitly. In the next example, the `retries` property is a number, so we need to convert the property value accordingly by calling the `tonumber` built-in jq function.
+
+[source,json]
+----
+{
+ "condition": ".retries > ($SECRET._max_retries|tonumber)"
+}
+----
+
Besides constants and secrets, you might access contextual information of the running workflow by using the $WORKFLOW reserved word.
{product_name} supports the following contextual keys:
* `id`: The id of the running workflow definition
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org