docs: misc updates #3053 (#3294)

docs/admin/developer/agama/hello-world-closer.md

@@ -24,7 +24,7 @@ In normal circumstances the flow is launched through a web browser via an [OIDC
 
 ### First request cycle
 
-The GET request for `agama.fls` is processed by [this servlet](https://github.com/JanssenProject/jans/blob/main/agama/engine/src/main/java/io/jans/agama/engine/servlet/ExecutionServlet.java). Most of logic takes place at method `startFlow` of [FlowService](
+The GET request for `agama.fls` is processed by [this servlet](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/agama/engine/src/main/java/io/jans/agama/engine/servlet/ExecutionServlet.java). Most of logic takes place at method `startFlow` of [FlowService](
 https://github.com/JanssenProject/jans/blob/main/agama/engine/src/main/java/io/jans/agama/engine/service/FlowService.java) bean. Here, the associated data of the flow in question is retrieved from the database. Its transpiled code in addition to utility code ([util.js](https://github.com/JanssenProject/jans/blob/main/agama/transpiler/src/main/resources/util.js)) is loaded and the main entry point called - see invocation of `callFunctionWithContinuations`. This will throw a `ContinuationPending` exception once the equivalent instruction to `RRF` (or `RFAC`) is found in the transpiled code.
 
 The above means that at line 6 of [Hello world](https://github.com/JanssenProject/jans/blob/main/docs/admin/developer/agama/test#L6), the DSL code execution is interrupted: method `processPause` collects the required data for template rendering, like template location and its associated data model. This is saved to permanent storage in addition to the "state of the program", that is the values of all variables defined so far in the flow - this is known as the "continuation".
@@ -33,7 +33,7 @@ Finally the `ExecutionServlet` sends a response consisting of a redirect. This c
 
 ### Second request cycle
 
-As a consequence of the HTTP redirect received, the browser will request the server a URL like `/jans-auth/fl/hello/index.fls`. Note how this is correlated to the template path defined in the flow. Here the GET handler of `ExecutionServlet` takes control again, this time calling the `sendPageContents` method defined in the parent class [BaseServlet](https://github.com/JanssenProject/jans/blob/main/agama/engine/src/main/java/io/jans/agama/engine/servlet/BaseServlet.java). `sendPageContents` performs the actual page rendering - specifically for `hello/index.ftlh` in this case - and the produced markup is sent to browser.
+As a consequence of the HTTP redirect received, the browser will request the server a URL like `/jans-auth/fl/hello/index.fls`. Note how this is correlated to the template path defined in the flow. Here the GET handler of `ExecutionServlet` takes control again, this time calling the `sendPageContents` method defined in the parent class [BaseServlet](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/agama/engine/src/main/java/io/jans/agama/engine/servlet/BaseServlet.java). `sendPageContents` performs the actual page rendering - specifically for `hello/index.ftlh` in this case - and the produced markup is sent to browser.
 
 So far we have "covered" the first two letters of the RRF instruction.
 

docs/admin/developer/agama/lifecycle.md

@@ -76,7 +76,17 @@ where `flow.js` might look like this:
 {
   "qname": "com.acme.myflow",
   "source": "Flow com.acme.myflow\n\tBasepath \"\"\n\nin = { name: \"John\" }\nRRF \"index.ftlh\" in\n\nFinish \"john_doe\"",
-  "enabled": true,
+  "enabled": true
+}
+```
+
+**Notes:**
+
+- Only `qname` and `source` are required in the JSON payload
+- If `enabled` is absent, a `false` value is used by default in the JSON-based endpoint. The text-based version always assumes `true`. This property allows or prevents launching a flow directly from the browser
+
+<!--
+,
   "metadata": {
     "displayName": "Biometric authentication",
     "author": "John",
@@ -86,14 +96,8 @@ where `flow.js` might look like this:
       "secret": "change it"
     }
   }
-}
-```
-
-**Notes:**
-
-- Only `qname` and `source` are required in the JSON payload
 - `properties` in `metadata` refers to the configuration parameters of the flow. See `Configs` keyword [here](./dsl-full.md#header-basics)
-- If `enabled` is absent, a `false` value is used by default in the JSON-based endpoint. The text-based version always assumes `true`. This property allows or prevents launching a flow directly from the browser
+-->
 
 ## Upload required assets
 

docs/admin/developer/agama/quick-start.md

@@ -43,9 +43,7 @@ These are elements used to build the user interface such as templates, images, s
 
 Templates are written using [FreeMarker Template Language](https://freemarker.apache.org/docs/index.html) (FTL). This is a simple and highly productive language to produce HTML and other forms of output. By convention templates generating HTML markup in Agama have the extension `ftlh`.
 
-In Agama, templates must reside in the filesystem under `/opt/jans/jetty/jans-auth/agama/ftl` directory.
-
-All the other assets (CSS, JS, etc.) are expected to be under `/opt/jans/jetty/jans-auth/agama/fl`.
+In Agama, templates must reside in the filesystem under `/opt/jans/jetty/jans-auth/agama/ftl` directory. All other assets (CSS, JS, etc.) are expected to be under `/opt/jans/jetty/jans-auth/agama/fl`. Later we'll see a flow can designate a given directory for its assets, thus, such directory must be created at both places (inside `ftl` and `fl` folders).
 
 ### Java classes
 

docs/admin/developer/agama/ui-pages.md

@@ -26,7 +26,7 @@ As you will see, the task boils down to produce the desired markup plus adding s
 
 In Agama, every template is generally "injected" some data, see [RRF](./dsl.md#rrf). This data in FreeMarker terms is known as "data-model". In practice, this will be an Agama [map](./dsl-full.md#maps) which can be accessed from the templates using standard FreeMarker notation. This _map_ is attached a couple of additional keys for developer's convenience:
 
-- `webCtx`. It gives easy access to often needed bits like current path, locale, etc. This is a Java object you can inspect [here](https://github.com/JanssenProject/jans/blob/main/agama/engine/src/main/java/io/jans/agama/engine/service/WebContext.java). Take a look at the getters; writing `${webCtx.contextPath}` in a template will insert the result of calling method `getContextPath` - normally the string `/jans-auth`.
+- `webCtx`. It gives easy access to often needed bits like current path, locale, etc. This is a Java object you can inspect [here](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/agama/engine/src/main/java/io/jans/agama/engine/service/WebContext.java). Take a look at the getters; writing `${webCtx.contextPath}` in a template will insert the result of calling method `getContextPath` - normally the string `/jans-auth`.
 
 - `msgs`. It gives access to the localized messages of jans-auth application. Some developers might know this as the "internationalization labels" or "resource bundle" of an application. This is a collection of `.properties` files where common UI-related messages in different languages can be found. A message (label) is identified by a key, so in a template `${msgs.<KEY>}` could be used. As most keys in resource bundles have dot characters, the alternative notation `${webCtx["KEY"]}` works better for FreeMarker, for example `${msgs["login.errorMessage"]}`.
 

docs/agama-catalog/jans/inboundID/README.md

@@ -180,7 +180,7 @@ Launch the main flow (learn about this topic [here](https://jans.io/docs/admin/d
     
 ### Main flow configurations
 
-Configuration is supplied in a JSON object whose keys are the identifiers of the existing identity providers. The associated value for a key is a JSON object itself and follows the structure represented by [this](https://github.com/JanssenProject/jans/blob/main/agama/inboundID/src/main/java/io/jans/inbound/Provider.java) Java class.
+Configuration is supplied in a JSON object whose keys are the identifiers of the existing identity providers. The associated value for a key is a JSON object itself and follows the structure represented by [this](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/agama/inboundID/src/main/java/io/jans/inbound/Provider.java) Java class.
 
 This is an example of a configuration for a couple of identity providers:
 
@@ -227,7 +227,7 @@ The table below explains the meaning of properties:
 
 Configurations for this kind of flows don't have to adhere to any specific structure. Developers are free to choose what fits best for their needs. Also note provider flows **must not** receive any inputs: the main flow won't pass any arguments when triggering them. Thus, design your flows so there is no use of `Inputs` but `Configs` directive in the [header](https://jans.io/docs/admin/developer/agama/dsl-full/#header-basics).
 
-In practice many identity providers adhere to the OAuth2 `code` grant, so you can re-use the structure represented by [this](https://github.com/JanssenProject/jans/blob/main/agama/inboundID/src/main/java/io/jans/inbound/oauth2/OAuthParams.java) Java class for the purpose. Particularly, the already implemented flows (like Facebook) use it for their configuration.
+In practice many identity providers adhere to the OAuth2 `code` grant, so you can re-use the structure represented by [this](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/agama/inboundID/src/main/java/io/jans/inbound/oauth2/OAuthParams.java) Java class for the purpose. Particularly, the already implemented flows (like Facebook) use it for their configuration.
 
 The table below explains the meaning of its properties:
 
@@ -274,15 +274,15 @@ As an example suppose a provider returned the following:
 
 None of this attributes exist in Janssen, database adheres to LDAP naming. Conformant names would be `uid`, `mail`, `sn`, and `givenName`. Also, let's assume you want to set `displayName` to a string composed by the first and last names separated by a white space. Writing a mapping is required.
 
-A mapping is implemented in Java in the form of a `java.util.function.UnaryOperator<Map<String, Object>>`, that is, a function that takes a `Map<String, Object>` as input and returns a `Map<String, Object>` as result. Several examples are provided [here](https://github.com/JanssenProject/jans/blob/main/agama/inboundID/src/main/java/io/jans/inbound/Mappings.java). 
+A mapping is implemented in Java in the form of a `java.util.function.UnaryOperator<Map<String, Object>>`, that is, a function that takes a `Map<String, Object>` as input and returns a `Map<String, Object>` as result. Several examples are provided [here](https://github.com/JanssenProject/jans/blob/main/jans-auth-server/agama/inboundID/src/main/java/io/jans/inbound/Mappings.java). 
 
 Note property `mappingClassField` of every provider defined in the [main flow](#main-flow-configurations) points to the fully qualified name of a mapping. Some important considerations:
 
 - A mapping has to be declared as a public field in a public class
 - Not all mappings have to belong to the same class
 - Several providers can use the same mapping
 
-While working on a mapping, having to pack the class in a jar file, uploading it to the server, and then restarting  every time a modification is made can be a big burden. To avoid this you can upload the source (java) file to the scripts directory of Agama and leverage hot reloading as outlined [here](https://jans.io/docs/admin/developer/agama/java-classpath/). A "template" for quickly start writing a mapping is already [available](https://github.com/JanssenProject/jans/raw/main/agama/inboundID/CustomMappings.java.txt). Save with `.java` extension only, edit the body of the lambda expression, upload to the server, and then update the main flow as follows:   
+While working on a mapping, having to pack the class in a jar file, uploading it to the server, and then restarting  every time a modification is made can be a big burden. To avoid this you can upload the source (java) file to the scripts directory of Agama and leverage hot reloading as outlined [here](https://jans.io/docs/admin/developer/agama/java-classpath/). A "template" for quickly start writing a mapping is already [available](https://github.com/JanssenProject/jans/raw/main/jans-auth-server/agama/inboundID/CustomMappings.java.txt). Save with `.java` extension only, edit the body of the lambda expression, upload to the server, and then update the main flow as follows:   
 
 - Add an instruction like `Call io.jans.inbound.CustomMappings#class` at the beginning of the flow body for the class to be effectively reloaded when the file is modified
 - Set `mappingClassField` to `io.jans.inbound.CustomMappings.SAMPLE_MAPPING` for the provider of interest. You may like the idea of using a different name for the field - update the java file accordingly