Merge pull request #1674 from folio-org/FOLIO-873-improve-docs-268

FOLIO-873 improve docs

_data/remote-docs.json

@@ -20,6 +20,7 @@
   "https://raw.githubusercontent.com/folio-org/rfcs/master/text/0002-kafka-tenant-collection-topics.md",
   "https://raw.githubusercontent.com/folio-org/rfcs/master/text/0003-folio-breaking-changes.md",
   "https://raw.githubusercontent.com/folio-org/rfcs/master/text/0004-iso-8601.md",
+  "https://raw.githubusercontent.com/folio-org/rfcs/master/text/0006-folio-distributed-vs-centralized-configration.md",
   "https://raw.githubusercontent.com/folio-org/stripes-cli/master/doc/dev-guide.md",
   "https://raw.githubusercontent.com/folio-org/stripes-cli/master/doc/user-guide.md",
   "https://raw.githubusercontent.com/folio-org/stripes-components/master/README.md",

_data/repos.json

@@ -1,6 +1,6 @@
 {
   "metadata": {
-    "generatedDateTime": "2024-04-23T23:55:39.713613+00:00"
+    "generatedDateTime": "2024-05-22T06:26:22.691494+00:00"
   },
   "repos": [
     {
@@ -299,7 +299,7 @@
       "ramlDirName": null,
       "repoLanguageHint": "java",
       "repoType": "backend-edge",
-      "snippetIntro": "<p>Provides an ability to retrieve license term information</p>",
+      "snippetIntro": "<p>Provides an ability to retrieve license term information from FOLIO to external systems. The data flow is <code>edge-erm &lt;-&gt; FOLIO &lt;-&gt; mod-agreements</code>.</p>",
       "workflows": [
         "api-doc.yml",
         "api-lint.yml",
@@ -2653,19 +2653,20 @@
       "apiTypes": "OAS",
       "defaultBranch": "master",
       "description": "Module manages record specifications and validates records against them",
-      "docDirName": null,
+      "docDirName": "docs",
       "hintOas": true,
       "isSpringway": true,
       "name": "mod-record-specifications",
       "org": "folio-org",
       "ramlDirName": null,
       "repoLanguageHint": "java",
       "repoType": "backend-mod",
-      "snippetIntro": "<p>Module for managing and validating records against predefined specifications.</p>",
+      "snippetIntro": "<p>mod-record-specifications is a module for managing and validating records against predefined specifications.</p>",
       "workflows": [
         "api-doc.yml",
         "api-lint.yml",
         "api-schema-lint.yml",
+        "build-dependants.yml",
         "spectral-lint.yml"
       ],
       "workflowsFolio": [
@@ -4503,6 +4504,9 @@
       "snippetIntro": "<p>The Lists UI Module, or <code>ui-lists</code>, is a Stripes UI Module used to create and manage Lists which are queries across multiple modules (for example: find all items marked as missing or declared lost, or find all open loans assigned to inactive users).</p>",
       "workflows": [
         "ui.yml"
+      ],
+      "workflowsFolio": [
+        "ui.yml"
       ]
     },
     {
@@ -4677,12 +4681,10 @@
       "repoType": "ui-plugin",
       "snippetIntro": "<p>This package furnishes a single Stripes plugin of type <code>bursar-export</code>, which can be included in Stripes modules by means of a <code>&lt;Pluggable type='bursar-export'&gt;</code> element. See <a href='https://github.com/folio-org/stripes-core/blob/master/doc/dev-guide.md#plugins'>the <em>Plugins</em> section</a> of the Module Developer's Guide.</p>",
       "workflows": [
-        "build-npm-release.yml",
-        "build-npm.yml"
+        "ui.yml"
       ],
       "workflowsFolio": [
-        "build-npm-release.yml",
-        "build-npm.yml"
+        "ui.yml"
       ]
     },
     {

_faqs/how-to-get-started-with-rancher.md

@@ -27,6 +27,7 @@ Some teams also provide [further general instructions](/guides/run-local-folio/#
 For general assistance use the [Slack channel](/guidelines/which-forum/#slack) `#rancher-support` and help via your team-specific channel.
 
 To raise Jira tickets related to Rancher scratch environments, refer to the [FAQ](/faqs/how-to-raise-devops-ticket/#rancher-scratch-environments).
+This is needed when contacting the `#rancher-support` Slack channel.
 
 See the Wiki [How to work with Rancher environments](https://folio-org.atlassian.net/wiki/spaces/FOLIJET/pages/1396559/How+to+work+with+Rancher+environments).
 

_faqs/how-to-obtain-refenv-logs.md

@@ -22,3 +22,5 @@ For example notify yourself, or another person, or notify your team channel.
 
 All members of folio-org are configured to run this job. The service creates a tar file containing the specified logs and uploads to an S3 bucket. A URL to retrieve the logs is returned via a Slack notification.
 
+For failed [Platform hourly build](/guides/automation/#platform-hourly-build) jobs, the Okapi log is linked from the left-hand panel of its Jenkins job summary page.
+

_faqs/how-to-specify-backend-java-ci.md

@@ -9,7 +9,7 @@ faqOrder: 12
 
 Back-end Java-based modules can specify which build image to use during the Jenkins continuous integration builds.
 
-For front-end modules that still use Jenkins build rather than GitHub Workflows, the buildNode provides the relevant Nodejs version.
+For the few front-end modules that still use Jenkins build rather than GitHub Workflows, the buildNode provides the relevant Nodejs version.
 
 ## Using Java 17
 
@@ -20,10 +20,11 @@ For projects that use Java 17:
 * In [Jenkinsfile](/guides/jenkinsfile/), declare the mandatory module heath check endpoint via the Docker command `healthChkCmd` to use 'wget'. (There is no 'curl' available on the base image.) 
 * In Dockerfile, use:\
   `FROM folioci/alpine-jre-openjdk17:latest`
+* See other notes (e.g. POM file, and dependencies, and wget example) at Wiki [JDK 17 and Java 17](https://folio-org.atlassian.net/wiki/x/Th9N).
 
 ## Using Java 11
 
-For projects that use Java 11:
+For some projects that use Java 11 (there should now not be any):
 
 * In [Jenkinsfile](/guides/jenkinsfile/), declare this in the "buildMvn" section:\
   `buildNode = 'jenkins-agent-java11'`

_remote/edge-common/README.md

@@ -152,22 +152,52 @@ e.g. Key=`ab73kbw90e/diku`, Field=`diku`
 
 Configuration information is specified in two forms:
 1. System Properties - General configuration
-1. Properties File - Configuration specific to the desired secure store
+2. Properties File - Configuration specific to the desired secure store
 
 ### System Properties
 
-Property                 | Default     | Description
------------------------- | ----------- | -------------
-`port`                   | `8081`      | Server port to listen on
-`okapi_url`              | *required*  | Where to find Okapi (URL)
-`secure_store`           | `Ephemeral` | Type of secure store to use.  Valid: `Ephemeral`, `AwsSsm`, `Vault`
-`secure_store_props`     | `NA`        | Path to a properties file specifying secure store configuration
-`token_cache_ttl_ms`     | `3600000`   | How long to cache JWTs, in milliseconds (ms)
-`null_token_cache_ttl_ms`| `30000`     | How long to cache login failure (null JWTs), in milliseconds (ms)
-`token_cache_capacity`   | `100`       | Max token cache size
-`log_level`              | `INFO`      | Log4j Log Level
-`request_timeout_ms`     | `30000`     | Request Timeout
-`api_key_sources`        | `PARAM,HEADER,PATH` | Defines the sources (order of precendence) of the API key.
+| Property                  | Default             | Description                                                               |
+|---------------------------|---------------------|---------------------------------------------------------------------------|
+| `port`                    | `8081`              | Server port to listen on                                                  |
+| `okapi_url`               | *required*          | Where to find Okapi (URL)                                                 |
+| `secure_store`            | `Ephemeral`         | Type of secure store to use.  Valid: `Ephemeral`, `AwsSsm`, `Vault`       |
+| `secure_store_props`      | `NA`                | Path to a properties file specifying secure store configuration           |
+| `token_cache_ttl_ms`      | `3600000`           | How long to cache JWTs, in milliseconds (ms)                              |
+| `null_token_cache_ttl_ms` | `30000`             | How long to cache login failure (null JWTs), in milliseconds (ms)         |
+| `token_cache_capacity`    | `100`               | Max token cache size                                                      |
+| `log_level`               | `INFO`              | Log4j Log Level                                                           |
+| `request_timeout_ms`      | `30000`             | Request Timeout                                                           |
+| `api_key_sources`         | `PARAM,HEADER,PATH` | Defines the sources (order of precendence) of the API key.                |
+
+### System Properties for TLS configuration for Http server
+To configure Transport Layer Security (TLS) for the HTTP server in an edge module, the following configuration parameters should be used.
+Parameters marked as Required are required only in case when ssl_enabled is set to true.
+
+| Property                          | Default           | Description                                                                                 |
+|-----------------------------------|-------------------|---------------------------------------------------------------------------------------------|
+| `http-server.ssl_enabled`         | `false`           | Set whether SSL/TLS is enabled for Vertx Http Server                                        |
+| `http-server.keystore_type`       | `NA`              | (Required). Set the type of the keystore. Common types include `JKS`, `PKCS12`, and `BCFKS` |
+| `http-server.keystore_provider`   | `NA`              | Set the provider name of the key store                                                      |
+| `http-server.keystore_path`       | `NA`              | (Required). Set the location of the keystore file in the local file system                  |
+| `http-server.keystore_password`   | `NA`              | (Required). Set the password for the keystore                                               |
+| `http-server.key_alias`           | `NA`              | Set the alias of the key within the keystore.                                               |
+| `http-server.key_alias_password`  | `NA`              | Optional param that points to a password of `key_alias` if it protected                     |
+
+### System Properties for TLS configuration for Web Client
+To configure Transport Layer Security (TLS) for Web clients in the edge module, you can use the following configuration parameters.
+Truststore parameters for configuring Web clients are optional even when ssl_enabled = true.
+If truststore parameters need to be populated, truststore_type, truststore_path and truststore_password are required.
+
+| Property                          | Default           | Description                                                                      |
+|-----------------------------------|-------------------|----------------------------------------------------------------------------------|
+| `web-client.ssl_enabled`          | `false`           | Set whether SSL/TLS is enabled for Vertx Http Server                             |
+| `web-client.truststore_type`      | `NA`              | Set the type of the keystore. Common types include `JKS`, `PKCS12`, and `BCFKS`  |
+| `web-client.truststore_provider`  | `NA`              | Set the provider name of the key store                                           |
+| `web-client.truststore_path`      | `NA`              | Set the location of the keystore file in the local file system                   |
+| `web-client.truststore_password`  | `NA`              | Set the password for the keystore                                                |
+| `web-client.key_alias`            | `NA`              | Set the alias of the key within the keystore.                                    |
+| `web-client.key_alias_password`   | `NA`              | Optional param that points to a password of `key_alias` if it protected          |
+
 
 ## Additional information
 

_remote/raml-module-builder/README.md

@@ -1611,7 +1611,7 @@ For each **table** in `tables` property:
     * `arraySubfield` - is the key of the object that is used for the primary term when array relation modifiers are in use. This is typically also defined when `arrayModifiers` are also defined.
     * `multiFieldNames` - see [CQL2PgJSON: Multi Field Index](#cql2pgjson-multi-field-index) above
     * `sqlExpression` - see [CQL2PgJSON: Multi Field Index](#cql2pgjson-multi-field-index) above
-    * `sqlExpressionQuery` - How to wrap the query string $ before matching against the index expression. This overwrites any `caseSensitive` and `removeAccents` wrapping. Example that manually implements case insensitive matching: `"sqlExpression": "lower(jsonb->>'name')", "sqlExpressionQuery": "lower($)"`
+    * `sqlExpressionQuery` - How to wrap the query string $ before matching against the index expression. This overwrites any `caseSensitive` and `removeAccents` wrapping. Example that manually implements case insensitive matching: `"sqlExpression": "lower(jsonb->>'name')", "sqlExpressionQuery": "lower($)"`. Example for plain field, note the required braces: `"sqlExpression": "(jsonb->>'name')", "sqlExpressionQuery": "$"`.
     * Do not manually add an index for an `id` field or a foreign key field. They get indexed automatically.
 7. `ginIndex` - generate an inverted index on the JSON using the `gin_trgm_ops` extension. Allows for left and right truncation LIKE queries and regex queries to run in an optimal manner (similar to a simple search engine). Note that the generated index is large and does not support the full field match (SQL `=` operator and CQL `==` operator without wildcards). See the `likeIndex` for available options.
 8. `uniqueIndex` - create a unique index on a field in the JSON
@@ -1713,7 +1713,7 @@ The fields in the **script** section include:
 1. `run` - either `before` or `after` the tables / views are generated
 2. `snippet` - the SQL to run. There is no variable replacement. Use `snippetPath` if variable replacement or line breaks for readability are needed.
 3. `snippetPath` - relative path to a file with SQL script to run. If `snippetPath` is set then `snippet` field will be ignored.
-4. `fromModuleVersion` - same as `fromModuleVersion` for table. If no fromModuleVersion is provided the SQL runs on each upgrade. This is reasonable if the SQL runs fast and is idempotent, for example ```CREATE OR REPLACE FUNCTION``` and you want to avoid the error-prone fromModuleVersion value maintenance needed when changing the function.
+4. `fromModuleVersion` - same as `fromModuleVersion` for table. If no fromModuleVersion is provided the SQL runs on each upgrade. This is reasonable if the SQL runs fast and is idempotent, for example ```CREATE OR REPLACE FUNCTION``` and you want to avoid the error-prone fromModuleVersion value maintenance needed when changing the function. The SQL also runs on the initial install of a tenant.
 
 A `snippetPath` SQL file (but not a `snippet` SQL statement) can make use of
 [FreeMarker template engine](https://freemarker.apache.org) that runs and evaluates on runtime. For examples, see RMB's