[KOGITO-7257] Documenting workflow metainfo

serverlessworkflow/antora.yml

@@ -68,6 +68,7 @@ asciidoc:
     kogito_sw_operator_examples_url: https://github.com/apache/incubator-kie-kogito-examples/tree/main/serverless-operator-examples
     kogito_examples_url: https://github.com/apache/incubator-kie-kogito-examples.git
     kogito_apps_url: https://github.com/apache/incubator-kie-kogito-apps/tree/main
+    kogito_runtimes_url: https://github.com/apache/incubator-kie-kogito-runtimes/tree/main
     quarkus_cli_url: https://quarkus.io/guides/cli-tooling
     spec_website_url: https://serverlessworkflow.io/
     spec_doc_url: https://github.com/serverlessworkflow/specification/blob/0.8.x/specification.md

serverlessworkflow/modules/ROOT/pages/core/understanding-jq-expressions.adoc

@@ -199,6 +199,45 @@ 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.
 --
 
+== Workflow secrets, constants and context
+
+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
+----
+{
+      "name": "secretMessage",
+      "type": "expression",
+      "operation": ".message |= \"my name is \"+$SECRET.my_name"
+}
+----
+
+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
+ * `name`: The name of the running workflow definition
+ * `instanceId`: The id of the running workflow instance
+ * `headers`: Optional map containing the headers, if any, of the invocation that started the running workflow instance 
+ * `prevActionResult`: In a `foreach` state, give access the result of the previous loop iteration output. 
+ * `identity`: Quarkus security identity
+
+ Therefore, the following function, for a serverless workflow definition whose id  is `expressionTest`, will append the string `worklow id is expressionTest` to the `message` variable
+
+----
+{
+      "name": "contextMessage",
+      "type": "expression",
+      "operation": ".message |= \"workflow id is \"+$WORKFLOW.id"
+}
+----
+
+=== Customizing workflow context
+
+In addition to the predefined keys mentioned previously, you can add your own keys to workflow context using Java Service Loader mechanism, by providing an implementation of class link:{kogito_runtimes_url}/kogito-serverless-workflow/kogito-serverless-workflow-utils/src/main/java/org/kie/kogito/serverless/workflow/utils/KogitoProcessContextResolverExtension.java[KogitoProcessContextResolverExtension] 
+
+This feature was used to add quarkus security identity support, you can check source code as reference link:{kogito_runtimes_url}/quarkus/extensions/kogito-quarkus-serverless-workflow-extension/kogito-quarkus-serverless-workflow/src/main/java/org/kie/kogito/serverless/workflow/QuarkusKogitoProcessContextResolver.java[here].
+
+
 == Additional resources
 
 * link:{jq_play} [JQ Play offline]